@flexsurfer/reflex 0.1.23 → 0.1.25

package/README.md

@@ -32,11 +32,39 @@ After many years of building applications with re-frame in the ClojureScript wor
 - [Step-by-Step Tutorial](https://reflex.js.org/docs/quick-start.html)
 - [Best Practices](https://reflex.js.org/docs/api-reference.html)
 - [API Reference](https://reflex.js.org/docs/best-practices.html)
+- [AI Context (llms.txt)](./llms.txt) - Compact guide for AI-assisted Reflex project scaffolding and state architecture
 - [re-frame Documentation](https://day8.github.io/re-frame/re-frame/) - The original and comprehensive guide to understanding the philosophy and patterns
 
 - Examples
   - [TodoMVC](https://github.com/flexsurfer/reflex/tree/main/examples/todomvc) - Classic todo app implementation showcasing core reflex patterns
-  - [Einbürgerungstest](https://github.com/flexsurfer/einburgerungstest/) - German citizenship test app built with reflex ([Live Demo](https://www.ebtest.org/))
+  - [Einbürgerungstest](https://github.com/flexsurfer/einburgerungstest/) - Cross-platform web/mobile app built with reflex ([Live Demo](https://www.ebtest.org/))
+  - [StarRupture Planner](https://github.com/flexsurfer/starrupture-planner) - Production planning tool built with reflex ([Live Demo](https://www.starrupture-planner.com/))
+
+## 🤖 Using with AI Assistants
+
+Reflex ships an [`llms.txt`](./llms.txt) file — a compact, AI-readable guide covering state architecture, event/effect/subscription patterns, and code generation rules. Point your AI tool at it so it generates idiomatic Reflex code from the start.
+
+**Claude Code** — add to `CLAUDE.md` in your project root:
+```bash
+curl -o CLAUDE.md https://raw.githubusercontent.com/flexsurfer/reflex/main/llms.txt
+```
+
+**Codex (OpenAI)** — add to `AGENTS.md` in your project root:
+```bash
+curl -o AGENTS.md https://raw.githubusercontent.com/flexsurfer/reflex/main/llms.txt
+```
+Codex reads project instructions from `AGENTS.md`, so this gives it Reflex-specific architecture and code generation rules for your repo.
+
+**Cursor** — create `.cursor/rules/reflex.mdc` and paste the contents, or reference via project rules.
+
+**GitHub Copilot** — add to `.github/copilot-instructions.md`:
+```bash
+curl -o .github/copilot-instructions.md https://raw.githubusercontent.com/flexsurfer/reflex/main/llms.txt
+```
+
+**ChatGPT / Claude.ai Projects** — upload `llms.txt` from your `node_modules/@flexsurfer/reflex/` as a project file, or paste the raw URL into the conversation.
+
+The file is also included in the npm package, so after installing Reflex you can find it at `node_modules/@flexsurfer/reflex/llms.txt`.
 
 ## 🤝 Contributing
 

package/dist/index.cjs

@@ -127,12 +127,16 @@ function clearHandlers(kind, id) {
     for (const k in kindToIdToHandler) {
       kindToIdToHandler[k] = {};
     }
+    clearRootSubSources();
   } else if (id == null) {
     if (!(kind in kindToIdToHandler)) {
       consoleLog("error", `[reflex] Unknown kind: ${kind}`);
       return;
     }
     kindToIdToHandler[kind] = {};
+    if (kind === "sub") {
+      clearRootSubSources();
+    }
   } else {
     if (kindToIdToHandler[kind][id]) {
       delete kindToIdToHandler[kind][id];
@@ -161,6 +165,16 @@ function clearReactions(id) {
     reactionsRegistry.delete(id);
   }
 }
+var rootSubIdBySource = /* @__PURE__ */ new Map();
+function setRootSubSource(subId, sourceKey) {
+  rootSubIdBySource.set(sourceKey, subId);
+}
+function getRootSubIdBySource(sourceKey) {
+  return rootSubIdBySource.get(sourceKey);
+}
+function clearRootSubSources() {
+  rootSubIdBySource.clear();
+}
 function clearSubs() {
   clearReactions();
   clearHandlers("sub");
@@ -230,7 +244,14 @@ function updateAppDbWithPatches(newDb, patches) {
       const pathSegments = patch.path;
       if (pathSegments.length > 0) {
         const rootKey = pathSegments[0];
-        const subVectorKey = JSON.stringify([rootKey]);
+        if (typeof rootKey !== "string") {
+          continue;
+        }
+        const subId = getRootSubIdBySource(rootKey);
+        if (!subId) {
+          continue;
+        }
+        const subVectorKey = JSON.stringify([subId]);
         const reaction = getReaction(subVectorKey);
         if (reaction) {
           if (!reaction.isRoot) {
@@ -1089,16 +1110,23 @@ var Reaction = class _Reaction {
 // src/subs.ts
 var KIND4 = "sub";
 var KIND_DEPS = "subDeps";
+function registerRootSub(id, sourceKey) {
+  const conflictingSubId = getRootSubIdBySource(sourceKey);
+  if (conflictingSubId && conflictingSubId !== id) {
+    consoleLog("error", `[reflex] Subscription with id '${id}' will be overridden. Root key '${sourceKey}' is already used by subscription '${conflictingSubId}'.`);
+  }
+  setRootSubSource(id, sourceKey);
+  registerHandler(KIND4, id, () => getAppDb()[sourceKey]);
+  registerHandler(KIND_DEPS, id, () => []);
+}
 function regSub(id, computeFn, depsFn, config) {
   if (hasHandler(KIND4, id)) {
     consoleLog("warn", `[reflex] Overriding. Subscription '${id}' already registered.`);
   }
   if (!computeFn) {
-    registerHandler(KIND4, id, () => getAppDb()[id]);
-    registerHandler(KIND_DEPS, id, () => []);
+    registerRootSub(id, id);
   } else if (typeof computeFn === "string") {
-    registerHandler(KIND4, id, () => getAppDb()[computeFn]);
-    registerHandler(KIND_DEPS, id, () => []);
+    registerRootSub(id, computeFn);
   } else {
     if (!depsFn) {
       consoleLog("error", `[reflex] Subscription '${id}' has computeFn but missing depsFn. Computed subscriptions must specify their dependencies.`);

package/dist/index.mjs

@@ -49,12 +49,16 @@ function clearHandlers(kind, id) {
     for (const k in kindToIdToHandler) {
       kindToIdToHandler[k] = {};
     }
+    clearRootSubSources();
   } else if (id == null) {
     if (!(kind in kindToIdToHandler)) {
       consoleLog("error", `[reflex] Unknown kind: ${kind}`);
       return;
     }
     kindToIdToHandler[kind] = {};
+    if (kind === "sub") {
+      clearRootSubSources();
+    }
   } else {
     if (kindToIdToHandler[kind][id]) {
       delete kindToIdToHandler[kind][id];
@@ -83,6 +87,16 @@ function clearReactions(id) {
     reactionsRegistry.delete(id);
   }
 }
+var rootSubIdBySource = /* @__PURE__ */ new Map();
+function setRootSubSource(subId, sourceKey) {
+  rootSubIdBySource.set(sourceKey, subId);
+}
+function getRootSubIdBySource(sourceKey) {
+  return rootSubIdBySource.get(sourceKey);
+}
+function clearRootSubSources() {
+  rootSubIdBySource.clear();
+}
 function clearSubs() {
   clearReactions();
   clearHandlers("sub");
@@ -152,7 +166,14 @@ function updateAppDbWithPatches(newDb, patches) {
       const pathSegments = patch.path;
       if (pathSegments.length > 0) {
         const rootKey = pathSegments[0];
-        const subVectorKey = JSON.stringify([rootKey]);
+        if (typeof rootKey !== "string") {
+          continue;
+        }
+        const subId = getRootSubIdBySource(rootKey);
+        if (!subId) {
+          continue;
+        }
+        const subVectorKey = JSON.stringify([subId]);
         const reaction = getReaction(subVectorKey);
         if (reaction) {
           if (!reaction.isRoot) {
@@ -1011,16 +1032,23 @@ var Reaction = class _Reaction {
 // src/subs.ts
 var KIND4 = "sub";
 var KIND_DEPS = "subDeps";
+function registerRootSub(id, sourceKey) {
+  const conflictingSubId = getRootSubIdBySource(sourceKey);
+  if (conflictingSubId && conflictingSubId !== id) {
+    consoleLog("error", `[reflex] Subscription with id '${id}' will be overridden. Root key '${sourceKey}' is already used by subscription '${conflictingSubId}'.`);
+  }
+  setRootSubSource(id, sourceKey);
+  registerHandler(KIND4, id, () => getAppDb()[sourceKey]);
+  registerHandler(KIND_DEPS, id, () => []);
+}
 function regSub(id, computeFn, depsFn, config) {
   if (hasHandler(KIND4, id)) {
     consoleLog("warn", `[reflex] Overriding. Subscription '${id}' already registered.`);
   }
   if (!computeFn) {
-    registerHandler(KIND4, id, () => getAppDb()[id]);
-    registerHandler(KIND_DEPS, id, () => []);
+    registerRootSub(id, id);
   } else if (typeof computeFn === "string") {
-    registerHandler(KIND4, id, () => getAppDb()[computeFn]);
-    registerHandler(KIND_DEPS, id, () => []);
+    registerRootSub(id, computeFn);
   } else {
     if (!depsFn) {
       consoleLog("error", `[reflex] Subscription '${id}' has computeFn but missing depsFn. Computed subscriptions must specify their dependencies.`);

package/llms.txt

@@ -0,0 +1,186 @@
+## 0) Reflex Quick Info
+
+- Reflex is a React state-management library inspired by ClojureScript re-frame (event-driven updates, subscriptions for derived data, effects/coeffects for side effects).
+- Install:
+  - Runtime: `npm i @flexsurfer/reflex`
+  - Devtools (dev only): `npm i -D @flexsurfer/reflex-devtools`
+- Docs:
+  - Main docs: [reflex.js.org/docs](https://reflex.js.org/docs)
+  - Best practices: [reflex.js.org/docs/best-practices.html](https://reflex.js.org/docs/best-practices.html)
+  - Packages: [@flexsurfer/reflex](https://www.npmjs.com/package/@flexsurfer/reflex), [@flexsurfer/reflex-devtools](https://www.npmjs.com/package/@flexsurfer/reflex-devtools)
+
+## 1) State Architecture
+
+Use this baseline structure:
+
+```text
+src/state/
+  db.ts
+  event-ids.ts
+  events.ts
+  effect-ids.ts
+  effects.ts
+  sub-ids.ts
+  subs.ts
+```
+
+Rules:
+- Keep IDs centralized in `event-ids.ts`, `effect-ids.ts`, `sub-ids.ts`.
+- Keep init in `db.ts` (`initAppDb(...)`).
+- Register events/effects/subscriptions via side-effect imports in app bootstrap (`main.tsx` style).
+- If `events.ts` or `subs.ts` grows too large, split by feature, keep shared/global state separate.
+
+## 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.
+- If using `Map`/`Set` in DB, call `enableMapSet()` before `initAppDb`.
+
+## 3) Events `regEvent`
+
+- Events must be synchronous and focused on state transitions.
+- Events should read all required data from `draftDb` (or via coeffects) — never rely on callers passing subscription-derived state; dispatch calls from views should only carry user intent (IDs, input values, flags).
+- Validate inputs and guard clauses first; return early on invalid state.
+- Mutate only required fields on `draftDb`.
+- Avoid unnecessary object/array recreation (`{...obj}`, `[...arr]`) when no actual change is needed.
+- Never perform async/API/localStorage work directly in events.
+- Return effect tuples for side effects.
+- When sending mutated draft data to effects, always use `current(...)`.
+- Prefer deterministic coeffects (time/id/random/env) instead of direct globals for testability.
+
+Event naming:
+- Keep exported constant keys in `UPPER_SNAKE_CASE`.
+- Use namespaced string values: `feature/action` (example: `bases/create`).
+- Keep key and value aligned:
+  - `BASES_CREATE` -> `bases/create`
+  - `PRODUCTION_PLAN_ADD_BUILDINGS_TO_BASE` -> `production_plan/add_buildings_to_base`
+
+## 4) Effects and Coeffects
+
+- Put all I/O here: localStorage, HTTP, timers, analytics, navigation.
+- Effects should be small, defensive, and fail-soft (log, do not crash app state flow).
+
+## 5) Subscriptions `regSub`
+
+- Define root subscriptions first `regSub(id, "pathKey")`.
+- Build derived subscriptions from other subscriptions only.
+- Use parameterized subscriptions for by-id and section-specific queries.
+- Keep subscriptions deterministic and lightweight.
+- Subscriptions must return data shaped and ready for direct view consumption — all filtering, sorting, formatting, and joining should happen in the subscription layer, not in React components.
+- Move heavy computations to events (precompute once, read many); avoid repeated expensive derivations in hot subscriptions.
+
+## 6) React Component Contract
+
+- Components should only:
+  - 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
+- 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
+  - UI-only toggles scoped to one component (hover/open/focus)
+  - refs, DOM measurement, animation lifecycle
+- Do not mirror Reflex global state in `useState`/`useReducer`.
+- If state is shared, persisted, or business-relevant, keep it in Reflex DB via events/subscriptions.
+- Keep `useEffect` thin in components; business side effects belong in Reflex effects/coeffects.
+- 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
+
+For every new feature:
+- Event tests: mutation correctness + emitted effect tuples.
+- Subscription tests: derived outputs from fixed state fixtures.
+
+## 8) AI Generation Checklist
+
+Before finalizing generated code:
+- IDs added/updated in all relevant `*-ids.ts` files.
+- Event namespaced and descriptive.
+- Side effects isolated to effects/coeffects.
+- `current(...)` used when passing draft-derived data to effects.
+- No unnecessary object/array recreation in events.
+- Expensive work not placed in frequently re-run subscriptions.
+- Subscriptions return view-ready data; components do not reshape subscription output.
+- 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)
+
+```ts
+import {
+  initAppDb,
+  regSub,
+  regEvent,
+  regEffect,
+  regCoeffect,
+  current,
+  dispatch,
+  useSubscription,
+} from '@flexsurfer/reflex';
+
+// event-ids.ts
+export const EVENT_IDS = {
+  APP_INIT: 'app/init',
+  TODOS_ADD: 'todos/add',
+} as const;
+
+// effect-ids.ts
+export const EFFECT_IDS = {
+  GET_TODOS: 'storage/get_todos',
+  SET_TODOS: 'storage/set_todos',
+} as const;
+
+// sub-ids.ts
+export const SUB_IDS = {
+  TODOS_LIST: 'todos/list',       // root sub
+  TODOS_OPEN_COUNT: 'todos/open_count', // computed sub
+} as const;
+
+// db.ts
+type Todo = { id: string; text: string; done: boolean };
+initAppDb({ todos: [] as Todo[] });
+
+// effects.ts
+regEffect(EFFECT_IDS.SET_TODOS, (todos: Todo[]) => {
+  localStorage.setItem('todos', JSON.stringify(todos));
+});
+
+regCoeffect(EFFECT_IDS.GET_TODOS, (coeffects) => {
+  const raw = localStorage.getItem('todos');
+  coeffects.localStoreTodos = raw ? (JSON.parse(raw) as Todo[]) : [];
+  return coeffects;
+});
+
+// events.ts
+regEvent(
+  EVENT_IDS.APP_INIT,
+  ({ draftDb, localStoreTodos }) => {
+    draftDb.todos = Array.isArray(localStoreTodos) ? localStoreTodos : [];
+  },
+  [[EFFECT_IDS.GET_TODOS]]
+);
+
+regEvent(EVENT_IDS.TODOS_ADD, ({ draftDb }, text: string) => {
+  const clean = text.trim();
+  if (!clean) return;
+  draftDb.todos.push({ id: `todo_${Date.now()}`, text: clean, done: false });
+  return [[EFFECT_IDS.SET_TODOS, current(draftDb.todos)]];
+});
+
+// subs.ts
+regSub(SUB_IDS.TODOS_LIST, 'todos'); // root sub
+
+regSub(
+  SUB_IDS.TODOS_OPEN_COUNT,          // computed sub from root sub
+  (todos: Todo[]) => todos.filter((t) => !t.done).length,
+  () => [[SUB_IDS.TODOS_LIST]]
+);
+
+// Usage example (React):
+// const todos = useSubscription([SUB_IDS.TODOS_LIST]);
+// const openCount = useSubscription([SUB_IDS.TODOS_OPEN_COUNT]);
+// dispatch([EVENT_IDS.APP_INIT]);
+// dispatch([EVENT_IDS.TODOS_ADD, 'Buy milk']);
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flexsurfer/reflex",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -23,7 +23,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "llms.txt"
   ],
   "scripts": {
     "build": "tsup",