@techninja/clearstack 0.3.16 → 0.3.19

package/templates/shared/docs/clearstack/JSDOC_TYPING.md

@@ -13,8 +13,8 @@
 TypeScript's `tsc` compiler validates JSDoc annotations via `--checkJs`,
 giving us compile-time type checking without a build step.
 
-A `jsconfig.json` at the project root enables `checkJs: true`. Running
-`npm run typecheck` invokes `tsc --project jsconfig.json` which:
+A `jsconfig.json` at `.configs/jsconfig.json` enables `checkJs: true` for
+frontend code. Running `npm run spec types` invokes `tsc` against it.
 
 1. Reads all `.js` files in `src/` and `scripts/`
 2. Parses JSDoc annotations as type information
@@ -24,6 +24,27 @@ A `jsconfig.json` at the project root enables `checkJs: true`. Running
 This means `@typedef`, `@type`, `@param`, and `@returns` are not just
 documentation — they are **enforced types**.
 
+### Multiple Type Configs
+
+The spec checker auto-discovers `jsconfig.json` files in subdirectories.
+If your project has a separate backend (e.g. `api/`) with its own
+dependencies and module resolution, add `api/jsconfig.json`:
+
+```
+your-project/
+├── .configs/jsconfig.json    ← frontend (src/, scripts/)
+└── api/jsconfig.json         ← backend (api/, auto-discovered)
+```
+
+```bash
+npm run spec types            # runs all discovered jsconfigs
+npm run spec types frontend   # just .configs/jsconfig.json
+npm run spec types api        # just api/jsconfig.json
+```
+
+The child key matches the directory name. Both must pass for
+`npm run spec all` to succeed.
+
 ---
 
 ## Component Properties
@@ -151,4 +172,4 @@ list: async (params) => {
 - Keep JSDoc blocks to 3–5 lines. No novels.
 - Use `/** @type {any} */ (expr)` for framework type limitations (e.g.
   `store.pending()` on array results) — document why with a comment.
-- Run `npm run typecheck` before committing. Zero errors required.
+- Run `npm run spec types` before committing. Zero errors required.

package/templates/shared/docs/clearstack/QUICKSTART.md

@@ -137,7 +137,7 @@ npm run spec lint      # ESLint + Stylelint + Markdown
 npm run spec lint es   # ESLint only
 npm run spec format    # Prettier
 npm run spec imports   # import map aliases
-npm run spec types     # JSDoc type validation
+npm run spec types     # JSDoc types (all jsconfigs)
 npm run spec audit     # security audit
 npm test               # Node + browser tests
 ```
@@ -172,7 +172,7 @@ spec all → lint + format + code + docs + imports + types + audit
 | Install dependencies  | `npm install`                              |
 | Start dev server      | `npm run dev`                              |
 | Lint + format         | `npm run spec lint && npm run spec format` |
-| Type check            | `npm run typecheck`                        |
+| Type check            | `npm run spec types`                       |
 | Run tests             | `npm test`                                 |
 | Full spec check       | `npm run spec`                             |
 | Update spec + configs | `npm run spec update`                      |

package/templates/shared/docs/clearstack/STATE_AND_ROUTING.md

@@ -253,6 +253,43 @@ This applies to any property with `value: []` and an async `connect`.
 The `connect` callback sets the value and calls `invalidate()`, but the
 first render happens before that resolves.
 
+#### Async Init with Child Component Props
+
+When a parent loads data during `connect` and passes it to a child via
+template props, the child may never see the change. Hybrids' change
+detection requires observing old → new. If the prop is set before the
+child mounts, there's no "old" value to compare against.
+
+```javascript
+// ❌ BAD — resultCount set during connect, before child mounts
+_init: {
+  value: false,
+  connect: (host, _key, invalidate) => {
+    loadData(host).then(() => {
+      host.resultCount = 14;
+      invalidate(); // child mounts with 14, never sees a change
+    });
+  },
+},
+```
+
+The fix: defer the prop update to after the first render frame so the
+child is mounted and can observe the transition:
+
+```javascript
+// ✅ GOOD — child mounts with default (0), then sees 0 → 14
+connect: (host, _key, invalidate) => {
+  loadData(host).then(() => {
+    invalidate();
+    requestAnimationFrame(() => { host.resultCount = loadedCount; });
+  });
+},
+```
+
+Pre-populate external caches during `loadData` so the child has data
+ready when the deferred update triggers. The 0 → 14 transition happens
+within a single frame — no flicker.
+
 ---
 
 ## Routing
@@ -410,37 +447,16 @@ For live data updates, the backend pushes events via **Server-Sent Events
 
 ### Frontend: SSE Listener
 
-Lives in `src/utils/realtimeSync.js`:
-
-```javascript
-import { store } from 'hybrids';
-
-export function connectRealtime(url, modelMap) {
-  const source = new EventSource(url);
-
-  source.addEventListener('update', (event) => {
-    const { type } = JSON.parse(event.data);
-    const Model = modelMap[type];
-    if (Model) store.clear(Model); // full clear triggers re-fetch
-  });
-
-  source.addEventListener('error', () => {
-    source.close();
-    setTimeout(() => connectRealtime(url, modelMap), 5000);
-  });
-
-  return () => source.close();
-}
-```
+`src/utils/realtimeSync.js` connects to the SSE endpoint, listens for
+`update` events, and calls `store.clear(Model)` to invalidate the cache.
+Any component bound via `store()` re-fetches automatically.
 
-`store.clear(Model)` fully invalidates the cache for that model type.
-Any component bound to the model via `store()` will automatically re-fetch
-from the API. This is the mechanism that makes multi-user realtime work —
-when user A creates a task, user B's task list updates automatically.
+The listener reconnects on error (5s delay) and returns a disconnect
+function for cleanup in the router shell's `connect` descriptor.
 
-For the local user, form submit handlers also call `store.clear(Model)`
-immediately after a successful save. The SSE event that follows is
-redundant for the local user but ensures other connected clients update.
+`store.clear(Model)` is also called by form submit handlers after a
+successful save. The SSE event that follows is redundant for the local
+user but ensures other connected clients update.
 
 ### Backend: SSE Endpoint
 
@@ -449,31 +465,20 @@ contract.
 
 ### Wiring It Up
 
-In the router shell's `connect` descriptor:
+In the router shell, use a `connect` descriptor to start SSE and return
+the disconnect function. Map entity types to store models:
 
 ```javascript
-import { connectRealtime } from '../utils/realtimeSync.js';
-import UserModel from '../store/UserModel.js';
-
-export default define({
-  tag: 'app-router',
-  stack: router(HomeView, { url: '/' }),
-  connection: {
-    value: undefined,
-    connect(host) {
-      const disconnect = connectRealtime('/api/events', {
-        user: UserModel,
-      });
-      return disconnect;
-    },
+connection: {
+  value: undefined,
+  connect(host) {
+    return connectRealtime('/api/events', { user: UserModel });
   },
-  render: ({ stack }) => html` <template layout="column height::100vh">${stack}</template> `,
-});
+},
 ```
 
-When the backend sends `{ type: "user", id: "42" }` over SSE, the store
-cache for `UserModel` is cleared, and any component displaying that user
-re-fetches automatically.
+When the backend sends `{ type: "user" }` over SSE, the store cache for
+`UserModel` is cleared and any bound component re-fetches automatically.
 
 ### Debouncing Batch Operations
 

package/templates/shared/docs/clearstack/TESTING.md

@@ -169,36 +169,31 @@ describe('GET /api/users?schema=true', () => {
 
 ### Component Tests (browser)
 
-Using `@web/test-runner` with `@open-wc/testing`:
+Using `@web/test-runner` with `@open-wc/testing`. Since all components
+use light DOM (`shadow: false`), query the host element directly — not
+`shadowRoot`:
 
 ```javascript
 // src/components/atoms/app-button/app-button.test.js
-import { fixture, html, expect } from '@open-wc/testing';
+import { fixture, expect } from '@open-wc/testing';
 import './app-button.js';
 
 describe('app-button', () => {
   it('renders with label', async () => {
-    const el = await fixture(html`<app-button label="Click me"></app-button>`);
-    const button = el.shadowRoot.querySelector('button');
+    const el = await fixture(`<app-button label="Click me"></app-button>`);
+    await new Promise((r) => requestAnimationFrame(r));
+    const button = el.querySelector('button');
     expect(button.textContent).to.contain('Click me');
   });
+});
+```
 
-  it('reflects disabled attribute', async () => {
-    const el = await fixture(html`<app-button disabled></app-button>`);
-    const button = el.shadowRoot.querySelector('button');
-    expect(button.hasAttribute('disabled')).to.be.true;
-  });
+The `requestAnimationFrame` wait gives hybrids time to complete its
+render cycle. For components with async store data, use a longer timeout:
 
-  it('dispatches click event', async () => {
-    const el = await fixture(html`<app-button label="Go"></app-button>`);
-    let clicked = false;
-    el.addEventListener('click', () => {
-      clicked = true;
-    });
-    el.shadowRoot.querySelector('button').click();
-    expect(clicked).to.be.true;
-  });
-});
+```javascript
+const tick = () => new Promise((r) => setTimeout(r, 100));
+await tick(); // after fixture, before assertions
 ```
 
 ### Store Integration Tests (browser)
@@ -227,16 +222,54 @@ describe('task-list', () => {
 
 ### web-test-runner.config.js
 
+`@web/test-runner` uses `nodeResolve` for bare specifiers like `hybrids`,
+but it does **not** support browser import maps. The `#prefix/` aliases
+from `index.html` won't resolve in tests without a custom plugin:
+
 ```javascript
 import { playwrightLauncher } from '@web/test-runner-playwright';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+const aliases = {
+  '#store/': '/src/store/',
+  '#utils/': '/src/utils/',
+  '#atoms/': '/src/components/atoms/',
+  '#molecules/': '/src/components/molecules/',
+  '#organisms/': '/src/components/organisms/',
+  '#templates/': '/src/components/templates/',
+  '#pages/': '/src/pages/',
+};
+
+function importMapPlugin() {
+  return {
+    name: 'import-map-aliases',
+    resolveImport({ source }) {
+      for (const [prefix, target] of Object.entries(aliases)) {
+        if (source.startsWith(prefix)) return source.replace(prefix, target);
+      }
+    },
+  };
+}
 
 export default {
   files: 'src/components/**/*.test.js',
   nodeResolve: true,
+  rootDir: ROOT,
   browsers: [playwrightLauncher({ product: 'chromium' })],
+  plugins: [importMapPlugin()],
 };
 ```
 
+Key points:
+
+- **`rootDir`** must be the project root so `/src/store/` resolves correctly.
+- **Aliases must match the import map** in `index.html`. If you add a prefix
+  there, add it here too.
+- Test files can use `#prefix/` imports just like app code.
+
 ### package.json Scripts
 
 ```json

package/templates/shared/docs/clearstack/BUILD_LOG.md

@@ -1,252 +0,0 @@
-# Build Log
-
-## How This Project Was Built
-
-> This entire repository — specification, implementation, tests, and this
-> document — was authored in a single continuous conversation between a human
-> and an LLM (Amazon Q). No code was written outside this collaboration.
-
----
-
-## Timeline
-
-The project was built over ~1.5 days in a single LLM context window.
-Each phase was implemented, tested, and verified before proceeding.
-
-### Phase 1: Specification
-
-- Wrote the initial spec as one file, hit ~500 lines
-- Split into 7 topic-specific documents (the spec eating its own dogfood)
-- Chose Hybrids.js after reading its source and type definitions from node_modules
-
-### Phase 2: Infrastructure
-
-- Express server, vendor-deps script, import maps, HTML shell
-- JSON Schema registry with seed data
-- Generic CRUD router — one router handles all entity types
-- 15 server tests passing before writing any frontend code
-
-### Phase 3: Store Models & Utils
-
-- Singleton models (AppState, UserPrefs) with localStorage connectors
-- Enumerable models (ProjectModel, TaskModel) with API connectors
-- Utility functions (formatDate, timeAgo, statusColors)
-- 35 tests passing
-
-### Phase 4: Components (Atoms → Molecules → Organisms)
-
-- Built bottom-up: app-button, app-badge, app-icon → task-card, project-card → task-list, project-header
-- Browser tests via @web/test-runner + Playwright
-- 63 tests passing
-
-### Phase 5: Pages, Router & Integration
-
-- page-layout template, home-view, project-view, app-router
-- SSE realtime sync wired at the router level
-- SPA fallback for direct URL navigation
-
-### Phase 6: Schema-Driven Forms
-
-- OPTIONS endpoint returns JSON Schema + form layout
-- schema-form organism auto-generates fields from schema
-- Native HTML validation from schema constraints
-- Server-side validation returns 422 with per-field errors
-- Form layout system with column grouping and action alignment
-
-### Phase 7: Polish & Tooling
-
-- Dark mode via CSS custom property overrides
-- Spec checker CLI with interactive menu
-- ESLint + Prettier + tsc --checkJs for JSDoc type validation
-- GitHub Actions CI pipeline
-- File reorganization (docs/, .configs/, tests/)
-
-### Phase 8: Drag Reorder & Whiteboard
-
-- Drag-to-reorder with visual gap indicator and backend persistence
-- WebSocket server for real-time canvas collaboration
-- SVG whiteboard with drawing tools (in progress)
-
----
-
-## Discoveries & Corrections
-
-The spec was written first, then corrected as implementation revealed gaps.
-These are the significant corrections:
-
-### Light DOM breaks slots
-
-- **Expected:** `<slot>` for content composition
-- **Actual:** Hybrids throws on `<slot>` in light DOM
-- **Fix:** Template functions instead of template components
-- **Documented in:** COMPONENT_PATTERNS.md → Content Composition
-
-### Template components break host context
-
-- **Expected:** Event handlers in content templates resolve to the page
-- **Actual:** `host` resolves to the nearest hybrids component (the template)
-- **Fix:** Use plain functions that return `html`, not `define()`'d components
-- **Documented in:** COMPONENT_PATTERNS.md → Event Handler Host Context
-
-### Custom events don't bubble by default
-
-- **Expected:** `dispatch(host, 'press')` reaches parent listeners
-- **Actual:** Without `bubbles: true`, events stop at the dispatching element
-- **Fix:** Always `dispatch(host, 'event', { bubbles: true })`
-- **Documented in:** COMPONENT_PATTERNS.md → Custom Events Must Bubble
-
-### store.clear(Model) vs store.clear([Model])
-
-- **Expected:** `store.clear(TaskModel)` refreshes task lists
-- **Actual:** Only clears singular cache, not list cache
-- **Fix:** Use `store.clear([TaskModel])` for list stores
-- **Documented in:** STATE_AND_ROUTING.md → Store API Quick Reference
-
-### store.ready(list) doesn't guarantee item readiness
-
-- **Expected:** If the list is ready, items are ready
-- **Actual:** Individual items can be pending after cache clear
-- **Fix:** Guard each item with `store.ready(task)` in map()
-- **Documented in:** STATE_AND_ROUTING.md → Guarding List Item Access
-
-### localStorage connector must return {}, not undefined
-
-- **Expected:** Returning undefined uses model defaults
-- **Actual:** Hybrids treats undefined as a failed get → error state
-- **Fix:** Return `{}` so hybrids merges with defaults
-- **Documented in:** STATE_AND_ROUTING.md → localStorage Connector
-
-### Batch operations cause SSE storms
-
-- **Expected:** Reordering N tasks sends N updates, UI handles it
-- **Actual:** N SSE events → N store.clear() calls → cascading errors
-- **Fix:** Debounce SSE handler per entity type (300ms)
-- **Documented in:** STATE_AND_ROUTING.md → Debouncing Batch Operations
-
-### Server sort used string comparison for numbers
-
-- **Expected:** sortOrder field sorts numerically
-- **Actual:** `localeCompare` on numbers gives wrong order
-- **Fix:** Detect numeric values and use `a - b` comparison
-
-### SVG transforms: two-group rotation approach
-
-- **Expected:** Embed rotation in shapeTransform string
-- **Actual:** Rotation center in local coords doesn't match screen position
-- **Fix:** Outer `<g>` for rotation (screen-space center), inner `<g>` for translate+scale
-- **Documented in:** COMPONENT_PATTERNS.md → Coordinate Transforms
-
-### Move after rotation: unrotate is wrong for translate
-
-- **Expected:** Unrotate screen delta for the inner translate
-- **Actual:** Causes magnified/skewed movement
-- **Fix:** Move both rotation center AND inner translate by raw screen delta
-- **Key insight:** `rotate(deg, cx, cy)` = `translate(cx,cy) rotate(deg) translate(-cx,-cy)`. Shifting cx,cy and translate by the same delta cancels out.
-
-### Resize after rotation: unrotate IS needed
-
-- **Expected:** Same approach as move
-- **Actual:** Handles are visually rotated, so screen drag doesn't align with object axes
-- **Fix:** Unrotate resize deltas only, not move deltas
-
-### SVG innerHTML destroys event listeners
-
-- **Expected:** Event listeners persist across renders
-- **Actual:** `innerHTML` replaces the DOM, losing all listeners
-- **Fix:** Re-bind mouse listeners in `observe`, attach keyboard to host element
-- **Documented in:** COMPONENT_PATTERNS.md → SVG Content via innerHTML
-
-### Path d-string manipulation breaks arc commands
-
-- **Expected:** Regex replace on coordinate pairs works for all paths
-- **Actual:** Arc commands have flags (0/1) that get mangled
-- **Fix:** Use `shapeTransform` for complex shapes, only rewrite d for M/L paths
-
-### Canvas pan offset not applied to drawing coordinates
-
-- **Expected:** Drawing at the visual position works after panning
-- **Actual:** Coordinates calculated from SVG rect, not accounting for pan
-- **Fix:** Shared `canvasPos()` utility subtracts pan offset from all tools
-
-### Enumerable models (`id: true`) break tsc
-
-- **Expected:** `@type {import('hybrids').Model<Product>}` works with `id: true`
-- **Actual:** tsc rejects `id: true` — it's not in the Model type definition
-- **Fix:** Type the model as `@type {any}` with a comment explaining the cast
-- **Documented in:** JSDOC_TYPING.md → Enumerable Models Need `@type {any}`
-
-### Empty arrays in store models throw at runtime
-
-- **Expected:** `items: []` on a singleton model works as an empty default
-- **Actual:** Hybrids throws `The first item of the 'items' array must be defined`
-- **Why:** Hybrids infers array item type from the first element at model setup
-- **Fix:** Provide a prototype item: `items: [{ sku: '', quantity: 0 }]`
-- **Documented in:** STATE_AND_ROUTING.md → Store Array Properties
-
-### List store descriptors don't match array types in tsc
-
-- **Expected:** `store([Model])` assignable to an array-typed host property
-- **Actual:** tsc sees `EnumerableInstance`, not `any[]` — three separate casts needed
-- **Fix:** Cast the descriptor, `store.ready()` call, and the array before `.map()`
-- **Documented in:** JSDOC_TYPING.md → List Store Properties Need Casts
-
-### Organisms importing pages creates circular dependencies
-
-- **Expected:** `router.url(PageView)` works from an organism for link generation
-- **Actual:** Page imports organism, organism imports page → circular
-- **Fix:** Use string URLs (`/product/${sku}`) in organisms instead of `router.url()`
-- **Documented in:** FRONTEND_IMPLEMENTATION_RULES.md → Organisms Must Not Import Pages
-
-### `list` connector params need cast for custom filter properties
-
-- **Expected:** `list: async ({ category }) => ...` destructures cleanly
-- **Actual:** Param is `ModelIdentifier`, tsc rejects `.category` access
-- **Fix:** Cast params to `any` before accessing custom properties
-- **Documented in:** JSDOC_TYPING.md → `list` Connector Params
-
----
-
-## Metrics
-
-| Metric                       | Value                                            |
-| ---------------------------- | ------------------------------------------------ |
-| Total source files           | 108                                              |
-| Utility modules              | 25                                               |
-| Component files              | 13                                               |
-| Style sheets                 | 6                                                |
-| API modules                  | 6                                                |
-| Page views                   | 2                                                |
-| Test files                   | 14                                               |
-| Node tests                   | 65                                               |
-| Browser tests                | 41                                               |
-| Spec documents               | 10                                               |
-| Max lines per file           | 150 (enforced)                                   |
-| Max lines per doc            | 500 (enforced)                                   |
-| Automated checks             | 7 (line counts, lint, format, types, tests)      |
-| Build phases                 | 8 + whiteboard                                   |
-| Bugs found & fixed           | ~25 significant                                  |
-| Bugs requiring >4 iterations | 3 (drag reorder, event bubbling, SVG transforms) |
-| External dependencies        | 4 runtime (hybrids, express, ws, lucide-static)  |
-| Build tools                  | 0                                                |
-
----
-
-## What This Proves
-
-1. **Small files work for LLMs.** Every file fits in a single read. No scrolling,
-   no "show me lines 200-300", no losing context.
-
-2. **The spec catches drift.** When implementation diverged from the spec
-   (e.g. using slots in light DOM), the spec checker or manual review caught
-   it, and both the code and spec were corrected.
-
-3. **Test-at-the-boundary works.** Each phase was tested before the next began.
-   The two hardest bugs (drag reorder, event bubbling) were in the last phases
-   where components composed deeply — exactly where integration tests matter.
-
-4. **No-build is viable.** The app loads in 0.17s LCP, handles real-time sync
-   across browsers, and every file is debuggable as-written in devtools.
-
-5. **The spec improves through implementation.** 9 significant corrections were
-   made to the spec based on what we learned building the proof. The spec is
-   now more accurate than if it had been written in isolation.