@techninja/clearstack 0.3.17 → 0.3.19

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/BUILD_LOG.md

@@ -1,349 +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.
-
----
-
-## StatiCart: Second Project Validation
-
-StatiCart is a full e-commerce platform built on Clearstack — the second
-project built against the spec, validating that the patterns hold beyond
-the original POC. Three phases (catalog, cart, polish) were completed in
-a single LLM session.
-
-### Velocity
-
-| Metric | Value |
-| --- | --- |
-| Phases completed | 3 of 8 |
-| Components created | 7 (2 atoms, 2 molecules, 2 organisms, 0 templates) |
-| Pages created | 5 (catalog, product-detail, cart, order-success, order-cancelled) |
-| Store models | 2 (Product enumerable, CartState singleton) |
-| Utilities | 4 (formatPrice, setPageMeta, productVariants, statusColors) |
-| Tests | 41 (10 node, 31 browser) |
-| Spec checks | 9/9 passing |
-| Files over 150 lines | 0 (2 hit the limit, both split successfully) |
-
-Three phases of a real app in one session. No blocked-on-framework moments.
-Every blocker was a hybrids runtime behavior, not a Clearstack constraint.
-
-### What the 150-Line Limit Actually Did
-
-The limit forced two splits during this build:
-
-1. `shared.css` hit 203 lines after adding page layout styles → split into
-   `pages.css`. Later `pages.css` hit 163 → split into `pages-cart.css`.
-2. `product-detail-view.js` hit 154 after adding the image gallery →
-   extracted `productVariants.js` utility.
-
-Both splits improved the code. The page styles split by concern (catalog
-vs cart) which made each file scannable. The utility extraction made
-`effectivePrice`/`effectiveStock` reusable and independently testable.
-
-Without the limit, these would have stayed as 300-line monoliths. The
-LLM would have needed to re-read them on every edit, and the utility
-functions would never have gotten their own test file.
-
-### What the Spec Documentation Prevented
-
-The Clearstack spec docs prevented several classes of bugs entirely:
-
-- **No `../` imports.** The import map alias rule (`#store/`, `#atoms/`)
-  was enforced from the first file. Zero refactoring of import paths.
-- **`shadow: false` everywhere.** No time wasted on shadow DOM styling
-  issues. Global CSS just worked.
-- **Named event handlers.** No "button doesn't work" debugging from
-  inline arrows in nested templates.
-- **`store.connect.get` returns `{}`.** The localStorage pattern was
-  correct on first write for CartState.
-- **Template functions over template components.** No host context bugs.
-
-### What the Spec Didn't Prevent (New Discoveries)
-
-Five new hybrids gotchas were found and documented:
-
-1. **Empty arrays throw** — `items: []` needs a prototype item
-2. **`id` is reserved in nested models** — even inside array prototypes
-3. **Enumerable models need `@type {any}`** — tsc can't type `id: true`
-4. **List store descriptors need 3 casts** — descriptor, ready(), and map()
-5. **`list` connector params need cast** — `ModelIdentifier` not plain object
-
-All five are hybrids type system friction, not architectural issues. The
-runtime behavior is correct — it's the JSDoc/tsc layer that struggles.
-Each was fixed in under 2 minutes once identified.
-
-### Test Runner Discovery
-
-`@web/test-runner` doesn't support browser import maps. A custom
-`resolveImport` plugin was needed to map `#prefix/` aliases to absolute
-paths. This is now documented in TESTING.md with the full config pattern.
-
-### Framework Reuse Validation
-
-The Clearstack scaffolder (`npm run spec update`) worked correctly for
-doc syncing. The config overwrite issue (jsconfig.json, eslint.config.js)
-was found and fixed upstream — `update` now skips existing configs unless
-`--force` is passed. This validates the "dependency, not template" model.
-
-### Key Insight
-
-The speed came from **not having to make architectural decisions**. The
-spec answered every "where does this go" question before it was asked:
-store models in `src/store/`, atoms vs molecules vs organisms, CSS in
-per-component files registered in `components.css`, pages in `src/pages/`.
-The LLM never had to ask "how should I structure this?" — it read the
-spec and built.
-
-This is the core value proposition: **Clearstack trades flexibility for
-velocity.** A team (or LLM) that knows the spec can build without
-discussion. The constraints aren't limitations — they're decisions that
-have already been made.