@techninja/clearstack 0.3.16 → 0.3.17

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

@@ -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

@@ -137,7 +137,7 @@ 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 type validation
+npm run spec types     # JSDoc types (all jsconfigs)
 npm run spec audit     # security audit
 npm test               # Node + browser tests
 ```
@@ -172,7 +172,7 @@ spec all → lint + format + code + docs + imports + types + audit
 | Install dependencies  | `npm install`                              |
 | Start dev server      | `npm run dev`                              |
 | Lint + format         | `npm run spec lint && npm run spec format` |
-| Type check            | `npm run typecheck`                        |
+| Type check            | `npm run spec types`                       |
 | Run tests             | `npm test`                                 |
 | Full spec check       | `npm run spec`                             |
 | Update spec + configs | `npm run spec update`                      |

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

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.3.16",
+  "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

@@ -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

@@ -137,7 +137,7 @@ 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 type validation
+npm run spec types     # JSDoc types (all jsconfigs)
 npm run spec audit     # security audit
 npm test               # Node + browser tests
 ```
@@ -172,7 +172,7 @@ spec all → lint + format + code + docs + imports + types + audit
 | Install dependencies  | `npm install`                              |
 | Start dev server      | `npm run dev`                              |
 | Lint + format         | `npm run spec lint && npm run spec format` |
-| Type check            | `npm run typecheck`                        |
+| Type check            | `npm run spec types`                       |
 | Run tests             | `npm test`                                 |
 | Full spec check       | `npm run spec`                             |
 | Update spec + configs | `npm run spec update`                      |

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