@techninja/clearstack 0.3.15 → 0.3.17

package/README.md

@@ -50,8 +50,9 @@ npm install -D @techninja/clearstack    # add to your project
 npx clearstack init                     # scaffold (interactive)
 npx clearstack init -y                  # scaffold (fullstack defaults)
 npx clearstack init --static            # scaffold (static, no server)
+npx clearstack update                   # sync docs (skip existing configs)
+npx clearstack update --force           # sync docs + overwrite configs
 npm run spec                            # check compliance
-npm run spec:update                     # sync docs + configs on upgrade
 ```
 
 Two modes: **fullstack** (Express + WebSocket + JSON DB + SSE) or **static** (localStorage, no server).
@@ -65,7 +66,7 @@ See [QUICKSTART.md](./docs/QUICKSTART.md) for the full walkthrough.
 - **Light DOM by default.** Shared styles just work.
 - **JSDoc over TypeScript.** Types without a compile step — validated by `tsc --checkJs`.
 - **Test at the boundary.** Each phase passes before the next begins.
-- **The spec checks itself.** `npm run spec:code` and `npm run spec:docs`.
+- **The spec checks itself.** `npm run spec code` and `npm run spec docs`.
 - **Lint and format.** ESLint + Prettier, semicolons, 2-space indent.
 
 ## Scripts
@@ -78,10 +79,11 @@ npm run lint        # ESLint check
 npm run lint:fix    # ESLint auto-fix
 npm run format      # Prettier auto-format
 npm run typecheck   # JSDoc type validation via tsc
-npm run spec        # Spec compliance check
-npm run spec:code   # Check code files ≤150 lines
-npm run spec:docs   # Check doc files ≤500 lines
-npm run spec:update # Sync docs + configs from upstream
+npm run spec        # Spec compliance (interactive)
+npm run spec all    # Full spec check
+npm run spec code   # Check code files ≤150 lines
+npm run spec docs   # Check doc files ≤500 lines
+npm run spec update # Sync docs from upstream
 ```
 
 ## License

package/bin/cli.js

@@ -4,7 +4,7 @@
  * clearstack CLI — scaffold, update, and check spec-compliant projects.
  * Usage:
  *   clearstack init [-y] [--static|--fullstack] [--port 3000]
- *   clearstack update
+ *   clearstack update [--force]
  *   clearstack check [code|docs|imports|lint|lint es|format|types|audit|all]
  *   clearstack                   → interactive menu
  */
@@ -54,7 +54,7 @@ async function run(action) {
     await init(PKG_ROOT, { yes, ...flags });
   } else if (action === 'update') {
     const { update } = await import('../lib/update.js');
-    await update(PKG_ROOT);
+    await update(PKG_ROOT, { force: !!flags.force });
   } else if (action === 'check') {
     const subs = args.filter((a) => a !== cmd && !a.startsWith('-'));
     const { check } = await import('../lib/check.js');

package/docs/BUILD_LOG.md

@@ -250,3 +250,100 @@ These are the significant corrections:
 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.

package/docs/CONVENTIONS.md

@@ -298,7 +298,7 @@ multiple keys.
 
 - **One script per domain.** `test`, `spec`, `lint` — not `test:node`,
   `test:browser`, `lint:fix`, `spec:code`, `spec:docs`.
-- **Arguments over aliases.** `pnpm spec check code` instead of
+- **Arguments over aliases.** `pnpm spec code` instead of
   `pnpm spec:code`. The CLI handles routing.
 - **Interactive by default.** Running `pnpm spec` with no arguments shows
   a menu of available actions. Users discover commands by using the tool.
@@ -370,7 +370,8 @@ npm run spec all
 npm run spec code          # line counts (code files ≤150)
 npm run spec docs          # line counts (doc files ≤500)
 npm run spec imports       # import map aliases (no ../)
-npm run spec types         # JSDoc types (tsc --checkJs)
+npm run spec types         # all jsconfigs (auto-discovered)
+npm run spec types frontend # just .configs/jsconfig.json
 npm run spec audit         # security audit
 
 # Parent keys run all children

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

@@ -43,7 +43,7 @@ If a `package.json` already exists, Clearstack merges into it — your existing
 
 ```
 your-project/
-├── .configs/              # ⟳ Managed — synced on update
+├── .configs/              # ✏️ Scaffolded once — yours to customize
 ├── .github/               # CI workflow, PR + issue templates
 ├── docs/
 │   ├── clearstack/        # ⟳ Managed — spec docs, synced on update
@@ -108,14 +108,16 @@ When Clearstack releases a new version:
 
 ```bash
 npm update @techninja/clearstack    # bump the package
-npm run spec:update                 # sync docs + configs
+npm run spec update                 # sync docs, skip existing configs
+npm run spec update --force         # sync docs + overwrite configs
 git diff docs/ .configs/            # review what changed
 ```
 
 This updates:
 
-- `docs/clearstack/*.md` — spec documentation
-- `.configs/*` — linter, formatter, type checker, test runner configs
+- `docs/clearstack/*.md` — spec documentation (always overwritten)
+- `.configs/*` — skipped if already exists (your customizations are safe)
+- `.configs/*` with `--force` — overwritten with latest defaults
 
 This never touches:
 
@@ -127,12 +129,16 @@ This never touches:
 ## 8. Spec Compliance
 
 ```bash
-npm run spec           # full check via clearstack binary
-npm run spec:code      # code files ≤150 lines
-npm run spec:docs      # doc files ≤500 lines
-npm run lint:fix       # ESLint auto-fix
-npm run format         # Prettier auto-format
-npm run typecheck      # JSDoc type validation
+npm run spec           # interactive menu
+npm run spec all       # full check
+npm run spec code      # code files ≤150 lines
+npm run spec docs      # doc files ≤500 lines
+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 types (all jsconfigs)
+npm run spec audit     # security audit
 npm test               # Node + browser tests
 ```
 
@@ -153,21 +159,21 @@ SPEC_IGNORE_DIRS=node_modules,src/vendor,.git,.configs
 The scaffolded `.github/workflows/spec.yml` runs all checks on every PR:
 
 ```
-spec:code → spec:docs → lint → format → typecheck → test
+spec all → lint + format + code + docs + imports + types + audit
 ```
 
 ## Summary
 
-| Task                  | Command                                |
-| --------------------- | -------------------------------------- |
-| Install Clearstack    | `npm install -D @techninja/clearstack` |
-| 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`   |
-| Type check            | `npm run typecheck`                    |
-| Run tests             | `npm test`                             |
-| Full spec check       | `npm run spec`                         |
-| Update spec + configs | `npm run spec:update`                  |
-| Review spec changes   | `git diff docs/ .configs/`             |
+| Task                  | Command                                    |
+| --------------------- | ------------------------------------------ |
+| Install Clearstack    | `npm install -D @techninja/clearstack`     |
+| 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 spec lint && npm run spec format` |
+| Type check            | `npm run spec types`                       |
+| Run tests             | `npm test`                                 |
+| Full spec check       | `npm run spec`                             |
+| Update spec + configs | `npm run spec update`                      |
+| Review spec changes   | `git diff docs/ .configs/`                 |

package/docs/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/lib/check.js

@@ -3,7 +3,7 @@
  * @module lib/check
  */
 
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { checkFileLines, runCmd, countFiles, checkImports } from './spec-utils.js';
 
@@ -51,7 +51,6 @@ export function buildCmds(projectDir) {
     stylelint: `${runner} stylelint --config .configs/.stylelintrc.json "src/**/*.css" --fix`,
     prettier: `${runner} prettier --config .configs/.prettierrc --write src scripts`,
     mdlint: `${runner} markdownlint-cli2 --config .configs/.markdownlint.jsonc --fix "docs/**/*.md" "*.md"`,
-    types: `${runner} tsc --project .configs/jsconfig.json`,
     audit,
   };
 }
@@ -59,11 +58,29 @@ export function buildCmds(projectDir) {
 
 /** @typedef {{ key: string, name: string, parent?: string, run: () => boolean }} Check */
 
-/** Build the unified checks array. Children have a `parent` key. */
+/** Find all jsconfig.json files — main config + any in subdirectories. */
+function findTypeConfigs(dir, runner) {
+  const main = resolve(dir, '.configs/jsconfig.json');
+  const configs = [];
+  if (existsSync(main)) configs.push({ key: 'frontend', label: 'Frontend', path: main });
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+    const p = resolve(dir, entry.name, 'jsconfig.json');
+    if (existsSync(p)) configs.push({ key: entry.name, label: entry.name, path: p });
+  }
+  return configs.map((c) => ({
+    key: c.key, name: `JSDoc types — ${c.label}`, parent: 'types',
+    run: () => runCmd(`Types (${c.label})`, `${runner} tsc --project ${c.path}`, dir),
+  }));
+}
+
+/** Build the unified checks array. Children have a `parent` key.
+ * @returns {Check[]} */
 export function buildChecks(dir, cfg, cmds) {
   const js = () => countFiles(dir, ['.js'], cfg.ignore);
   const css = () => countFiles(dir, ['.css'], cfg.ignore);
   const md = () => countFiles(dir, ['.md'], cfg.ignore);
+  const runner = detectRunner(dir);
   return [
     { key: 'es', name: 'ESLint', parent: 'lint',
       run: () => runCmd('ESLint', cmds.lint, dir, `${js()} files`) },
@@ -79,8 +96,7 @@ export function buildChecks(dir, cfg, cmds) {
       run: () => checkFileLines(dir, cfg.docsExt, cfg.docsMax, cfg.ignore, `Docs (max ${cfg.docsMax} lines)`) },
     { key: 'imports', name: 'Import map aliases (no ../ imports)',
       run: () => checkImports(dir, cfg.ignore, 'Import map aliases (no ../ imports)') },
-    { key: 'types', name: 'JSDoc types (tsc --checkJs)',
-      run: () => runCmd('JSDoc types', cmds.types, dir, `${js()} files`) },
+    ...findTypeConfigs(dir, runner),
     { key: 'audit', name: 'Security audit',
       run: () => runCmd('Security audit', cmds.audit, dir) },
   ];

package/lib/update.js

@@ -1,6 +1,7 @@
 /**
  * Spec updater — syncs docs and configs from the clearstack package.
- * Copies new versions so the user can review the git diff.
+ * Docs are overwritten (clearstack-owned). Configs skip existing files
+ * to preserve project customizations — use --force to overwrite.
  * @module lib/update
  */
 
@@ -8,24 +9,27 @@ import { readdirSync, readFileSync, writeFileSync, existsSync, mkdirSync } from
 import { resolve, join } from 'node:path';
 
 /**
- * Sync a source directory to a destination, comparing file contents.
+ * Sync a source directory to a destination.
  * @param {string} src
  * @param {string} dest
  * @param {string} label
+ * @param {{ skipExisting?: boolean }} [opts]
  * @returns {number} count of updated files
  */
-function syncDir(src, dest, label) {
+function syncDir(src, dest, label, opts = {}) {
   if (!existsSync(src)) return 0;
   mkdirSync(dest, { recursive: true });
-
   const files = readdirSync(src).filter((f) => !f.startsWith('.spec'));
   let updated = 0;
 
   for (const file of files) {
-    const srcContent = readFileSync(join(src, file), 'utf-8');
     const destPath = join(dest, file);
+    if (opts.skipExisting && existsSync(destPath)) {
+      console.log(`  ⏭ Skipped: ${label}/${file} (exists, use --force to overwrite)`);
+      continue;
+    }
+    const srcContent = readFileSync(join(src, file), 'utf-8');
     const destContent = existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '';
-
     if (srcContent !== destContent) {
       writeFileSync(destPath, srcContent);
       console.log(`  ✓ Updated: ${label}/${file}`);
@@ -36,25 +40,29 @@ function syncDir(src, dest, label) {
 }
 
 /**
- * Update spec docs and configs from the clearstack package to the local project.
+ * Update spec docs and configs from the clearstack package.
  * @param {string} pkgRoot - Root of the clearstack package
+ * @param {{ force?: boolean }} [opts]
  */
-export async function update(pkgRoot) {
+export async function update(pkgRoot, opts = {}) {
   const templateShared = resolve(pkgRoot, 'templates/shared');
   let total = 0;
 
   console.log('');
 
+  // Docs: always overwrite (clearstack-owned content)
   total += syncDir(
     resolve(templateShared, 'docs/clearstack'),
     resolve(process.cwd(), 'docs/clearstack'),
     'docs/clearstack',
   );
 
+  // Configs: skip existing unless --force (project may have customized)
   total += syncDir(
     resolve(templateShared, '.configs'),
     resolve(process.cwd(), '.configs'),
     '.configs',
+    { skipExisting: !opts.force },
   );
 
   // Merge .gitignore (append missing lines, never remove user entries)

package/package.json

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

package/templates/shared/.configs/web-test-runner.config.js

@@ -1,8 +1,35 @@
 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/',
+};
+
+/** Resolve #prefix/ imports for @web/test-runner. */
+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: '..',
+  rootDir: ROOT,
   browsers: [playwrightLauncher({ product: 'chromium' })],
+  plugins: [importMapPlugin()],
 };

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

@@ -250,3 +250,100 @@ These are the significant corrections:
 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.

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

@@ -298,7 +298,7 @@ multiple keys.
 
 - **One script per domain.** `test`, `spec`, `lint` — not `test:node`,
   `test:browser`, `lint:fix`, `spec:code`, `spec:docs`.
-- **Arguments over aliases.** `pnpm spec check code` instead of
+- **Arguments over aliases.** `pnpm spec code` instead of
   `pnpm spec:code`. The CLI handles routing.
 - **Interactive by default.** Running `pnpm spec` with no arguments shows
   a menu of available actions. Users discover commands by using the tool.
@@ -370,7 +370,8 @@ npm run spec all
 npm run spec code          # line counts (code files ≤150)
 npm run spec docs          # line counts (doc files ≤500)
 npm run spec imports       # import map aliases (no ../)
-npm run spec types         # JSDoc types (tsc --checkJs)
+npm run spec types         # all jsconfigs (auto-discovered)
+npm run spec types frontend # just .configs/jsconfig.json
 npm run spec audit         # security audit
 
 # Parent keys run all children

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

@@ -43,7 +43,7 @@ If a `package.json` already exists, Clearstack merges into it — your existing
 
 ```
 your-project/
-├── .configs/              # ⟳ Managed — synced on update
+├── .configs/              # ✏️ Scaffolded once — yours to customize
 ├── .github/               # CI workflow, PR + issue templates
 ├── docs/
 │   ├── clearstack/        # ⟳ Managed — spec docs, synced on update
@@ -108,14 +108,16 @@ When Clearstack releases a new version:
 
 ```bash
 npm update @techninja/clearstack    # bump the package
-npm run spec:update                 # sync docs + configs
+npm run spec update                 # sync docs, skip existing configs
+npm run spec update --force         # sync docs + overwrite configs
 git diff docs/ .configs/            # review what changed
 ```
 
 This updates:
 
-- `docs/clearstack/*.md` — spec documentation
-- `.configs/*` — linter, formatter, type checker, test runner configs
+- `docs/clearstack/*.md` — spec documentation (always overwritten)
+- `.configs/*` — skipped if already exists (your customizations are safe)
+- `.configs/*` with `--force` — overwritten with latest defaults
 
 This never touches:
 
@@ -127,12 +129,16 @@ This never touches:
 ## 8. Spec Compliance
 
 ```bash
-npm run spec           # full check via clearstack binary
-npm run spec:code      # code files ≤150 lines
-npm run spec:docs      # doc files ≤500 lines
-npm run lint:fix       # ESLint auto-fix
-npm run format         # Prettier auto-format
-npm run typecheck      # JSDoc type validation
+npm run spec           # interactive menu
+npm run spec all       # full check
+npm run spec code      # code files ≤150 lines
+npm run spec docs      # doc files ≤500 lines
+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 types (all jsconfigs)
+npm run spec audit     # security audit
 npm test               # Node + browser tests
 ```
 
@@ -153,21 +159,21 @@ SPEC_IGNORE_DIRS=node_modules,src/vendor,.git,.configs
 The scaffolded `.github/workflows/spec.yml` runs all checks on every PR:
 
 ```
-spec:code → spec:docs → lint → format → typecheck → test
+spec all → lint + format + code + docs + imports + types + audit
 ```
 
 ## Summary
 
-| Task                  | Command                                |
-| --------------------- | -------------------------------------- |
-| Install Clearstack    | `npm install -D @techninja/clearstack` |
-| 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`   |
-| Type check            | `npm run typecheck`                    |
-| Run tests             | `npm test`                             |
-| Full spec check       | `npm run spec`                         |
-| Update spec + configs | `npm run spec:update`                  |
-| Review spec changes   | `git diff docs/ .configs/`             |
+| Task                  | Command                                    |
+| --------------------- | ------------------------------------------ |
+| Install Clearstack    | `npm install -D @techninja/clearstack`     |
+| 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 spec lint && npm run spec format` |
+| Type check            | `npm run spec types`                       |
+| Run tests             | `npm test`                                 |
+| Full spec check       | `npm run spec`                             |
+| Update spec + configs | `npm run spec update`                      |
+| Review spec changes   | `git diff docs/ .configs/`                 |

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