tsquare 0.1.0

package/src/icons.ts

@@ -0,0 +1,54 @@
+import { icons } from "lucide";
+import { editDistance } from "./suggest";
+
+// Lucide exports icons in PascalCase (BarChart2); wireframes use kebab-case (bar-chart-2).
+const pascal = (s: string) => s.replace(/(^|[-_ ])(\w)/g, (_, __, c) => c.toUpperCase());
+const kebab = (s: string) =>
+  s
+    .replace(/([a-z])([A-Z0-9])/g, "$1-$2")
+    .replace(/([0-9])([A-Z])/g, "$1-$2") // Grid3X3 → grid-3-x-3, but Grid3x2 → grid-3x-2
+    .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
+    .toLowerCase();
+
+const table = icons as Record<string, any>;
+
+/** Kebab-case names for every Lucide icon (including Lucide's aliases, e.g. home and house). */
+export const iconNames: string[] = Object.keys(table).map(kebab);
+
+/** The Lucide icon node for a kebab-case name, or undefined if there's no such icon. */
+export function iconNode(name: string): any {
+  return table[pascal(name)];
+}
+
+export const isIcon = (name: string) => iconNode(name) !== undefined;
+
+/**
+ * Close matches for an unknown name: near spellings ("serach" → search) and names that
+ * share a word with it ("cart" → shopping-cart, "call" → phone-call).
+ * There are no synonyms: "notification" won't find bell.
+ */
+export function suggestIcons(name: string, limit = 3): string[] {
+  const q = name.toLowerCase().replace(/[_ ]/g, "-");
+  const words = q.split("-").filter((w) => w.length > 2);
+  const maxEdits = Math.max(1, Math.floor(q.length / 3));
+  const scored: [string, number][] = [];
+  for (const n of iconNames) {
+    const parts = n.split("-");
+    const shared = words.filter((w) => parts.includes(w)).length;
+    // Lower is closer. A shared word scores 0.6–1 (more shared words, fewer extra words rank
+    // higher). A typo scores by edits relative to length, so one wrong letter in a long name
+    // (chevron-rigth → 0.23) beats a shared word, but in a short one (cart → car, 0.75) it doesn't.
+    const wordScore = shared ? 1 - 0.4 * (shared / words.length) + 0.05 * (parts.length - shared) : Infinity;
+    const d = editDistance(q, n);
+    const score = Math.min(wordScore, d <= maxEdits ? (3 * d) / q.length : Infinity);
+    if (score < Infinity) scored.push([n, score]);
+  }
+  return scored.sort((a, b) => a[1] - b[1] || a[0].localeCompare(b[0])).slice(0, limit).map(([n]) => n);
+}
+
+export function unknownIconMessage(name: string) {
+  const close = suggestIcons(name);
+  return close.length
+    ? `unknown icon "${name}" (did you mean ${close.join(", ")}?)`
+    : `unknown icon "${name}" (use a Lucide name in kebab-case, e.g. search, user, settings)`;
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+// Main API: wireframe text in, SVG/PNG out.
+export { renderWireframe, compileWireframe, formatIssues, WireframeError } from "./compile";
+export { wireframePrompt, repairPrompt } from "./prompt";
+export { printWireframeText as formatWireframe } from "./print";
+
+// Lower level: the compiled spec and the pieces used to render it.
+export { renderWireframeSvg, renderWireframePng, checkSpec, boardSize } from "./render";
+export { parseWireframeText } from "./text";
+export { catalog, componentDefinitions } from "./catalog";
+export { registry } from "./components";
+export { theme, DEVICES } from "./layout";

package/src/layout.ts

@@ -0,0 +1,63 @@
+/** Sizes and colors shared by the components and the board-size calculation. */
+
+export const theme = {
+  font: "Inter",
+  board: "#e6e8eb",
+  paper: "#ffffff",
+  ink: "#1f2328",
+  text: "#3d434a",
+  muted: "#868d96",
+  line: "#d0d4d9",
+  lineStrong: "#9ca3ab",
+  fill: "#f0f2f4",
+  fill2: "#e1e4e8",
+  primary: "#2b3035",
+  onPrimary: "#ffffff",
+  scrim: "rgba(31, 35, 40, 0.38)",
+  notes: {
+    yellow: "#fdf1a8",
+    blue: "#cfe6fb",
+    pink: "#fbd3e0",
+    green: "#d4f1d0",
+  },
+} as const;
+
+export const DEVICES = {
+  phone: { width: 390, height: 844, radius: 36, padding: 16 },
+  tablet: { width: 820, height: 1180, radius: 24, padding: 24 },
+  desktop: { width: 1280, height: 800, radius: 10, padding: 24 },
+  custom: { width: 800, height: 600, radius: 8, padding: 20 },
+} as const;
+
+export type Device = keyof typeof DEVICES;
+
+/** Height of the screen name label plus the space under it. */
+export const LABEL_H = 40;
+/** Height of the board title block. */
+export const TITLE_H = 64;
+export const BOARD_PADDING = 56;
+export const BOARD_GAP = 64;
+export const NOTE_WIDTH = 220;
+
+export function screenSize(props: Record<string, any> = {}) {
+  const device: Device = props.device ?? "phone";
+  const base = DEVICES[device] ?? DEVICES.phone;
+  const custom = device === "custom";
+  return {
+    device,
+    width: (custom ? props.width : null) ?? base.width,
+    height: (custom ? props.height : null) ?? base.height,
+    radius: base.radius,
+    padding: props.padding ?? base.padding,
+    chrome: props.chrome ?? (device === "phone" || device === "desktop"),
+  };
+}
+
+/** Rough height of a Note so the board is tall enough to hold it. */
+export function estimateNoteHeight(text: string, width: number) {
+  const charsPerLine = Math.max(8, Math.floor((width - 28) / 7.4));
+  const lines = text
+    .split("\n")
+    .reduce((n, para) => n + Math.max(1, Math.ceil(para.length / charsPerLine)), 0);
+  return 28 + lines * 21;
+}

package/src/print.ts

@@ -0,0 +1,73 @@
+import type { Spec } from "@json-render/core";
+import { componentDefinitions } from "./catalog";
+import { PRIMARY_PROP } from "./text";
+
+const BARE_WORD = /^[A-Za-z][\w-]*$/;
+/** Props whose values read naturally as bare words (phone, primary, row, sm, left…). */
+const BARE_PROPS = new Set(["device", "variant", "direction", "size", "side", "type", "layout"]);
+
+function unwrap(t: any): any {
+  let cur = t;
+  while (cur && ["optional", "nullable", "default"].includes(cur.def?.type)) cur = cur.def.innerType;
+  return cur;
+}
+
+function fmt(v: unknown): string {
+  if (typeof v === "string") return BARE_WORD.test(v) && !["true", "false", "null"].includes(v) ? v : JSON.stringify(v);
+  if (typeof v === "number" || typeof v === "boolean" || v === null) return String(v);
+  if (Array.isArray(v)) return `[${v.map(fmt).join(", ")}]`;
+  if (typeof v === "object") {
+    return `{${Object.entries(v as object).map(([k, x]) => `${k}=${fmt(x)}`).join(" ")}}`;
+  }
+  return JSON.stringify(v);
+}
+
+/** Enum values that can be written bare for a component (unambiguous only). */
+function bareEnums(type: string) {
+  const shape = (componentDefinitions as any)[type].props.shape;
+  const seen = new Map<string, string>();
+  const dup = new Set<string>();
+  for (const [prop, s] of Object.entries(shape)) {
+    const inner = unwrap(s);
+    if (inner?.def?.type === "enum") {
+      for (const v of inner.options) (seen.has(v) ? dup.add(v) : seen.set(v, prop));
+    }
+  }
+  for (const d of dup) seen.delete(d);
+  return seen;
+}
+
+function booleans(type: string) {
+  const shape = (componentDefinitions as any)[type].props.shape;
+  return new Set(Object.entries(shape).filter(([, s]) => unwrap(s)?.def?.type === "boolean").map(([k]) => k));
+}
+
+export function printWireframeText(spec: Spec, indentUnit = "  "): string {
+  const out: string[] = [];
+  const walk = (id: string, depth: number) => {
+    const el = spec.elements[id];
+    const props = { ...(el.props ?? {}) } as Record<string, unknown>;
+    const parts: string[] = [el.type.toLowerCase()];
+    const enums = bareEnums(el.type);
+    const bools = booleans(el.type);
+    const primary = PRIMARY_PROP[el.type];
+
+    // bare enum words first (device, variant, direction…), then the quoted text, then the rest
+    for (const [k, v] of Object.entries(props)) {
+      if (typeof v === "string" && BARE_PROPS.has(k) && enums.get(v) === k) { parts.push(v); delete props[k]; }
+    }
+    if (primary && typeof props[primary] === "string") {
+      parts.push(JSON.stringify(props[primary]));
+      delete props[primary];
+    }
+    for (const [k, v] of Object.entries(props)) {
+      if (v === undefined || v === null) continue;
+      if (v === true && bools.has(k)) parts.push(k);
+      else parts.push(`${k}=${fmt(v)}`);
+    }
+    out.push(indentUnit.repeat(depth) + parts.join(" "));
+    for (const c of el.children ?? []) walk(c, depth + 1);
+  };
+  walk(spec.root, 0);
+  return out.join("\n") + "\n";
+}

package/src/prompt-example.ts

@@ -0,0 +1,43 @@
+import type { Spec } from "@json-render/core";
+
+/** The worked example in the model prompt (also used by the format eval). */
+export const exampleSpec: Spec = {
+  root: "board",
+  elements: {
+    board: { type: "Board", props: { title: "Recipe app" }, children: ["browse", "detail", "note"] },
+
+    browse: { type: "Screen", props: { name: "Browse", device: "phone" }, children: ["b-nav", "b-search", "b-tabs", "b-grid", "b-tabbar"] },
+    "b-nav": { type: "NavBar", props: { title: "Recipes", leading: "menu", actions: ["bell"] }, children: [] },
+    "b-search": { type: "Input", props: { type: "search", placeholder: "Search recipes" }, children: [] },
+    "b-tabs": { type: "Tabs", props: { items: ["All", "Quick", "Vegetarian"], active: 0 }, children: [] },
+    "b-grid": { type: "Grid", props: { columns: 2, gap: 12 }, children: ["card-1", "card-2"] },
+    "card-1": { type: "Card", props: { padding: 10 }, children: ["c1-img", "c1-title", "c1-meta"] },
+    "c1-img": { type: "Image", props: { height: 110 }, children: [] },
+    "c1-title": { type: "Text", props: { text: "Tomato soup", bold: true }, children: [] },
+    "c1-meta": { type: "Text", props: { text: "25 min", size: "sm", muted: true }, children: [] },
+    "card-2": { type: "Card", props: { padding: 10 }, children: ["c2-img", "c2-title"] },
+    "c2-img": { type: "Image", props: { height: 110 }, children: [] },
+    "c2-title": { type: "Text", props: { lines: 2 }, children: [] },
+    "b-tabbar": {
+      type: "TabBar",
+      props: { items: [{ label: "Browse", icon: "book-open" }, { label: "Saved", icon: "heart" }, { label: "Profile", icon: "user" }], active: 0 },
+      children: [],
+    },
+
+    detail: { type: "Screen", props: { name: "Recipe", device: "phone" }, children: ["d-nav", "d-img", "d-title", "d-tags", "d-body", "d-cook", "d-sheet"] },
+    "d-nav": { type: "NavBar", props: { leading: "back", actions: ["share", "more-horizontal"] }, children: [] },
+    "d-img": { type: "Image", props: { height: 200, label: "Photo" }, children: [] },
+    "d-title": { type: "Heading", props: { text: "Tomato soup", level: 1 }, children: [] },
+    "d-tags": { type: "Stack", props: { direction: "row", gap: 8 }, children: ["tag-1", "tag-2"] },
+    "tag-1": { type: "Badge", props: { label: "25 min", variant: "outline" }, children: [] },
+    "tag-2": { type: "Badge", props: { label: "Vegan", variant: "outline" }, children: [] },
+    "d-body": { type: "Text", props: { lines: 4 }, children: [] },
+    "d-cook": { type: "Button", props: { label: "Start cooking", variant: "primary", fullWidth: true }, children: [] },
+    "d-sheet": { type: "Drawer", props: { side: "bottom", title: "Options", size: 260 }, children: ["opt-1", "opt-2", "opt-3"] },
+    "opt-1": { type: "Toggle", props: { label: "Metric units", on: true }, children: [] },
+    "opt-2": { type: "Select", props: { label: "Servings", value: "4" }, children: [] },
+    "opt-3": { type: "Checkbox", props: { label: "Add to shopping list" }, children: [] },
+
+    note: { type: "Note", props: { text: "Detail screen shown with the options sheet open." }, children: [] },
+  },
+};

package/src/prompt.ts

@@ -0,0 +1,121 @@
+/**
+ * System prompt for models that write wireframe text. Built from the catalog,
+ * so it always matches the components and props the renderer accepts.
+ */
+import { componentDefinitions } from "./catalog";
+import { printWireframeText } from "./print";
+import { exampleSpec } from "./prompt-example";
+import { PRIMARY_PROP } from "./text";
+
+function unwrap(t: any): any {
+  let cur = t;
+  while (cur && ["optional", "nullable", "default"].includes(cur.def?.type)) cur = cur.def.innerType;
+  return cur;
+}
+
+function describeType(t: any): string {
+  const s = unwrap(t);
+  switch (s?.def?.type) {
+    case "string": return "string";
+    case "number": return "number";
+    case "boolean": return "boolean";
+    case "enum": return (s.options as string[]).map((o) => `"${o}"`).join(" | ");
+    case "literal": return s.def.values.map((v: unknown) => JSON.stringify(v)).join(" | ");
+    case "union": return s.def.options.map(describeType).join(" | ");
+    case "array": return `array of ${describeType(s.def.element)}`;
+    case "object":
+      return `{ ${Object.entries(s.shape).map(([k, v]) => `${k}: ${describeType(v)}`).join(", ")} }`;
+    default: return "any";
+  }
+}
+
+export interface PropDoc {
+  name: string;
+  type: string;
+  required: boolean;
+  /** This prop is filled by a quoted string, e.g. the label of `button "Save"`. */
+  main: boolean;
+  description?: string;
+}
+
+/** Every component with its description and props, straight from the catalog. */
+export function componentDocs() {
+  return Object.entries(componentDefinitions).map(([name, def]) => ({
+    name,
+    description: def.description,
+    props: Object.entries((def.props as any).shape).map(([prop, schema]: [string, any]): PropDoc => ({
+      name: prop,
+      type: describeType(schema),
+      required: !["optional", "nullable"].includes(schema.def?.type),
+      main: PRIMARY_PROP[name] === prop,
+      description: schema.description ?? unwrap(schema)?.description,
+    })),
+  }));
+}
+
+export function componentReference() {
+  const lines: string[] = [];
+  for (const c of componentDocs()) {
+    lines.push(`### ${c.name}`, c.description);
+    for (const p of c.props) {
+      lines.push(`- ${p.name}${p.required ? " (required)" : ""}: ${p.type}${p.main ? " (main text)" : ""}${p.description ? ` — ${p.description}` : ""}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+export const RULES = `## Rules
+1. The top element is a Board. The Board's children are Screens, plus optional Notes beside them.
+2. Each Screen is one view of the product. Use several Screens to show several views or states.
+3. A Screen lays out its children top to bottom. Use Stack (direction row or column) and Grid to arrange content.
+4. NavBar is pinned to the top of its Screen and TabBar to the bottom.
+5. Modal and Drawer are overlays. They must be direct children of a Screen.
+6. This is a low-fidelity wireframe. Prefer placeholders (Image boxes, Text with lines) over invented copy unless the copy matters.
+7. Only use the components and props listed below. All props are optional unless marked required.
+8. Wireframes are grayscale. The only UI colors: Board accent (one color for primary buttons, checked controls, toggles, active tabs and ghost buttons), Badge tone (success, warning, danger) and Input error. Only add an accent if the request asks for color or a brand.`;
+
+export const TEXT_FORMAT = `## Output format: wireframe text
+One element per line. Indent children two spaces under their parent. The first line is the board.
+
+A line is the component name in lowercase, followed by arguments separated by spaces:
+- "a quoted string" sets the component's main text prop (marked "main text" below)
+- a bare word that is one of the component's option values sets that option: phone, desktop, primary, ghost, row, sm, left, bottom, password, …
+- a bare prop name sets a boolean prop to true: checked, fullWidth, grow, muted. \`off\` and \`unchecked\` set on/checked to false
+- key=value sets any prop. Values: "string", number, true/false, bare word, [list, of, values], {key=value key=value}
+- # starts a comment
+
+Lists: items are separated by commas, and an item can contain spaces without quotes: [All notes, Pinned, Shared]. To put a comma inside an item, quote the item: ["$1,200", "Smith, J"]. Inside quotes, write \\" for a quote character. Numbers in a list of text are fine: [2023, 2024].
+
+If a bare word could mean more than one prop, write it as key=value.`;
+
+export const EXAMPLE_REQUEST =
+  "Two phone screens for a recipe app: a browse screen with search, category tabs, a grid of recipe cards and a tab bar; and a recipe detail screen with its options sheet open.";
+
+/** The system prompt for writing wireframe text. */
+export function wireframePrompt() {
+  return [
+    "You write low-fidelity UI wireframes as specs that a renderer turns into images.",
+    "Reply with only the spec in a single code block, with no explanation.",
+    "",
+    TEXT_FORMAT,
+    "",
+    RULES,
+    "",
+    "## Example",
+    `Request: ${EXAMPLE_REQUEST}`,
+    "",
+    "```tsquare",
+    printWireframeText(exampleSpec).trimEnd(),
+    "```",
+    "",
+    "## Components",
+    "",
+    componentReference(),
+  ].join("\n");
+}
+
+/** Follow-up message asking a model to fix the problems in its last reply. */
+export function repairPrompt(issues: string) {
+  return `The wireframe has these problems:\n${issues}\n\nReply with the corrected wireframe in a single code block.`;
+}

package/src/render.ts

@@ -0,0 +1,178 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import type { Spec } from "@json-render/core";
+import { renderToSvg } from "@json-render/image/render";
+import { catalog, componentDefinitions } from "./catalog";
+import { withPalette } from "./components";
+import { paletteFor } from "./colors";
+import { unknownComponentMessage } from "./suggest";
+import {
+  BOARD_GAP,
+  BOARD_PADDING,
+  LABEL_H,
+  NOTE_WIDTH,
+  TITLE_H,
+  estimateNoteHeight,
+  screenSize,
+} from "./layout";
+
+// Inter from @fontsource/inter, pinned to an exact version: a font change shifts
+// text metrics and line wraps, so treat a bump like a renderer change.
+const fontFile = (name: string) =>
+  createRequire(import.meta.url).resolve(`@fontsource/inter/files/${name}`);
+
+let fontCache: Promise<any[]> | null = null;
+function loadFonts() {
+  fontCache ??= Promise.all([
+    readFile(fontFile("inter-latin-400-normal.woff")),
+    readFile(fontFile("inter-latin-600-normal.woff")),
+  ]).then(([regular, semibold]) => [
+    { name: "Inter", data: regular, weight: 400, style: "normal" },
+    { name: "Inter", data: semibold, weight: 600, style: "normal" },
+  ]);
+  return fontCache;
+}
+
+export class SpecError extends Error {
+  constructor(public issues: string[]) {
+    super(`Invalid wireframe spec:\n  - ${issues.join("\n  - ")}`);
+  }
+}
+
+/** Catalog validation plus the structural rules the renderer depends on. */
+export function checkSpec(spec: Spec): string[] {
+  const issues: string[] = [];
+  const result = catalog.validate(spec);
+  if (!result.success) {
+    const err: any = (result as any).error;
+    const zodIssues = err?.issues ?? [];
+    if (zodIssues.length) {
+      for (const i of zodIssues) issues.push(`${(i.path ?? []).join(".")}: ${i.message}`);
+    } else {
+      issues.push(String(err ?? "catalog validation failed"));
+    }
+  }
+
+  const root = spec.elements?.[spec.root];
+  if (!root) {
+    issues.push(`root "${spec.root}" is not in elements`);
+    return issues;
+  }
+  if (root.type !== "Board") issues.push(`root must be a Board (got ${root.type})`);
+
+  for (const [id, el] of Object.entries(spec.elements)) {
+    // catalog.validate checks the spec's shape but not each element's props,
+    // so validate props against the component's Zod schema here.
+    const def = (componentDefinitions as Record<string, { props: any }>)[el.type];
+    if (!def) {
+      issues.push(`${id}: ${unknownComponentMessage(el.type, Object.keys(componentDefinitions))}`);
+    } else {
+      const parsed = def.props.safeParse(el.props ?? {});
+      if (!parsed.success) {
+        for (const i of parsed.error.issues) {
+          issues.push(`${id}.props${i.path.length ? "." + i.path.join(".") : ""}: ${i.message}`);
+        }
+      }
+      // Zod drops unknown keys silently; report them so the author (or model) hears about it.
+      for (const key of Object.keys(el.props ?? {})) {
+        if (!(key in def.props.shape)) issues.push(`${id}.props: ${el.type} has no prop "${key}"`);
+      }
+    }
+    for (const child of el.children ?? []) {
+      if (!spec.elements[child]) issues.push(`${id}: child "${child}" does not exist`);
+    }
+    if (el.type === "Screen" && !(root.children ?? []).includes(id)) {
+      issues.push(`${id}: Screen must be a direct child of the Board`);
+    }
+    if (el.type === "Modal" || el.type === "Drawer") {
+      const parent = Object.entries(spec.elements).find(([, p]) => p.children?.includes(id));
+      if (parent && parent[1].type !== "Screen") {
+        issues.push(`${id}: ${el.type} must be a direct child of a Screen (found in ${parent[1].type} "${parent[0]}")`);
+      }
+    }
+    // The renderer would silently drop extra cells. Usually the cause is an unquoted
+    // cell with a space, which the text syntax splits into two.
+    if (el.type === "Table") {
+      const { columns, data } = (el.props ?? {}) as { columns?: unknown; data?: unknown };
+      if (Array.isArray(columns) && Array.isArray(data)) {
+        const bad = data
+          .map((row, i) => ({ row: i + 1, cells: Array.isArray(row) ? row.length : 1 }))
+          .filter((r) => r.cells !== columns.length);
+        if (bad.length) {
+          const cells = (n: number) => `${n} cell${n === 1 ? "" : "s"}`;
+          const rows = bad.length === 1
+            ? `data row ${bad[0].row} has ${cells(bad[0].cells)}`
+            : `data rows ${bad.map((r) => `${r.row} (${cells(r.cells)})`).join(", ")} don't match`;
+          const hints = [
+            bad.some((r) => r.cells > columns.length) && `quote cells that contain a comma, e.g. ["$1,200", Paid]`,
+            bad.some((r) => r.cells < columns.length) && `use "" for an empty cell`,
+          ].filter(Boolean);
+          issues.push(`${id}: Table has ${columns.length} columns, but ${rows} (${hints.join("; ")})`);
+        }
+      }
+    }
+  }
+  return issues;
+}
+
+/** Work out the canvas size from the Board's screens (Satori needs it up front). */
+export function boardSize(spec: Spec) {
+  const board = spec.elements[spec.root];
+  const p = (board.props ?? {}) as Record<string, any>;
+  const gap = p.gap ?? BOARD_GAP;
+  const pad = p.padding ?? BOARD_PADDING;
+  const kids = (board.children ?? []).map((id) => spec.elements[id]).filter(Boolean);
+
+  const boxes = kids.map((el) => {
+    const props = (el.props ?? {}) as Record<string, any>;
+    if (el.type === "Screen") {
+      const s = screenSize(props);
+      return { w: s.width, h: s.height + LABEL_H };
+    }
+    if (el.type === "Note") {
+      const w = props.width ?? NOTE_WIDTH;
+      return { w, h: LABEL_H + estimateNoteHeight(props.text ?? "", w) };
+    }
+    return { w: 0, h: 0 };
+  });
+
+  const perRow = p.layout === "grid" ? Math.max(1, p.columns ?? 3) : Math.max(1, boxes.length);
+  let width = 0;
+  let height = 0;
+  for (let i = 0; i < boxes.length; i += perRow) {
+    const row = boxes.slice(i, i + perRow);
+    width = Math.max(width, row.reduce((sum, b) => sum + b.w, 0) + gap * (row.length - 1));
+    height += Math.max(...row.map((b) => b.h)) + (i > 0 ? gap : 0);
+  }
+  return {
+    width: Math.ceil(width + pad * 2),
+    height: Math.ceil(height + pad * 2 + (p.title ? TITLE_H : 0)),
+  };
+}
+
+export interface RenderWireframeOptions {
+  /** Skip validation (e.g. while a spec is still streaming in). */
+  skipValidation?: boolean;
+}
+
+export async function renderWireframeSvg(spec: Spec, opts: RenderWireframeOptions = {}) {
+  if (!opts.skipValidation) {
+    const issues = checkSpec(spec);
+    if (issues.length) throw new SpecError(issues);
+  }
+  const { width, height } = boardSize(spec);
+  return renderToSvg(spec, {
+    registry: withPalette(paletteFor((spec.elements[spec.root]?.props as any)?.accent)) as any,
+    includeStandard: false,
+    fonts: await loadFonts(),
+    width,
+    height,
+  });
+}
+
+export async function renderWireframePng(spec: Spec, opts: RenderWireframeOptions & { scale?: number } = {}) {
+  const svg = await renderWireframeSvg(spec, opts);
+  const { Resvg } = await import("@resvg/resvg-js");
+  const resvg = new Resvg(svg, { fitTo: { mode: "zoom", value: opts.scale ?? 1 } });
+  return resvg.render().asPng();
+}

package/src/schema.ts

@@ -0,0 +1,43 @@
+import { defineSchema } from "@json-render/core";
+
+/**
+ * Wireframe spec schema. Same flat element shape as the other json-render
+ * renderers (root + elements map), with wireframe-specific rules for the
+ * generated LLM prompt.
+ */
+export const wireframeSchema = defineSchema(
+  (s) => ({
+    spec: s.object({
+      root: s.string(),
+      elements: s.record(
+        s.object({
+          type: s.ref("catalog.components"),
+          props: s.propsOf("catalog.components"),
+          children: s.array(s.string()),
+          visible: { ...s.any(), ...s.optional() },
+          repeat: { ...s.any(), ...s.optional() },
+        }),
+      ),
+    }),
+    catalog: s.object({
+      components: s.map({
+        props: s.zod(),
+        slots: s.array(s.string()),
+        description: s.string(),
+        example: s.any(),
+      }),
+    }),
+  }),
+  {
+    defaultRules: [
+      "The root element MUST be a Board. A Board's children are Screens (and optional Notes placed beside them).",
+      "Every Screen MUST be a direct child of the Board. Each Screen is one view of the product; use several Screens to show several views or states.",
+      "Screens lay out their children top to bottom. Use Stack (direction row/column) and Grid inside a Screen to arrange content.",
+      "Modal and Drawer are overlays. They MUST be direct children of a Screen, and SHOULD be listed last in the Screen's children so they draw on top.",
+      "NavBar goes first in a Screen's children and TabBar goes last (before any overlay).",
+      "This is a low-fidelity wireframe: prefer placeholders (Image boxes, Text with lines) over invented copy, unless the copy matters to the design.",
+      "Every element MUST include a \"children\" array. Leaf elements use an empty array: \"children\": [].",
+      "Every id listed in a children array MUST exist as its own element.",
+    ],
+  },
+);

package/src/suggest.ts

@@ -0,0 +1,34 @@
+// Close-match suggestions for error messages, so a model (or person) can fix a typo in one step.
+
+/** Edit distance counting a swap of neighbouring letters as one edit ("serach" → search). */
+export function editDistance(a: string, b: string) {
+  const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j++) d[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+    }
+  }
+  return d[a.length][b.length];
+}
+
+/** Up to `limit` candidates within a small edit distance of `word`, closest first. */
+export function closeMatches(word: string, candidates: string[], limit = 3): string[] {
+  const q = word.toLowerCase();
+  const maxEdits = Math.max(1, Math.floor(q.length / 3));
+  return candidates
+    .map((c) => [c, editDistance(q, c.toLowerCase())] as const)
+    .filter(([, d]) => d <= maxEdits)
+    .sort((a, b) => a[1] - b[1] || a[0].localeCompare(b[0]))
+    .slice(0, limit)
+    .map(([c]) => c);
+}
+
+export function unknownComponentMessage(name: string, components: string[]) {
+  const close = closeMatches(name, components);
+  return close.length
+    ? `unknown component "${name}" (did you mean ${close.join(", ")}?)`
+    : `unknown component "${name}" (components: ${components.join(", ")})`;
+}