@techninja/clearstack 0.3.13 → 0.3.15

package/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

package/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**.

package/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.

package/lib/check.js

@@ -42,11 +42,9 @@ export function loadConfig(projectDir) {
   };
 }
 
-/**
- * Build check commands for the detected package manager.
- * @param {string} runner
- */
-function buildCmds(runner) {
+/** Build check commands for the detected package manager. */
+export function buildCmds(projectDir) {
+  const runner = detectRunner(projectDir);
   const audit = runner === 'pnpm exec' ? 'pnpm audit --prod' : 'npm audit --omit=dev';
   return {
     lint: `${runner} eslint --config .configs/eslint.config.js . --fix`,
@@ -58,8 +56,6 @@ function buildCmds(runner) {
   };
 }
 
-/** @deprecated Use buildCmds() instead — kept for backward compat. */
-export const CMDS = buildCmds('npx');
 
 /** @typedef {{ key: string, name: string, parent?: string, run: () => boolean }} Check */
 
@@ -108,10 +104,10 @@ export function parentKeys(checks) {
   return [...new Set(checks.filter((c) => c.parent).map((c) => c.parent))];
 }
 
-/** Run the full spec compliance check (used by clearstack CLI). */
+/** Run the full spec compliance check (used by clearstack CLI and scripts/spec.js). */
 export async function check(projectDir, scope) {
   const cfg = loadConfig(projectDir);
-  const cmds = buildCmds(detectRunner(projectDir));
+  const cmds = buildCmds(projectDir);
   const checks = buildChecks(projectDir, cfg, cmds);
 
   if (scope && scope !== 'all') {
@@ -127,7 +123,7 @@ export async function check(projectDir, scope) {
     return;
   }
 
-  console.log('Running spec compliance check...\n');
+  console.log('🔍 Clearstack compliance checking now... 💙\n');
   const results = checks.map((c) => c.run());
   const passed = results.filter(Boolean).length;
   console.log(`\n${'='.repeat(40)}`);

package/lib/package-gen.js

@@ -21,7 +21,7 @@ export async function writePackageJson(dest, vars, existing) {
     dev: 'node --watch --env-file=.env --env-file=.env.local src/server.js',
     postinstall: 'node scripts/setup.js',
     test: 'node scripts/test.js',
-    spec: 'clearstack',
+    spec: 'node scripts/spec.js',
   };
 
   const specDeps = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {

package/templates/shared/.github/workflows/spec.yml

@@ -24,20 +24,8 @@ jobs:
       - name: Install Playwright Chromium
         run: npx playwright install chromium --with-deps
 
-      - name: Code line counts (≤150)
-        run: node scripts/spec.js code
-
-      - name: Doc line counts (≤500)
-        run: node scripts/spec.js docs
-
-      - name: ESLint
-        run: npx eslint --config .configs/eslint.config.js .
-
-      - name: Prettier
-        run: npx prettier --config .configs/.prettierrc --check src scripts server.js tests
-
-      - name: JSDoc types (tsc --checkJs)
-        run: npx tsc --project .configs/jsconfig.json
+      - name: Spec compliance
+        run: node scripts/spec.js all
 
       - name: Node tests
         run: node --test tests/*.test.js src/utils/*.test.js src/store/*.test.js

package/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

package/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**.

package/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.

package/templates/shared/scripts/spec.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+/**
+ * Spec enforcement — interactive menu + CLI shortcuts.
+ * Delegates all check logic to @techninja/clearstack.
+ * @module scripts/spec
+ */
+
+import {
+  loadConfig,
+  buildChecks,
+  buildCmds,
+  resolveChecks,
+  parentKeys,
+  check,
+} from '@techninja/clearstack/lib/check.js';
+
+const ROOT = new URL('..', import.meta.url).pathname.replace(/\/$/, '');
+const [sub, subsub] = process.argv.slice(2);
+const scope = subsub ? `${sub} ${subsub}` : sub;
+
+if (scope) {
+  await check(ROOT, scope);
+} else {
+  await interactive(ROOT);
+}
+
+/** Show interactive menu, then run the selected check. */
+async function interactive(dir) {
+  const cfg = loadConfig(dir);
+  const checks = buildChecks(dir, cfg, buildCmds(dir));
+  try {
+    const { select } = await import('@inquirer/prompts');
+    const action = await select({
+      message: 'Spec checker — what do you want to validate?',
+      choices: menuChoices(checks),
+    });
+    await check(dir, action);
+  } catch (e) {
+    if (e?.name === 'ExitPromptError') process.exit(0);
+    throw e;
+  }
+}
+
+/** Build interactive menu choices with hierarchy. */
+function menuChoices(checks) {
+  const choices = [];
+  const seen = new Set();
+  for (const c of checks) {
+    if (c.parent && !seen.has(c.parent)) {
+      seen.add(c.parent);
+      const kids = checks.filter((k) => k.parent === c.parent);
+      const label = kids.map((k) => k.name).join(' + ');
+      choices.push({ name: `${label} [${c.parent}]`, value: c.parent });
+      for (const k of kids)
+        choices.push({ name: `  ${k.name} [${c.parent} ${k.key}]`, value: `${c.parent} ${k.key}` });
+    } else if (!c.parent) {
+      choices.push({ name: `${c.name} [${c.key}]`, value: c.key });
+    }
+  }
+  choices.push({ name: 'All (full spec check)', value: 'all' });
+  return choices;
+}