@techninja/clearstack 0.3.49 → 0.4.1

package/README.md

@@ -36,6 +36,7 @@ A project/task tracker that exercises every pattern in the spec: API-backed enti
 | [SERVER_AND_DEPS.md](./docs/SERVER_AND_DEPS.md)                             | Express server, import maps, vendor dependency loading         |
 | [BACKEND_API_SPEC.md](./docs/BACKEND_API_SPEC.md)                           | REST CRUD, JSON Schema via HEAD, entity management             |
 | [TESTING.md](./docs/TESTING.md)                                             | Testing philosophy, tools, patterns, phase checkpoints         |
+| [I18N.md](./docs/I18N.md)                                                   | Internationalization — 4-layer cascade, `t()` usage, conventions |
 | [BUILD_LOG.md](./docs/BUILD_LOG.md)                                         | How this project was built — LLM-human collaboration proof     |
 | [QUICKSTART.md](./docs/QUICKSTART.md)                                       | Scaffolder setup, development workflow, updating, compliance   |
 

package/docs/I18N.md

@@ -0,0 +1,197 @@
+# Internationalization (i18n)
+
+## Why This Matters
+
+Hardcoding UI strings is a foot gun. Retrofitting i18n into an existing app
+requires touching every component — a painful, error-prone refactor. Starting
+with `t('key')` or `msg\`` from day one costs almost nothing and keeps the door
+open while also clearly separating UI copy from component logic.
+
+## Two Patterns — Use Both
+
+Clearstack supports two complementary approaches. They are not mutually
+exclusive; most apps will use both.
+
+### Pattern A — `t()` cascade (non-template strings)
+
+A 4-layer message cascade resolved at call time. Best for strings outside
+Hybrids templates: error messages, queue status, validators, utility functions.
+
+```
+1. App defaults     → DEFAULTS in utils/i18n.js (English, ships with app)
+2. Locale file      → /locales/<lang>.json (e.g. es.json)
+3. Overrides        → /locales/overrides.json (project customizes English)
+4. Locale overrides → /locales/overrides.<lang>.json (project customizes locale)
+```
+
+```js
+import { t, loadLocale } from '#utils/i18n.js';
+
+// Call once at app init
+await loadLocale(navigator.language);
+
+t('general.loading')                    // → 'Loading…'
+t('task.empty')                         // → 'No tasks yet.'
+t('greeting', { name: 'James' })        // → 'Hello, James!'
+t('missing.key')                        // → 'missing.key' (never throws)
+```
+
+### Pattern B — `localize` + `msg\`` (Hybrids-native, template strings)
+
+Hybrids has first-class i18n built in. Template text content is **translated
+automatically** — no source changes needed for simple strings. Use `msg\`` for
+dynamic values, plural forms, and attribute content.
+
+```js
+import { html, define, localize, msg } from 'hybrids';
+
+// Simple static text — translated automatically, no code change needed
+html`<button>Save</button>`
+
+// Dynamic value in a template
+html`<div>${msg`${count} variants scored`}</div>`
+
+// As an attribute
+html`<my-button label="${msg`Submit`}"></my-button>`
+
+// Load translations once before first render (router/index.js or app init)
+import { localize } from 'hybrids';
+const msgs = await fetch('/locales/es.json').then(r => r.json());
+localize('es', msgs);
+```
+
+#### Plural Forms
+
+The `msg\`` helper uses`Intl.PluralRules` automatically when the dictionary
+entry is an object with plural keys:
+
+```js
+// In a template:
+html`<p>${msg`${count} variants matched`}</p>`
+
+// In locales/es.json (or via localize()):
+{
+  "${0} variants matched": {
+    "message": {
+      "one": "${0} variante encontrada",
+      "other": "${0} variantes encontradas",
+      "zero": "Ninguna variante encontrada"
+    }
+  }
+}
+```
+
+For English-only apps with irregular plurals, use `msg\`` with a`localize('default', ...)` entry:
+
+```js
+// Avoids inline ternaries like: `${n} trait${n !== 1 ? 's' : ''}`
+html`<p>${msg`${n} traits scored`}</p>`
+
+localize('default', {
+  '${0} traits scored': {
+    message: { one: '${0} trait scored', other: '${0} traits scored' }
+  }
+});
+```
+
+## Which Pattern to Use
+
+| Situation | Pattern |
+|---|---|
+| String inside `html\`` template | B — auto-translated or `msg\`` |
+| Plural form | B — `msg\`` + plural object |
+| String outside a template (util, queue, validator) | A — `t()` |
+| Attribute value on a component | B — `msg\`` in expression |
+| Brand voice / English overrides | A — `overrides.json` |
+| Adding a full language | B — `localize(lang, msgs)` |
+
+## App Init
+
+Call `loadLocale()` (Pattern A) and/or `localize()` (Pattern B) once before
+first render. The router's `connect` is the right place in a Hybrids app:
+
+```js
+// router/index.js
+import { loadLocale } from '#utils/i18n.js';
+import { localize } from 'hybrids';
+
+// Pattern A — cascade for non-template strings
+loadLocale(navigator.language);
+
+// Pattern B — load a locale file for template auto-translation
+const lang = navigator.language.split('-')[0];
+if (lang !== 'en') {
+  fetch(`/locales/${lang}.json`)
+    .then(r => r.ok ? r.json() : {})
+    .then(msgs => localize(lang, msgs));
+}
+```
+
+## Key Naming Convention (Pattern A)
+
+`domain.concept` — dot-separated, lowercase, no spaces. Keys should read as
+documentation.
+
+```
+general.loading     general.error      general.save       general.cancel
+nav.home            nav.back           nav.signIn
+error.notFound      error.offline
+task.empty          task.addTask       task.deleteConfirm
+```
+
+Avoid `button1`, `label`, or anything that doesn't describe the content.
+
+## Extracting Keys (Pattern B)
+
+Hybrids ships a CLI extractor that scans source files and generates a
+translation-ready JSON file:
+
+```bash
+npx hybrids extract ./src ./locales/en.json
+npx hybrids extract --include-path ./src ./locales/en.json
+```
+
+Wire it as a script so translators always have a fresh key file:
+
+```json
+{ "scripts": { "i18n:extract": "hybrids extract ./src ./locales/en.json" } }
+```
+
+The extractor is optional — use it when you're ready to hand off to a
+translator or add a second language.
+
+## Adding a Language
+
+1. Run `npm run i18n:extract` to get the current key list
+2. Translate into `locales/<lang>.json` — only include keys that differ
+3. Load it at init via `localize(lang, msgs)`
+4. For Pattern A overrides: add `locales/overrides.<lang>.json`
+
+## Spec Check
+
+`npm run spec code i18n` reports readiness without blocking the build:
+
+```
+✅ i18n readiness (12ms)
+   Pattern:   t() ×9, msg` ×3
+   Init:      yes · Overrides: yes · Languages: es, fr
+   Unwrapped: ~4 prose strings across 2 template files
+```
+
+- **Pattern** — which i18n calls are present and how many files use them
+- **Init** — whether `loadLocale` or `localize` is called at startup
+- **Overrides** — whether `locales/overrides.json` exists
+- **Languages** — locale files found beyond English
+- **Unwrapped** — estimated prose strings in templates not yet wrapped in
+  `t()`/`msg\`` (heuristic, not exhaustive)
+
+The check always passes — it surfaces gaps, not failures.
+
+## Rules
+
+- **Always use `t()` or `msg\`** for any user-visible string in components
+- **Never hardcode UI strings** directly in render functions
+- **Plural forms belong in the dictionary**, not inline ternaries
+- **`loadLocale()` is safe to call multiple times** — last call wins
+- **Locale files are optional** — English-only apps just use `overrides.json`
+- **Keys fall back to themselves** — `t('missing')` returns `'missing'`, never throws

package/lib/check.js

@@ -7,9 +7,11 @@
 import { existsSync, readdirSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { checkFileLines, runCmd, countFiles, checkImports } from './spec-utils.js';
+import { checkI18n } from './spec-i18n.js';
 import { loadConfig, buildCmds, detectRunner } from './spec-config.js';
 
 export { checkFileLines, runCmd, countFiles, findFiles, elapsed, checkImports } from './spec-utils.js';
+export { checkI18n } from './spec-i18n.js';
 export { loadConfig, buildCmds, detectRunner } from './spec-config.js';
 
 /** @typedef {{ key: string, name: string, parent?: string, run: () => boolean }} Check */
@@ -48,8 +50,10 @@ export function buildChecks(dir, cfg, cmds) {
       run: () => runCmd('Markdown', cmds.mdlint, dir, `${md()} files`).pass },
     { key: 'prettier', name: 'Prettier', parent: 'format',
       run: () => runCmd('Prettier', cmds.prettier, dir, `${js()} files`).pass },
-    { key: 'code', name: `Code (max ${cfg.codeMax} lines)`,
+    { key: 'lines', name: `Code (max ${cfg.codeMax} lines)`, parent: 'code',
       run: () => checkFileLines(dir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`, { exclude: cfg.testPattern }).pass },
+    { key: 'i18n', name: 'i18n readiness', parent: 'code',
+      run: () => checkI18n(dir, cfg.ignore, 'i18n readiness').pass },
     { 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 }).pass },
     { key: 'docs', name: `Docs (max ${cfg.docsMax} lines)`,

package/lib/spec-i18n.js

@@ -0,0 +1,90 @@
+/**
+ * i18n readiness check — detects patterns, locale files, hardcoded prose density.
+ * Always passes (informational). Surfaces coverage gaps without blocking the build.
+ * @module lib/spec-i18n
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { findFiles, elapsed } from './spec-utils.js';
+
+/** @typedef {import('./spec-utils.js').CheckResult} CheckResult */
+
+const PROSE_RE = />\s*[A-Z][a-z]{2,}[^<$`\\]{3,}\s*[<$]/g;
+const T_RE = /\bt\s*\(/;
+const MSG_RE = /\bmsg`/;
+const LOC_RE = /\blocalize\s*\(/;
+const INIT_RE = /loadLocale|localize\s*\(/;
+const TPL_RE = /html`[\s\S]*?`/g;
+
+/**
+ * Check i18n readiness — informational, always passes.
+ * @param {string} root
+ * @param {string[]} ignoreDirs
+ * @param {string} label
+ * @param {{ quiet?: boolean }} [opts]
+ * @returns {CheckResult}
+ */
+export function checkI18n(root, ignoreDirs, label, opts) {
+  const start = performance.now();
+  const srcFiles = findFiles(root, ['.js'], ignoreDirs, root).filter(
+    (f) =>
+      f.startsWith('src/') &&
+      !f.includes('vendor/') &&
+      !f.includes('deps/') &&
+      !f.endsWith('.test.js'),
+  );
+
+  let usesT = 0,
+    usesMsg = 0,
+    usesLocalize = 0,
+    hasInit = false,
+    hardcodedHits = 0,
+    templateFiles = 0;
+
+  for (const file of srcFiles) {
+    const src = readFileSync(resolve(root, file), 'utf-8');
+    if (T_RE.test(src)) usesT++;
+    if (MSG_RE.test(src)) usesMsg++;
+    if (LOC_RE.test(src)) usesLocalize++;
+    if (/router\/index|app.*init|main\.js/.test(file) && INIT_RE.test(src)) hasInit = true;
+    const templates = src.match(TPL_RE);
+    if (templates) {
+      templateFiles++;
+      for (const tpl of templates) {
+        const hits = tpl.match(PROSE_RE);
+        if (hits) hardcodedHits += hits.length;
+      }
+    }
+  }
+
+  const localesDir = existsSync(resolve(root, 'src/locales'))
+    ? resolve(root, 'src/locales')
+    : existsSync(resolve(root, 'locales'))
+      ? resolve(root, 'locales')
+      : null;
+
+  const localeFiles = localesDir
+    ? readdirSync(localesDir).filter((f) => f.endsWith('.json') && f !== 'overrides.json')
+    : [];
+  const languages = localeFiles.map((f) => f.replace(/\.json$/, '').replace(/^overrides\./, ''));
+  const hasOverrides = localesDir ? existsSync(resolve(localesDir, 'overrides.json')) : false;
+
+  const patternParts = [
+    usesT ? `t() ×${usesT}` : '',
+    usesMsg ? `msg\` ×${usesMsg}` : '',
+    usesLocalize ? `localize() ×${usesLocalize}` : '',
+  ].filter(Boolean);
+
+  const time = elapsed(start);
+  if (!opts?.quiet) {
+    const icon = patternParts.length ? '✅' : '⚠️ ';
+    const pattern = patternParts.length ? patternParts.join(', ') : 'none detected';
+    const langs = languages.length ? languages.join(', ') : 'en only';
+    const init = `${hasInit ? 'yes' : 'not detected'} · Overrides: ${hasOverrides ? 'yes' : 'no'} · Languages: ${langs}`;
+    const unwrapped = hardcodedHits > 0 ? `\n     Unwrapped: ~${hardcodedHits} prose strings across ${templateFiles} template files` : '';
+    console.log(`  ${icon} ${label} (${time})\n     Pattern:   ${pattern}\n     Init:      ${init}${unwrapped}`);
+  }
+
+  return { pass: true, label, time };
+}

package/package.json

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

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

@@ -0,0 +1,197 @@
+# Internationalization (i18n)
+
+## Why This Matters
+
+Hardcoding UI strings is a foot gun. Retrofitting i18n into an existing app
+requires touching every component — a painful, error-prone refactor. Starting
+with `t('key')` or `msg\`` from day one costs almost nothing and keeps the door
+open while also clearly separating UI copy from component logic.
+
+## Two Patterns — Use Both
+
+Clearstack supports two complementary approaches. They are not mutually
+exclusive; most apps will use both.
+
+### Pattern A — `t()` cascade (non-template strings)
+
+A 4-layer message cascade resolved at call time. Best for strings outside
+Hybrids templates: error messages, queue status, validators, utility functions.
+
+```
+1. App defaults     → DEFAULTS in utils/i18n.js (English, ships with app)
+2. Locale file      → /locales/<lang>.json (e.g. es.json)
+3. Overrides        → /locales/overrides.json (project customizes English)
+4. Locale overrides → /locales/overrides.<lang>.json (project customizes locale)
+```
+
+```js
+import { t, loadLocale } from '#utils/i18n.js';
+
+// Call once at app init
+await loadLocale(navigator.language);
+
+t('general.loading')                    // → 'Loading…'
+t('task.empty')                         // → 'No tasks yet.'
+t('greeting', { name: 'James' })        // → 'Hello, James!'
+t('missing.key')                        // → 'missing.key' (never throws)
+```
+
+### Pattern B — `localize` + `msg\`` (Hybrids-native, template strings)
+
+Hybrids has first-class i18n built in. Template text content is **translated
+automatically** — no source changes needed for simple strings. Use `msg\`` for
+dynamic values, plural forms, and attribute content.
+
+```js
+import { html, define, localize, msg } from 'hybrids';
+
+// Simple static text — translated automatically, no code change needed
+html`<button>Save</button>`
+
+// Dynamic value in a template
+html`<div>${msg`${count} variants scored`}</div>`
+
+// As an attribute
+html`<my-button label="${msg`Submit`}"></my-button>`
+
+// Load translations once before first render (router/index.js or app init)
+import { localize } from 'hybrids';
+const msgs = await fetch('/locales/es.json').then(r => r.json());
+localize('es', msgs);
+```
+
+#### Plural Forms
+
+The `msg\`` helper uses`Intl.PluralRules` automatically when the dictionary
+entry is an object with plural keys:
+
+```js
+// In a template:
+html`<p>${msg`${count} variants matched`}</p>`
+
+// In locales/es.json (or via localize()):
+{
+  "${0} variants matched": {
+    "message": {
+      "one": "${0} variante encontrada",
+      "other": "${0} variantes encontradas",
+      "zero": "Ninguna variante encontrada"
+    }
+  }
+}
+```
+
+For English-only apps with irregular plurals, use `msg\`` with a`localize('default', ...)` entry:
+
+```js
+// Avoids inline ternaries like: `${n} trait${n !== 1 ? 's' : ''}`
+html`<p>${msg`${n} traits scored`}</p>`
+
+localize('default', {
+  '${0} traits scored': {
+    message: { one: '${0} trait scored', other: '${0} traits scored' }
+  }
+});
+```
+
+## Which Pattern to Use
+
+| Situation | Pattern |
+|---|---|
+| String inside `html\`` template | B — auto-translated or `msg\`` |
+| Plural form | B — `msg\`` + plural object |
+| String outside a template (util, queue, validator) | A — `t()` |
+| Attribute value on a component | B — `msg\`` in expression |
+| Brand voice / English overrides | A — `overrides.json` |
+| Adding a full language | B — `localize(lang, msgs)` |
+
+## App Init
+
+Call `loadLocale()` (Pattern A) and/or `localize()` (Pattern B) once before
+first render. The router's `connect` is the right place in a Hybrids app:
+
+```js
+// router/index.js
+import { loadLocale } from '#utils/i18n.js';
+import { localize } from 'hybrids';
+
+// Pattern A — cascade for non-template strings
+loadLocale(navigator.language);
+
+// Pattern B — load a locale file for template auto-translation
+const lang = navigator.language.split('-')[0];
+if (lang !== 'en') {
+  fetch(`/locales/${lang}.json`)
+    .then(r => r.ok ? r.json() : {})
+    .then(msgs => localize(lang, msgs));
+}
+```
+
+## Key Naming Convention (Pattern A)
+
+`domain.concept` — dot-separated, lowercase, no spaces. Keys should read as
+documentation.
+
+```
+general.loading     general.error      general.save       general.cancel
+nav.home            nav.back           nav.signIn
+error.notFound      error.offline
+task.empty          task.addTask       task.deleteConfirm
+```
+
+Avoid `button1`, `label`, or anything that doesn't describe the content.
+
+## Extracting Keys (Pattern B)
+
+Hybrids ships a CLI extractor that scans source files and generates a
+translation-ready JSON file:
+
+```bash
+npx hybrids extract ./src ./locales/en.json
+npx hybrids extract --include-path ./src ./locales/en.json
+```
+
+Wire it as a script so translators always have a fresh key file:
+
+```json
+{ "scripts": { "i18n:extract": "hybrids extract ./src ./locales/en.json" } }
+```
+
+The extractor is optional — use it when you're ready to hand off to a
+translator or add a second language.
+
+## Adding a Language
+
+1. Run `npm run i18n:extract` to get the current key list
+2. Translate into `locales/<lang>.json` — only include keys that differ
+3. Load it at init via `localize(lang, msgs)`
+4. For Pattern A overrides: add `locales/overrides.<lang>.json`
+
+## Spec Check
+
+`npm run spec code i18n` reports readiness without blocking the build:
+
+```
+✅ i18n readiness (12ms)
+   Pattern:   t() ×9, msg` ×3
+   Init:      yes · Overrides: yes · Languages: es, fr
+   Unwrapped: ~4 prose strings across 2 template files
+```
+
+- **Pattern** — which i18n calls are present and how many files use them
+- **Init** — whether `loadLocale` or `localize` is called at startup
+- **Overrides** — whether `locales/overrides.json` exists
+- **Languages** — locale files found beyond English
+- **Unwrapped** — estimated prose strings in templates not yet wrapped in
+  `t()`/`msg\`` (heuristic, not exhaustive)
+
+The check always passes — it surfaces gaps, not failures.
+
+## Rules
+
+- **Always use `t()` or `msg\`** for any user-visible string in components
+- **Never hardcode UI strings** directly in render functions
+- **Plural forms belong in the dictionary**, not inline ternaries
+- **`loadLocale()` is safe to call multiple times** — last call wins
+- **Locale files are optional** — English-only apps just use `overrides.json`
+- **Keys fall back to themselves** — `t('missing')` returns `'missing'`, never throws

package/templates/shared/src/locales/overrides.json

@@ -0,0 +1,3 @@
+{
+  "general.loading": "Loading…"
+}

package/templates/shared/src/utils/i18n.js

@@ -0,0 +1,87 @@
+/**
+ * i18n — 4-layer message cascade.
+ *
+ * Resolution order (last wins):
+ * 1. App defaults (English, defined in this file)
+ * 2. Locale file (/locales/<lang>.json)
+ * 3. Project overrides (/locales/overrides.json)
+ * 4. Project locale overrides (/locales/overrides.<lang>.json)
+ *
+ * Usage:
+ *   import { t, loadLocale } from '#utils/i18n.js';
+ *   await loadLocale(navigator.language); // call once at app init
+ *   t('general.loading')                 // → 'Loading…'
+ *   t('greeting', { name: 'James' })     // → 'Hello, James!'
+ *
+ * Key convention: component.action or domain.concept
+ * Add app-specific defaults below and override per-project in overrides.json.
+ * @module utils/i18n
+ */
+
+/** @type {Record<string, string>} */
+const DEFAULTS = {
+  'general.loading': 'Loading…',
+  'general.error': 'Something went wrong.',
+  'general.retry': 'Try again',
+  'general.back': 'Back',
+  'general.close': 'Close',
+  'general.save': 'Save',
+  'general.cancel': 'Cancel',
+  'general.confirm': 'Confirm',
+  'general.noResults': 'No results found.',
+  'nav.home': 'Home',
+  'error.notFound': 'Page not found.',
+  'error.offline': 'You appear to be offline.',
+};
+
+/** @type {Record<string, string>} */
+let active = { ...DEFAULTS };
+
+/** @param {string} url @returns {Promise<Record<string, string>>} */
+async function fetchJson(url) {
+  try {
+    const res = await fetch(url);
+    return res.ok ? await res.json() : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Load and merge all i18n layers. Call once on app init.
+ * @param {string} [locale] - BCP 47 locale string e.g. 'es', 'es-MX'
+ */
+export async function loadLocale(locale) {
+  const lang = locale?.split('-')[0] || '';
+  const isEnglish = !lang || lang === 'en';
+
+  const [localeStrings, overrides, localeOverrides] = await Promise.all([
+    isEnglish ? {} : fetchJson(`/locales/${lang}.json`),
+    fetchJson('/locales/overrides.json'),
+    isEnglish ? {} : fetchJson(`/locales/overrides.${lang}.json`),
+  ]);
+
+  active = { ...DEFAULTS, ...localeStrings, ...overrides, ...localeOverrides };
+}
+
+/**
+ * Get a translated string with optional {param} interpolation.
+ * Falls back to the key itself if not found.
+ * @param {string} key
+ * @param {Record<string, string>} [params]
+ * @returns {string}
+ */
+export function t(key, params) {
+  let msg = active[key] ?? key;
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      msg = msg.replace(`{${k}}`, v);
+    }
+  }
+  return msg;
+}
+
+/** @returns {string} Active locale language code e.g. 'en', 'es' */
+export function getLocale() {
+  return navigator.language?.split('-')[0] || 'en';
+}