openink 0.1.0

package/src/render/blocks/forms.js

@@ -0,0 +1,86 @@
+const label = { type: "text", doc: "Label shown above the control." };
+const placeholder = { type: "text", doc: "Placeholder text." };
+
+/** @type {import("./index.js").BlockDef[]} */
+export default [
+  {
+    name: "input",
+    group: "Forms",
+    summary: "Single-line text field.",
+    props: {
+      label,
+      placeholder,
+      value: { type: "text", doc: "Pre-filled value." },
+      inputType: { type: "string", doc: "HTML input type: `text`, `email`, `password`, `number`…" },
+      disabled: { type: "boolean", doc: "Grey out the field." },
+    },
+    render: (b, c) =>
+      `<div class="field">${c.label(b)}<wired-input type="${c.esc(b.inputType || "text")}"${c.attr("placeholder", b.placeholder)}${
+        b.value != null ? ` value="${c.esc(c.plain(b.value))}"` : ""
+      }${b.disabled ? " disabled" : ""}></wired-input></div>`,
+  },
+  {
+    name: "search",
+    group: "Forms",
+    summary: "Search field with a magnifier.",
+    props: { placeholder },
+    render: (b, c) => `<wired-search-input${c.attr("placeholder", b.placeholder)}></wired-search-input>`,
+  },
+  {
+    name: "textarea",
+    group: "Forms",
+    summary: "Multi-line text field.",
+    props: { label, placeholder, rows: { type: "number", doc: "Visible rows (default 3)." } },
+    render: (b, c) =>
+      `<div class="field">${c.label(b)}<wired-textarea rows="${+b.rows || 3}"${c.attr("placeholder", b.placeholder)}></wired-textarea></div>`,
+  },
+  {
+    name: "select",
+    group: "Forms",
+    summary: "Dropdown.",
+    props: {
+      label,
+      options: { type: "text[]", doc: "Choices.", required: true },
+      selected: { type: "number", doc: "Index of the pre-selected option (default 0)." },
+    },
+    render: (b, c) =>
+      `<div class="field">${c.label(b)}<wired-combo selected="${+b.selected || 0}">${(b.options || [])
+        .map((o, i) => `<wired-item value="${i}">${c.tx(o)}</wired-item>`)
+        .join("")}</wired-combo></div>`,
+  },
+  {
+    name: "checkbox",
+    group: "Forms",
+    summary: "Checkbox with a label.",
+    props: { label: { ...label, required: true }, checked: { type: "boolean", doc: "Start ticked." } },
+    render: (b, c) => `<wired-checkbox${b.checked ? " checked" : ""}>${c.tx(b.label)}</wired-checkbox>`,
+  },
+  {
+    name: "toggle",
+    group: "Forms",
+    summary: "On/off switch with a label.",
+    props: { label: { ...label, required: true }, checked: { type: "boolean", doc: "Start switched on." } },
+    render: (b, c) => `<div class="row">${c.tx(b.label)}<wired-toggle${b.checked ? " checked" : ""}></wired-toggle></div>`,
+  },
+  {
+    name: "radio",
+    group: "Forms",
+    summary: "Radio group.",
+    props: {
+      label,
+      options: { type: "text[]", doc: "Choices.", required: true },
+      selected: { type: "number", doc: "Index of the pre-selected option (default 0)." },
+    },
+    render: (b, c) =>
+      `<div class="field">${c.label(b)}<wired-radio-group selected="${+b.selected || 0}">${(b.options || [])
+        .map((o, i) => `<wired-radio name="${i}">${c.tx(o)}</wired-radio>`)
+        .join("")}</wired-radio-group></div>`,
+  },
+  {
+    name: "slider",
+    group: "Forms",
+    summary: "Range slider.",
+    props: { label, value: { type: "number", doc: "Start position, 0 to 100 (default 30)." } },
+    render: (b, c) => `<div class="field">${c.label(b)}<wired-slider value="${+b.value || 30}"></wired-slider></div>`,
+  },
+];

package/src/render/blocks/index.js

@@ -0,0 +1,42 @@
+import layout from "./layout.js";
+import text from "./text.js";
+import media from "./media.js";
+import forms from "./forms.js";
+import actions from "./actions.js";
+import data from "./data.js";
+import content from "./content.js";
+import feedback from "./feedback.js";
+import navigation from "./navigation.js";
+import overlay from "./overlay.js";
+
+/**
+ * A block is one entry in a screen's `blocks` list. Everything the framework knows about it
+ * (validation, docs, JSON Schema, rendering) comes from this one definition.
+ *
+ * @typedef {object} PropDef
+ * @property {"text"|"string"|"number"|"boolean"|"text[]"|"number[]"|"sections"|"links"|"rows"} type
+ *   `text` = string, number, or a `{ lang: string }` translation object.
+ *   `sections` = list of `{ label, children }`; `links` = list of `{ icon, label, go, toast, open }`.
+ * @property {string} doc            Shown in the generated docs and in editor tooltips.
+ * @property {boolean} [required]
+ * @property {string[]} [enum]       Allowed values (for `type: "string"`).
+ *
+ * @typedef {object} BlockDef
+ * @property {string} name           The `type:` value used in a spec.
+ * @property {string} group          Section heading in the generated docs.
+ * @property {string} summary        One-line description.
+ * @property {boolean} [children]    Accepts a `children` list of blocks.
+ * @property {Record<string, PropDef>} props
+ * @property {(b: object) => Array<[string, any]>} [nested]   Extra nested blocks as [path suffix, block] pairs.
+ * @property {(b: object) => string[]} [targets]              Extra screen ids this block links to.
+ * @property {(b: object, ctx: import("../context.js").Context) => string} render
+ */
+
+/** @type {BlockDef[]} */
+export const blocks = [...layout, ...text, ...content, ...media, ...forms, ...actions, ...navigation, ...feedback, ...overlay, ...data];
+
+const byName = new Map(blocks.map((b) => [b.name, b]));
+if (byName.size !== blocks.length) throw new Error("Duplicate block name in src/render/blocks");
+
+export const getBlock = (name) => byName.get(name);
+export const blockNames = () => [...byName.keys()];

package/src/render/blocks/layout.js

@@ -0,0 +1,102 @@
+import { ACTION } from "./shared.js";
+
+/** @type {import("./index.js").BlockDef[]} */
+export default [
+  {
+    name: "stack",
+    group: "Layout",
+    summary: "Vertical stack of blocks.",
+    children: true,
+    props: { center: { type: "boolean", doc: "Center the children horizontally." } },
+    render: (b, c) => `<div class="stack${b.center ? " center-items" : ""}">${c.kids(b)}</div>`,
+  },
+  {
+    name: "row",
+    group: "Layout",
+    summary: "Horizontal row that wraps on small screens.",
+    children: true,
+    props: {
+      between: { type: "boolean", doc: "Push the first and last child to opposite ends." },
+      center: { type: "boolean", doc: "Center the children." },
+    },
+    render: (b, c) => `<div class="row${b.between ? " between" : ""}${b.center ? " center" : ""}">${c.kids(b)}</div>`,
+  },
+  {
+    name: "grid",
+    group: "Layout",
+    summary: "Equal-width columns. Collapses to one column on phones.",
+    children: true,
+    props: { cols: { type: "number", doc: "Number of columns (default 2)." } },
+    render: (b, c) => `<div class="grid" style="--cols:${+b.cols || 2}">${c.kids(b)}</div>`,
+  },
+  {
+    name: "card",
+    group: "Layout",
+    summary: "Hand-drawn box around related blocks. Clickable when `go` is set.",
+    children: true,
+    props: {
+      title: { type: "text", doc: "Small heading at the top of the card." },
+      dash: { type: "boolean", doc: "No fill (a lighter, secondary card)." },
+      center: { type: "boolean", doc: "Center the content horizontally." },
+      elevation: { type: "number", doc: "Shadow layers, 1 to 5 (default 1)." },
+      ...ACTION,
+    },
+    render: (b, c) =>
+      `<wired-card elevation="${+b.elevation || 1}"${c.act(b)} class="card${b.go ? " click" : ""}${b.dash ? " dash" : ""}">${
+        b.title ? `<h3>${c.tx(b.title)}</h3>` : ""
+      }<div class="stack${b.center ? " center-items" : ""}">${c.kids(b)}</div></wired-card>`,
+  },
+  {
+    name: "accordion",
+    group: "Layout",
+    summary: "Collapsible sections (FAQ, filters, settings groups).",
+    props: {
+      items: { type: "sections", doc: "List of `{ label, children }`.", required: true },
+      open: { type: "number", doc: "Index of the section open at first (default: all closed)." },
+    },
+    nested: (b) => (b.items || []).flatMap((t, i) => (t?.children || []).map((x, j) => [`.items[${i}].children[${j}]`, x])),
+    render: (b, c) =>
+      `<div class="accordion">${(b.items || [])
+        .map(
+          (s, i) =>
+            `<details${b.open === i ? " open" : ""}><summary>${c.tx(s.label)}<oi-icon name="chevron-down" size="18"></oi-icon></summary><div class="stack">${(s.children || [])
+              .map((x) => c.block(x))
+              .join("")}</div></details>`
+        )
+        .join("")}</div>`,
+  },
+  {
+    name: "device",
+    group: "Layout",
+    summary: "Wrap screens in a phone, tablet or browser frame. Ideal for mobile-app and responsive sketches.",
+    children: true,
+    props: {
+      kind: { type: "string", enum: ["phone", "tablet", "browser"], doc: "Frame type (default `phone`)." },
+      title: { type: "text", doc: "Address shown in the browser bar." },
+    },
+    render: (b, c) => {
+      const kind = b.kind || "phone";
+      const bar =
+        kind === "browser"
+          ? `<div class="device-bar"><i></i><i></i><i></i><span>${c.tx(b.title || "example.com")}</span></div>`
+          : kind === "phone"
+            ? `<div class="device-notch"></div>`
+            : "";
+      return `<div class="device device-${kind}"><wired-card elevation="2" class="device-frame">${bar}<div class="stack device-body">${c.kids(b)}</div></wired-card></div>`;
+    },
+  },
+  {
+    name: "divider",
+    group: "Layout",
+    summary: "Hand-drawn horizontal line.",
+    props: {},
+    render: () => `<wired-divider></wired-divider>`,
+  },
+  {
+    name: "spacer",
+    group: "Layout",
+    summary: "Empty vertical space.",
+    props: { h: { type: "number", doc: "Height in px (default 16)." } },
+    render: (b) => `<div style="height:${+b.h || 16}px"></div>`,
+  },
+];

package/src/render/blocks/media.js

@@ -0,0 +1,65 @@
+const size = { type: "number", doc: "Height in px." };
+const label = { type: "text", doc: "Caption centered in the box." };
+
+/** @type {import("./index.js").BlockDef[]} */
+export default [
+  {
+    name: "image",
+    group: "Media",
+    summary: "Image placeholder: hand-drawn box with a cross. Use `round` for avatars.",
+    props: { h: size, label, round: { type: "boolean", doc: "Draw a circle instead of a box." } },
+    render: (b, c) =>
+      `<oi-placeholder h="${+b.h || 140}" cross${b.label ? ` label="${c.esc(c.plain(b.label))}"` : ""}${b.round ? " round" : ""}></oi-placeholder>`,
+  },
+  {
+    name: "map",
+    group: "Media",
+    summary: "Map placeholder with a pin.",
+    props: { h: size, label },
+    render: (b, c) => `<oi-placeholder h="${+b.h || 160}" label="${c.esc(c.plain(b.label) || "Map")}" pin></oi-placeholder>`,
+  },
+  {
+    name: "box",
+    group: "Media",
+    summary: "Generic hand-drawn box, for ads, embeds, anything else.",
+    props: { h: size, label },
+    render: (b, c) => `<oi-placeholder h="${+b.h || 80}" label="${c.esc(c.plain(b.label))}"></oi-placeholder>`,
+  },
+  {
+    name: "video",
+    group: "Media",
+    summary: "Video placeholder with a play button.",
+    props: { h: size, label },
+    render: (b, c) => `<oi-placeholder h="${+b.h || 220}" play${b.label ? ` label="${c.esc(c.plain(b.label))}"` : ""}></oi-placeholder>`,
+  },
+  {
+    name: "carousel",
+    group: "Media",
+    summary: "Swipeable gallery: image placeholder with arrows and page dots.",
+    props: { h: size, label, count: { type: "number", doc: "Number of slides shown as dots (default 4)." } },
+    render: (b, c) =>
+      `<oi-placeholder h="${+b.h || 260}" cross dots="${+b.count || 4}"${b.label ? ` label="${c.esc(c.plain(b.label))}"` : ""}></oi-placeholder>`,
+  },
+  {
+    name: "dropzone",
+    group: "Media",
+    summary: "Dashed upload area with an arrow.",
+    props: { h: size, label },
+    render: (b, c) => `<oi-placeholder h="${+b.h || 140}" upload label="${c.esc(c.plain(b.label) || "Drop files here")}"></oi-placeholder>`,
+  },
+  {
+    name: "chart",
+    group: "Media",
+    summary: "Hand-drawn chart with sample data. It shows where a chart goes and what kind it is.",
+    props: {
+      kind: { type: "string", enum: ["line", "area", "bar", "pie", "donut"], doc: "Chart type (default `line`)." },
+      h: size,
+      values: { type: "number[]", doc: "Your own data points. Leave out for sample data." },
+      label: { type: "text", doc: "Caption in the corner." },
+    },
+    render: (b, c) =>
+      `<oi-chart kind="${c.esc(b.kind || "line")}" h="${+b.h || 200}"${b.values ? ` values="${c.esc(b.values.join(","))}"` : ""}${
+        b.label ? ` label="${c.esc(c.plain(b.label))}"` : ""
+      }></oi-chart>`,
+  },
+];

package/src/render/blocks/navigation.js

@@ -0,0 +1,67 @@
+/** @type {import("./index.js").BlockDef[]} */
+export default [
+  {
+    name: "breadcrumb",
+    group: "Navigation",
+    summary: "Path to the current page. The last item is the current one.",
+    props: { items: { type: "text[]", doc: "Path segments.", required: true } },
+    render: (b, c) => {
+      const items = b.items || [];
+      return `<nav class="crumbs">${items
+        .map((x, i) => `<span${i === items.length - 1 ? ' class="current"' : ""}>${c.tx(x)}</span>`)
+        .join('<span class="sep">/</span>')}</nav>`;
+    },
+  },
+  {
+    name: "pagination",
+    group: "Navigation",
+    summary: "Previous / page numbers / next.",
+    props: {
+      pages: { type: "number", doc: "Number of pages (default 5)." },
+      active: { type: "number", doc: "Current page, starting at 1 (default 1)." },
+    },
+    render: (b, c) => {
+      const pages = +b.pages || 5;
+      const active = +b.active || 1;
+      return `<div class="row pagination"><wired-button data-toast="Previous page">${c.icon("arrow-left")}</wired-button><div class="row" data-chips>${Array.from(
+        { length: pages },
+        (_, i) => `<wired-button class="chip${i + 1 === active ? " on" : ""}" elevation="${i + 1 === active ? 3 : 1}">${i + 1}</wired-button>`
+      ).join("")}</div><wired-button data-toast="Next page">${c.icon("arrow-right")}</wired-button></div>`;
+    },
+  },
+  {
+    name: "steps",
+    group: "Navigation",
+    summary: "Numbered progress through a multi-step flow (checkout, onboarding).",
+    props: {
+      items: { type: "text[]", doc: "Step names.", required: true },
+      active: { type: "number", doc: "Index of the current step, starting at 0 (default 0)." },
+    },
+    render: (b, c) => {
+      const active = +b.active || 0;
+      return `<ol class="steps">${(b.items || [])
+        .map((x, i) => `<li class="${i < active ? "done" : i === active ? "on" : ""}"><span class="dot">${i < active ? c.icon("check", 14) : i + 1}</span>${c.tx(x)}</li>`)
+        .join("")}</ol>`;
+    },
+  },
+  {
+    name: "tabbar",
+    group: "Navigation",
+    summary: "Bottom tab bar of a mobile app: icons with small labels.",
+    props: {
+      items: { type: "links", doc: "List of `{ icon, label, go, toast, open }`.", required: true },
+      active: { type: "number", doc: "Index of the highlighted item (default 0)." },
+    },
+    render: (b, c) => {
+      const active = +b.active || 0;
+      return `<div class="tabbar">${(b.items || [])
+        .map(
+          (i, n) =>
+            `<wired-button class="tab-item${n === active ? " on" : ""}" elevation="${n === active ? 3 : 1}"${c.act(i)}>${
+              i.icon ? c.icon(i.icon, 22, n === active) : ""
+            }${i.label != null ? `<span class="tab-label">${c.tx(i.label)}</span>` : ""}</wired-button>`
+        )
+        .join("")}</div>`;
+    },
+  },
+];

package/src/render/blocks/overlay.js

@@ -0,0 +1,18 @@
+/** @type {import("./index.js").BlockDef[]} */
+export default [
+  {
+    name: "modal",
+    group: "Overlays",
+    summary: "Dialog that opens over the screen when a button, card or link has `open: <id>`. Close with a `close: true` button, the X, or a click outside.",
+    children: true,
+    props: {
+      id: { type: "string", doc: "Unique id; other blocks use it in `open:`.", required: true },
+      title: { type: "text", doc: "Heading of the dialog." },
+      width: { type: "string", enum: ["narrow", "medium", "wide"], doc: "Dialog width (default `medium`)." },
+    },
+    render: (b, c) =>
+      `<div class="modal" data-modal="${c.esc(b.id)}" data-width="${c.esc(b.width || "medium")}"><div class="modal-backdrop" data-close></div><wired-card elevation="3" class="modal-card"><div class="row between"><h3>${
+        b.title ? c.tx(b.title) : ""
+      }</h3><wired-button data-close>${c.icon("close")}</wired-button></div><div class="stack">${c.kids(b)}</div></wired-card></div>`,
+  },
+];

package/src/render/blocks/shared.js

@@ -0,0 +1,20 @@
+import { ICON_NAMES } from "../../icons.js";
+
+/** Named colours a block or screen can be tinted with (`tone:`). Defined as CSS variables in openink.css. */
+export const TONES = ["blue", "green", "yellow", "red", "purple", "pink", "orange", "teal", "gray"];
+
+/** Props every block accepts, whatever its type. Handled by the renderer, not by individual blocks. */
+export const COMMON = {
+  tone: { type: "string", enum: TONES, doc: "Colour this block and everything inside it: outlines, text and drawn shapes." },
+  fill: { type: "boolean", doc: "Give the block a tinted background (uses `tone`, or a neutral tint)." },
+};
+
+/** Props shared by every clickable block. */
+export const ACTION = {
+  go: { type: "string", doc: "Id of the screen to open when clicked." },
+  toast: { type: "text", doc: "Message shown in a toast when clicked." },
+  open: { type: "string", doc: "Id of a `modal` block to open when clicked." },
+  close: { type: "boolean", doc: "Close the modal this block is inside when clicked." },
+};
+
+export const ICON = { type: "string", enum: ICON_NAMES, doc: "Hand-drawn icon name." };

package/src/render/blocks/text.js

@@ -0,0 +1,49 @@
+const heading = (level) => ({
+  name: `h${level}`,
+  group: "Text",
+  summary: `Level ${level} heading.`,
+  props: { text: { type: "text", doc: "Heading text.", required: true } },
+  render: (b, c) => `<h${level}>${c.tx(b.text)}</h${level}>`,
+});
+
+/** @type {import("./index.js").BlockDef[]} */
+export default [
+  heading(1),
+  heading(2),
+  heading(3),
+  {
+    name: "text",
+    group: "Text",
+    summary: "Paragraph. A bare string in a `children` list is shorthand for this block.",
+    props: {
+      text: { type: "text", doc: "Paragraph text.", required: true },
+      muted: { type: "boolean", doc: "Grey, smaller text." },
+      bold: { type: "boolean", doc: "Bold text." },
+    },
+    render: (b, c) => `<p class="${b.muted ? "muted" : ""}${b.bold ? " bold" : ""}">${c.tx(b.text)}</p>`,
+  },
+  {
+    name: "list",
+    group: "Text",
+    summary: "Bulleted list.",
+    props: { items: { type: "text[]", doc: "List items.", required: true } },
+    render: (b, c) => `<ul class="oi-list">${(b.items || []).map((i) => `<li>${c.tx(i)}</li>`).join("")}</ul>`,
+  },
+  {
+    name: "note",
+    group: "Text",
+    summary: "Yellow sticky-note annotation. Use it for behaviour a sketch cannot show.",
+    props: { text: { type: "text", doc: "Note text.", required: true } },
+    render: (b, c) => `<div class="note">${c.tx(b.text)}</div>`,
+  },
+  {
+    name: "badge",
+    group: "Text",
+    summary: "Small status pill.",
+    props: {
+      text: { type: "text", doc: "Badge text.", required: true },
+      status: { type: "string", enum: ["on", "wait", "off"], doc: "Colour: `on` green, `wait` orange, `off` grey." },
+    },
+    render: (b, c) => `<span class="badge ${c.esc(b.status || "")}">${c.tx(b.text)}</span>`,
+  },
+];

package/src/render/context.js

@@ -0,0 +1,63 @@
+import { getBlock, blockNames } from "./blocks/index.js";
+
+export const esc = (s) =>
+  String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+/**
+ * Helpers handed to every block's `render(b, ctx)`.
+ * @typedef {ReturnType<typeof createContext>} Context
+ */
+export function createContext(spec) {
+  const langs = spec.languages ?? [];
+  const def = langs[0];
+  const isTranslation = (v) => v && typeof v === "object" && !Array.isArray(v);
+
+  /** Plain string for a text value: first language, or the only value. */
+  const plain = (v) => (isTranslation(v) ? v[def] ?? Object.values(v)[0] ?? "" : v ?? "");
+
+  const ctx = {
+    langs,
+    esc,
+    plain,
+
+    /** Text node content. Translations become one <span data-l="xx"> per language. */
+    tx(v) {
+      if (v == null) return "";
+      if (isTranslation(v) && langs.length) return langs.map((l) => `<span data-l="${l}">${esc(v[l] ?? v[def] ?? "")}</span>`).join("");
+      return esc(plain(v));
+    },
+
+    /** Attribute. Translations add data-<name>-<lang> attributes that the runtime swaps in. */
+    attr(name, v) {
+      if (v == null) return "";
+      let s = ` ${name}="${esc(plain(v))}"`;
+      if (isTranslation(v) && langs.length) for (const l of langs) if (v[l] != null) s += ` data-${name}-${l}="${esc(v[l])}"`;
+      return s;
+    },
+
+    /** data-go / data-toast / data-open / data-close attributes for clickable blocks. */
+    act: (b) =>
+      `${b.go ? ` data-go="${esc(b.go)}"` : ""}${b.toast ? ctx.attr("data-toast", b.toast) : ""}${b.open ? ` data-open="${esc(b.open)}"` : ""}${b.close ? " data-close" : ""}`,
+
+    /** A hand-drawn icon. */
+    icon: (name, size = 18, filled = false) => `<oi-icon name="${esc(name)}" size="${size}"${filled ? " filled" : ""}></oi-icon>`,
+
+    /** Icon + label, for buttons and nav items. Either may be missing. */
+    inner: (b) => `${b.icon ? ctx.icon(b.icon) : ""}${b.label != null ? `<span class="btn-label">${ctx.tx(b.label)}</span>` : ""}`,
+
+    label: (b) => (b.label ? `<label class="fl">${ctx.tx(b.label)}</label>` : ""),
+
+    block(b) {
+      if (typeof b === "string") return getBlock("text").render({ text: b }, ctx);
+      const def = getBlock(b?.type);
+      if (!def) throw new Error(`Unknown block type "${b?.type}". Known types: ${blockNames().join(", ")}`);
+      const html = def.render(b, ctx);
+      // `tone` / `fill` work on any block: wrap it in an element that sets the colour variables
+      if (!b.tone && !b.fill) return html;
+      return `<div class="tone"${b.tone ? ` data-tone="${esc(b.tone)}"` : ""}${b.fill ? " data-fill" : ""}>${html}</div>`;
+    },
+
+    kids: (b) => (b.children || []).map((x) => ctx.block(x)).join(""),
+  };
+  return ctx;
+}

package/src/render/page.js

@@ -0,0 +1,76 @@
+import { createContext, esc } from "./context.js";
+import { colorVar, isPreset } from "../themes.js";
+
+const DEV_RELOAD = `<script>(function(){var v;setInterval(function(){fetch("/__version").then(function(r){return r.text()}).then(function(t){if(v&&t!==v)location.reload();v=t}).catch(function(){})},600)})()</script>`;
+
+/**
+ * Render a validated spec to a complete HTML document.
+ * @param {object} spec
+ * @param {{ dev?: boolean }} [opts]  dev = inject the live-reload poller
+ */
+export function renderPage(spec, { dev = false } = {}) {
+  const c = createContext(spec);
+  const langs = c.langs;
+  const first = spec.screens[0].id;
+
+  const navSets = Array.isArray(spec.nav) ? { default: spec.nav } : spec.nav || { default: [] };
+  const nav = Object.entries(navSets)
+    .map(([key, items]) => `<nav data-nav="${esc(key)}" hidden>${items.map((n) => `<wired-button${c.act(n)}>${c.inner(n)}</wired-button>`).join("")}</nav>`)
+    .join("");
+
+  const screens = spec.screens
+    .map(
+      (s) => `<section class="screen" id="${esc(s.id)}" data-title="${esc(c.plain(s.title) || s.id)}" data-nav="${esc(s.nav || "default")}"${s.width ? ` data-width="${esc(s.width)}"` : ""}${s.tone ? ` data-tone="${esc(s.tone)}"` : ""}>
+<p class="screen-title">${c.tx(s.title || s.id)}</p>
+${s.note ? `<div class="note">${c.tx(s.note)}</div>` : ""}
+${(s.blocks || []).map((b) => c.block(b)).join("\n")}
+</section>`
+    )
+    .join("\n");
+
+  // global modals live outside the screens, so any screen can open them
+  const modals = (spec.modals || []).map((m) => c.block({ ...m, type: "modal" })).join("\n");
+
+  const langBar = langs.length ? `<div class="lang">${langs.map((l) => `<wired-button data-lang="${esc(l)}">${esc(l.toUpperCase())}</wired-button>`).join("")}</div>` : "";
+  const langCss = langs.length
+    ? `<style>[data-l]{display:none}${langs.map((l) => `html[lang="${esc(l)}"] [data-l="${esc(l)}"]{display:inline}`).join("")}</style>`
+    : "";
+
+  // theme: a built-in preset (theme-<name>.css is copied by the build) or the project's own .css file
+  const themeLink = spec.theme && spec.theme !== "sketch" ? `<link rel="stylesheet" href="${esc(isPreset(spec.theme) ? `theme-${spec.theme}.css` : spec.theme)}" />` : "";
+  const colors = Object.entries(spec.colors || {});
+  const colorCss = colors.length ? `<style>:root{${colors.map(([k, v]) => `${colorVar(k)}:${v}`).join(";")}}</style>` : "";
+
+  return `<!DOCTYPE html>
+<html lang="${esc(langs[0] || "en")}">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${esc(spec.name)} · wireframe</title>
+<link rel="stylesheet" href="openink.css" />
+${themeLink}
+${colorCss}
+${langCss}
+<script>window.OPENINK=${JSON.stringify({ languages: langs, first }).replace(/</g, "\\u003c")};</script>
+<script src="openink.js" defer></script>
+${dev ? DEV_RELOAD : ""}
+</head>
+<body>
+<div class="shell">
+<header class="oi-bar">
+<a class="brand" data-go="${esc(first)}">${esc(spec.name)}</a>
+${nav}
+${langBar}
+<wired-button class="print-btn" onclick="window.print()">PDF</wired-button>
+</header>
+<main>
+${screens}
+</main>
+${modals}
+<footer class="muted center">${esc(spec.footer || "Wireframe · not the final design")}</footer>
+</div>
+<div class="toast" id="toast"></div>
+</body>
+</html>
+`;
+}