@techninja/clearstack 0.3.17 → 0.3.20

package/docs/STATE_AND_ROUTING.md

@@ -253,6 +253,43 @@ This applies to any property with `value: []` and an async `connect`.
 The `connect` callback sets the value and calls `invalidate()`, but the
 first render happens before that resolves.
 
+#### Async Init with Child Component Props
+
+When a parent loads data during `connect` and passes it to a child via
+template props, the child may never see the change. Hybrids' change
+detection requires observing old → new. If the prop is set before the
+child mounts, there's no "old" value to compare against.
+
+```javascript
+// ❌ BAD — resultCount set during connect, before child mounts
+_init: {
+  value: false,
+  connect: (host, _key, invalidate) => {
+    loadData(host).then(() => {
+      host.resultCount = 14;
+      invalidate(); // child mounts with 14, never sees a change
+    });
+  },
+},
+```
+
+The fix: defer the prop update to after the first render frame so the
+child is mounted and can observe the transition:
+
+```javascript
+// ✅ GOOD — child mounts with default (0), then sees 0 → 14
+connect: (host, _key, invalidate) => {
+  loadData(host).then(() => {
+    invalidate();
+    requestAnimationFrame(() => { host.resultCount = loadedCount; });
+  });
+},
+```
+
+Pre-populate external caches during `loadData` so the child has data
+ready when the deferred update triggers. The 0 → 14 transition happens
+within a single frame — no flicker.
+
 ---
 
 ## Routing
@@ -410,37 +447,16 @@ For live data updates, the backend pushes events via **Server-Sent Events
 
 ### Frontend: SSE Listener
 
-Lives in `src/utils/realtimeSync.js`:
-
-```javascript
-import { store } from 'hybrids';
-
-export function connectRealtime(url, modelMap) {
-  const source = new EventSource(url);
-
-  source.addEventListener('update', (event) => {
-    const { type } = JSON.parse(event.data);
-    const Model = modelMap[type];
-    if (Model) store.clear(Model); // full clear triggers re-fetch
-  });
-
-  source.addEventListener('error', () => {
-    source.close();
-    setTimeout(() => connectRealtime(url, modelMap), 5000);
-  });
-
-  return () => source.close();
-}
-```
+`src/utils/realtimeSync.js` connects to the SSE endpoint, listens for
+`update` events, and calls `store.clear(Model)` to invalidate the cache.
+Any component bound via `store()` re-fetches automatically.
 
-`store.clear(Model)` fully invalidates the cache for that model type.
-Any component bound to the model via `store()` will automatically re-fetch
-from the API. This is the mechanism that makes multi-user realtime work —
-when user A creates a task, user B's task list updates automatically.
+The listener reconnects on error (5s delay) and returns a disconnect
+function for cleanup in the router shell's `connect` descriptor.
 
-For the local user, form submit handlers also call `store.clear(Model)`
-immediately after a successful save. The SSE event that follows is
-redundant for the local user but ensures other connected clients update.
+`store.clear(Model)` is also called by form submit handlers after a
+successful save. The SSE event that follows is redundant for the local
+user but ensures other connected clients update.
 
 ### Backend: SSE Endpoint
 
@@ -449,31 +465,20 @@ contract.
 
 ### Wiring It Up
 
-In the router shell's `connect` descriptor:
+In the router shell, use a `connect` descriptor to start SSE and return
+the disconnect function. Map entity types to store models:
 
 ```javascript
-import { connectRealtime } from '../utils/realtimeSync.js';
-import UserModel from '../store/UserModel.js';
-
-export default define({
-  tag: 'app-router',
-  stack: router(HomeView, { url: '/' }),
-  connection: {
-    value: undefined,
-    connect(host) {
-      const disconnect = connectRealtime('/api/events', {
-        user: UserModel,
-      });
-      return disconnect;
-    },
+connection: {
+  value: undefined,
+  connect(host) {
+    return connectRealtime('/api/events', { user: UserModel });
   },
-  render: ({ stack }) => html` <template layout="column height::100vh">${stack}</template> `,
-});
+},
 ```
 
-When the backend sends `{ type: "user", id: "42" }` over SSE, the store
-cache for `UserModel` is cleared, and any component displaying that user
-re-fetches automatically.
+When the backend sends `{ type: "user" }` over SSE, the store cache for
+`UserModel` is cleared and any bound component re-fetches automatically.
 
 ### Debouncing Batch Operations
 

package/lib/check.js

@@ -1,64 +1,20 @@
 /**
- * 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, readdirSync } 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';
-
-/** 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';
-}
-
-/** @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,
-    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"`,
-    audit,
-  };
-}
-
+export { loadConfig, buildCmds, detectRunner } from './spec-config.js';
 
 /** @typedef {{ key: string, name: string, parent?: string, run: () => boolean }} Check */
 
-/** Find all jsconfig.json files — main config + any in subdirectories. */
+/** Find all jsconfig.json files — main config + subdirectories. */
 function findTypeConfigs(dir, runner) {
   const main = resolve(dir, '.configs/jsconfig.json');
   const configs = [];
@@ -74,8 +30,10 @@ function findTypeConfigs(dir, runner) {
   }));
 }
 
-/** Build the unified checks array. Children have a `parent` key.
- * @returns {Check[]} */
+/**
+ * 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);
@@ -91,7 +49,9 @@ 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)',

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

@@ -22,6 +22,7 @@ export async function writePackageJson(dest, vars, existing) {
     postinstall: 'node scripts/setup.js',
     test: 'node scripts/test.js',
     spec: 'node scripts/spec.js',
+    release: 'node scripts/release.js',
   };
 
   const specDeps = {

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.17",
+  "version": "0.3.20",
   "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/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    name: Publish to npm + GitHub Release
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+
+      - run: npm ci
+
+      - name: Publish to npm
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Generate changelog from commits
+        id: changelog
+        run: |
+          PREV_TAG=$(git tag --sort=-v:refname | sed -n '2p')
+          if [ -z "$PREV_TAG" ]; then
+            LOG=$(git log --pretty=format:"- %s (%h)" HEAD)
+          else
+            LOG=$(git log --pretty=format:"- %s (%h)" "$PREV_TAG"..HEAD)
+          fi
+          echo "log<<EOF" >> "$GITHUB_OUTPUT"
+          echo "$LOG" >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: |
+            ## Changes
+            ${{ steps.changelog.outputs.log }}
+          generate_release_notes: true

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