Add findings from StatiCart

# Conflicts:
#	CHANGELOG.md

Author: techninja

.vscode/settings.json

@@ -4,6 +4,10 @@
     "activityBar.foreground": "#c6f2f1",
     "activityBar.inactiveForeground": "#4a8ab5",
     "activityBarBadge.background": "#00c0e0",
-    "activityBarBadge.foreground": "#002040"
+    "activityBarBadge.foreground": "#002040",
+    "titleBar.activeBackground": "#063466",
+    "titleBar.activeForeground": "#c6f2f1",
+    "titleBar.inactiveBackground": "#042a52",
+    "titleBar.inactiveForeground": "#4a8ab5"
   }
 }

CHANGELOG.md

@@ -11,7 +11,6 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Spec linting
 - Allow passing --static for serverless builds
 
-
 ## [0.3.12] - 2026-04-07
 
 - Fix ordering of spec check to account for auto lint fixes Also add convention around splitting vs compressing for big files

docs/BUILD_LOG.md

@@ -168,6 +168,42 @@ These are the significant corrections:
 - **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

docs/FRONTEND_IMPLEMENTATION_RULES.md

@@ -212,6 +212,29 @@ Pages → Templates → Organisms → Molecules → Atoms
                                           Store / Utils
 ```
 
+#### Organisms Must Not Import Pages
+
+Organisms sit below pages in the import hierarchy. If an organism needs
+to generate a URL to a page (e.g. a product grid linking to a product
+detail page), **use a string URL, not `router.url(PageView)`**.
+
+`router.url()` requires importing the page component, which creates a
+circular dependency: page → organism → page. Even if the bundler or
+browser resolves it, it makes the dependency graph untraceable.
+
+```javascript
+// ❌ BAD — organism imports a page, circular dependency
+import ProductDetailView from '#pages/product-detail/product-detail-view.js';
+html`<a href="${router.url(ProductDetailView, { sku })}">View</a>`;
+
+// ✅ GOOD — string URL, no import needed
+html`<a href="${`/product/${sku}`}">View</a>`;
+```
+
+If the URL pattern changes, update it in one place. For complex URL
+generation, extract a `buildUrl(view, params)` utility in `src/utils/`
+that returns strings — no component imports.
+
 - Atoms import **nothing** from other component tiers.
 - Molecules import only from **atoms**.
 - Organisms import from **molecules** and **atoms**.

docs/JSDOC_TYPING.md

@@ -76,6 +76,73 @@ function handleClick(host, event) {
 }
 ```
 
+## Enumerable Models Need `@type {any}`
+
+Hybrids' TypeScript definitions don't support `id: true` on `Model<T>` —
+`tsc` rejects it because `id` isn't in the typedef. The fix is to type
+the entire model as `any` with a comment explaining why:
+
+```javascript
+/** @type {any} — hybrids Model with id:true; cast to bypass tsc limitations */
+const Product = {
+  id: true,
+  name: '',
+  // ...
+  [store.connect]: { get: ..., list: ... },
+};
+```
+
+Do **not** add `id` to the `@typedef` — it's a hybrids directive, not a
+data field. The `@typedef` should describe the shape of the data.
+
+## List Store Properties Need Casts
+
+`store([Model])` returns a descriptor that `tsc` can't reconcile with
+array-typed host properties. Both the descriptor and `store.ready()` calls
+need `any` casts:
+
+```javascript
+/**
+ * @typedef {Object} MyGridHost
+ * @property {any} items — list store, cast for tsc
+ */
+
+/** @type {import('hybrids').Component<MyGridHost>} */
+export default define({
+  tag: 'my-grid',
+  items: /** @type {any} */ (store([Product], { id: () => ({}) })),
+  render: {
+    value: ({ items }) => html`
+      ${
+        /** @type {any} */ (store).ready(items)
+          ? /** @type {any[]} */ (items).map((i) => html`<span>${i.name}</span>`)
+          : html`<p>Loading…</p>`
+      }
+    `,
+    shadow: false,
+  },
+});
+```
+
+Three casts are needed:
+
+1. `/** @type {any} */` on the `store([Model])` descriptor assignment
+2. `/** @type {any} */ (store).ready(items)` — `store.ready()` overloads
+   reject array-typed arguments
+3. `/** @type {any[]} */ (items)` before calling `.map()` / `.filter()`
+
+## `list` Connector Params Are `ModelIdentifier`
+
+The `list` connector receives a `ModelIdentifier`, not a plain object.
+Accessing custom filter properties (like `.category`) requires a cast:
+
+```javascript
+list: async (params) => {
+  const category = /** @type {any} */ (params)?.category;
+  // ...
+},
+```
+
 ## Rules
 
 - Every exported component gets a `@typedef` for its host interface.

templates/shared/docs/clearstack/BUILD_LOG.md

@@ -168,6 +168,42 @@ These are the significant corrections:
 - **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

templates/shared/docs/clearstack/FRONTEND_IMPLEMENTATION_RULES.md

@@ -212,6 +212,29 @@ Pages → Templates → Organisms → Molecules → Atoms
                                           Store / Utils
 ```
 
+#### Organisms Must Not Import Pages
+
+Organisms sit below pages in the import hierarchy. If an organism needs
+to generate a URL to a page (e.g. a product grid linking to a product
+detail page), **use a string URL, not `router.url(PageView)`**.
+
+`router.url()` requires importing the page component, which creates a
+circular dependency: page → organism → page. Even if the bundler or
+browser resolves it, it makes the dependency graph untraceable.
+
+```javascript
+// ❌ BAD — organism imports a page, circular dependency
+import ProductDetailView from '#pages/product-detail/product-detail-view.js';
+html`<a href="${router.url(ProductDetailView, { sku })}">View</a>`;
+
+// ✅ GOOD — string URL, no import needed
+html`<a href="${`/product/${sku}`}">View</a>`;
+```
+
+If the URL pattern changes, update it in one place. For complex URL
+generation, extract a `buildUrl(view, params)` utility in `src/utils/`
+that returns strings — no component imports.
+
 - Atoms import **nothing** from other component tiers.
 - Molecules import only from **atoms**.
 - Organisms import from **molecules** and **atoms**.

templates/shared/docs/clearstack/JSDOC_TYPING.md

@@ -76,6 +76,73 @@ function handleClick(host, event) {
 }
 ```
 
+## Enumerable Models Need `@type {any}`
+
+Hybrids' TypeScript definitions don't support `id: true` on `Model<T>` —
+`tsc` rejects it because `id` isn't in the typedef. The fix is to type
+the entire model as `any` with a comment explaining why:
+
+```javascript
+/** @type {any} — hybrids Model with id:true; cast to bypass tsc limitations */
+const Product = {
+  id: true,
+  name: '',
+  // ...
+  [store.connect]: { get: ..., list: ... },
+};
+```
+
+Do **not** add `id` to the `@typedef` — it's a hybrids directive, not a
+data field. The `@typedef` should describe the shape of the data.
+
+## List Store Properties Need Casts
+
+`store([Model])` returns a descriptor that `tsc` can't reconcile with
+array-typed host properties. Both the descriptor and `store.ready()` calls
+need `any` casts:
+
+```javascript
+/**
+ * @typedef {Object} MyGridHost
+ * @property {any} items — list store, cast for tsc
+ */
+
+/** @type {import('hybrids').Component<MyGridHost>} */
+export default define({
+  tag: 'my-grid',
+  items: /** @type {any} */ (store([Product], { id: () => ({}) })),
+  render: {
+    value: ({ items }) => html`
+      ${
+        /** @type {any} */ (store).ready(items)
+          ? /** @type {any[]} */ (items).map((i) => html`<span>${i.name}</span>`)
+          : html`<p>Loading…</p>`
+      }
+    `,
+    shadow: false,
+  },
+});
+```
+
+Three casts are needed:
+
+1. `/** @type {any} */` on the `store([Model])` descriptor assignment
+2. `/** @type {any} */ (store).ready(items)` — `store.ready()` overloads
+   reject array-typed arguments
+3. `/** @type {any[]} */ (items)` before calling `.map()` / `.filter()`
+
+## `list` Connector Params Are `ModelIdentifier`
+
+The `list` connector receives a `ModelIdentifier`, not a plain object.
+Accessing custom filter properties (like `.category`) requires a cast:
+
+```javascript
+list: async (params) => {
+  const category = /** @type {any} */ (params)?.category;
+  // ...
+},
+```
+
 ## Rules
 
 - Every exported component gets a `@typedef` for its host interface.