Refine llms.txt with detailed guidelines for UI state management, event handling, and devtools setup. Introduce a new section on testing events and subscriptions, emphasizing best practices for handler extraction and mock inputs.

Author: flexsurfer

llms.txt

@@ -33,8 +33,7 @@ Rules:
 ## 2) State Shape
 
 - Grow horizontally (new top-level feature keys), avoid deep nesting.
-- Normalize entity-like data (`byId` maps + id arrays) for fast lookup and simpler updates.
-- Keep UI state explicit and separate from domain entities.
+- Keep UI state explicit and separate from domain entities. Use a plain prefix on field names to group by domain (e.g. `uiSidebarOpen`, `uiSelectedTab`, `uiModalVisible` for UI state; `todosMap`, `todosFilter` for domain state). Avoid separators like `/` or `.` in field names — flat `camelCase` with a domain prefix keeps keys simple, grep-friendly, and avoids issues with object path accessors.
 - If using `Map`/`Set` in DB, call `enableMapSet()` before `initAppDb`.
 
 ## 3) Events `regEvent`
@@ -76,6 +75,8 @@ Event naming:
   - subscribe to minimal required data
   - dispatch events on user intent (pass only user-provided values — e.g. input text, selected id — never forward subscription data back through dispatch; the event handler should read everything it needs from the DB itself)
   - render UI
+- Always pass the component name as the second argument to `useSubscription` for devtools tracing:
+  `const todos = useSubscription<Todo[]>([SUB_IDS.TODOS], 'TodoList');`
 - Never transform, filter, sort, or reshape subscription data inside a component — if the view needs a different shape, create a dedicated subscription that returns it ready to render.
 - Use direct React hooks only for local/ephemeral component concerns:
   - temporary form/input draft state before dispatch
@@ -87,13 +88,129 @@ Event naming:
 - Do not place business rules/validation pipelines in component handlers.
 - Avoid over-subscription (row/item components should not subscribe to full collections).
 
-## 7) Test Minimum
+## 7) Devtools Setup
+
+Install devtools as a dev dependency:
+
+```bash
+npm i -D @flexsurfer/reflex-devtools
+```
+
+Enable in your app entry point (`main.tsx`) before dispatching any events:
+
+```ts
+import { dispatch, enableTracing } from '@flexsurfer/reflex';
+import { enableDevtools } from '@flexsurfer/reflex-devtools';
+
+enableTracing();   // required — turns on the trace pipeline that devtools reads
+enableDevtools();  // opens the devtools connection
+
+dispatch([EVENT_IDS.APP_INIT]);
+```
+
+`enableTracing()` activates internal trace collection for events, subscriptions, and renders. `enableDevtools()` hooks into those traces and exposes them to the devtools UI / MCP server. Both calls are cheap no-ops in production when tree-shaken behind a `process.env.NODE_ENV` guard.
+
+If your app uses Vite with local source aliases (monorepo / examples), make sure reflex-devtools resolves the same Reflex instance:
+
+```ts
+// vite.config.ts
+resolve: {
+  alias: {
+    '@flexsurfer/reflex': path.resolve(__dirname, '../../src')
+  }
+},
+optimizeDeps: {
+  exclude: ['@flexsurfer/reflex-devtools']
+}
+```
+
+## 8) Test Minimum
 
 For every new feature:
 - Event tests: mutation correctness + emitted effect tuples.
 - Subscription tests: derived outputs from fixed state fixtures.
 
-## 8) AI Generation Checklist
+Events and subscriptions are pure functions — test them by extracting the handler with `getHandler` and calling it directly with mock inputs.
+
+### Testing Events
+
+Use `getHandler('event', EVENT_ID)` to get the raw handler. Build a mock `coeffects` object with `draftDb` (and any injected coeffects), call the handler, then assert mutations on `draftDb` and the returned effect tuples.
+
+```ts
+import { getHandler } from '@flexsurfer/reflex';
+import type { EventHandler, CoEffects } from '@flexsurfer/reflex';
+import './events'; // side-effect import registers handlers
+
+it('ADD_TODO should add a todo and persist', () => {
+  const handler = getHandler('event', EVENT_IDS.ADD_TODO) as EventHandler;
+
+  const mockDB = { todos: [], showing: 'all' };
+  const coeffects = {
+    event: [EVENT_IDS.ADD_TODO, 'Buy milk'],
+    draftDb: mockDB,
+    now: 12345,
+  } as CoEffects;
+
+  const effects = handler(coeffects, 'Buy milk');
+
+  // Assert state mutation
+  expect(mockDB.todos).toHaveLength(1);
+  expect(mockDB.todos[0]).toEqual({ id: 12345, title: 'Buy milk', done: false });
+
+  // Assert emitted effects
+  expect(effects).toEqual([[EFFECT_IDS.SET_TODOS, mockDB.todos]]);
+});
+
+it('ADD_TODO should ignore empty input', () => {
+  const handler = getHandler('event', EVENT_IDS.ADD_TODO) as EventHandler;
+
+  const mockDB = { todos: [], showing: 'all' };
+  const coeffects = { event: [EVENT_IDS.ADD_TODO, '  '], draftDb: mockDB, now: 1 } as CoEffects;
+
+  const effects = handler(coeffects, '  ');
+
+  expect(mockDB.todos).toHaveLength(0);
+  expect(effects).toBeUndefined();
+});
+```
+
+### Testing Subscriptions
+
+Root subscriptions: call `initAppDb(mockDB)` then call `handler()` with no arguments.
+Computed subscriptions: call `handler(inputFromParentSub1, inputFromParentSub2, ...)` directly — the handler receives its parent subscription values as positional arguments.
+Dependency checks: use `getHandler('subDeps', SUB_ID)` to verify the subscription's input signals.
+
+```ts
+import { getHandler, initAppDb } from '@flexsurfer/reflex';
+import type { SubHandler, SubDepsHandler } from '@flexsurfer/reflex';
+import './subs';
+
+it('TODOS root sub returns todos from db', () => {
+  const handler = getHandler('sub', SUB_IDS.TODOS) as SubHandler;
+  const mockDB = { todos: [{ id: 1, title: 'Test', done: false }] };
+  initAppDb(mockDB);
+
+  expect(handler()).toBe(mockDB.todos);
+});
+
+it('OPEN_COUNT computed sub counts active todos', () => {
+  const handler = getHandler('sub', SUB_IDS.TODOS_OPEN_COUNT) as SubHandler;
+  const todos = [
+    { id: 1, title: 'A', done: false },
+    { id: 2, title: 'B', done: true },
+    { id: 3, title: 'C', done: false },
+  ];
+
+  expect(handler(todos)).toBe(2);
+});
+
+it('OPEN_COUNT has correct dependency chain', () => {
+  const depsHandler = getHandler('subDeps', SUB_IDS.TODOS_OPEN_COUNT) as SubDepsHandler;
+  expect(depsHandler()).toEqual([[SUB_IDS.TODOS]]);
+});
+```
+
+## 9) AI Generation Checklist
 
 Before finalizing generated code:
 - IDs added/updated in all relevant `*-ids.ts` files.
@@ -106,7 +223,7 @@ Before finalizing generated code:
 - Dispatch calls from components pass only user intent, not subscription data; events read from DB.
 - Tests added for new event/subscription behavior.
 
-## 9) Starter Skeleton (copy pattern)
+## 10) Starter Skeleton (copy pattern)
 
 ```ts
 import {
@@ -179,8 +296,8 @@ regSub(
 );
 
 // Usage example (React):
-// const todos = useSubscription([SUB_IDS.TODOS_LIST]);
-// const openCount = useSubscription([SUB_IDS.TODOS_OPEN_COUNT]);
+// const todos = useSubscription([SUB_IDS.TODOS_LIST], 'TodoList');
+// const openCount = useSubscription([SUB_IDS.TODOS_OPEN_COUNT], 'TodoFooter');
 // dispatch([EVENT_IDS.APP_INIT]);
 // dispatch([EVENT_IDS.TODOS_ADD, 'Buy milk']);
 ```