baldart 4.74.0 → 4.76.0

package/framework/scripts/extract-mockup-design.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// extract-mockup-design.mjs — FALLBACK extractor for a Claude Design "Standalone
+// HTML (offline)" export, whose readable code lives inside an encoded
+// `<script type="__bundler/template">` blob. It decodes that blob into readable
+// HTML + CSS under the PRD's mockups/_src/ so `ui-expert` can build FROM the code
+// instead of reinterpreting a screenshot.
+//
+// This is the LAST-RESORT path. The preferred inputs are already-readable source:
+//   1. the DesignSync MCP handoff (pulled at /prd time), or
+//   2. a Download-as-.zip export (raw .jsx/.css on disk).
+// Use this only when all the user has is the offline single-file HTML.
+//
+// Contract (mirrors canvas-intake-recipe.md:111 — NEVER abort the PRD):
+//   node extract-mockup-design.mjs --input <file> --out <dir>
+//   - always exits 0; prints a single JSON line to stdout describing the outcome
+//   - status: "ok" | "no-code" | "skipped"
+//   - on any internal error → {status:"skipped", reason} exit 0 (caller proceeds
+//     with the visual/image path unchanged).
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+function parseArgs(argv) {
+  const a = { input: null, out: null };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--input') a.input = argv[++i];
+    else if (argv[i] === '--out') a.out = argv[++i];
+  }
+  return a;
+}
+
+function emit(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n');
+  process.exit(0); // never non-zero: a fallback must not break /prd
+}
+
+function extractStyleBlocks(html) {
+  const out = [];
+  const re = /<style[^>]*>([\s\S]*?)<\/style>/gi;
+  let m;
+  while ((m = re.exec(html)) !== null) out.push(m[1]);
+  return out.join('\n\n');
+}
+
+function main() {
+  const { input, out } = parseArgs(process.argv);
+  if (!input || !out) emit({ status: 'skipped', reason: 'missing --input/--out' });
+  if (!fs.existsSync(input)) emit({ status: 'skipped', reason: 'input not found: ' + input });
+
+  const base = path.basename(input).replace(/\.[^.]+$/, '');
+  const raw = fs.readFileSync(input, 'utf8');
+
+  // No-code forms: a real image / binary, or text without any markup. The caller
+  // keeps using the visual (image-load) path for these.
+  if (!/[<{]/.test(raw.substring(0, 4096))) emit({ status: 'no-code', reason: 'no markup detected' });
+
+  fs.mkdirSync(out, { recursive: true });
+  const written = [];
+
+  // (a) Offline Claude Design bundle: readable code is the __bundler/template blob.
+  const tplMatch = raw.match(/<script type="__bundler\/template"[^>]*>([\s\S]*?)<\/script>/);
+  if (tplMatch) {
+    let template;
+    try {
+      template = JSON.parse(tplMatch[1].trim()); // the value is the full rendered HTML string
+    } catch (e) {
+      emit({ status: 'skipped', reason: 'template blob not JSON-parseable (format may have changed)' });
+    }
+    if (typeof template !== 'string' || template.length < 64) {
+      emit({ status: 'skipped', reason: 'template blob empty or not a string' });
+    }
+    const htmlPath = path.join(out, base + '.decoded.html');
+    fs.writeFileSync(htmlPath, template);
+    written.push(htmlPath);
+
+    const css = extractStyleBlocks(template);
+    if (css.trim()) {
+      const cssPath = path.join(out, base + '.styles.css');
+      fs.writeFileSync(cssPath, css);
+      written.push(cssPath);
+    }
+    emit({
+      status: 'ok',
+      source_form: 'offline-html-bundler-template',
+      input,
+      files: written,
+      note: 'Decoded the offline bundle into readable HTML+CSS. Binary assets in __bundler/manifest are NOT decoded (not needed to build from the code).',
+    });
+  }
+
+  // (b) Already-readable code (.jsx/.css/plain HTML with classes): just copy it in.
+  const ext = path.extname(input).toLowerCase();
+  const looksReadable = ['.jsx', '.tsx', '.css', '.js', '.ts'].includes(ext) ||
+    (ext === '.html' && /class=|className=/.test(raw));
+  if (looksReadable) {
+    const dest = path.join(out, path.basename(input));
+    fs.copyFileSync(input, dest);
+    emit({ status: 'ok', source_form: 'readable-source', input, files: [dest] });
+  }
+
+  // (c) Markup present but neither a known bundle nor readable component source.
+  emit({ status: 'no-code', reason: 'no __bundler/template and not readable component source' });
+}
+
+try {
+  main();
+} catch (e) {
+  emit({ status: 'skipped', reason: String((e && e.message) || e) });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.74.0",
+  "version": "4.76.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/render.js

@@ -0,0 +1,120 @@
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const { execFileSync } = require('child_process');
+const renderAdapters = require('../utils/render-adapters');
+
+/**
+ * `baldart render build|shot` (Stage C — the render harness engine).
+ *
+ *   build : render-manifest.mjs over the registry specs → pick adapter → generate
+ *           ephemeral render surface (Storybook stories) under <design_system>/.harness/.
+ *   shot  : build the surface + Playwright screenshot each entry → PNG + render-check.json.
+ *           Consumer-run (needs the project's Storybook + Playwright); degrades cleanly.
+ *
+ * Rides on `features.has_design_system` (no new flag). No Storybook → clean no-op.
+ * The PNGs are for ISOLATED quality verification (e2e-review Phase 4b/4c) — NEVER a
+ * fidelity diff (the `mockup_source.level: harness-render` guard enforces that).
+ */
+
+const CONFIG_FILE = 'baldart.config.yml';
+
+function loadConfig(cwd) {
+  try { return yaml.load(fs.readFileSync(path.join(cwd, CONFIG_FILE), 'utf8')) || {}; }
+  catch (_) { return null; }
+}
+
+// Resolve a framework script path: installed (.framework/...) or this repo (framework/...).
+function resolveScript(cwd, rel) {
+  for (const base of [path.join(cwd, '.framework', 'framework'), path.join(cwd, 'framework'), path.join(__dirname, '..', '..', 'framework')]) {
+    const p = path.join(base, rel);
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+function harnessDir(cwd, cfg) {
+  const ds = (cfg.paths && cfg.paths.design_system) || 'docs/design-system';
+  return path.join(cwd, ds, '.harness');
+}
+
+function specsDir(cwd, cfg) {
+  const ds = (cfg.paths && cfg.paths.design_system) || 'docs/design-system';
+  return path.join(cwd, ds, 'components');
+}
+
+/** build: generate the render-manifest + the adapter's render surface. */
+function build({ cwd, full = false, log = console.error }) {
+  const cfg = loadConfig(cwd);
+  if (!cfg) return { status: 'skipped', reason: `no ${CONFIG_FILE}` };
+  if (!(cfg.features && cfg.features.has_design_system)) return { status: 'skipped', reason: 'features.has_design_system not true' };
+
+  const adapterName = renderAdapters.detect(cwd);
+  if (!adapterName) return { status: 'no-op', reason: 'no render adapter detected (no Storybook) — harness is optional; manifest still emitted' };
+
+  const specs = specsDir(cwd, cfg);
+  const out = harnessDir(cwd, cfg);
+  fs.mkdirSync(out, { recursive: true });
+  const manifestPath = path.join(out, 'render-manifest.json');
+
+  const script = resolveScript(cwd, '.claude/skills/design-system-init/scripts/render-manifest.mjs');
+  if (!script) return { status: 'skipped', reason: 'render-manifest.mjs not found (framework not installed?)' };
+  try {
+    execFileSync(process.execPath, [script, '--components', specs, '--out', manifestPath, ...(full ? ['--full'] : [])], { cwd, stdio: ['ignore', 'ignore', 'inherit'] });
+  } catch (e) {
+    return { status: 'skipped', reason: 'render-manifest failed: ' + String((e && e.message) || e) };
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+
+  const adapter = renderAdapters.getAdapter(adapterName, cwd);
+  const gen = adapter.generate({ manifest, outDir: out });
+  log(`render build: adapter=${adapterName} components=${manifest.components.length} stories=${(gen.written || []).length}${gen.status ? ' status=' + gen.status : ''}`);
+  return { status: 'ok', adapter: adapterName, manifest: manifestPath, generated: gen, harness: out };
+}
+
+/**
+ * shot: render each entry and capture a PNG + render-check.json. CONSUMER-RUN:
+ * needs the project's Storybook build + Playwright. Implemented best-effort;
+ * degrades to a reasoned skip when the toolchain is missing (never throws).
+ */
+function shot({ cwd, full = false, probe = false, log = console.error }) {
+  const built = build({ cwd, full, log });
+  if (built.status !== 'ok') return built;
+
+  // Preflight: Playwright must be reachable (do NOT auto-install in a consumer repo).
+  try { execFileSync('npx', ['playwright', '--version'], { cwd, stdio: 'ignore' }); }
+  catch (_) { return { ...built, shot: { status: 'skipped', reason: 'playwright not installed (npm i -D playwright && npx playwright install chromium)' } }; }
+
+  const adapter = renderAdapters.getAdapter(built.adapter, cwd);
+  if (typeof adapter.buildSurfaceCommand !== 'function') {
+    return { ...built, shot: { status: 'skipped', reason: `adapter ${built.adapter} has no static render surface (probe: ${probe})` } };
+  }
+  // The actual storybook-build + Playwright screenshot loop is consumer-run; we
+  // emit a render-check.json scaffold so e2e-review Phase 4b/4c has the certificate
+  // contract even before a live screenshot session. The screenshot loop itself is
+  // performed by the /ds-render skill via playwright-skill (it owns the browser).
+  const manifest = JSON.parse(fs.readFileSync(built.manifest, 'utf8'));
+  const total = manifest.components.reduce((n, c) => n + (c.entries || []).filter((e) => !e.truncated).length, 0);
+  const check = {
+    schema: 'baldart.render-check/1',
+    adapter: built.adapter,
+    surface_command: adapter.buildSurfaceCommand(),
+    total, rendered: 0, empty: 0, error: 0, variantsIdentical: 0, shimPartial: 0,
+    i18n_incomplete: null, // set true by the skill when a primitive rendered raw t() keys
+    note: 'Scaffold — the /ds-render skill runs the storybook build + Playwright screenshot loop and fills the counts. PNGs go to e2e-review Phase 4b/4c (quality) ONLY, never Phase 4 (fidelity).',
+  };
+  const checkPath = path.join(built.harness, 'render-check.json');
+  fs.writeFileSync(checkPath, JSON.stringify(check, null, 2) + '\n');
+  return { ...built, shot: { status: 'scaffolded', render_check: checkPath, total } };
+}
+
+function run(argv, cwd = process.cwd()) {
+  const sub = argv[0];
+  const full = argv.includes('--full');
+  const probe = argv.includes('--probe');
+  if (sub === 'build') return build({ cwd, full });
+  if (sub === 'shot') return shot({ cwd, full, probe });
+  throw new Error('usage: baldart render <build|shot> [--full] [--probe]');
+}
+
+module.exports = { run, build, shot, loadConfig, resolveScript };

package/src/utils/design-sync-state.js

@@ -0,0 +1,162 @@
+/**
+ * Consumer-side closed-loop state — `.baldart/design-sync.json` (since v4.76.0).
+ *
+ * Records the binding between the in-repo design-system registry (the SSOT) and
+ * its Claude Design satellite "mirror" project, plus the SYNCHRONIZED BASELINE
+ * used to detect drift in either direction. Sibling of `state.json`; consumer-
+ * owned, committed, never overwritten by `baldart update`. NOT a
+ * `baldart.config.yml` key (so the schema-change propagation rule does NOT apply).
+ *
+ * INVARIANTS (SSOT discipline — see framework/agents/design-system-protocol.md):
+ *   - `source_of_truth` is ALWAYS "code". The satellite is a mirror, never authority.
+ *   - The baseline is CONTENT-FREE: it stores ONLY hashes/revs
+ *     (`tokens_sha`, per-component `source_sha`+`spec_sha`, satellite `rev`), never
+ *     the component bodies. A baseline that carried content would become a 2nd SSOT.
+ *   - The `source_sha` reused here is the SAME `git hash-object` value
+ *     `extract-manifest.mjs` computes and `ds-drift` diffs — no new hashing scheme.
+ *
+ * Schema (v1):
+ *   {
+ *     "design_sync_version": 1,
+ *     "project_id": "<claude-design design-system projectId>" | null,
+ *     "source_of_truth": "code",                 // invariant
+ *     "bound_at": "<iso>" | null,
+ *     "baseline": {
+ *       "tokens_sha": "<sha>" | null,
+ *       "components": { "<Name>": { "source_sha": "...", "spec_sha": "...", "satellite_rev": "..." } }
+ *     },
+ *     "last_publish": { "version": "x.y.z", "ts": "...", "files_written": N } | null,
+ *     "history": [ { "ts", "event": "bootstrap"|"publish"|"reconcile"|"seed", ... } ]   // rolling 20
+ *   }
+ *
+ * NOTE on 1:1 vs N:N (M5): v1 is 1:1 (one registry ↔ one satellite project) — the
+ * recommended default. A future N:N (multi-brand) layout would key `project_id` +
+ * `baseline` by design-system path; that is a deliberate schema bump, not silent.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const STATE_DIR = '.baldart';
+const STATE_FILE = path.join(STATE_DIR, 'design-sync.json');
+const DESIGN_SYNC_VERSION = 1;
+const HISTORY_LIMIT = 20;
+
+function defaultState() {
+  return {
+    design_sync_version: DESIGN_SYNC_VERSION,
+    project_id: null,
+    source_of_truth: 'code', // invariant — never "design"
+    bound_at: null,
+    baseline: { tokens_sha: null, components: {} },
+    last_publish: null,
+    history: [],
+  };
+}
+
+function fullPath(cwd = process.cwd()) {
+  return path.join(cwd, STATE_FILE);
+}
+
+function exists(cwd = process.cwd()) {
+  return fs.existsSync(fullPath(cwd));
+}
+
+function load(cwd = process.cwd()) {
+  const full = fullPath(cwd);
+  if (!fs.existsSync(full)) return defaultState();
+  try {
+    const raw = JSON.parse(fs.readFileSync(full, 'utf8'));
+    const merged = { ...defaultState(), ...raw };
+    // Deep-merge the baseline so a partial file never loses the nested shape.
+    merged.baseline = { ...defaultState().baseline, ...(raw.baseline || {}) };
+    merged.baseline.components = (raw.baseline && raw.baseline.components) || {};
+    merged.source_of_truth = 'code'; // enforce the invariant on read — never trust a tampered value
+    return merged;
+  } catch (_) {
+    // Corrupt file — fall back to defaults, never throw (auxiliary state).
+    return defaultState();
+  }
+}
+
+function save(state, cwd = process.cwd()) {
+  const dir = path.join(cwd, STATE_DIR);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  state.source_of_truth = 'code'; // enforce on write
+  fs.writeFileSync(fullPath(cwd), JSON.stringify(state, null, 2) + '\n', 'utf8');
+}
+
+function appendHistory(state, entry) {
+  const next = [...(state.history || []), { ts: new Date().toISOString(), ...entry }];
+  return next.slice(-HISTORY_LIMIT);
+}
+
+/** Bind the registry to a satellite project (idempotent on project_id). */
+function recordBootstrap({ projectId, initialState }, cwd = process.cwd()) {
+  const state = load(cwd);
+  const wasFirst = !state.project_id;
+  state.project_id = projectId || state.project_id;
+  if (wasFirst && state.project_id) state.bound_at = new Date().toISOString();
+  state.history = appendHistory(state, { event: 'bootstrap', project_id: state.project_id, initial_state: initialState || null });
+  save(state, cwd);
+  return state;
+}
+
+/**
+ * Record a publish and update the baseline. `components` is a map
+ * {<Name>: {source_sha, spec_sha, satellite_rev?}} — CONTENT-FREE.
+ */
+function recordPublish({ version, components, tokensSha, filesWritten }, cwd = process.cwd()) {
+  const state = load(cwd);
+  state.last_publish = { version: version || null, ts: new Date().toISOString(), files_written: filesWritten || 0 };
+  if (tokensSha) state.baseline.tokens_sha = tokensSha;
+  for (const [name, anchors] of Object.entries(components || {})) {
+    state.baseline.components[name] = {
+      source_sha: anchors.source_sha || null,
+      spec_sha: anchors.spec_sha || null,
+      satellite_rev: anchors.satellite_rev || null,
+    };
+  }
+  state.history = appendHistory(state, { event: 'publish', version: version || null, files_written: filesWritten || 0 });
+  save(state, cwd);
+  return state;
+}
+
+/** Record a governed reconcile (a designer edit recepted via /ds-edit). */
+function recordReconcile({ summary, components }, cwd = process.cwd()) {
+  const state = load(cwd);
+  // Reconcile updates the satellite_rev anchor for the touched components so the
+  // next drift-check measures from the just-reconciled point. NEVER writes content.
+  for (const [name, anchors] of Object.entries(components || {})) {
+    state.baseline.components[name] = { ...(state.baseline.components[name] || {}), ...pickAnchors(anchors) };
+  }
+  state.history = appendHistory(state, { event: 'reconcile', summary: summary || null });
+  save(state, cwd);
+  return state;
+}
+
+function pickAnchors(a = {}) {
+  const out = {};
+  if (a.source_sha) out.source_sha = a.source_sha;
+  if (a.spec_sha) out.spec_sha = a.spec_sha;
+  if (a.satellite_rev) out.satellite_rev = a.satellite_rev;
+  return out;
+}
+
+/** The per-component baseline anchors (for the drift-check to diff against). */
+function getBaseline(cwd = process.cwd()) {
+  return load(cwd).baseline;
+}
+
+module.exports = {
+  load,
+  save,
+  exists,
+  appendHistory,
+  recordBootstrap,
+  recordPublish,
+  recordReconcile,
+  getBaseline,
+  STATE_FILE,
+  DESIGN_SYNC_VERSION,
+};

package/src/utils/render-adapters/claude-design-seed.js

@@ -0,0 +1,51 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Claude-Design-seed render adapter (Stage F — CONDITIONAL, probe-gated).
+ *
+ * The "design-led" (mayo) case: when /design-system-init seeded the registry FROM
+ * a Claude Design project, the seed brought the `.jsx` primitives + a
+ * `Design System.html` gallery into the repo. IF Playwright can isolate one
+ * primitive×variant from that gallery, this adapter renders per-primitive for free.
+ *
+ * REFUTED ASSUMPTION (kept honest): the "free render path" is NOT guaranteed —
+ * `.jsx` may be absent (source_kind html-css/image-only) and `Design System.html`
+ * may only render as a WHOLE gallery. So this adapter is gated on an empirical
+ * probe (`render shot --probe`): if per-primitive isolation fails, it degrades to
+ * a single gallery screenshot flagged `shimPartial`, and the canonical render path
+ * falls back to Storybook-regenerate. Render canonical = Storybook when present;
+ * Playwright-gallery only for the one-time seed (C4).
+ *
+ * v1 is a STUB that detects the seed marker and reports `needs_probe` — the
+ * Playwright isolation logic lands only after the probe confirms feasibility on a
+ * real seeded export (see the plan's must-measure-first #5).
+ */
+class ClaudeDesignSeedAdapter {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  static get name() { return 'claude-design-seed'; }
+  get label() { return 'Claude Design seed gallery'; }
+
+  /**
+   * Detect: a seed marker recorded in .baldart/design-sync.json history AND a
+   * Design System gallery html present in the seed staging dir. Conservative:
+   * only fires when both are true, else lets Storybook win.
+   */
+  static detect(cwd = process.cwd()) {
+    try {
+      const stateFile = path.join(cwd, '.baldart', 'design-sync.json');
+      if (!fs.existsSync(stateFile)) return false;
+      const st = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+      const seeded = (st.history || []).some((h) => h.event === 'seed' || (h.event === 'bootstrap' && h.initial_state === 'only-claude-design'));
+      return Boolean(seeded);
+    } catch (_) { return false; }
+  }
+
+  /** v1: no generation — the probe must confirm Playwright isolation first. */
+  generate() {
+    return { written: [], skipped: [], status: 'needs_probe', note: 'Run `baldart render shot --probe` on the seeded export to confirm per-primitive Playwright isolation before this adapter generates. Until then, Storybook is the canonical render path.' };
+  }
+}
+
+module.exports = ClaudeDesignSeedAdapter;

package/src/utils/render-adapters/index.js

@@ -0,0 +1,59 @@
+const StorybookAdapter = require('./storybook');
+const ClaudeDesignSeedAdapter = require('./claude-design-seed');
+
+/**
+ * Render-harness adapter registry (Stage C, since v4.76.0).
+ *
+ * Mirrors the lsp/toolchain/routine adapter-registry pattern (REGISTRY +
+ * getAdapter + detectAll). An adapter turns a `render-manifest.json` into a real
+ * render surface (mounted primitives) per ONE strategy. The harness exists to
+ * render registry primitives in isolation — today BALDART documents components but
+ * never renders them isolated.
+ *
+ * Adding a render strategy:
+ *   1. Create `src/utils/render-adapters/<name>.js` with the shape of
+ *      StorybookAdapter (static get name, get label, static detect(cwd),
+ *      generate({manifest,outDir})).
+ *   2. Add it to REGISTRY below, in PRIORITY order (detectAll returns the first
+ *      that fires — Storybook is canonical when present).
+ *
+ * REFUTED (do NOT add): a per-stack framework-native preview-route generator +
+ * an auto-provider-shim. Those are code-generators with unbounded surface that
+ * mount providers out-of-tree → wrong-but-green renders (false fidelity). Use
+ * Storybook where present; the seed-gallery only for the one-time seed case.
+ */
+const REGISTRY = {
+  storybook: StorybookAdapter,
+  'claude-design-seed': ClaudeDesignSeedAdapter,
+};
+
+// Priority order for detection: Storybook is the canonical render path when
+// present; the seed gallery is a conditional one-time fallback.
+const PRIORITY = ['storybook', 'claude-design-seed'];
+
+function listAdapters() { return Object.keys(REGISTRY); }
+
+function getAdapter(name, cwd) {
+  const Cls = REGISTRY[name];
+  if (!Cls) throw new Error(`Unknown render adapter: ${name}. Available: ${listAdapters().join(', ')}`);
+  return new Cls(cwd);
+}
+
+/**
+ * Return the FIRST adapter (by priority) whose static detect() fires, or null
+ * when none does (→ the harness is a no-op for this consumer, which is fine:
+ * Stage C degrades cleanly without Storybook). Pure: no side effects.
+ */
+function detect(cwd = process.cwd()) {
+  for (const name of PRIORITY) {
+    try { if (REGISTRY[name].detect(cwd)) return name; } catch (_) { /* keep scanning */ }
+  }
+  return null;
+}
+
+/** All adapters whose detect() fires (diagnostic). */
+function detectAll(cwd = process.cwd()) {
+  return PRIORITY.filter((name) => { try { return REGISTRY[name].detect(cwd); } catch { return false; } });
+}
+
+module.exports = { REGISTRY, listAdapters, getAdapter, detect, detectAll };

package/src/utils/render-adapters/storybook.js

@@ -0,0 +1,104 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Storybook render adapter (Stage C, v1 — the ONLY render path the adversarial
+ * pass kept). When the consumer already has Storybook, we generate EPHEMERAL CSF
+ * stories from the render-manifest and let Storybook's OWN runtime do the
+ * context-shimming (ThemeProvider/router/i18n via the project's real
+ * `.storybook/preview` decorators). We never re-grep a provider chain and never
+ * mount out-of-tree — that refuted "auto-provider-shim" is exactly what produces
+ * wrong-but-green renders. Storybook exists to solve isolated mounting; reuse it.
+ *
+ * The generated stories carry a marker so they are identifiable + safe to delete;
+ * co-located hand-authored stories are NEVER touched.
+ */
+const MARKER = '// @baldart-render-harness — generated from render-manifest.json, safe to delete';
+
+class StorybookAdapter {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  static get name() { return 'storybook'; }
+  get label() { return 'Storybook'; }
+
+  /** Detect: a `.storybook/` config dir at the repo root (matches configure.js:234). */
+  static detect(cwd = process.cwd()) {
+    return fs.existsSync(path.join(cwd, '.storybook'));
+  }
+
+  /**
+   * Generate one ephemeral `.stories.tsx` per component into outDir.
+   * Returns { written: [paths], skipped: [names] }.
+   * i18n note (M6): the project's own preview decorators supply the i18n provider
+   * if it has one; if it doesn't, the story still renders but text shows raw keys —
+   * such PNGs are flagged i18n-incomplete by `render shot`, never fed to a fidelity diff.
+   */
+  generate({ manifest, outDir }) {
+    fs.mkdirSync(outDir, { recursive: true });
+    const written = [];
+    const skipped = [];
+    for (const comp of (manifest.components || [])) {
+      if (!comp.source) { skipped.push(comp.name); continue; } // no source → can't import → skip honestly
+      const file = path.join(outDir, `${comp.name}.baldart.stories.tsx`);
+      fs.writeFileSync(file, this._story(comp, outDir));
+      written.push(file);
+    }
+    return { written, skipped };
+  }
+
+  _story(comp, outDir) {
+    const abs = path.join(this.cwd, comp.source);
+    let imp = path.relative(outDir, abs).replace(/\.(tsx?|jsx?)$/, '');
+    if (!imp.startsWith('.')) imp = './' + imp;
+    imp = imp.split(path.sep).join('/');
+    const lines = [
+      MARKER,
+      `import { ${comp.name} } from '${imp}';`,
+      ``,
+      `export default { title: 'Baldart Harness/${comp.name}', component: ${comp.name} };`,
+      ``,
+    ];
+    const usedNames = new Set();
+    for (const entry of (comp.entries || [])) {
+      if (entry.truncated) continue;
+      let exp = this._exportName(entry, comp.name);
+      while (usedNames.has(exp)) exp += '_';
+      usedNames.add(exp);
+      lines.push(`export const ${exp} = { args: ${this._args(entry.props)} };`);
+    }
+    return lines.join('\n') + '\n';
+  }
+
+  _exportName(entry, compName) {
+    let tail = entry.id.startsWith(compName + '--') ? entry.id.slice(compName.length + 2) : entry.id;
+    const parts = tail.split('--').map((p) => p.replace(/[^A-Za-z0-9]+/g, ' ').trim());
+    let name = parts.map((p) => p.split(' ').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('')).join('');
+    if (!name || /^\d/.test(name)) name = 'Story' + name;
+    return name;
+  }
+
+  _args(props) {
+    const out = Object.entries(props || {}).map(([k, v]) => `${JSON.stringify(k)}: ${this._coerce(v)}`);
+    return `{ ${out.join(', ')} }`;
+  }
+
+  _coerce(v) {
+    if (v === 'true' || v === true) return 'true';
+    if (v === 'false' || v === false) return 'false';
+    if (typeof v === 'string' && /^-?\d+(\.\d+)?$/.test(v)) return v;
+    return JSON.stringify(v);
+  }
+
+  /** How `render shot` builds a static render surface (consumer-run, needs deps). */
+  buildSurfaceCommand() {
+    return { cmd: 'npx', args: ['storybook', 'build', '-o', '.harness/storybook-static'] };
+  }
+
+  /** The iframe URL pattern for a story id in a static Storybook build. */
+  storyUrl(baseUrl, storyId) {
+    return `${baseUrl}/iframe.html?id=${storyId}&viewMode=story`;
+  }
+}
+
+module.exports = StorybookAdapter;
+module.exports.MARKER = MARKER;