@cs4alhaider/screenbook 0.1.0

package/shell/sidebar.js

@@ -0,0 +1,112 @@
+/* Sidebar: current feature header + searchable, grouped screen list. */
+
+import { store, feature, set } from './store.js';
+import { DEVICE_LABELS } from './frames.js';
+
+const featureBox = document.getElementById('sidebar-feature');
+const listBox = document.getElementById('screen-list');
+const searchInput = document.getElementById('search');
+
+searchInput.addEventListener('input', () => set({ search: searchInput.value.trim() }));
+
+function esc(s) {
+  return String(s ?? '').replace(/[&<>"]/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]
+  ));
+}
+
+const KNOWN_STATUS = ['draft', 'wip', 'ready', 'review'];
+
+export function visibleScreens() {
+  const f = feature();
+  if (!f) return [];
+  const q = store.ui.search.toLowerCase();
+
+  if (f.type === 'app') {
+    return (f.appScreens || []).filter((s) =>
+      !q || `${s.id} ${s.title} ${s.description || ''}`.toLowerCase().includes(q));
+  }
+
+  const devFilter = store.ui.deviceFilter;
+  return (f.manifest.screens || []).filter((s) => {
+    const devs = s.devices?.length ? s.devices : [s.device || 'none'];
+    if (devFilter !== 'all' && !devs.includes(devFilter)) return false;
+    if (!q) return true;
+    const hay = `${s.id} ${s.title} ${s.description || ''} ${(s.tags || []).join(' ')}`.toLowerCase();
+    return hay.includes(q);
+  });
+}
+
+export function renderSidebar() {
+  const f = feature();
+
+  if (!f) {
+    featureBox.innerHTML = '';
+    listBox.innerHTML = `<div class="list-empty">No features yet.<br>Add one with the CLI or MCP.</div>`;
+    return;
+  }
+
+  featureBox.innerHTML =
+    `<div class="sf-title"><span class="sf-icon">${esc(f.meta.icon || '📄')}</span>${esc(f.meta.title || f.id)}</div>` +
+    (f.meta.description ? `<div class="sf-desc">${esc(f.meta.description)}</div>` : '');
+
+  const screens = visibleScreens();
+  if (!screens.length) {
+    listBox.innerHTML = `<div class="list-empty">${
+      f.type === 'app' && f.appScreens === null
+        ? 'Waiting for the app to register and report its screens…'
+        : store.ui.search || store.ui.deviceFilter !== 'all'
+          ? 'No screens match the current search / device filter.'
+          : 'No screens in this feature yet.'
+    }</div>`;
+    return;
+  }
+
+  const showDevice = store.ui.deviceFilter === 'all' &&
+    new Set(screens.map((s) => s.device || 'none')).size > 1;
+
+  listBox.innerHTML = '';
+  let lastGroup = Symbol('none');
+  for (const s of screens) {
+    const group = s.group || null;
+    if (group !== lastGroup) {
+      if (group) {
+        const head = document.createElement('div');
+        head.className = 'group-head';
+        head.textContent = group;
+        listBox.append(head);
+      }
+      lastGroup = group;
+    }
+
+    const row = document.createElement('button');
+    row.type = 'button';
+    row.className = `screen-row${s.id === store.ui.screen ? ' is-active' : ''}`;
+    row.dataset.screen = s.id;
+
+    const pills = [];
+    if (s.status) {
+      const cls = KNOWN_STATUS.includes(s.status) ? ` st-${s.status}` : '';
+      pills.push(`<span class="pill${cls}">${esc(s.status)}</span>`);
+    }
+    if (showDevice) {
+      const d = DEVICE_LABELS[s.device || 'none'];
+      pills.push(`<span class="pill pill-device">${esc(d ? d.title : s.device)}</span>`);
+    }
+    for (const t of (s.tags || []).slice(0, 3)) {
+      pills.push(`<span class="pill">${esc(t)}</span>`);
+    }
+
+    row.innerHTML =
+      `<div class="sr-title">${esc(s.title || s.id)}</div>` +
+      (s.description ? `<div class="sr-desc">${esc(s.description)}</div>` : '') +
+      `<div class="sr-meta">${s.updated ? `<span class="sr-date">${esc(s.updated)}</span>` : ''}${pills.join('')}</div>`;
+
+    row.addEventListener('click', () => set({ screen: s.id, flow: null }));
+    listBox.append(row);
+  }
+}
+
+export function scrollActiveIntoView() {
+  listBox.querySelector('.screen-row.is-active')?.scrollIntoView({ block: 'nearest' });
+}

package/shell/store.js

@@ -0,0 +1,119 @@
+/* Shell state store: one plain object + subscriptions + URL (hash) sync.
+   Deep link shape:  #feature/screen?scenario=…&mode=dark&theme=…&dir=rtl&lang=ar&device=ios&flow=…&step=2 */
+
+const listeners = new Set();
+
+export const store = {
+  project: null,          // { config, features: Map(id → feature), themes: Map(id → json) }
+  ui: {
+    feature: null,
+    screen: null,
+    deviceFilter: 'all',
+    scenario: 'default',
+    theme: null,
+    mode: 'light',
+    dir: 'ltr',
+    lang: 'en',
+    flow: null,
+    flowStep: 0,
+    review: false,
+    themeLab: false,
+    search: '',
+    serveLive: false,
+    solo: false
+  }
+};
+
+export function subscribe(fn) {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}
+
+/* set(patch) → notifies subscribers with the set of changed keys */
+export function set(patch) {
+  const changed = new Set();
+  for (const [k, v] of Object.entries(patch)) {
+    if (store.ui[k] !== v) {
+      store.ui[k] = v;
+      changed.add(k);
+    }
+  }
+  if (changed.size) {
+    syncHash();
+    for (const fn of listeners) fn(changed);
+  }
+  return changed;
+}
+
+export function feature(id = store.ui.feature) {
+  return store.project?.features.get(id) || null;
+}
+
+export function screenEntry(featureId = store.ui.feature, screenId = store.ui.screen) {
+  const f = feature(featureId);
+  if (f?.type === 'app') return (f.appScreens || []).find((s) => s.id === screenId) || null;
+  return f?.manifest?.screens?.find((s) => s.id === screenId) || null;
+}
+
+export function activeTheme() {
+  return store.project?.themes.get(store.ui.theme) || null;
+}
+
+export function activeScenario(featureId = store.ui.feature) {
+  const f = feature(featureId);
+  const list = f?.scenarios?.list || [];
+  return list.find((s) => s.id === store.ui.scenario) || null;
+}
+
+/* ---------------- hash routing ---------------- */
+
+const HASH_KEYS = ['scenario', 'mode', 'theme', 'dir', 'lang', 'flow'];
+let applyingHash = false;
+
+export function parseHash() {
+  const raw = location.hash.replace(/^#/, '');
+  if (!raw) return null;
+  const [path, query = ''] = raw.split('?');
+  const [feature, screen] = path.split('/').map((s) => decodeURIComponent(s || ''));
+  const params = new URLSearchParams(query);
+  const out = { feature: feature || null, screen: screen || null };
+  for (const k of HASH_KEYS) if (params.has(k)) out[k] = params.get(k);
+  if (params.has('device')) out.deviceFilter = params.get('device');
+  if (params.has('step')) out.flowStep = parseInt(params.get('step'), 10) || 0;
+  return out;
+}
+
+export function syncHash() {
+  if (applyingHash || store.ui.solo) return;
+  const u = store.ui;
+  if (!u.feature) return;
+  let hash = `#${encodeURIComponent(u.feature)}`;
+  if (u.screen) hash += `/${encodeURIComponent(u.screen)}`;
+  const params = new URLSearchParams();
+  if (u.scenario && u.scenario !== 'default') params.set('scenario', u.scenario);
+  if (u.mode !== 'light') params.set('mode', u.mode);
+  if (u.theme && store.project?.config?.themes?.[0] !== u.theme) params.set('theme', u.theme);
+  if (u.dir !== 'ltr') params.set('dir', u.dir);
+  if (u.lang && u.lang !== (store.project?.config?.defaultLanguage || 'en')) params.set('lang', u.lang);
+  if (u.deviceFilter !== 'all') params.set('device', u.deviceFilter);
+  if (u.flow) { params.set('flow', u.flow); params.set('step', String(u.flowStep)); }
+  const q = params.toString();
+  if (q) hash += `?${q}`;
+  if (location.hash !== hash) history.replaceState(null, '', hash);
+}
+
+export function applyHash() {
+  const parsed = parseHash();
+  if (!parsed) return false;
+  applyingHash = true;
+  try {
+    const patch = {};
+    for (const k of ['feature', 'screen', 'scenario', 'mode', 'theme', 'dir', 'lang', 'deviceFilter', 'flow', 'flowStep']) {
+      if (parsed[k] !== undefined && parsed[k] !== null) patch[k] = parsed[k];
+    }
+    set(patch);
+  } finally {
+    applyingHash = false;
+  }
+  return true;
+}

package/shell/themelab.js

@@ -0,0 +1,186 @@
+/* 🎨 Theme Lab (EN-15): see every token the active theme defines, edit them
+   LIVE against the hosted screens, switch themes, export JSON — and save back
+   to themes/<id>.json when running under `engine serve`. */
+
+import { store, set } from './store.js';
+import { pushUpdate } from './screenhost.js';
+import { fetchJSON, url } from './net.js';
+import { toast } from './toast.js';
+
+const Kit = window.EngineKit;
+const panel = document.getElementById('theme-panel');
+
+let working = null;      // deep clone of the theme being edited
+let workingId = null;
+let dirty = false;
+let applyTimer = null;
+
+export function themeLabDirty() {
+  return dirty;
+}
+
+function ensureWorking() {
+  const id = store.ui.theme;
+  if (!working || workingId !== id) {
+    working = Kit.clone(store.project.themes.get(id)) || Kit.clone(Kit.FALLBACK_THEME);
+    workingId = id;
+    dirty = false;
+  }
+}
+
+/* Effective (light ⊕ dark for dark mode) rows; edits always write the delta
+   into modes[activeMode] so dark stays a delta over light. */
+function tokenRows() {
+  const mode = store.ui.mode;
+  const light = working.modes?.light || {};
+  const effective = mode === 'dark' ? Kit.deepMerge(light, working.modes?.dark || {}) : light;
+  const rows = [];
+  (function walk(node, path) {
+    for (const [key, value] of Object.entries(node)) {
+      const p = [...path, key];
+      if (value !== null && typeof value === 'object' && !Array.isArray(value)) walk(value, p);
+      else rows.push({ path: p, value: String(value) });
+    }
+  })(effective, []);
+  return rows;
+}
+
+function setToken(pathArr, value) {
+  const mode = store.ui.mode;
+  if (!working.modes) working.modes = {};
+  if (!working.modes[mode]) working.modes[mode] = {};
+  let cur = working.modes[mode];
+  for (let i = 0; i < pathArr.length - 1; i++) {
+    if (typeof cur[pathArr[i]] !== 'object' || cur[pathArr[i]] === null) cur[pathArr[i]] = {};
+    cur = cur[pathArr[i]];
+  }
+  cur[pathArr[pathArr.length - 1]] = value;
+  dirty = true;
+
+  clearTimeout(applyTimer);
+  applyTimer = setTimeout(() => {
+    store.project.themes.set(workingId, working);
+    pushUpdate();
+    renderHeaderBits();
+  }, 60);
+}
+
+const HEX_RE = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+const CORE_PREVIEW = ['color.accent', 'color.bg', 'color.card', 'color.ink', 'color.ink-2', 'color.line'];
+
+function esc(s) {
+  return String(s ?? '').replace(/[&<>"]/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]
+  ));
+}
+
+function download() {
+  const blob = new Blob([JSON.stringify(working, null, 2) + '\n'], { type: 'application/json' });
+  const a = document.createElement('a');
+  a.href = URL.createObjectURL(blob);
+  a.download = `${workingId}.json`;
+  a.click();
+  URL.revokeObjectURL(a.href);
+}
+
+async function saveToDisk() {
+  try {
+    const res = await fetch(url(`__sb/theme/${encodeURIComponent(workingId)}`), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ theme: working })
+    });
+    if (!res.ok) throw new Error(String(res.status));
+    dirty = false;
+    toast(`Saved themes/${workingId}.json ✓`);
+    renderThemeLab();
+  } catch {
+    toast('⚠︎ Save failed — is engine serve running?');
+  }
+}
+
+async function revert() {
+  const disk = await fetchJSON(`themes/${workingId}.json`, { optional: true });
+  working = disk || Kit.clone(Kit.FALLBACK_THEME);
+  dirty = false;
+  store.project.themes.set(workingId, working);
+  pushUpdate();
+  renderThemeLab();
+  toast('Reverted to disk version');
+}
+
+function renderHeaderBits() {
+  const badge = panel.querySelector('#tl-dirty');
+  if (badge) badge.hidden = !dirty;
+  const strip = panel.querySelector('#tl-strip');
+  if (strip) {
+    const vars = Kit.themeVars(working, store.ui.mode);
+    strip.querySelectorAll('[data-swatch]').forEach((el) => {
+      el.style.background = vars[`--${el.dataset.swatch.replace(/\./g, '-')}`] || 'transparent';
+    });
+  }
+}
+
+export function renderThemeLab() {
+  if (!store.ui.themeLab) {
+    panel.hidden = true;
+    panel.innerHTML = '';
+    return;
+  }
+  ensureWorking();
+  panel.hidden = false;
+
+  const themes = [...store.project.themes.keys()];
+  const mode = store.ui.mode;
+  const vars = Kit.themeVars(working, mode);
+
+  panel.innerHTML =
+    `<div class="rp-head"><h3>🎨 ${esc(working.title || workingId)}
+       <span class="rp-count" id="tl-dirty" ${dirty ? '' : 'hidden'}>· unsaved</span></h3>
+      <div class="rp-tools">
+        <button class="rp-tool" data-act="export">Export</button>
+        <button class="rp-tool" data-act="save" title="${store.ui.serveLive ? `Writes themes/${esc(workingId)}.json` : 'Needs engine serve'}">Save</button>
+        <button class="rp-tool" data-act="revert">Revert</button>
+      </div></div>` +
+    (themes.length > 1
+      ? `<div class="tl-themes">${themes.map((t) =>
+          `<button class="tl-theme-chip${t === workingId ? ' is-on' : ''}" data-theme="${esc(t)}">${esc(store.project.themes.get(t)?.title || t)}</button>`).join('')}</div>`
+      : '') +
+    `<div class="tl-strip" id="tl-strip">${CORE_PREVIEW.map((p) =>
+       `<span data-swatch="${esc(p)}" title="${esc(p)}" style="background:${esc(vars[`--${p.replace(/\./g, '-')}`] || 'transparent')}"></span>`).join('')}</div>` +
+    `<div class="rp-hint">Editing <b>${esc(mode)}</b> tokens of <b>themes/${esc(workingId)}.json</b> — flip ☾/☀︎ to edit the other mode. Changes hit the screen live.</div>` +
+    `<div class="tl-rows">${tokenRows().map((r, i) => {
+      const pathStr = r.path.join('.');
+      const isHex = HEX_RE.test(r.value.trim());
+      return `<div class="tl-row">
+        <label for="tl-i${i}" title="--${esc(r.path.join('-'))}">${esc(pathStr)}</label>
+        ${isHex ? `<input type="color" data-path="${esc(pathStr)}" value="${esc(r.value.trim())}" aria-label="${esc(pathStr)} color">` : `<span class="tl-mini" style="background:${esc(r.value)}"></span>`}
+        <input type="text" id="tl-i${i}" data-path="${esc(pathStr)}" value="${esc(r.value)}" spellcheck="false">
+      </div>`;
+    }).join('')}</div>`;
+
+  panel.querySelector('[data-act="export"]').addEventListener('click', download);
+  panel.querySelector('[data-act="save"]').addEventListener('click', saveToDisk);
+  panel.querySelector('[data-act="revert"]').addEventListener('click', revert);
+
+  panel.querySelectorAll('.tl-theme-chip').forEach((chip) =>
+    chip.addEventListener('click', () => {
+      working = null;
+      set({ theme: chip.dataset.theme });
+      renderThemeLab();
+    }));
+
+  panel.querySelectorAll('.tl-rows input').forEach((input) => {
+    input.addEventListener('input', () => {
+      const pathArr = input.dataset.path.split('.');
+      setToken(pathArr, input.value);
+      /* keep the twin control in sync */
+      const twin = panel.querySelectorAll(`.tl-rows input[data-path="${CSS.escape(input.dataset.path)}"]`);
+      twin.forEach((other) => {
+        if (other !== input && other.value !== input.value && HEX_RE.test(input.value.trim())) {
+          other.value = input.value.trim();
+        }
+      });
+    });
+  });
+}

package/shell/toast.js

@@ -0,0 +1,15 @@
+/* Shell-level toasts (screen-level toasts are Engine.toast inside the iframe). */
+
+const box = document.getElementById('shell-toasts');
+
+export function toast(msg) {
+  const t = document.createElement('div');
+  t.className = 'shell-toast';
+  t.textContent = msg;
+  box.append(t);
+  requestAnimationFrame(() => t.classList.add('is-in'));
+  setTimeout(() => {
+    t.classList.remove('is-in');
+    setTimeout(() => t.remove(), 220);
+  }, 2200);
+}

package/shell/toolbar.js

@@ -0,0 +1,128 @@
+/* Toolbar widgets: dropdown chips + toggle chips. One open menu at a time. */
+
+let openMenu = null;
+
+document.addEventListener('click', (e) => {
+  if (openMenu && !openMenu.contains(e.target)) closeMenus();
+});
+document.addEventListener('keydown', (e) => {
+  if (e.key === 'Escape') closeMenus();
+});
+
+export function closeMenus() {
+  if (openMenu) {
+    openMenu.querySelector('.menu')?.remove();
+    openMenu = null;
+  }
+}
+
+function h(tag, className, html) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (html !== undefined) node.innerHTML = html;
+  return node;
+}
+
+function esc(s) {
+  return String(s ?? '').replace(/[&<>"]/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]
+  ));
+}
+
+/*
+ * dropdown({ icon, title, value(), items(), onPick(id), head? })
+ *   items() → [{ id, icon, title, desc, checked }]
+ * Returns { el, refresh } — refresh re-renders the chip's value label.
+ */
+export function dropdown(spec) {
+  const wrap = h('div', 'dropdown');
+  const chip = h('button', 'chip');
+  chip.type = 'button';
+  if (spec.tooltip) chip.title = spec.tooltip;
+  wrap.append(chip);
+
+  function renderChip() {
+    const value = spec.value ? spec.value() : null;
+    chip.innerHTML =
+      `<span class="chip-icon">${esc(spec.icon)}</span>` +
+      (spec.title ? `<span>${esc(spec.title)}</span>` : '') +
+      (value ? `<span class="chip-value">${esc(value)}</span>` : '') +
+      `<span class="chip-caret">▼</span>`;
+  }
+
+  function open() {
+    closeMenus();
+    const menu = h('div', 'menu');
+    if (spec.head) menu.append(h('div', 'menu-head', esc(spec.head)));
+    const items = spec.items();
+    if (!items.length) {
+      menu.append(h('div', 'menu-empty', esc(spec.empty || 'Nothing here yet')));
+    }
+    for (const item of items) {
+      if (item.head) {
+        menu.append(h('div', 'menu-head', esc(item.title)));
+        continue;
+      }
+      const btn = h('button', `menu-item${item.checked ? ' is-checked' : ''}`);
+      btn.type = 'button';
+      btn.innerHTML =
+        `<span class="mi-icon">${esc(item.icon ?? '')}</span>` +
+        `<span class="mi-body"><span class="mi-title">${esc(item.title)}</span>` +
+        (item.desc ? `<span class="mi-desc">${esc(item.desc)}</span>` : '') +
+        `</span><span class="mi-check">✓</span>`;
+      btn.addEventListener('click', () => {
+        closeMenus();
+        spec.onPick(item.id);
+      });
+      menu.append(btn);
+    }
+    wrap.append(menu);
+    openMenu = wrap;
+  }
+
+  chip.addEventListener('click', (e) => {
+    e.stopPropagation();
+    if (openMenu === wrap) closeMenus();
+    else open();
+  });
+
+  renderChip();
+  return { el: wrap, refresh: renderChip };
+}
+
+/*
+ * toggle({ icon, iconOn?, title?, tooltip, is(), onToggle, danger? })
+ * Returns { el, refresh }.
+ */
+export function toggle(spec) {
+  const chip = h('button', `chip icon-only${spec.danger ? ' is-danger' : ''}`);
+  chip.type = 'button';
+  chip.title = spec.tooltip || '';
+
+  function refresh() {
+    const on = spec.is();
+    chip.classList.toggle('is-on', !!on);
+    chip.innerHTML =
+      `<span class="chip-icon">${esc(on && spec.iconOn ? spec.iconOn : spec.icon)}</span>` +
+      (spec.label ? `<span>${esc(typeof spec.label === 'function' ? spec.label() : spec.label)}</span>` : '');
+  }
+
+  chip.addEventListener('click', () => { spec.onToggle(); refresh(); });
+  refresh();
+  return { el: chip, refresh };
+}
+
+/* Plain action chip (no state). */
+export function action(spec) {
+  const chip = h('button', 'chip icon-only');
+  chip.type = 'button';
+  chip.title = spec.tooltip || '';
+  chip.innerHTML = `<span class="chip-icon">${esc(spec.icon)}</span>` +
+    (spec.label ? `<span>${esc(spec.label)}</span>` : '');
+  chip.addEventListener('click', spec.onClick);
+  return { el: chip, refresh() {} };
+}
+
+export function divider() {
+  return { el: h('div', 'tb-divider'), refresh() {} };
+}

package/skill/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: screenbook
+description: Author and review ScreenBook prototype screens — standalone HTML screens with a meta block, JSON mock data + scenarios, JSON design tokens, guided flows, review comments. Use whenever working in a project containing app.config.json + features/ + engine/ (a ScreenBook project), for creating/editing screens, changing mock data or scenarios, theming, building demo flows, taking screenshots, or addressing review pins.
+---
+
+# ScreenBook authoring
+
+ScreenBook is a static, no-build prototype studio: folders of standalone HTML screens + JSON
+files, rendered by a shell into a device-framed gallery. You author the **project**; you never
+read or modify `engine/` internals.
+
+## The 60-second mental model
+
+- One screen = one full HTML document in `features/<f>/screens/<id>.html`, with a required
+  `<script type="application/json" id="screen-meta">` block and one bridge include
+  (`../../../engine/bridge.js`). It works opened alone AND inside the shell.
+- Mock data = `features/<f>/data/seed.json`; named **scenarios** overlay it
+  (`patch` deep-merge, `remove` dot-paths, `{{today±N}}` date tokens).
+- Look = design tokens in `themes/<id>.json`, flattened to CSS vars (`--color-accent`,
+  `--font-sans`, `--radius-card`, `--space-page`); dark mode merges over light.
+- `manifest.json` is derived — regenerate, never hand-edit.
+- Done = `validate` green (static contract checks + every screen renders in every
+  theme × mode × direction with zero console errors).
+
+## Typical loops
+
+**Add a screen**: read a sibling screen (`get_screen`) to copy its idioms → write the new
+document → `add_screen` (validates + stamps + regenerates manifest) → `validate` →
+`screenshot` if you want to look at it.
+
+**Change data/scenarios**: `get_data` → edit → `set_data` → `validate`.
+
+**Address review**: `get_review_comments {unresolvedOnly: true}` → each comment carries
+screen, scenario, theme, mode, dir + the CSS path that was clicked → fix the screen →
+`resolve_comment`.
+
+**Demo story**: `set_flows` with steps `{screen, note, scenario?}` — the shell plays them
+as a guided walkthrough.
+
+Without MCP, the CLI does the same: `node engine/cli/screenbook.js manifest | validate |
+serve | screenshot --screen <feature>/<screen>`.
+
+## References (read the one you need)
+
+- `references/screen-contract.md` — full screen anatomy, meta fields, safe areas, standalone mode
+- `references/bridge-api.md` — Engine.* API: ready/data/state/go/toast/env + dark/RTL idioms
+- `references/tokens.md` — theme JSON schema, flattening rules, theming discipline
+- `references/scenarios.md` — seed + overlay semantics, date tokens, scenario design tips
+- `references/flows.md` — flows.json schema + how the player behaves
+- `references/cli-mcp.md` — every CLI command + MCP tool, serve endpoints, validation gates
+- `references/app-mode.md` — embedding whole single-page apps (cooperative include or injected driver)
+- `references/i18n.md` — per-feature strings: key-first i18n.json + `Engine.t(key, {vars})`