command updates, prettier fixes

Author: gallayl

.cursor/commands/review-changes.md

@@ -67,6 +67,7 @@ For each issue, be specific: file, line, problem, suggested fix.
 **5. Learnings & Rule Updates:**
 
 At the end of the review, summarize any patterns or learnings that emerged from the review (or from user feedback during the review process) that could be codified into rules. Ask the user if they would like to:
+
 - Update an existing rule file in `.cursor/rules/`
 - Create a new rule file for the pattern
 - Skip persisting the learning

.cursor/rules/FRONTEND_PATTERNS.mdc

@@ -68,6 +68,89 @@ const MyComponent = Shade<{ prop: string }>({
 - **Loading states**: Boolean observables for async operations
 - **Error states**: String observables for error messages
 
+## DOM Access in Shades Components
+
+### Avoid Global Document Queries
+
+Never use `document.querySelector()` in Shades components. It bypasses shadow DOM boundaries and may not find elements correctly.
+
+```typescript
+// ❌ Bad - using document.querySelector
+export const MyForm = Shade({
+  shadowDomName: 'my-form',
+  render: ({ useDisposable }) => {
+    const handleSubmit = async () => {
+      // This may fail due to shadow DOM encapsulation
+      const form = document.querySelector('form[data-my-form]') as HTMLFormElement
+      form?.reset()
+    }
+
+    return <form data-my-form>{/* Form content */}</form>
+  },
+})
+
+// ✅ Good - use element from Shades context
+export const MyForm = Shade({
+  shadowDomName: 'my-form',
+  render: ({ element, useDisposable }) => {
+    const handleSubmit = async () => {
+      // Use element.querySelector to query within component's shadow DOM
+      const form = element.querySelector<HTMLFormElement>('form[data-my-form]')
+      form?.reset()
+    }
+
+    return <form data-my-form>{/* Form content */}</form>
+  },
+})
+
+// ✅ Better - use state to trigger re-render instead of DOM manipulation
+export const MyForm = Shade({
+  shadowDomName: 'my-form',
+  render: ({ useDisposable, useObservable }) => {
+    const formKey = useDisposable('formKey', () => new ObservableValue(0))
+    const [key] = useObservable('formKeyValue', formKey)
+
+    const handleSubmit = async () => {
+      // Success - increment key to force form re-render with fresh state
+      formKey.setValue(key + 1)
+    }
+
+    return <form key={key}>{/* Form content with fresh state */}</form>
+  },
+})
+```
+
+### Accessing DOM Elements in Components
+
+When you need to access DOM elements within a Shades component:
+
+1. **Use `element` from render context** - This is the component's shadow root
+2. **Use `element.querySelector()`** - Queries within the shadow DOM
+3. **Prefer state-driven updates** - Use ObservableValue to trigger re-renders instead of direct DOM manipulation
+
+```typescript
+// ✅ Good - using element context for input focus
+export const SearchInput = Shade({
+  shadowDomName: 'search-input',
+  constructed: ({ element }) => {
+    // Safe to use element.querySelector after construction
+    element.querySelector<HTMLInputElement>('input[autofocus]')?.focus()
+  },
+  render: ({ element }) => {
+    const focusInput = () => {
+      element.querySelector<HTMLInputElement>('input')?.focus()
+    }
+
+    return (
+      <div>
+        <input type="text" autofocus />
+        <button onclick={focusInput}>Focus</button>
+      </div>
+    )
+  },
+})
+```
+
 ## Form Patterns
 
 ### Standard Form Structure

.cursor/rules/OBSERVABLE_STATE.md

@@ -189,6 +189,7 @@ export const BrokenFormComponent = Shade({
 ```
 
 **Rule of thumb:**
+
 - Use `useDisposable` alone when you only need to **set** values (e.g., in event handlers)
 - Pair with `useObservable` when you need the UI to **react** to value changes
 
@@ -563,6 +564,118 @@ export const LoginForm = Shade({
 });
 ```
 
+## Service Initialization and Disposal
+
+### Services with Event Listeners
+
+When services need to add event listeners (e.g., WebSocket messages), implement proper `init()` and `dispose()` methods:
+
+```typescript
+// ✅ Good - service with init/dispose pattern
+@Injectable({ lifetime: 'singleton' })
+export class LoggingService {
+  @Injected(WebsocketNotificationsService)
+  declare readonly websocketNotificationsService: WebsocketNotificationsService
+
+  private logEntryCache = new Cache({
+    capacity: 100,
+    load: async (id: string) => {
+      // Load logic
+    },
+  })
+
+  // Bind the handler to preserve 'this' context
+  private onMessage = ((messageData: WebsocketMessage) => {
+    if (messageData.type === 'log-entry-added') {
+      this.logEntryCache.setExplicitValue({
+        loadArgs: [messageData.logEntry.id],
+        value: { status: 'loaded', value: messageData.logEntry, updatedAt: new Date() },
+      })
+    }
+  }).bind(this)
+
+  public init() {
+    this.websocketNotificationsService.addListener('onMessage', this.onMessage)
+  }
+
+  public dispose() {
+    this.websocketNotificationsService.removeListener('onMessage', this.onMessage)
+  }
+
+  // Implement Symbol.dispose for automatic cleanup
+  public [Symbol.dispose]() {
+    this.dispose()
+  }
+}
+```
+
+### Service Initialization Patterns
+
+Services that require initialization should be initialized explicitly:
+
+```typescript
+// ✅ Good - explicit service initialization
+// In app setup or component
+const loggingService = injector.getInstance(LoggingService)
+loggingService.init()
+
+// Or use useDisposable for automatic disposal
+export const LogViewer = Shade({
+  shadowDomName: 'log-viewer',
+  render: ({ injector, useDisposable }) => {
+    const loggingService = useDisposable('loggingService', () => {
+      const service = injector.getInstance(LoggingService)
+      service.init()
+      return {
+        service,
+        [Symbol.dispose]: () => service.dispose(),
+      }
+    })
+
+    return <div>Log viewer content</div>
+  },
+})
+```
+
+### Avoiding Memory Leaks
+
+Always ensure listeners are removed when the service is no longer needed:
+
+```typescript
+// ❌ Bad - listener never removed
+@Injectable({ lifetime: 'singleton' })
+export class BrokenService {
+  @Injected(EventService)
+  declare readonly eventService: EventService
+
+  constructor() {
+    // Memory leak: listener added but never removed
+    this.eventService.addListener('event', (data) => {
+      this.handleEvent(data)
+    })
+  }
+}
+
+// ✅ Good - listener properly managed
+@Injectable({ lifetime: 'singleton' })
+export class ProperService {
+  @Injected(EventService)
+  declare readonly eventService: EventService
+
+  private handleEvent = ((data: EventData) => {
+    // Handle event
+  }).bind(this)
+
+  public init() {
+    this.eventService.addListener('event', this.handleEvent)
+  }
+
+  public [Symbol.dispose]() {
+    this.eventService.removeListener('event', this.handleEvent)
+  }
+}
+```
+
 ## Summary
 
 **Key Principles:**
@@ -577,6 +690,7 @@ export const LoginForm = Shade({
 8. **Manual subscriptions** must be disposed manually
 9. **Computed observables** for derived state
 10. **Symbol.dispose** for resource cleanup
+11. **init/dispose pattern** for services with event listeners
 
 **Observable State Checklist:**
 
@@ -589,6 +703,8 @@ export const LoginForm = Shade({
 - [ ] Symbol.dispose for service cleanup
 - [ ] No memory leaks (subscriptions cleaned up)
 - [ ] Type-safe observables
+- [ ] Services with listeners have init/dispose methods
+- [ ] Event handlers are bound to preserve `this` context
 
 **Common Patterns:**
 

.cursor/rules/TESTING_GUIDELINES.md

@@ -375,6 +375,155 @@ describe('DataService', () => {
 })
 ```
 
+## Backend Action Testing
+
+### Testing REST Actions
+
+Test backend actions with proper mocking of injector dependencies:
+
+```typescript
+// ✅ Good - backend action unit test
+import { Injector } from '@furystack/inject'
+import { StoreManager } from '@furystack/core'
+import { describe, expect, it, vi } from 'vitest'
+import { RegisterAction } from './register-action.js'
+
+describe('RegisterAction', () => {
+  const createTestInjector = () => {
+    const injector = new Injector()
+
+    // Mock store manager
+    const mockUserStore = {
+      get: vi.fn(),
+      add: vi.fn(),
+      remove: vi.fn(),
+    }
+
+    const mockCredentialStore = {
+      add: vi.fn(),
+    }
+
+    injector.setExplicitInstance(
+      {
+        getStoreFor: vi.fn((model) => {
+          if (model.name === 'User') return mockUserStore
+          if (model.name === 'PasswordCredential') return mockCredentialStore
+          throw new Error(`Unknown model: ${model.name}`)
+        }),
+      } as unknown as StoreManager,
+      StoreManager,
+    )
+
+    return { injector, mockUserStore, mockCredentialStore }
+  }
+
+  it('should create a new user when username does not exist', async () => {
+    const { injector, mockUserStore, mockCredentialStore } = createTestInjector()
+
+    mockUserStore.get.mockResolvedValue(null) // User doesn't exist
+    mockUserStore.add.mockResolvedValue({ username: '[email protected]', roles: [] })
+    mockCredentialStore.add.mockResolvedValue({})
+
+    const result = await RegisterAction({
+      injector,
+      getBody: async () => ({ username: '[email protected]', password: 'password123' }),
+      response: {} as Response,
+      request: {} as Request,
+    })
+
+    expect(mockUserStore.add).toHaveBeenCalledWith(expect.objectContaining({ username: '[email protected]' }))
+  })
+
+  it('should throw 409 when user already exists', async () => {
+    const { injector, mockUserStore } = createTestInjector()
+
+    mockUserStore.get.mockResolvedValue({ username: '[email protected]' })
+
+    await expect(
+      RegisterAction({
+        injector,
+        getBody: async () => ({ username: '[email protected]', password: 'password123' }),
+        response: {} as Response,
+        request: {} as Request,
+      }),
+    ).rejects.toThrow('User already exists')
+  })
+})
+```
+
+### Action Test Patterns
+
+When testing backend actions:
+
+1. **Mock StoreManager** - Provide mock stores for each entity type
+2. **Mock Authentication** - Use `HttpUserContext` for authenticated actions
+3. **Test error cases** - Verify proper RequestError codes (400, 401, 404, 409, 500)
+4. **Test cleanup logic** - Verify partial state is cleaned up on failure
+
+```typescript
+// ✅ Good - testing authenticated action
+import { getCurrentUser } from '@furystack/core'
+
+vi.mock('@furystack/core', () => ({
+  getCurrentUser: vi.fn(),
+}))
+
+describe('PasswordResetAction', () => {
+  it('should throw 401 when user is not authenticated', async () => {
+    vi.mocked(getCurrentUser).mockResolvedValue(null)
+
+    await expect(PasswordResetAction({ injector, getBody: async () => ({}) })).rejects.toThrow('User not authenticated')
+  })
+
+  it('should throw 400 when current password is incorrect', async () => {
+    vi.mocked(getCurrentUser).mockResolvedValue({ username: '[email protected]' })
+    mockAuthenticator.setPasswordForUser.mockRejectedValue(new UnauthenticatedError())
+
+    await expect(
+      PasswordResetAction({
+        injector,
+        getBody: async () => ({ currentPassword: 'wrong', newPassword: 'new123' }),
+      }),
+    ).rejects.toThrow('Current password is incorrect')
+  })
+})
+```
+
+### RequestError Testing
+
+Test that actions throw appropriate HTTP error codes:
+
+```typescript
+// ✅ Good - testing RequestError codes
+import { RequestError } from '@furystack/rest'
+
+it('should throw 409 for duplicate resource', async () => {
+  // Setup duplicate condition
+  mockStore.find.mockResolvedValue({ count: 1 })
+
+  try {
+    await CreateResourceAction({ injector, getBody: async () => ({}) })
+    fail('Expected RequestError to be thrown')
+  } catch (error) {
+    expect(error).toBeInstanceOf(RequestError)
+    expect((error as RequestError).responseCode).toBe(409)
+  }
+})
+
+it('should throw 400 for validation errors', async () => {
+  try {
+    await CreateResourceAction({
+      injector,
+      getBody: async () => ({ invalidField: true }),
+    })
+    fail('Expected RequestError to be thrown')
+  } catch (error) {
+    expect(error).toBeInstanceOf(RequestError)
+    expect((error as RequestError).responseCode).toBe(400)
+  }
+})
+```
+
 ## Test Organization
 
 ### Co-location