@1agh/maude 0.15.0

package/plugins/design/dev-server/canvas-meta.schema.json

@@ -0,0 +1,181 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Canvas metadata sidecar",
+  "description": "Per-canvas .meta.json sidecar that mirrors Claude Design's `.design-canvas.state.json` pattern. Stores section + artboard labels, brief, and provenance separate from the HTML so file tree and handoff bundle can render rich descriptions without parsing JSX.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["title", "sections"],
+  "properties": {
+    "title": {
+      "type": "string",
+      "description": "Canvas project title (e.g. 'Match Recap' or 'Sparta Studio'). Shown as H1 in handoff bundle."
+    },
+    "subtitle": {
+      "type": "string",
+      "description": "One-line description of the canvas project's purpose."
+    },
+    "brief": {
+      "type": "string",
+      "description": "The full brief that produced this canvas (from /design:new). Preserved for handoff."
+    },
+    "platform": {
+      "type": "string",
+      "enum": ["desktop", "mobile", "tablet", "responsive", "tv", "watch", "other"],
+      "description": "Primary intended platform for this canvas project."
+    },
+    "created": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO timestamp when /design:new generated the canvas."
+    },
+    "last_modified": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO timestamp of the last /design edit."
+    },
+    "sections": {
+      "type": "array",
+      "description": "Top-level sections inside the canvas (DCSection wrapper instances). Order matches reading order in the canvas.",
+      "items": {
+        "type": "object",
+        "required": ["id", "label"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Stable slug for the section (matches DCSection id prop)."
+          },
+          "label": { "type": "string", "description": "Human-readable section title." },
+          "subtitle": {
+            "type": "string",
+            "description": "Optional one-line subtitle / brief for the section."
+          },
+          "artboards": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["id", "label"],
+              "additionalProperties": false,
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "description": "Stable slug (matches DCArtboard id prop)."
+                },
+                "label": {
+                  "type": "string",
+                  "description": "Artboard title shown in canvas + handoff."
+                },
+                "subtitle": { "type": "string", "description": "Optional short description." },
+                "platform": {
+                  "type": "string",
+                  "enum": ["desktop", "mobile", "tablet", "watch", "tv"]
+                },
+                "width": { "type": "number", "description": "Design width in CSS px." },
+                "height": { "type": "number", "description": "Design height in CSS px." },
+                "screen_route": {
+                  "type": "string",
+                  "description": "Production route this artboard maps to (e.g. '/team/[id]/roster'). Optional — used by /design:handoff."
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "iteration_count": {
+      "type": "integer",
+      "description": "Total /design iterations applied to this canvas. Maintained by the orchestrator."
+    },
+    "tokens_used": {
+      "type": "array",
+      "description": "CSS variables referenced by the canvas (auto-extracted on each /design:edit). Used by /design:handoff to know which tokens the canvas depends on.",
+      "items": { "type": "string" }
+    },
+    "designSystem": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Which design system this canvas was built against. Kebab-case slug matching a name in config.designSystems[]. Read by skill 'design-system' (read mode) + design-system-completeness-critic + flow's design-system-guard to scope rules to the right tokens / philosophy. Optional in single-DS projects (falls back to config.defaultDesignSystem); REQUIRED in multi-DS projects to avoid cross-DS contamination."
+    },
+    "opt_out_scope": {
+      "type": "string",
+      "enum": ["palette", "aesthetic", "full"],
+      "description": "Persisted DS opt-out scope for this canvas. Subsequent /design:edit iterations inherit this; --opt-out=<scope> on the flag overrides for that iteration and persists the new value. a11y is enforced at every scope.",
+      "default": "palette"
+    },
+    "css_mode": {
+      "type": "string",
+      "enum": ["inline", "tailwind", "modules"],
+      "description": "How this canvas writes CSS. 'inline' (MDCC-DSN/01 default) uses bespoke classes from `_components.css` + ad-hoc `style={{}}` for one-off values. 'tailwind' opts the canvas into Tailwind utilities (requires `bun-plugin-tailwind` on the dev-server). 'modules' uses a sibling `<Slug>.module.css`. The /design:handoff CSS-bundling path only fires for 'inline' (Phase 3.6 Task 12b).",
+      "default": "inline"
+    },
+    "data_cd_id_version": {
+      "type": "integer",
+      "description": "Major version of the data-cd-id scheme this canvas was last transpiled against. Bumped when the ID derivation rule changes (renumbering the universe of IDs). Future-proofing for v2 of the inspector; v1 = current Bun.hash(componentName + ':' + idx) → 8 hex.",
+      "default": 1,
+      "minimum": 1
+    },
+    "layout": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Phase 4 canvas-v2 spatial layout. Optional — when absent the canvas runtime synthesizes a default grid (3 cols × 1280 × 820, 80 px gutter, alphabetical by DCArtboard id). Authoring state only — stripped from /design:handoff emitted registry items. Phase 4.2 (DDR-027): artboard size is JSX-authoritative (props.width / props.height on <DCArtboard>); `layout.artboards[]` persists positions only. Writes strip any incoming `w`/`h`; reads tolerate them for back-compat with Phase 4 default-grid snapshots.",
+      "properties": {
+        "artboards": {
+          "type": "array",
+          "description": "Per-DCArtboard world-coord rects keyed by `id`. ids not listed fall back to the default grid slot for their render-order index.",
+          "items": {
+            "type": "object",
+            "required": ["id", "x", "y"],
+            "additionalProperties": false,
+            "properties": {
+              "id": { "type": "string" },
+              "x": { "type": "number" },
+              "y": { "type": "number" },
+              "w": {
+                "type": "number",
+                "exclusiveMinimum": 0,
+                "description": "Read-only legacy field — Phase 4 default-grid snapshots wrote this; Phase 4.2 writers strip it. JSX width prop is the source of truth."
+              },
+              "h": {
+                "type": "number",
+                "exclusiveMinimum": 0,
+                "description": "Read-only legacy field — see `w`."
+              }
+            }
+          }
+        }
+      }
+    },
+    "viewport": {
+      "type": "object",
+      "required": ["x", "y", "zoom"],
+      "additionalProperties": false,
+      "description": "Phase 4 canvas-v2 pan/zoom state for the world plane. Optional — when absent the canvas runtime fits-to-screen on the artboard union. Authoring state — stripped from /design:handoff.",
+      "properties": {
+        "x": { "type": "number" },
+        "y": { "type": "number" },
+        "zoom": { "type": "number", "minimum": 0.1, "maximum": 4.0 }
+      }
+    },
+    "ai_context": {
+      "type": "object",
+      "description": "Opt-in metadata for AI cold-read. Persists hard-won context that doesn't live in the canvas source itself — pinned decisions, known quirks, rationale for why this canvas exists. Read by /design:edit's pre-flight to seed the model. Hand-edited; never auto-filled (auto-fill would defeat the purpose).",
+      "additionalProperties": false,
+      "properties": {
+        "pinned_decisions": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Short one-liners — decisions tried, accepted or rejected, that shaped the canvas (e.g. 'tried gradient hero — rejected: phosphor-dark theme clashed')."
+        },
+        "known_quirks": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Non-obvious behaviour callers might trip over (e.g. 'docs-article artboard intentionally taller than the rest — reserves room for fold-line annotations')."
+        },
+        "why_this_exists": {
+          "type": "string",
+          "description": "One paragraph explaining the canvas's reason for being. Surfaced in the generated JSDoc header as `@notes` when present."
+        }
+      }
+    }
+  }
+}

package/plugins/design/dev-server/canvas-pipeline.ts

@@ -0,0 +1,270 @@
+// Two-pass canvas TSX transform (DDR-019, Phase 3.6 Task 1).
+//
+// Pass 1 — parse the source with oxc-parser, walk JSX elements in pre-order,
+// inject ` data-cd-id="<8 hex>"` on every opening element via magic-string
+// byte-range append. The ID is derived from `Bun.hash(componentName + ":" + idx)`
+// so it survives whitespace edits inside the same component but renumbers on
+// sibling insertion (documented contract — see DDR-019 "Identity stability").
+//
+// Pass 2 — Bun.Transpiler lowers TSX to JS. The output is re-parsed by the
+// caller's smoke test to confirm parseability; making it BROWSER-loadable is
+// the _shell.html + react-runtime bundle's job (Task 6, future session).
+//
+// Exports are pure: no fs writes, no side effects. The route handler (http.ts)
+// calls writeLocator(...) and serves the JS body itself.
+//
+// Toolchain matches scripts/migrate-canvases.ts (codemod) and canvas-edit.ts
+// (AST-aware /design:edit element edits) — same oxc-parser + magic-string pair
+// in three call sites, one mental model.
+
+import MagicString from 'magic-string';
+import { parseSync } from 'oxc-parser';
+
+import type { LocatorEntry, LocatorMap } from './locator.ts';
+
+export interface TranspileResult {
+  /** TSX -> JS output from Bun.Transpiler. Browser-loadable contract is Task 6's job. */
+  js: string;
+  /** Map of injected `data-cd-id` -> source location, one entry per JSX element. */
+  locator: LocatorMap;
+  /** ETag derived from the post-pass-1 source (the source the browser would see decompiled). */
+  etag: string;
+  /** Source after Pass 1 (data-cd-id injected, JSX still). Useful for tests + debugging. */
+  withIds: string;
+}
+
+let cachedTranspiler: InstanceType<typeof Bun.Transpiler> | null = null;
+function getTranspiler(): InstanceType<typeof Bun.Transpiler> {
+  if (cachedTranspiler) return cachedTranspiler;
+  // jsx: "automatic" pairs with jsxImportSource: "react" — produces calls to
+  // jsx/jsxDEV/Fragment from "react/jsx-dev-runtime". Resolution is the loader's
+  // problem (Task 6); Pass 2 here just lowers syntax.
+  cachedTranspiler = new Bun.Transpiler({
+    loader: 'tsx',
+    target: 'browser',
+    tsconfig: JSON.stringify({
+      compilerOptions: { jsx: 'react-jsx', jsxImportSource: 'react' },
+    }),
+  });
+  return cachedTranspiler;
+}
+
+/**
+ * Transpile a canvas TSX file end-to-end (parse -> inject IDs -> JSX lower).
+ * Pure — no fs writes. Caller persists the locator map via writeLocator().
+ *
+ * @param canvasAbsPath  Absolute path of the .tsx file (used as the locator key + diagnostics).
+ * @param source         Raw TSX source. Caller is responsible for reading it via Bun.file().
+ */
+export function transpileCanvasSource(canvasAbsPath: string, source: string): TranspileResult {
+  const parsed = parseSync(canvasAbsPath, source, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    const first = parsed.errors[0];
+    const where = first?.labels?.[0]?.start ?? 0;
+    throw new TranspileError(
+      `oxc-parser failed on ${canvasAbsPath} (${parsed.errors.length} errors). First: ${first?.message ?? 'unknown'} at byte ${where}.`,
+      { canvas: canvasAbsPath, byte: where }
+    );
+  }
+
+  const s = new MagicString(source);
+  const locator: LocatorMap = {};
+
+  walkInjectIds(parsed.program, source, canvasAbsPath, s, locator);
+
+  const withIds = s.toString();
+  const js = getTranspiler().transformSync(withIds);
+  const etag = Bun.hash(withIds).toString(16);
+
+  return { js, locator, etag, withIds };
+}
+
+export class TranspileError extends Error {
+  readonly canvas: string;
+  readonly byte: number;
+  constructor(message: string, info: { canvas: string; byte: number }) {
+    super(message);
+    this.name = 'TranspileError';
+    this.canvas = info.canvas;
+    this.byte = info.byte;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// AST walker — pre-order over the parsed program; tracks the enclosing
+// component (PascalCase FunctionDeclaration / Variable+ArrowFunction) so each
+// JSX element's ID is scoped to its component.
+
+interface ComponentFrame {
+  componentName: string;
+  /** Pre-order JSX index within the component. */
+  jsxIndex: number;
+  /** Stack of element-type names from the component root down to current. */
+  jsxPath: string[];
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: oxc-parser AST nodes are heterogeneous; we shape-check at use site.
+type AnyNode = any;
+
+const PASCAL_CASE = /^[A-Z][A-Za-z0-9_]*$/;
+
+function isPascalIdent(name: unknown): name is string {
+  return typeof name === 'string' && PASCAL_CASE.test(name);
+}
+
+function componentNameOf(node: AnyNode): string | null {
+  if (!node || typeof node !== 'object') return null;
+  // function Foo() { ... }
+  if (node.type === 'FunctionDeclaration' && isPascalIdent(node.id?.name)) {
+    return node.id.name;
+  }
+  // const Foo = () => ...  /  const Foo = function() { ... }
+  if (node.type === 'VariableDeclarator' && isPascalIdent(node.id?.name)) {
+    const init = node.init;
+    if (init && (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression')) {
+      return node.id.name;
+    }
+  }
+  // export default function Foo() { ... }
+  if (node.type === 'FunctionExpression' && isPascalIdent(node.id?.name)) {
+    return node.id.name;
+  }
+  return null;
+}
+
+function jsxElementName(opening: AnyNode): string {
+  const name = opening?.name;
+  if (!name) return '?';
+  if (name.type === 'JSXIdentifier') return name.name ?? '?';
+  if (name.type === 'JSXMemberExpression') {
+    // e.g. <motion.div>  ->  "motion.div"
+    const parts: string[] = [];
+    let cur: AnyNode = name;
+    while (cur?.type === 'JSXMemberExpression') {
+      if (cur.property?.name) parts.unshift(cur.property.name);
+      cur = cur.object;
+    }
+    if (cur?.type === 'JSXIdentifier') parts.unshift(cur.name);
+    return parts.join('.') || '?';
+  }
+  if (name.type === 'JSXNamespacedName') {
+    return `${name.namespace?.name ?? '?'}:${name.name?.name ?? '?'}`;
+  }
+  return '?';
+}
+
+function hasDataCdIdAttr(opening: AnyNode): boolean {
+  const attrs = opening?.attributes;
+  if (!Array.isArray(attrs)) return false;
+  for (const a of attrs) {
+    if (
+      a?.type === 'JSXAttribute' &&
+      a.name?.type === 'JSXIdentifier' &&
+      a.name.name === 'data-cd-id'
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function computeId(componentName: string, idx: number): string {
+  // 8 hex chars from Bun.hash — 32 bits of entropy. Per-component collision
+  // probability for the canvas-scale we ship (≤ ~300 JSX elements) is < 1e-5.
+  // Documented in DDR-019; 16 chars available as a future migration knob.
+  return Bun.hash(`${componentName}:${idx}`).toString(16).padStart(16, '0').slice(0, 8);
+}
+
+function walkInjectIds(
+  program: AnyNode,
+  source: string,
+  canvasAbsPath: string,
+  s: MagicString,
+  locator: LocatorMap
+): void {
+  // Stack of enclosing components. JSX outside any component (e.g. a top-level
+  // `const x = <div/>;` constant) attributes to "" -- still gets an ID, just
+  // scoped under the empty-string bucket. Rare in practice.
+  const stack: ComponentFrame[] = [{ componentName: '', jsxIndex: 0, jsxPath: [] }];
+  const top = (): ComponentFrame => stack[stack.length - 1] as ComponentFrame;
+
+  function visit(node: AnyNode): void {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node)) {
+      for (const c of node) visit(c);
+      return;
+    }
+    if (typeof node.type !== 'string') return;
+
+    const newComp = componentNameOf(node);
+    let pushed = false;
+    if (newComp !== null) {
+      stack.push({ componentName: newComp, jsxIndex: 0, jsxPath: [] });
+      pushed = true;
+    }
+
+    if (node.type === 'JSXElement') {
+      const frame = top();
+      const opening = node.openingElement;
+      const elName = jsxElementName(opening);
+      const idx = frame.jsxIndex;
+      frame.jsxIndex += 1;
+
+      if (!hasDataCdIdAttr(opening)) {
+        const id = computeId(frame.componentName, idx);
+        // Insert " data-cd-id=\"<id>\"" right after the tag name. magic-string's
+        // appendLeft puts the new text before any subsequent attribute. JSX
+        // attribute order is irrelevant at runtime; visually the new attr lands
+        // first, which makes it easy to spot in devtools.
+        const insertAt: number | undefined = opening?.name?.end;
+        if (typeof insertAt === 'number') {
+          s.appendLeft(insertAt, ` data-cd-id="${id}"`);
+          const entry: LocatorEntry = {
+            canvas: canvasAbsPath,
+            line: node.loc?.start?.line ?? lineColFromByte(source, node.start).line,
+            col: node.loc?.start?.column ?? lineColFromByte(source, node.start).col,
+            jsxPath: [...frame.jsxPath, elName],
+            componentName: frame.componentName,
+          };
+          locator[id] = entry;
+        }
+      }
+
+      // Recurse into opening attributes + children, with the jsxPath extended.
+      frame.jsxPath.push(elName);
+      if (opening) visit(opening.attributes);
+      visit(node.children);
+      frame.jsxPath.pop();
+
+      if (pushed) stack.pop();
+      return;
+    }
+
+    // Generic recursion — visit every own value that isn't location metadata.
+    for (const k of Object.keys(node)) {
+      if (k === 'loc' || k === 'range' || k === 'start' || k === 'end' || k === 'type') continue;
+      visit(node[k]);
+    }
+
+    if (pushed) stack.pop();
+  }
+
+  visit(program);
+}
+
+// oxc-parser populates node.loc on most nodes, but defensively recompute from
+// the byte offset if it's missing (some attribute children skip it).
+function lineColFromByte(source: string, byte: number | undefined): { line: number; col: number } {
+  if (typeof byte !== 'number' || byte < 0) return { line: 1, col: 0 };
+  let line = 1;
+  let col = 0;
+  for (let i = 0; i < byte && i < source.length; i++) {
+    if (source.charCodeAt(i) === 10) {
+      line += 1;
+      col = 0;
+    } else {
+      col += 1;
+    }
+  }
+  return { line, col };
+}