@techninja/clearstack 0.3.12 → 0.3.14

package/README.md

@@ -29,17 +29,17 @@ A project/task tracker that exercises every pattern in the spec: API-backed enti
 
 ## Specification
 
-| Document | What It Covers |
-|---|---|
+| Document                                                                    | What It Covers                                                 |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------- |
 | [FRONTEND_IMPLEMENTATION_RULES.md](./docs/FRONTEND_IMPLEMENTATION_RULES.md) | Philosophy, framework choice, project structure, atomic design |
-| [COMPONENT_PATTERNS.md](./docs/COMPONENT_PATTERNS.md) | Authoring, light DOM, styling, layout engine, JSDoc typing |
-| [STATE_AND_ROUTING.md](./docs/STATE_AND_ROUTING.md) | Store, routing, unified app state, realtime SSE sync |
-| [CONVENTIONS.md](./docs/CONVENTIONS.md) | Naming rules, anti-patterns |
-| [SERVER_AND_DEPS.md](./docs/SERVER_AND_DEPS.md) | Express server, import maps, vendor dependency loading |
-| [BACKEND_API_SPEC.md](./docs/BACKEND_API_SPEC.md) | REST CRUD, JSON Schema via HEAD, entity management |
-| [TESTING.md](./docs/TESTING.md) | Testing philosophy, tools, patterns, phase checkpoints |
-| [BUILD_LOG.md](./docs/BUILD_LOG.md) | How this project was built — LLM-human collaboration proof |
-| [QUICKSTART.md](./docs/QUICKSTART.md) | Scaffolder setup, development workflow, updating, compliance |
+| [COMPONENT_PATTERNS.md](./docs/COMPONENT_PATTERNS.md)                       | Authoring, light DOM, styling, layout engine, JSDoc typing     |
+| [STATE_AND_ROUTING.md](./docs/STATE_AND_ROUTING.md)                         | Store, routing, unified app state, realtime SSE sync           |
+| [CONVENTIONS.md](./docs/CONVENTIONS.md)                                     | Naming rules, anti-patterns                                    |
+| [SERVER_AND_DEPS.md](./docs/SERVER_AND_DEPS.md)                             | Express server, import maps, vendor dependency loading         |
+| [BACKEND_API_SPEC.md](./docs/BACKEND_API_SPEC.md)                           | REST CRUD, JSON Schema via HEAD, entity management             |
+| [TESTING.md](./docs/TESTING.md)                                             | Testing philosophy, tools, patterns, phase checkpoints         |
+| [BUILD_LOG.md](./docs/BUILD_LOG.md)                                         | How this project was built — LLM-human collaboration proof     |
+| [QUICKSTART.md](./docs/QUICKSTART.md)                                       | Scaffolder setup, development workflow, updating, compliance   |
 
 ## Using Clearstack
 
@@ -48,7 +48,8 @@ Install as a dev dependency, scaffold, and keep in sync:
 ```bash
 npm install -D @techninja/clearstack    # add to your project
 npx clearstack init                     # scaffold (interactive)
-npx clearstack init -y                  # scaffold (defaults)
+npx clearstack init -y                  # scaffold (fullstack defaults)
+npx clearstack init --static            # scaffold (static, no server)
 npm run spec                            # check compliance
 npm run spec:update                     # sync docs + configs on upgrade
 ```

package/bin/cli.js

@@ -3,7 +3,7 @@
 /**
  * clearstack CLI — scaffold, update, and check spec-compliant projects.
  * Usage:
- *   clearstack init [-y] [--mode fullstack|static] [--port 3000]
+ *   clearstack init [-y] [--static|--fullstack] [--port 3000]
  *   clearstack update
  *   clearstack check [code|docs|imports|lint|lint es|format|types|audit|all]
  *   clearstack                   → interactive menu
@@ -22,6 +22,8 @@ const flags = Object.fromEntries(
   }),
 );
 const yes = args.includes('-y') || args.includes('--yes');
+if (flags.static) flags.mode = 'static';
+if (flags.fullstack) flags.mode = 'fullstack';
 
 /** Show interactive menu. */
 async function interactive() {

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/docs/QUICKSTART.md

@@ -22,8 +22,10 @@ pnpm add -D @techninja/clearstack
 From your project root:
 
 ```bash
-npx clearstack init        # interactive
-npx clearstack init -y     # non-interactive (defaults)
+npx clearstack init            # interactive
+npx clearstack init -y         # non-interactive (fullstack defaults)
+npx clearstack init --static   # non-interactive, static mode
+npx clearstack init -y --static # same as above
 ```
 
 The interactive prompt asks for:
@@ -159,7 +161,8 @@ spec:code → spec:docs → lint → format → typecheck → test
 | Task                  | Command                                |
 | --------------------- | -------------------------------------- |
 | Install Clearstack    | `npm install -D @techninja/clearstack` |
-| Scaffold a project    | `npx clearstack init`                  |
+| Scaffold (fullstack)  | `npx clearstack init`                  |
+| Scaffold (static)     | `npx clearstack init --static`         |
 | Install dependencies  | `npm install`                          |
 | Start dev server      | `npm run dev`                          |
 | Lint + format         | `npm run lint:fix && npm run format`   |

package/package.json

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

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/docs/clearstack/QUICKSTART.md

@@ -22,8 +22,10 @@ pnpm add -D @techninja/clearstack
 From your project root:
 
 ```bash
-npx clearstack init        # interactive
-npx clearstack init -y     # non-interactive (defaults)
+npx clearstack init            # interactive
+npx clearstack init -y         # non-interactive (fullstack defaults)
+npx clearstack init --static   # non-interactive, static mode
+npx clearstack init -y --static # same as above
 ```
 
 The interactive prompt asks for:
@@ -159,7 +161,8 @@ spec:code → spec:docs → lint → format → typecheck → test
 | Task                  | Command                                |
 | --------------------- | -------------------------------------- |
 | Install Clearstack    | `npm install -D @techninja/clearstack` |
-| Scaffold a project    | `npx clearstack init`                  |
+| Scaffold (fullstack)  | `npx clearstack init`                  |
+| Scaffold (static)     | `npx clearstack init --static`         |
 | Install dependencies  | `npm install`                          |
 | Start dev server      | `npm run dev`                          |
 | Lint + format         | `npm run lint:fix && npm run format`   |