@helical-design/substrate 0.1.0

package/src/harness.mjs

@@ -0,0 +1,449 @@
+// src/harness.mjs — reusable build-substrate checks. Each check takes a project
+// `root` and returns string[] (empty = pass, non-empty = offender descriptions).
+// runHarness aggregates them into { ok, violations }. Scaffolded projects inherit
+// this harness so every surface is held to the same gates.
+import {
+  readFileSync, readdirSync, statSync, existsSync, mkdtempSync, rmSync,
+} from 'node:fs';
+import { join, relative, extname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { wcagContrast } from 'culori';
+import { loadStore } from './store.mjs';
+import { buildContent } from './build.mjs';
+import { buildTokens } from './tokens.mjs';
+import { PROFILES, buildScale, generateScale } from './scale.mjs';
+
+const HEX = /#[0-9a-fA-F]{3,8}\b/;
+const AA = 4.5;
+// Static-asset extensions. An href ending in one of these is an asset reference
+// (stylesheet, script, image, font…), not a navigational page link — link
+// integrity only governs page-to-page navigation.
+const ASSET_EXT = new Set([
+  '.css', '.js', '.mjs', '.svg', '.png', '.jpg', '.jpeg', '.gif', '.webp',
+  '.ico', '.woff', '.woff2', '.map', '.json', '.txt', '.xml', '.pdf',
+]);
+// Context keys supplied by the build runtime rather than the content store:
+// the layout body slot, and per-entry loop aliases / collection slugs.
+const RUNTIME_KEYS = new Set(['body', 'slug', 'entry']);
+
+// --- shared helpers ---------------------------------------------------------
+
+function walk(dir, exts, out = []) {
+  if (!existsSync(dir)) return out;
+  for (const f of readdirSync(dir)) {
+    const p = join(dir, f);
+    if (statSync(p).isDirectory()) { walk(p, exts, out); continue; }
+    if (exts.includes(extname(f))) out.push(p);
+  }
+  return out;
+}
+
+function readPages(root) {
+  const manifest = join(root, 'pages.json');
+  return existsSync(manifest) ? JSON.parse(readFileSync(manifest, 'utf8')) : [];
+}
+
+function pageTemplates(root) {
+  return walk(join(root, 'templates', 'pages'), ['.html']);
+}
+
+// Strip {{ ... }} interpolation/blocks so we can reason about literal markup.
+function stripInterpolation(html) {
+  return html.replace(/\{\{[\s\S]*?\}\}/g, '');
+}
+
+// Build the project into a fresh temp dir and return that dir. Throws on build
+// failure; callers wrap in try/catch and surface the message as a violation.
+function buildInto(root, dir) {
+  buildContent({
+    contentDir: join(root, 'content'),
+    templatesDir: join(root, 'templates'),
+    outDir: dir,
+    pages: readPages(root),
+  });
+  return dir;
+}
+
+// Build tokens into a throwaway temp dir and return the combined CSS. Never
+// touches the working-tree dist/ — every build-dependent check is isolated so
+// parallel test files can't race on a shared output path.
+async function buildTokensCss(root) {
+  const dir = mkdtempSync(join(tmpdir(), 'helical-harness-'));
+  try {
+    await buildTokens(root, dir);
+    return readFileSync(join(dir, 'tokens.css'), 'utf8');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// --- checks -----------------------------------------------------------------
+
+// Hardcoded hex literals in templates/components (must use var()/tokens instead).
+// `dirs` overrides which subdirectories of `root` are scanned (default: the
+// template + component trees a scaffolded project ships).
+export function checkNoHardcodedHex(root, { dirs = ['templates', 'components'] } = {}) {
+  const offenders = [];
+  for (const base of dirs) {
+    for (const p of walk(join(root, base), ['.html', '.css'])) {
+      readFileSync(p, 'utf8').split('\n').forEach((line, i) => {
+        if (HEX.test(line)) offenders.push(`${relative(root, p)}:${i + 1}: ${line.trim()}`);
+      });
+    }
+  }
+  return offenders;
+}
+
+// User-visible prose sitting outside {{ }} in a page template. Heading text
+// (h1–h6) is the one sanctioned exception (section/heading labels live in markup).
+export function checkNoInlineCopy(root) {
+  const offenders = [];
+  for (const p of pageTemplates(root)) {
+    let html = stripInterpolation(readFileSync(p, 'utf8'));
+    // Headings are exempt: drop their text content before inspecting the rest.
+    html = html.replace(/<(h[1-6])\b[^>]*>[\s\S]*?<\/\1>/gi, '');
+    // Inspect text nodes that sit between tags.
+    for (const m of html.matchAll(/>([^<]+)</g)) {
+      const text = m[1].replace(/\s+/g, ' ').trim();
+      // Prose = a real sentence of words; ignore whitespace, slot markers, and
+      // stray single tokens (e.g. %%BODY%%) that aren't user-facing copy.
+      const words = text.split(' ').filter((w) => /[A-Za-z]/.test(w));
+      if (words.length >= 3) offenders.push(`${relative(root, p)}: inline copy: "${text}"`);
+    }
+  }
+  return offenders;
+}
+
+// Collect the top-level context keys a page template references.
+function referencedKeys(html) {
+  const keys = new Set();
+  for (const m of html.matchAll(/\{\{\s*#?\s*(?:each\s+)?([\w.]+)/g)) {
+    const head = m[1].split('.')[0];
+    if (head && head !== '.') keys.add(head);
+  }
+  return keys;
+}
+
+// Orphan content keys (in store, referenced by no template) AND template-
+// referenced keys missing from the store.
+export function checkContentCompleteness(root) {
+  const contentDir = join(root, 'content');
+  const store = existsSync(contentDir) ? loadStore(contentDir) : {};
+  const storeKeys = new Set(Object.keys(store));
+
+  // Loop aliases declared in the page manifest are runtime-provided, not store keys.
+  const aliases = new Set(RUNTIME_KEYS);
+  for (const p of readPages(root)) if (p.as) aliases.add(p.as);
+
+  const referenced = new Set();
+  for (const p of pageTemplates(root)) {
+    for (const k of referencedKeys(readFileSync(p, 'utf8'))) referenced.add(k);
+  }
+
+  const offenders = [];
+  for (const k of storeKeys) {
+    if (!referenced.has(k)) offenders.push(`orphan content key: ${k} (referenced by no template)`);
+  }
+  for (const k of referenced) {
+    if (!storeKeys.has(k) && !aliases.has(k)) offenders.push(`missing content key: ${k} (referenced by a template, absent from store)`);
+  }
+  return offenders;
+}
+
+// Internal href="/x" links with no corresponding output page.
+//
+// Static by design: the set of expected output pages is derived directly from
+// the page manifest (the same `pages` list buildContent consumes), and internal
+// links are scanned from the raw template files. This check never builds the
+// project, so an unrelated missing content key (a content-completeness
+// violation) can no longer crash it — a broken link and a missing key are
+// independent violations and each is reported by its own check.
+export function checkLinkIntegrity(root) {
+  // 1. Expected output pages from the manifest. Collection rows (forEach) expand
+  //    one output per item; here we can't know the slugs without the store, so a
+  //    parametric `:slug` out is treated as a wildcard target prefix below.
+  const outs = [];
+  const slugPrefixes = [];
+  for (const p of readPages(root)) {
+    if (!p.out) continue;
+    if (p.out.includes(':slug')) {
+      // e.g. "journal/:slug.html" -> any href under "journal/" is considered live.
+      slugPrefixes.push('/' + p.out.split(':slug')[0].split('\\').join('/'));
+    } else {
+      outs.push('/' + p.out.split('\\').join('/'));
+    }
+  }
+  const pages = new Set(outs);
+
+  const isKnown = (href) => {
+    const target = href === '/' ? '/index.html' : href;
+    const candidates = [target];
+    if (!extname(target)) candidates.push(target + '.html', target + '/index.html');
+    if (candidates.some((c) => pages.has(c))) return true;
+    // A parametric collection out (".../:slug.html") covers any href under it.
+    return slugPrefixes.some((pre) => target.startsWith(pre));
+  };
+
+  // 2. Scan raw template files (pages, layout, partials) for internal hrefs.
+  const templatesDir = join(root, 'templates');
+  const templateFiles = [
+    ...pageTemplates(root),
+    ...walk(templatesDir, ['.html']).filter((p) => !p.includes(join('templates', 'pages'))),
+  ];
+  const seen = new Set();
+  const offenders = [];
+  for (const p of templateFiles) {
+    if (seen.has(p)) continue;
+    seen.add(p);
+    const html = readFileSync(p, 'utf8');
+    for (const m of html.matchAll(/href="(\/[^"#?]*)/g)) {
+      const href = m[1];
+      if (ASSET_EXT.has(extname(href).toLowerCase())) continue; // asset ref, not a page link
+      if (!isKnown(href)) {
+        offenders.push(`broken internal link: href="${href}" has no output page`);
+      }
+    }
+  }
+  return offenders;
+}
+
+// Parse a tokens.css mode block into { varName: hex }.
+function modeVars(css, selector) {
+  const m = css.match(new RegExp(selector.replace(/[[\]]/g, '\\$&') + '\\s*{([^}]*)}'));
+  const vars = {};
+  for (const line of (m ? m[1] : '').split(';')) {
+    const kv = line.match(/--([\w-]+):\s*(#[0-9a-fA-F]{6})/);
+    if (kv) vars[kv[1]] = kv[2];
+  }
+  return vars;
+}
+
+const CONTRAST_PAIRS = [
+  ['color-text', 'color-bg'], ['color-text', 'color-surface'],
+  ['color-text-secondary', 'color-bg'], ['color-on-accent', 'color-accent-solid'],
+];
+
+// Token text/surface pairs that fall below WCAG AA in either mode.
+export async function checkContrastAA(root) {
+  const offenders = [];
+  let css;
+  try {
+    css = await buildTokensCss(root);
+  } catch (e) {
+    return [`contrast-AA: token build failed: ${e.message}`];
+  }
+  for (const [mode, selector] of [['dark', ':root'], ['light', '[data-mode="light"]']]) {
+    const vars = modeVars(css, selector);
+    for (const [fg, bg] of CONTRAST_PAIRS) {
+      if (!vars[fg] || !vars[bg]) continue;
+      const ratio = wcagContrast(vars[fg], vars[bg]);
+      if (ratio < AA) offenders.push(`${mode}: ${fg} on ${bg} = ${ratio.toFixed(2)} (< ${AA})`);
+    }
+  }
+  return offenders;
+}
+
+// Two builds of the project are byte-identical (content + tokens).
+export async function checkDeterminism(root) {
+  const a = mkdtempSync(join(tmpdir(), 'helical-det-a-'));
+  const b = mkdtempSync(join(tmpdir(), 'helical-det-b-'));
+  try {
+    buildInto(root, a);
+    buildInto(root, b);
+    const tokens = await buildTokensCss(root); // also exercise token determinism
+    const tokens2 = await buildTokensCss(root);
+    const offenders = [];
+    if (tokens !== tokens2) offenders.push('determinism: tokens.css differs between builds');
+    const filesA = walk(a, ['.html']).map((p) => relative(a, p)).sort();
+    const filesB = walk(b, ['.html']).map((p) => relative(b, p)).sort();
+    if (filesA.join('|') !== filesB.join('|')) {
+      offenders.push('determinism: output file set differs between builds');
+    }
+    for (const f of filesA) {
+      if (!filesB.includes(f)) continue;
+      if (readFileSync(join(a, f), 'utf8') !== readFileSync(join(b, f), 'utf8')) {
+        offenders.push(`determinism: ${f} differs between builds`);
+      }
+    }
+    return offenders;
+  } catch (e) {
+    return [`determinism: build failed: ${e.message}`];
+  } finally {
+    rmSync(a, { recursive: true, force: true });
+    rmSync(b, { recursive: true, force: true });
+  }
+}
+
+// Diff dist/ against a committed golden snapshot if one exists; [] when none.
+export async function checkGoldenSnapshot(root, { goldenDir = join(root, 'golden') } = {}) {
+  if (!existsSync(goldenDir)) return [];
+  const dir = mkdtempSync(join(tmpdir(), 'helical-golden-'));
+  try {
+    buildInto(root, dir);
+    const offenders = [];
+    const goldenFiles = walk(goldenDir, ['.html']).map((p) => relative(goldenDir, p)).sort();
+    const builtFiles = walk(dir, ['.html']).map((p) => relative(dir, p)).sort();
+    for (const f of goldenFiles) {
+      if (!builtFiles.includes(f)) { offenders.push(`golden: missing output for ${f}`); continue; }
+      if (readFileSync(join(goldenDir, f), 'utf8') !== readFileSync(join(dir, f), 'utf8')) {
+        offenders.push(`golden: ${f} diverges from committed snapshot`);
+      }
+    }
+    for (const f of builtFiles) {
+      if (!goldenFiles.includes(f)) offenders.push(`golden: unexpected output ${f} (not in snapshot)`);
+    }
+    return offenders;
+  } catch (e) {
+    return [`golden: build failed: ${e.message}`];
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// --- scale guards -----------------------------------------------------------
+
+const SIZE_ROLES = ['caption', 'small', 'body', 'h3', 'h2', 'h1'];
+const isAscending = (a) => a.every((v, i) => i === 0 || v > a[i - 1]);
+
+// Structural invariants of the generative scale, asserted on both shipped
+// profiles: ladders strictly monotonic (both densities), the ratio guard rejects
+// degenerate ratios, the a11y target clears 24px and is density-stable, and the
+// compact font floor holds (body ≥14px, smallest role ≥12px).
+export function checkScale() {
+  const offenders = [];
+  for (const cfg of Object.values(PROFILES)) {
+    let s;
+    try { s = buildScale(cfg); }
+    catch (e) { offenders.push(`scale: ${cfg.name} buildScale threw: ${e.message}`); continue; }
+
+    for (const d of ['comfy', 'compact', 'spacious']) {
+      if (!isAscending(s[d].space)) offenders.push(`scale: ${cfg.name} ${d} space not monotonic`);
+      const sizes = SIZE_ROLES.map((k) => s[d].size[k]);
+      if (!isAscending(sizes)) offenders.push(`scale: ${cfg.name} ${d} size not monotonic`);
+      for (const v of sizes) {
+        if (v < 12) offenders.push(`scale: ${cfg.name} ${d} type ${v}px < 12px a11y floor`);
+      }
+    }
+    if (s.compact.size.body < 14) offenders.push(`scale: ${cfg.name} compact body ${s.compact.size.body}px < 14px floor`);
+
+    // Cross-density monotonicity: compact ≤ comfy ≤ spacious at every step (ties OK
+    // at the grid-floored bottom). A density that crossed over would be a bug.
+    for (let i = 0; i < s.comfy.space.length; i++) {
+      if (!(s.compact.space[i] <= s.comfy.space[i] && s.comfy.space[i] <= s.spacious.space[i])) {
+        offenders.push(`scale: ${cfg.name} space step ${i + 1} breaks compact≤comfy≤spacious`);
+      }
+    }
+    for (const k of SIZE_ROLES) {
+      if (!(s.compact.size[k] <= s.comfy.size[k] && s.comfy.size[k] <= s.spacious.size[k])) {
+        offenders.push(`scale: ${cfg.name} size.${k} breaks compact≤comfy≤spacious`);
+      }
+    }
+
+    // Leading couples to density (v2): body tightens compact / loosens spacious,
+    // floored at 1.4; heading `tight` leading is density-stable (:root only).
+    if (!(s.compact.leading.body <= s.comfy.leading.body && s.comfy.leading.body <= s.spacious.leading.body)) {
+      offenders.push(`scale: ${cfg.name} leading.body not coupled compact≤comfy≤spacious`);
+    }
+    if (s.compact.leading.body < 1.4) offenders.push(`scale: ${cfg.name} compact leading.body ${s.compact.leading.body} < 1.4 floor`);
+
+    // a11y SC 2.5.8 — target.min ≥24px and density-stable. radius/tracking/target
+    // must never leak into a density block; the density set is ⊆ {space,size,leading}.
+    if (s.comfy.target.min < 24) offenders.push(`scale: ${cfg.name} target.min ${s.comfy.target.min}px < 24px (SC 2.5.8)`);
+    for (const d of ['compact', 'spacious']) {
+      if (s[d].target !== undefined) offenders.push(`scale: ${cfg.name} ${d} carries target (must be density-stable)`);
+      if (s[d].radius !== undefined) offenders.push(`scale: ${cfg.name} ${d} carries radius (must be density-stable)`);
+      const extra = Object.keys(s[d]).filter((k) => !['space', 'size', 'leading'].includes(k));
+      if (extra.length) offenders.push(`scale: ${cfg.name} ${d} carries groups beyond space+size+leading: ${extra.join(',')}`);
+    }
+
+    // Size-coupled tracking (em): tighter as type grows → h1 ≤ h2 ≤ h3 numerically
+    // (h1 most negative). Each within the profile's [min, max] bounds.
+    const { h1, h2, h3 } = s.comfy.tracking;
+    if (!(h1 <= h2 && h2 <= h3)) offenders.push(`scale: ${cfg.name} tracking not monotonic by size (h1≤h2≤h3): ${h1},${h2},${h3}`);
+    for (const [role, v] of Object.entries(s.comfy.tracking)) {
+      if (v < cfg.tracking.min || v > cfg.tracking.max) {
+        offenders.push(`scale: ${cfg.name} tracking.${role} ${v} outside [${cfg.tracking.min}, ${cfg.tracking.max}]`);
+      }
+    }
+  }
+  // Ratio guard wired correctly (degenerate ratios throw).
+  for (const bad of [1, 2, 0.9, 2.5]) {
+    let threw = false;
+    try { buildScale({ ...PROFILES.ui, typeRatio: bad }); } catch { threw = true; }
+    if (!threw) offenders.push(`scale: ratio guard failed to reject typeRatio=${bad}`);
+  }
+  return offenders;
+}
+
+// Anti-staleness: regenerate the committed scale goldens into a temp dir and
+// byte-compare. Catches a hand-edited or out-of-date tokens/scale*.json — the
+// self-comparing determinism check cannot. Skipped when no goldens exist.
+export function checkScaleStaleness(root) {
+  const files = ['tokens/scale.json', 'tokens/scale.compact.json', 'tokens/scale.spacious.json'];
+  if (!files.every((f) => existsSync(join(root, f)))) return [];
+  const dir = mkdtempSync(join(tmpdir(), 'helical-scale-stale-'));
+  try {
+    generateScale('ui', dir);
+    const offenders = [];
+    for (const f of files) {
+      if (readFileSync(join(dir, f), 'utf8') !== readFileSync(join(root, f), 'utf8')) {
+        offenders.push(`scale: ${f} is stale vs generator output (run gen:scale)`);
+      }
+    }
+    return offenders;
+  } catch (e) {
+    return [`scale: staleness check failed: ${e.message}`];
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// Resolution: every var(--x) consumed by the seed base.css / showcase.css must
+// have a matching --x: declaration in the built tokens.css. A scale rename or a
+// dropped group surfaces here as a dangling var before it ships.
+export async function checkScaleResolution(root, { consumers } = {}) {
+  const files = consumers ?? [
+    join(root, 'templates/profiles/_base/assets/base.css'),
+    join(root, 'showcase/showcase.css'),
+  ].filter((p) => existsSync(p));
+  if (!files.length) return [];
+  let css;
+  try { css = await buildTokensCss(root); }
+  catch (e) { return [`scale-resolution: token build failed: ${e.message}`]; }
+  const declared = new Set([...css.matchAll(/--([a-z0-9-]+):/g)].map((m) => m[1]));
+  const missing = new Set();
+  for (const f of files) {
+    for (const m of readFileSync(f, 'utf8').matchAll(/var\(--([a-z0-9-]+)\)/g)) {
+      if (!declared.has(m[1])) missing.add(m[1]);
+    }
+  }
+  return [...missing].map((v) => `scale-resolution: var(--${v}) consumed but never declared`);
+}
+
+// Pure-static checks (synchronous) and build-dependent checks (async). They are
+// kept separate so the runner can await the latter without forcing the former.
+const SYNC_CHECKS = {
+  checkNoHardcodedHex, checkNoInlineCopy, checkContentCompleteness, checkLinkIntegrity,
+  checkScale, checkScaleStaleness,
+};
+const ASYNC_CHECKS = {
+  checkContrastAA, checkDeterminism, checkGoldenSnapshot, checkScaleResolution,
+};
+
+// Aggregate every check into a single { ok, violations } result.
+export async function runHarness(root, opts = {}) {
+  const violations = [];
+  for (const [name, fn] of Object.entries(SYNC_CHECKS)) {
+    let out;
+    try { out = fn(root, opts); }
+    catch (e) { out = [`${name}: threw: ${e.message}`]; }
+    for (const o of out) violations.push(`[${name}] ${o}`);
+  }
+  for (const [name, fn] of Object.entries(ASYNC_CHECKS)) {
+    let out;
+    try { out = await fn(root, opts); }
+    catch (e) { out = [`${name}: threw: ${e.message}`]; }
+    for (const o of out) violations.push(`[${name}] ${o}`);
+  }
+  return { ok: violations.length === 0, violations };
+}

package/src/index.mjs

@@ -0,0 +1,19 @@
+export { render } from './render.mjs';
+export { loadStore } from './store.mjs';
+export { resolvePages } from './pages.mjs';
+export { buildContent } from './build.mjs';
+export { build } from './build-all.mjs';
+export { generatePalette } from './palette.mjs';
+export { PROFILES, buildScale, generateScale } from './scale.mjs';
+export { buildTokens } from './tokens.mjs';
+export { buildRegistry } from './registry.mjs';
+export {
+  checkNoHardcodedHex, checkNoInlineCopy, checkContentCompleteness,
+  checkLinkIntegrity, checkContrastAA, checkDeterminism, checkGoldenSnapshot,
+  checkScale, checkScaleStaleness, checkScaleResolution,
+  runHarness,
+} from './harness.mjs';
+export { scaffold } from './scaffold.mjs';
+export { createDb, assertPooled } from './db/client.mjs';
+export { nearest } from './db/vector.mjs';
+export { documents } from './db/schema.mjs';

package/src/pages.mjs

@@ -0,0 +1,14 @@
+// Resolve a page manifest into concrete pages. Config-driven; supports collection expansion.
+export function resolvePages(pages, store) {
+  const out = [];
+  for (const p of pages) {
+    if (p.forEach) {
+      for (const item of (store[p.forEach] || [])) {
+        out.push({ out: p.out.replace(':slug', item.slug), template: p.template, context: { ...store, [p.as || 'entry']: item } });
+      }
+    } else {
+      out.push({ out: p.out, template: p.template, context: store });
+    }
+  }
+  return out;
+}

package/src/palette.mjs

@@ -0,0 +1,39 @@
+// Editorial Neon — Leonardo-generated accessible ramps, emitted as DTCG per mode.
+// Neutral = violet-tinted gray (synth heart); single brand accent = cyan.
+import { Theme, Color, BackgroundColor } from '@adobe/leonardo-contrast-colors';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const neutral = new BackgroundColor({ name: 'neutral', colorKeys: ['#8d86a8'], ratios: [1.12, 1.35, 1.9, 3, 4.5, 7, 11, 16] });
+const accent  = new Color({ name: 'accent',  colorKeys: ['#36d6e6'], ratios: [1.4, 2.4, 3.2, 4.5, 7, 9.5] });
+const success = new Color({ name: 'success', colorKeys: ['#3fd6a0'], ratios: [3, 4.5, 7] });
+const danger  = new Color({ name: 'danger',  colorKeys: ['#ff5d73'], ratios: [3, 4.5, 7] });
+
+function ramps(lightness) {
+  const t = new Theme({ colors: [neutral, accent, success, danger], backgroundColor: neutral, lightness, contrast: 1, saturation: 100 });
+  const out = {};
+  for (const c of t.contrastColors) {
+    if (c.background) { out.bg = c.background; continue; }
+    out[c.name] = c.values.map((v) => v.value);
+  }
+  return out;
+}
+
+function toDtcg(r) {
+  const grp = (arr) => Object.fromEntries(arr.map((hex, i) => [String(i + 1), { $value: hex, $type: 'color' }]));
+  return {
+    palette: {
+      bg: { $value: r.bg, $type: 'color' },
+      neutral: grp(r.neutral),
+      accent: grp(r.accent),
+      success: grp(r.success),
+      danger: grp(r.danger)
+    }
+  };
+}
+
+export function generatePalette(root = '.') {
+  mkdirSync(join(root, 'tokens'), { recursive: true });
+  writeFileSync(join(root, 'tokens/palette.dark.json'), JSON.stringify(toDtcg(ramps(8)), null, 2) + '\n');
+  writeFileSync(join(root, 'tokens/palette.light.json'), JSON.stringify(toDtcg(ramps(97)), null, 2) + '\n');
+}

package/src/registry.mjs

@@ -0,0 +1,29 @@
+// Convert built CSS variables into a shadcn registry:theme item.
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+function vars(css, selector) {
+  const m = css.match(new RegExp(selector.replace(/[[\]]/g, '\\$&') + '\\s*{([^}]*)}'));
+  const out = {};
+  for (const line of (m ? m[1] : '').split(';')) {
+    const kv = line.match(/--([\w-]+):\s*([^;]+)/);
+    if (kv) out[kv[1].trim()] = kv[2].trim();
+  }
+  return out;
+}
+
+export function buildRegistry(root = '.') {
+  const css = readFileSync(join(root, 'dist/tokens.css'), 'utf8');
+  const item = {
+    $schema: 'https://ui.shadcn.com/schema/registry-item.json',
+    name: 'editorial-neon',
+    type: 'registry:theme',
+    cssVars: {
+      dark: vars(css, ':root'),
+      light: vars(css, '[data-mode="light"]')
+    }
+  };
+
+  mkdirSync(join(root, 'dist/registry'), { recursive: true });
+  writeFileSync(join(root, 'dist/registry/editorial-neon.json'), JSON.stringify(item, null, 2) + '\n');
+}

package/src/render.mjs

@@ -0,0 +1,43 @@
+// Deterministic, fail-loud template resolver.
+// Grammar: {{ a.b.c }} | {{ . }} | {{> partial }} | {{# each key }}…{{/each}}
+
+function lookup(path, ctx) {
+  if (path === '.') return ctx;
+  const val = path.split('.').reduce((o, k) => (o == null ? o : o[k]), ctx);
+  if (val === undefined || val === null) throw new Error(`render: missing key: ${path}`);
+  return val;
+}
+
+function renderEach(tpl, ctx) {
+  // single-level only — nested {{# each }} is not supported (non-greedy regex).
+  const re = /\{\{#\s*each\s+([\w.]+)\s*\}\}([\s\S]*?)\{\{\/each\}\}/g;
+  return tpl.replace(re, (_, key, body) => {
+    const arr = lookup(key, ctx);
+    if (!Array.isArray(arr)) throw new Error(`render: 'each ${key}' is not an array`);
+    return arr.map((item) => renderVars(body, item)).join('');
+  });
+}
+
+function renderVars(tpl, ctx) {
+  return tpl.replace(/\{\{\s*([\w.]+|\.)\s*\}\}/g, (_, path) => {
+    const val = lookup(path, ctx);
+    // fail-loud: an object/array means an authoring mistake (use {{# each }}), not [object Object].
+    if (typeof val === 'object') throw new Error(`render: key '${path}' is an object/array; use {{# each }} instead`);
+    return String(val);
+  });
+}
+
+export function render(tpl, ctx, partials = {}, depth = 0) {
+  // guards against accidental partial cycles; 20 is far beyond any real template depth.
+  if (depth > 20) throw new Error('render: partial recursion too deep');
+  // 1. partials first (so they can contain each/vars)
+  let out = tpl.replace(/\{\{>\s*([\w-]+)\s*\}\}/g, (_, name) => {
+    if (!(name in partials)) throw new Error(`render: unknown partial: ${name}`);
+    return render(partials[name], ctx, partials, depth + 1);
+  });
+  // 2. each blocks, 3. vars
+  out = renderVars(renderEach(out, ctx), ctx);
+  // 4. nothing may remain
+  if (out.includes('{{')) throw new Error(`render: unresolved/unbalanced template near: ${out.slice(out.indexOf('{{'), out.indexOf('{{') + 40)}`);
+  return out;
+}