@techninja/clearstack 0.3.16 → 0.3.19

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

@@ -1,69 +1,44 @@
 /**
- * Spec compliance checker — config, commands, and orchestration.
+ * Spec compliance checker — check orchestration and resolution.
+ * Config lives in spec-config.js, utilities in spec-utils.js.
  * @module lib/check
  */
 
-import { readFileSync, existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { checkFileLines, runCmd, countFiles, checkImports } from './spec-utils.js';
+import { loadConfig, buildCmds, detectRunner } from './spec-config.js';
 
 export { checkFileLines, runCmd, countFiles, findFiles, elapsed, checkImports } from './spec-utils.js';
+export { loadConfig, buildCmds, detectRunner } from './spec-config.js';
 
-/** Detect the project's package manager runner (npx, pnpm exec, yarn). */
-function detectRunner(projectDir) {
-  if (existsSync(resolve(projectDir, 'pnpm-lock.yaml'))) return 'pnpm exec';
-  if (existsSync(resolve(projectDir, 'yarn.lock'))) return 'yarn';
-  return 'npx';
-}
+/** @typedef {{ key: string, name: string, parent?: string, run: () => boolean }} Check */
 
-/** @param {string} src */
-function parseEnv(src) {
-  const env = {};
-  for (const line of src.split('\n')) {
-    const m = line.match(/^([^#=]+)=(.*)$/);
-    if (m) env[m[1].trim()] = m[2].trim();
+/** Find all jsconfig.json files — main config + 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 env;
+  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),
+  }));
 }
 
 /**
- * Load spec config from project .env.
- * @param {string} projectDir
+ * Build the unified checks array. Children have a `parent` key.
+ * @returns {Check[]}
  */
-export function loadConfig(projectDir) {
-  const envPath = resolve(projectDir, '.env');
-  const env = existsSync(envPath) ? parseEnv(readFileSync(envPath, 'utf-8')) : {};
-  return {
-    codeMax: parseInt(env.SPEC_CODE_MAX_LINES) || 150,
-    docsMax: parseInt(env.SPEC_DOCS_MAX_LINES) || 500,
-    codeExt: (env.SPEC_CODE_EXTENSIONS || '.js,.css').split(','),
-    docsExt: (env.SPEC_DOCS_EXTENSIONS || '.md').split(','),
-    ignore: (env.SPEC_IGNORE_DIRS || 'node_modules,src/vendor,.git,.configs').split(','),
-  };
-}
-
-/** 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`,
-    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,
-  };
-}
-
-
-/** @typedef {{ key: string, name: string, parent?: string, run: () => boolean }} Check */
-
-/** Build the unified checks array. Children have a `parent` key. */
 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`) },
@@ -74,13 +49,14 @@ export function buildChecks(dir, cfg, cmds) {
     { key: 'prettier', name: 'Prettier', parent: 'format',
       run: () => runCmd('Prettier', cmds.prettier, dir, `${js()} files`) },
     { key: 'code', name: `Code (max ${cfg.codeMax} lines)`,
-      run: () => checkFileLines(dir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`) },
+      run: () => checkFileLines(dir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`, { exclude: cfg.testPattern }) },
+    { key: 'tests', name: `Tests (max ${cfg.testMax} lines)`,
+      run: () => checkFileLines(dir, cfg.codeExt, cfg.testMax, cfg.ignore, `Tests (max ${cfg.testMax} lines)`, { include: cfg.testPattern }) },
     { key: 'docs', name: `Docs (max ${cfg.docsMax} lines)`,
       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/init.js

@@ -7,6 +7,7 @@ import { copyFileSync, existsSync, readFileSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
 import { copyTemplates } from './copy.js';
 import { writePackageJson } from './package-gen.js';
+import { detectPlatforms, initPlatform } from './platform.js';
 
 /**
  * @typedef {Object} InitOptions
@@ -75,6 +76,10 @@ export async function init(pkgRoot, opts = {}) {
     console.log('  ✓ .env.local (edit this, .env has defaults)');
   }
 
+  // Platform stacking: detect and scaffold platform layers
+  const platforms = detectPlatforms(dest);
+  for (const platform of platforms) initPlatform(platform, dest);
+
   console.log(`\n✅ Project scaffolded at ${dest}`);
   console.log('   npm install');
   console.log('   npm run dev\n');

package/lib/platform-files.js

@@ -0,0 +1,113 @@
+/**
+ * Platform file operations — vendor, sync, init, update.
+ * Detection lives in platform.js.
+ * @module lib/platform-files
+ */
+
+import { cpSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+/**
+ * Copy src → dest recursively (always overwrite).
+ * @param {string} src
+ * @param {string} dest
+ * @param {string} label
+ */
+function copyDir(src, dest, label) {
+  if (!existsSync(src)) return 0;
+  mkdirSync(dest, { recursive: true });
+  cpSync(src, dest, { recursive: true });
+  console.log(`  ✓ Synced: ${label}`);
+  return 1;
+}
+
+/**
+ * Copy entries from src → dest, skipping files that already exist.
+ * @param {string} src
+ * @param {string} dest
+ * @param {string} label
+ */
+function copySkipExisting(src, dest, label) {
+  if (!existsSync(src)) return 0;
+  mkdirSync(dest, { recursive: true });
+  let count = 0;
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const destPath = join(dest, entry.name);
+    if (existsSync(destPath)) {
+      console.log(`  ⏭ Skipped: ${label}/${entry.name} (exists)`);
+      continue;
+    }
+    cpSync(join(src, entry.name), destPath, { recursive: entry.isDirectory() });
+    console.log(`  ✓ Created: ${label}/${entry.name}`);
+    count++;
+  }
+  return count;
+}
+
+/**
+ * Copy src → dest recursively, overwriting files but merging directories.
+ * @param {string} src
+ * @param {string} dest
+ * @param {string} label
+ */
+function copyMerge(src, dest, label) {
+  if (!existsSync(src)) return 0;
+  mkdirSync(dest, { recursive: true });
+  let count = 0;
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      count += copyMerge(srcPath, destPath, `${label}/${entry.name}`);
+    } else {
+      cpSync(srcPath, destPath);
+      console.log(`  ✓ ${label}/${entry.name}`);
+      count++;
+    }
+  }
+  return count;
+}
+
+/** Vendor platform files → src/vendor/<prefix>/ (always overwrite). */
+export function vendorPlatform(platform, projectDir) {
+  const { manifest, pkgDir } = platform;
+  return copyDir(
+    resolve(pkgDir, manifest.vendor),
+    resolve(projectDir, manifest.vendorDir),
+    `${manifest.prefix} → ${manifest.vendorDir}/`,
+  );
+}
+
+/** Sync platform docs → docs/<prefix>/ (always overwrite). */
+export function syncPlatformDocs(platform, projectDir) {
+  const { manifest, pkgDir } = platform;
+  if (!manifest.docs) return 0;
+  return copyDir(
+    resolve(pkgDir, manifest.docs),
+    resolve(projectDir, `docs/${manifest.prefix}`),
+    `docs/${manifest.prefix}/`,
+  );
+}
+
+/** Run full platform init: templates, vendor, docs, scripts, api. */
+export function initPlatform(platform, projectDir) {
+  const { manifest, pkgDir, name } = platform;
+  console.log(`\n📦 Platform detected: ${name} (${manifest.prefix})\n`);
+  copyMerge(resolve(pkgDir, manifest.templates), projectDir, 'templates');
+  vendorPlatform(platform, projectDir);
+  syncPlatformDocs(platform, projectDir);
+  if (manifest.scripts) {
+    copySkipExisting(resolve(pkgDir, manifest.scripts), resolve(projectDir, 'scripts'), 'scripts');
+  }
+  if (manifest.api) {
+    copySkipExisting(resolve(pkgDir, manifest.api), resolve(projectDir, 'api'), 'api');
+  }
+}
+
+/** Run platform update: re-vendor + sync docs only. */
+export function updatePlatform(platform, projectDir) {
+  const { name, manifest } = platform;
+  console.log(`\n📦 Platform: ${name} (${manifest.prefix})`);
+  vendorPlatform(platform, projectDir);
+  syncPlatformDocs(platform, projectDir);
+}

package/lib/platform.js

@@ -0,0 +1,52 @@
+/**
+ * Platform stacking — detect platforms in project dependencies.
+ * File operations live in platform-files.js.
+ * @module lib/platform
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export {
+  vendorPlatform, syncPlatformDocs, initPlatform, updatePlatform,
+} from './platform-files.js';
+
+/**
+ * @typedef {Object} PlatformManifest
+ * @property {string} prefix
+ * @property {string} vendorDir
+ * @property {string} configFile
+ * @property {string} templates
+ * @property {string} vendor
+ * @property {string} [docs]
+ * @property {string} [scripts]
+ * @property {string} [api]
+ */
+
+/** @typedef {{ name: string, pkgDir: string, manifest: PlatformManifest }} DetectedPlatform */
+
+/**
+ * Detect platforms in the project's dependencies.
+ * @param {string} projectDir
+ * @returns {DetectedPlatform[]}
+ */
+export function detectPlatforms(projectDir) {
+  const pkgPath = resolve(projectDir, 'package.json');
+  if (!existsSync(pkgPath)) return [];
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+  /** @type {DetectedPlatform[]} */
+  const platforms = [];
+  for (const name of Object.keys(allDeps)) {
+    const depPkg = resolve(projectDir, 'node_modules', name, 'package.json');
+    if (!existsSync(depPkg)) continue;
+    const dep = JSON.parse(readFileSync(depPkg, 'utf-8'));
+    if (!dep.clearstack?.platform) continue;
+    platforms.push({
+      name,
+      pkgDir: resolve(projectDir, 'node_modules', name),
+      manifest: dep.clearstack.platform,
+    });
+  }
+  return platforms;
+}

package/lib/spec-config.js

@@ -0,0 +1,55 @@
+/**
+ * Spec config — environment detection, .env parsing, command building.
+ * @module lib/spec-config
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+/** Detect the project's package manager runner (npx, pnpm exec, yarn). */
+export function detectRunner(projectDir) {
+  if (existsSync(resolve(projectDir, 'pnpm-lock.yaml'))) return 'pnpm exec';
+  if (existsSync(resolve(projectDir, 'yarn.lock'))) return 'yarn';
+  return 'npx';
+}
+
+/** @param {string} src */
+function parseEnv(src) {
+  const env = {};
+  for (const line of src.split('\n')) {
+    const m = line.match(/^([^#=]+)=(.*)$/);
+    if (m) env[m[1].trim()] = m[2].trim();
+  }
+  return env;
+}
+
+/**
+ * Load spec config from project .env.
+ * @param {string} projectDir
+ */
+export function loadConfig(projectDir) {
+  const envPath = resolve(projectDir, '.env');
+  const env = existsSync(envPath) ? parseEnv(readFileSync(envPath, 'utf-8')) : {};
+  return {
+    codeMax: parseInt(env.SPEC_CODE_MAX_LINES) || 150,
+    testMax: parseInt(env.SPEC_TEST_MAX_LINES) || 300,
+    docsMax: parseInt(env.SPEC_DOCS_MAX_LINES) || 500,
+    codeExt: (env.SPEC_CODE_EXTENSIONS || '.js,.css').split(','),
+    docsExt: (env.SPEC_DOCS_EXTENSIONS || '.md').split(','),
+    testPattern: env.SPEC_TEST_PATTERN || '.test.js',
+    ignore: (env.SPEC_IGNORE_DIRS || 'node_modules,src/vendor,.git,.configs').split(','),
+  };
+}
+
+/** 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`,
+    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"`,
+    audit,
+  };
+}

package/lib/spec-utils.js

@@ -59,11 +59,14 @@ export function countFiles(root, extensions, ignoreDirs, dirs, filter) {
  * @param {number} max
  * @param {string[]} ignoreDirs
  * @param {string} label
+ * @param {{ exclude?: string, include?: string }} [filter]
  * @returns {boolean}
  */
-export function checkFileLines(root, extensions, max, ignoreDirs, label) {
+export function checkFileLines(root, extensions, max, ignoreDirs, label, filter) {
   const start = performance.now();
-  const files = findFiles(root, extensions, ignoreDirs, root);
+  let files = findFiles(root, extensions, ignoreDirs, root);
+  if (filter?.exclude) files = files.filter((f) => !f.endsWith(filter.exclude));
+  if (filter?.include) files = files.filter((f) => f.endsWith(filter.include));
   const violations = [];
   for (const file of files) {
     const lines = readFileSync(resolve(root, file), 'utf-8').trimEnd().split('\n').length;

package/lib/update.js

@@ -7,6 +7,7 @@
 
 import { readdirSync, readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { resolve, join } from 'node:path';
+import { detectPlatforms, updatePlatform } from './platform.js';
 
 /**
  * Sync a source directory to a destination.
@@ -87,6 +88,13 @@ export async function update(pkgRoot, opts = {}) {
   mkdirSync(resolve(process.cwd(), 'docs/clearstack'), { recursive: true });
   writeFileSync(versionPath, pkg.version + '\n');
 
+  // Platform stacking: re-vendor + sync platform docs
+  const platforms = detectPlatforms(process.cwd());
+  for (const platform of platforms) {
+    updatePlatform(platform, process.cwd());
+    total++;
+  }
+
   console.log(`\n  docs/app-spec/ — untouched (your project specs are safe)`);
 
   if (total === 0) {

package/package.json

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

package/templates/fullstack/src/store/realtimeSync.js

@@ -33,13 +33,13 @@ export function connectRealtime(url, modelMap) {
       console.log(`[SSE] ${type} ${action} — clearing store cache`);
       try {
         store.clear([Model]);
-      } catch {
-        /* list may not exist */
+      } catch (e) {
+        console.warn(`[SSE] clear list failed for ${type}:`, e.message);
       }
       try {
         store.clear(Model);
-      } catch {
-        /* singular may not exist */
+      } catch (e) {
+        console.warn(`[SSE] clear singular failed for ${type}:`, e.message);
       }
     }, 300);
   });

package/templates/shared/.configs/eslint.config.js

@@ -39,6 +39,7 @@ export default [
       'unused-imports/no-unused-imports': 'error',
       'unused-imports/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
       'no-console': 'off',
+      'no-empty': ['error', { allowEmptyCatch: false }],
 
       // JSDoc enforcement
       'jsdoc/require-jsdoc': [

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/CONVENTIONS.md

@@ -197,6 +197,20 @@ function toggle(host) {
 }
 ```
 
+```javascript
+// BAD — silent catch hides the failure completely
+try {
+  store.clear([Model]);
+} catch {
+  /* list may not exist */
+}
+```
+
+**Never use empty `catch` blocks.** If you catch to prevent crashing,
+you must `console.warn` or `console.error` so the failure is visible.
+Silent catches turn bugs into ghosts — things "just don't work" with
+zero console output to trace.
+
 ### ✅ Do
 
 ```javascript
@@ -215,6 +229,15 @@ function toggle(host) {
 }
 ```
 
+```javascript
+// GOOD — catch to prevent crash, but log so failures are visible
+try {
+  store.clear([Model]);
+} catch (e) {
+  console.warn('[store] clear failed:', e.message);
+}
+```
+
 ---
 
 ### ✅ Always Do This
@@ -251,10 +274,24 @@ export const fullName = (user) => `${user.firstName} ${user.lastName}`;
 
 ---
 
-## File Size: Soft Warnings Before Hard Limits
+## File Size: Why 150 Lines
+
+The 150-line limit isn't about the number — it's about **context cost**.
+A 400-line file isn't hard to scroll through, but it's expensive to
+_hold in mind_. Humans can only reason about a limited scope at once.
+LLMs face the same constraint differently: every token spent reading a
+bloated file is a token not spent on the actual task. Small files mean
+context is spent on _building_, not on _understanding what you're
+looking at_.
+
+When every file is small enough to comprehend in one pass, both humans
+and LLMs can generate, review, and modify code without re-reading
+unrelated sections. Refactors become safe because the blast radius of
+any change is one small file. The limit forces decomposition into
+concept-sized units — not arbitrary chunks, but files where each one
+answers a single question.
 
-The 150-line limit is a hard gate in CI, but treat **~120 lines as a yellow
-light.** When a file passes 120 lines:
+Treat **~120 lines as a yellow light.** When a file passes 120 lines:
 
 1. Add a `// SPLIT CANDIDATE:` comment noting where a logical split could happen
 2. Continue working — don't split mid-feature
@@ -270,7 +307,9 @@ function moveObj(o, dx, dy) { ... }
 ### When a File Exceeds 150 Lines
 
 The **only correct response** is to split the file into two or more files.
-Never do any of the following to reduce line count:
+The concepts have outgrown the container — find the seam between them
+and give each its own file. Never do any of the following to reduce
+line count:
 
 - Remove or shorten JSDoc comments
 - Collapse multi-line expressions onto one line
@@ -370,7 +409,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