baldart 4.75.0 → 4.76.1

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;