openink 0.1.0

package/src/build.js

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import YAML from "yaml";
+import * as esbuild from "esbuild";
+import { validate } from "./spec/validate.js";
+import { renderPage } from "./render/page.js";
+import { isPreset } from "./themes.js";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const SPEC_FILES = ["spec.yaml", "spec.yml", "spec.json"];
+
+/** A spec that failed validation. `issues` is the list from validate(). */
+export class SpecError extends Error {
+  constructor(message, issues = []) {
+    super(message);
+    this.name = "SpecError";
+    this.issues = issues;
+  }
+}
+
+/** Find and parse the spec in a project directory. */
+export function loadSpec(dir = ".") {
+  const file = SPEC_FILES.map((f) => path.join(dir, f)).find(fs.existsSync);
+  if (!file) throw new SpecError(`No spec.yaml found in ${path.resolve(dir)}. Run \`openink init\` to create one.`);
+  let spec;
+  try {
+    spec = YAML.parse(fs.readFileSync(file, "utf8"));
+  } catch (e) {
+    throw new SpecError(`${path.basename(file)} is not valid YAML: ${e.message}`);
+  }
+  return { spec, file };
+}
+
+let runtimeCache;
+/** Bundle the browser runtime (wired-elements + roughjs inlined, so output works offline and from file://). */
+async function bundleRuntime() {
+  runtimeCache ??= esbuild
+    .build({ entryPoints: [path.join(here, "runtime/index.js")], bundle: true, minify: true, format: "iife", write: false, logLevel: "silent" })
+    .then((r) => r.outputFiles[0].text);
+  return runtimeCache;
+}
+
+/**
+ * Build a project into static files.
+ * @param {{ dir?: string, out?: string, dev?: boolean, theme?: string }} [opts]  `theme` overrides the spec's theme
+ * @returns {Promise<{ outDir: string, spec: object, warnings: {path:string,message:string}[] }>}
+ */
+export async function build({ dir = ".", out = "dist", dev = false, theme } = {}) {
+  const projectDir = path.resolve(dir);
+  const outDir = path.resolve(projectDir, out);
+  if (projectDir === outDir || projectDir.startsWith(outDir + path.sep)) {
+    throw new Error(`Output directory ${outDir} would contain the project itself. Choose a different --out.`);
+  }
+
+  const { spec } = loadSpec(projectDir);
+  if (theme) spec.theme = theme;
+  const { errors, warnings } = validate(spec);
+  const customTheme = typeof spec?.theme === "string" && !isPreset(spec.theme) && spec.theme.endsWith(".css");
+  if (customTheme && !fs.existsSync(path.join(projectDir, spec.theme))) {
+    errors.push({ path: "theme", message: `Theme file "${spec.theme}" not found next to the spec.` });
+  }
+  if (errors.length) throw new SpecError(`${errors.length} problem${errors.length > 1 ? "s" : ""} in the spec`, errors);
+
+  fs.rmSync(outDir, { recursive: true, force: true });
+  fs.mkdirSync(outDir, { recursive: true });
+  fs.writeFileSync(path.join(outDir, "index.html"), renderPage(spec, { dev }));
+  fs.writeFileSync(path.join(outDir, "openink.js"), await bundleRuntime());
+  fs.copyFileSync(path.join(here, "styles/openink.css"), path.join(outDir, "openink.css"));
+  if (customTheme) {
+    fs.mkdirSync(path.dirname(path.join(outDir, spec.theme)), { recursive: true });
+    fs.copyFileSync(path.join(projectDir, spec.theme), path.join(outDir, spec.theme));
+  } else if (spec.theme && spec.theme !== "sketch") {
+    fs.copyFileSync(path.join(here, "styles/themes", `${spec.theme}.css`), path.join(outDir, `theme-${spec.theme}.css`));
+  }
+
+  // Optional real images / logos: put them in <project>/assets and reference them as assets/…
+  const assets = path.join(projectDir, "assets");
+  if (fs.existsSync(assets)) fs.cpSync(assets, path.join(outDir, "assets"), { recursive: true });
+
+  return { outDir, spec, warnings };
+}

package/src/cli.js

@@ -0,0 +1,133 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { build, loadSpec, SpecError } from "./build.js";
+import { validate } from "./spec/validate.js";
+import { blocksMarkdown } from "./spec/docs.js";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const { version } = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+
+const HELP = `openink ${version}: sketchy, clickable wireframes from a YAML spec
+
+Usage: openink <command> [dir] [options]
+
+Commands:
+  init [dir]       Create a new project (spec.yaml + AI-assistant instructions)
+  build [dir]      Build static files into <dir>/dist
+  dev [dir]        Build, serve and live-reload while you edit the spec
+  validate [dir]   Check the spec without building
+  pdf [dir]        Build and export a PDF (one screen per page)
+  png [dir]        Build and export one PNG per screen
+  blocks           Print the reference for every block type
+
+Options:
+  --out <dir>      Output directory, relative to the project (default: dist)
+  --port <n>       Dev server port (default: 3000)
+  --theme <name>   Try a colour theme without editing the spec: sketch, color, pastel, blueprint, dark
+  -v, --version    Print the version
+  -h, --help       Show this help
+
+[dir] defaults to the current directory. PDF/PNG export needs Chrome, Chromium or Edge.`;
+
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+const red = paint(31), yellow = paint(33), green = paint(32), dim = paint(2);
+
+function parse(argv) {
+  const opts = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") opts.help = true;
+    else if (a === "-v" || a === "--version") opts.version = true;
+    else if (a === "--out" || a === "--port" || a === "--theme") {
+      if (argv[i + 1] === undefined) throw new Error(`${a} needs a value`);
+      opts[a.slice(2)] = argv[++i];
+    } else if (a.startsWith("-")) throw new Error(`Unknown option ${a}. Try --help.`);
+    else opts._.push(a);
+  }
+  return opts;
+}
+
+const printIssues = (list, color, label) =>
+  list.forEach((i) => console.error(`  ${color(label)} ${dim(i.path || "spec")}: ${i.message}`));
+
+function init(dir = ".") {
+  const target = path.resolve(dir);
+  if (fs.existsSync(path.join(target, "spec.yaml"))) throw new Error(`${path.join(target, "spec.yaml")} already exists.`);
+  fs.mkdirSync(target, { recursive: true });
+  const name = path.basename(target);
+  for (const file of fs.readdirSync(path.join(root, "templates/starter"))) {
+    const text = fs.readFileSync(path.join(root, "templates/starter", file), "utf8").replaceAll("{{name}}", name);
+    fs.writeFileSync(path.join(target, file === "gitignore" ? ".gitignore" : file), text);
+  }
+  const rel = path.relative(process.cwd(), target);
+  console.log(green("✓") + ` Created ${rel || "."}/spec.yaml\n\nNext:\n  ${rel ? `cd ${rel} && ` : ""}npx openink dev`);
+}
+
+/** @param {string[]} argv */
+export async function run(argv) {
+  const opts = parse(argv);
+  const [cmd, dir] = opts._;
+  if (opts.version) return console.log(version);
+  if (!cmd || opts.help || cmd === "help") return console.log(HELP);
+
+  const out = opts.out ?? "dist";
+  switch (cmd) {
+    case "init":
+      return init(dir);
+
+    case "blocks":
+      return console.log(blocksMarkdown());
+
+    case "validate": {
+      const { spec } = loadSpec(dir);
+      const { errors, warnings } = validate(spec);
+      printIssues(warnings, yellow, "warn ");
+      printIssues(errors, red, "error");
+      if (errors.length) throw new SpecError(`${errors.length} error${errors.length > 1 ? "s" : ""}`);
+      return console.log(green("✓") + ` Spec is valid${warnings.length ? ` (${warnings.length} warning${warnings.length > 1 ? "s" : ""})` : ""}`);
+    }
+
+    case "build": {
+      const { outDir, spec, warnings } = await build({ dir, out, theme: opts.theme });
+      printIssues(warnings, yellow, "warn ");
+      return console.log(green("✓") + ` ${spec.screens.length} screens → ${path.relative(process.cwd(), path.join(outDir, "index.html")) || "index.html"}`);
+    }
+
+    case "pdf":
+    case "png": {
+      const { exportFiles } = await import("./export.js");
+      const { files } = await exportFiles({ dir, out, png: cmd === "png", theme: opts.theme });
+      return console.log(green("✓") + ` ${files.length === 1 ? path.relative(process.cwd(), files[0]) : `${files.length} PNGs in ${path.relative(process.cwd(), path.dirname(files[0]))}`}`);
+    }
+
+    case "dev": {
+      const { dev } = await import("./dev.js");
+      const server = await dev({
+        dir,
+        port: opts.port ? +opts.port : 3000,
+        theme: opts.theme,
+        onIssues: (e) => { console.error(red("✗ " + e.message)); printIssues(e.issues, red, "error"); },
+      });
+      console.log(green("✓") + ` Serving ${server.url}  ${dim("(Ctrl+C to stop)")}`);
+      process.on("SIGINT", () => { server.close(); process.exit(0); });
+      return new Promise(() => {}); // keep running
+    }
+
+    default:
+      throw new Error(`Unknown command "${cmd}". Try \`openink --help\`.`);
+  }
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  try {
+    await run(argv);
+  } catch (e) {
+    if (e instanceof SpecError) {
+      console.error(red("✗ " + e.message));
+      printIssues(e.issues, red, "error");
+    } else console.error(red("✗ " + e.message));
+    process.exitCode = 1;
+  }
+}

package/src/dev.js

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { build, SpecError } from "./build.js";
+
+const MIME = {
+  ".html": "text/html; charset=utf-8", ".js": "text/javascript", ".css": "text/css", ".json": "application/json",
+  ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".svg": "image/svg+xml",
+  ".webp": "image/webp", ".ico": "image/x-icon", ".woff2": "font/woff2", ".pdf": "application/pdf",
+};
+
+/**
+ * Serve the project with live reload: rebuilds when files change and the browser refreshes itself.
+ * @param {{ dir?: string, out?: string, port?: number, theme?: string, log?: (msg: string) => void, onIssues?: (e: SpecError) => void }} [opts]
+ */
+export async function dev({ dir = ".", out = ".openink-dev", port = 3000, theme, log = console.log, onIssues = () => {} } = {}) {
+  const projectDir = path.resolve(dir);
+  const outDir = path.resolve(projectDir, out);
+  let version = String(Date.now());
+
+  const rebuild = async () => {
+    try {
+      const { warnings } = await build({ dir, out, dev: true, theme });
+      version = String(Date.now());
+      log(`✓ built${warnings.length ? ` (${warnings.length} warning${warnings.length > 1 ? "s" : ""})` : ""}`);
+    } catch (e) {
+      if (e instanceof SpecError) onIssues(e);
+      else log(`✗ ${e.message}`);
+    }
+  };
+  await rebuild();
+
+  const server = http.createServer((req, res) => {
+    const url = decodeURIComponent(new URL(req.url, "http://x").pathname);
+    if (url === "/__version") return void res.writeHead(200, { "Cache-Control": "no-store" }).end(version);
+    const file = path.join(outDir, url === "/" ? "index.html" : url);
+    if (!file.startsWith(outDir) || !fs.existsSync(file) || fs.statSync(file).isDirectory()) return void res.writeHead(404).end("Not found");
+    res.writeHead(200, { "Content-Type": MIME[path.extname(file)] || "application/octet-stream", "Cache-Control": "no-store" });
+    fs.createReadStream(file).pipe(res);
+  });
+  await new Promise((resolve, reject) => server.once("error", reject).listen(port, resolve));
+
+  let timer;
+  const watcher = fs.watch(projectDir, { recursive: true }, (_, name) => {
+    const changed = path.resolve(projectDir, name || "");
+    if (changed.startsWith(outDir) || changed.includes(`${path.sep}node_modules`)) return;
+    clearTimeout(timer);
+    timer = setTimeout(rebuild, 150);
+  });
+
+  const close = () => { watcher.close(); server.close(); fs.rmSync(outDir, { recursive: true, force: true }); };
+  return { url: `http://localhost:${port}`, close };
+}

package/src/export.js

@@ -0,0 +1,68 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { build } from "./build.js";
+
+const BROWSERS = [
+  process.env.CHROME_PATH,
+  "C:/Program Files/Google/Chrome/Application/chrome.exe",
+  "C:/Program Files (x86)/Google/Chrome/Application/chrome.exe",
+  "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe",
+  "C:/Program Files/Microsoft/Edge/Application/msedge.exe",
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+  "/usr/bin/google-chrome",
+  "/usr/bin/google-chrome-stable",
+  "/usr/bin/chromium",
+  "/usr/bin/chromium-browser",
+  "/usr/bin/microsoft-edge",
+].filter(Boolean);
+
+export const findBrowser = () => BROWSERS.find((p) => fs.existsSync(p));
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+const slug = (s) => String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "wireframe";
+
+/**
+ * Build the project, then export a PDF (one screen per A4 landscape page) or PNG screenshots.
+ * Needs Chrome, Chromium or Edge installed (set CHROME_PATH to point at one).
+ * @param {{ dir?: string, out?: string, png?: boolean, theme?: string }} [opts]
+ * @returns {Promise<{ files: string[] }>}
+ */
+export async function exportFiles({ dir = ".", out = "dist", png = false, theme } = {}) {
+  const executablePath = findBrowser();
+  if (!executablePath) throw new Error("No Chrome, Chromium or Edge found. Install one, or set CHROME_PATH to its executable.");
+
+  const { outDir, spec } = await build({ dir, out, theme });
+  const { default: puppeteer } = await import("puppeteer-core");
+  const browser = await puppeteer.launch({ executablePath, headless: true });
+  try {
+    const page = await browser.newPage();
+    await page.setViewport({ width: 1100, height: 800 });
+    await page.goto(pathToFileURL(path.join(outDir, "index.html")).href, { waitUntil: "networkidle0" });
+    await wait(500); // let wired-elements finish drawing
+
+    if (png) {
+      const dir = path.join(outDir, "png");
+      fs.mkdirSync(dir, { recursive: true });
+      const files = [];
+      for (const id of await page.$$eval(".screen", (s) => s.map((x) => x.id))) {
+        await page.evaluate((i) => { location.hash = i; }, id);
+        await wait(400);
+        const file = path.join(dir, `${id}.png`);
+        await page.screenshot({ path: file, fullPage: true });
+        files.push(file);
+      }
+      return { files };
+    }
+
+    // Print media shows every screen; the ones that were hidden have never been drawn, so force a render.
+    await page.emulateMediaType("print");
+    await page.evaluate(() => document.querySelectorAll("*").forEach((e) => e.wiredRender?.(true)));
+    await wait(500);
+    const file = path.join(outDir, `${slug(spec.name)}.pdf`);
+    await page.pdf({ path: file, format: "A4", landscape: true, printBackground: true, preferCSSPageSize: true });
+    return { files: [file] };
+  } finally {
+    await browser.close();
+  }
+}

package/src/icons.js

@@ -0,0 +1,47 @@
+// Icon paths on a 24x24 grid. Pure data: used by the validator (to list valid names) and by the
+// browser runtime (which draws them hand-drawn with RoughJS).
+// Each icon is a list of SVG path strings. `filled` icons can be solid when the `filled` attribute is set.
+
+const dot = (x, y, r = 1) => `M${x - r} ${y}a${r} ${r} 0 1 0 ${2 * r} 0a${r} ${r} 0 1 0 ${-2 * r} 0`;
+
+export const ICONS = {
+  home: ["M3 11.5L12 3l9 8.5", "M5.5 10v10.5h13V10", "M10 20.5v-6h4v6"],
+  search: ["M10.5 3a7.5 7.5 0 1 0 0 15 7.5 7.5 0 0 0 0-15z", "M16 16l5 5"],
+  heart: ["M12 20.5C5 15 3 11.5 3 8.6A4.6 4.6 0 0 1 12 7A4.6 4.6 0 0 1 21 8.6c0 2.9-2 6.4-9 11.9z"],
+  comment: ["M4 5h16v11H10l-4 4v-4H4z"],
+  share: ["M21 3L3 10.5l7 2.5 2.5 7z", "M10 13L21 3"],
+  bookmark: ["M6 3h12v18l-6-4.5L6 21z"],
+  plus: ["M12 4v16M4 12h16"],
+  bell: ["M6 16.5V11a6 6 0 0 1 12 0v5.5l2 2H4z", "M10 21h4"],
+  user: ["M12 3.5a4 4 0 1 0 0 8 4 4 0 0 0 0-8z", "M4 21c0-4.5 3.6-7 8-7s8 2.5 8 7"],
+  users: ["M9 4a3.5 3.5 0 1 0 0 7 3.5 3.5 0 0 0 0-7z", "M2 20c0-4 3-6 7-6s7 2 7 6", "M16 4.5a3.3 3.3 0 0 1 0 6.3", "M18 14.5c2.5.6 4 2.4 4 5.5"],
+  mail: ["M3 5.5h18v13H3z", "M3 6l9 7 9-7"],
+  settings: ["M12 8.5a3.5 3.5 0 1 0 0 7 3.5 3.5 0 0 0 0-7z", "M12 2.5v3M12 18.5v3M2.5 12h3M18.5 12h3", "M5.3 5.3l2.1 2.1M16.6 16.6l2.1 2.1M5.3 18.7l2.1-2.1M16.6 7.4l2.1-2.1"],
+  camera: ["M3 8h4l2-3h6l2 3h4v12H3z", "M12 10.5a3.5 3.5 0 1 0 0 7 3.5 3.5 0 0 0 0-7z"],
+  image: ["M3 5h18v14H3z", "M3 17l6-6 5 5 3-3 4 4", dot(8.5, 9.5, 1.5)],
+  video: ["M3 6h13v12H3z", "M16 10l5-3v10l-5-3"],
+  star: ["M12 3l2.7 5.9 6.3.7-4.7 4.3 1.3 6.3L12 17l-5.6 3.2 1.3-6.3L3 9.6l6.3-.7z"],
+  menu: ["M4 6h16M4 12h16M4 18h16"],
+  more: [dot(5, 12), dot(12, 12), dot(19, 12)],
+  close: ["M5 5l14 14M19 5L5 19"],
+  check: ["M4 12.5l5 5L20 6.5"],
+  "arrow-right": ["M4 12h16M14 6l6 6-6 6"],
+  "arrow-left": ["M20 12H4M10 6l-6 6 6 6"],
+  "chevron-down": ["M6 9l6 6 6-6"],
+  "chevron-right": ["M9 6l6 6-6 6"],
+  play: ["M7 4l13 8-13 8z"],
+  pin: ["M12 21s7-6.2 7-11.5a7 7 0 0 0-14 0C5 14.8 12 21 12 21z", "M12 7a2.5 2.5 0 1 0 0 5 2.5 2.5 0 0 0 0-5z"],
+  trash: ["M4 7h16M9 7V4h6v3", "M6 7l1 14h10l1-14"],
+  edit: ["M4 20l1-5L16 4l4 4L9 19z", "M14 6l4 4"],
+  upload: ["M12 16V4M6 10l6-6 6 6", "M4 20h16"],
+  download: ["M12 4v12M6 10l6 6 6-6", "M4 20h16"],
+  lock: ["M6 11h12v10H6z", "M8.5 11V8a3.5 3.5 0 0 1 7 0v3"],
+  cart: ["M3 4h3l2.5 11h10L21 7H7", dot(10, 20), dot(18, 20)],
+  chart: ["M4 4v16h16", "M8 15v-4M12 15V8M16 15v-6"],
+  calendar: ["M4 6h16v14H4z", "M4 10h16M8 3v4M16 3v4"],
+  filter: ["M3 5h18l-7 8v6l-4-2v-4z"],
+  info: ["M12 3a9 9 0 1 0 0 18 9 9 0 0 0 0-18z", "M12 11v6", dot(12, 7.5, 0.6)],
+  send: ["M3 11l18-8-8 18-2-8z"],
+};
+
+export const ICON_NAMES = Object.keys(ICONS);

package/src/index.js

@@ -0,0 +1,14 @@
+/**
+ * Programmatic API.
+ *
+ *   import { build } from "openink";
+ *   await build({ dir: "./my-project", out: "dist" });
+ */
+export { build, loadSpec, SpecError } from "./build.js";
+export { exportFiles } from "./export.js";
+export { dev } from "./dev.js";
+export { validate } from "./spec/validate.js";
+export { buildSchema } from "./spec/schema.js";
+export { blocksMarkdown } from "./spec/docs.js";
+export { blocks } from "./render/blocks/index.js";
+export { renderPage } from "./render/page.js";

package/src/render/blocks/actions.js

@@ -0,0 +1,68 @@
+import { ACTION, ICON } from "./shared.js";
+
+/** Nested blocks of a `{ label, children }` list (tabs, accordion sections). */
+export const sectionsNested = (key) => (b) =>
+  (b[key] || []).flatMap((t, i) => (t?.children || []).map((x, j) => [`.${key}[${i}].children[${j}]`, x]));
+
+/** @type {import("./index.js").BlockDef[]} */
+export default [
+  {
+    name: "button",
+    group: "Actions",
+    summary: "Button, optionally with an icon. Navigates with `go`, opens a `modal` with `open`, shows a message with `toast`.",
+    props: {
+      label: { type: "text", doc: "Button text. Leave out for an icon-only button." },
+      icon: { ...ICON, doc: "Icon shown before the label." },
+      primary: { type: "boolean", doc: "Heavier border: the main action on the screen." },
+      disabled: { type: "boolean", doc: "Grey out the button." },
+      ...ACTION,
+    },
+    render: (b, c) =>
+      `<wired-button elevation="${b.primary ? 3 : 1}"${c.act(b)}${b.disabled ? " disabled" : ""}>${c.inner(b)}</wired-button>`,
+  },
+  {
+    name: "chips",
+    group: "Actions",
+    summary: "Filter pills. Clicking one selects it and shows a “Results updated” toast.",
+    props: {
+      options: { type: "text[]", doc: "Pill labels.", required: true },
+      active: { type: "number", doc: "Index of the selected pill (default 0)." },
+    },
+    render: (b, c) => {
+      const active = +b.active || 0;
+      return `<div class="row chips" data-chips>${(b.options || [])
+        .map((o, i) => `<wired-button class="chip${i === active ? " on" : ""}" elevation="${i === active ? 3 : 1}">${c.tx(o)}</wired-button>`)
+        .join("")}</div>`;
+    },
+  },
+  {
+    name: "tabs",
+    group: "Actions",
+    summary: "Tab strip. Each tab has its own list of blocks.",
+    props: { tabs: { type: "sections", doc: "List of `{ label, children }`.", required: true } },
+    nested: sectionsNested("tabs"),
+    render: (b, c) => {
+      const tabs = b.tabs || [];
+      return `<div class="tabs" data-tabs><div class="row">${tabs
+        .map((t, i) => `<wired-button class="tab${i === 0 ? " on" : ""}" data-tab="${i}" elevation="${i === 0 ? 3 : 1}">${c.tx(t.label)}</wired-button>`)
+        .join("")}</div>${tabs
+        .map((t, i) => `<div class="tab-panel${i === 0 ? " on" : ""}" data-panel="${i}"><div class="stack">${(t.children || []).map(c.block).join("")}</div></div>`)
+        .join("")}</div>`;
+    },
+  },
+  {
+    name: "nextbar",
+    group: "Actions",
+    summary: "“Next →” strip at the bottom of a screen. Hidden in the PDF.",
+    props: {
+      label: { type: "text", doc: "Bold lead-in (default “Next →”)." },
+      text: { type: "text", doc: "What happens next." },
+      button: { type: "text", doc: "Button text (default “Continue →”)." },
+      ...ACTION,
+    },
+    render: (b, c) =>
+      `<div class="nextbar"><span><strong>${c.tx(b.label || "Next →")}</strong> ${c.tx(b.text)}</span><wired-button elevation="2"${c.act(b)}>${c.tx(
+        b.button || "Continue →"
+      )}</wired-button></div>`,
+  },
+];

package/src/render/blocks/content.js

@@ -0,0 +1,86 @@
+import { ACTION } from "./shared.js";
+import { ICON_NAMES } from "../../icons.js";
+
+/** @type {import("./index.js").BlockDef[]} */
+export default [
+  {
+    name: "icon",
+    group: "Content",
+    summary: "Hand-drawn icon.",
+    props: {
+      name: { type: "string", enum: ICON_NAMES, doc: "Icon name.", required: true },
+      size: { type: "number", doc: "Size in px (default 22)." },
+      filled: { type: "boolean", doc: "Solid instead of outline (heart, star, bookmark…)." },
+    },
+    render: (b, c) => c.icon(b.name, +b.size || 22, b.filled),
+  },
+  {
+    name: "avatar",
+    group: "Content",
+    summary: "Round profile picture with an optional name and sub-line. Clickable.",
+    props: {
+      name: { type: "text", doc: "Bold name next to the picture." },
+      sub: { type: "text", doc: "Smaller line under the name." },
+      size: { type: "number", doc: "Picture size in px (default 44)." },
+      ...ACTION,
+    },
+    render: (b, c) =>
+      `<div class="avatar${b.go || b.open ? " click" : ""}"${c.act(b)}><oi-placeholder h="${+b.size || 44}" round></oi-placeholder>${
+        b.name || b.sub ? `<div class="avatar-text">${b.name ? `<strong>${c.tx(b.name)}</strong>` : ""}${b.sub ? `<span class="muted">${c.tx(b.sub)}</span>` : ""}</div>` : ""
+      }</div>`,
+  },
+  {
+    name: "hero",
+    group: "Content",
+    summary: "Big headline block for landing pages. Put call-to-action buttons (or an image) in `children`.",
+    children: true,
+    props: {
+      title: { type: "text", doc: "Headline.", required: true },
+      text: { type: "text", doc: "Supporting sentence." },
+      align: { type: "string", enum: ["left", "center"], doc: "Text alignment (default `center`)." },
+    },
+    render: (b, c) =>
+      `<section class="hero${b.align === "left" ? " left" : ""}"><h1>${c.tx(b.title)}</h1>${b.text ? `<p class="lead">${c.tx(b.text)}</p>` : ""}${
+        b.children?.length ? `<div class="stack hero-body">${c.kids(b)}</div>` : ""
+      }</section>`,
+  },
+  {
+    name: "stat",
+    group: "Content",
+    summary: "Number card for dashboards: label, big value and a change indicator.",
+    props: {
+      label: { type: "text", doc: "What is measured.", required: true },
+      value: { type: "text", doc: "The number.", required: true },
+      delta: { type: "text", doc: "Change, e.g. `+8%`." },
+      trend: { type: "string", enum: ["up", "down", "flat"], doc: "Colours the change: `up` green, `down` orange, `flat` grey (default `up`)." },
+    },
+    render: (b, c) =>
+      `<wired-card elevation="1" class="card stat"><div class="stack tight"><span class="muted">${c.tx(b.label)}</span><div class="stat-value">${c.tx(b.value)}</div>${
+        b.delta ? `<span class="badge ${{ up: "on", down: "wait", flat: "off" }[b.trend || "up"]}">${c.tx(b.delta)}</span>` : ""
+      }</div></wired-card>`,
+  },
+  {
+    name: "rating",
+    group: "Content",
+    summary: "Star rating.",
+    props: {
+      value: { type: "number", doc: "Filled stars (default 4)." },
+      max: { type: "number", doc: "Total stars (default 5)." },
+      text: { type: "text", doc: "Text after the stars, e.g. `(128 reviews)`." },
+    },
+    render: (b, c) => {
+      const max = +b.max || 5;
+      const value = b.value ?? 4;
+      return `<div class="row rating">${Array.from({ length: max }, (_, i) => c.icon("star", 18, i < value)).join("")}${
+        b.text ? `<span class="muted">${c.tx(b.text)}</span>` : ""
+      }</div>`;
+    },
+  },
+  {
+    name: "link",
+    group: "Content",
+    summary: "Underlined text link.",
+    props: { text: { type: "text", doc: "Link text.", required: true }, ...ACTION },
+    render: (b, c) => `<a class="oi-link"${c.act(b)}>${c.tx(b.text)}</a>`,
+  },
+];

package/src/render/blocks/data.js

@@ -0,0 +1,24 @@
+const isBlock = (x) => x && typeof x === "object" && !Array.isArray(x) && x.type;
+const cellsOf = (row) => (Array.isArray(row) ? row : row?.cells || []);
+
+/** @type {import("./index.js").BlockDef[]} */
+export default [
+  {
+    name: "table",
+    group: "Data",
+    summary: "Table. A cell is text or a block (e.g. `badge`, `button`). A row can be `{ cells, go }` to make it clickable.",
+    props: {
+      columns: { type: "text[]", doc: "Column headings.", required: true },
+      rows: { type: "rows", doc: "List of rows: `[cell, cell]` or `{ cells: [...], go: screenId }`.", required: true },
+    },
+    nested: (b) =>
+      (b.rows || []).flatMap((r, i) => cellsOf(r).map((x, j) => [Array.isArray(r) ? `.rows[${i}][${j}]` : `.rows[${i}].cells[${j}]`, x]).filter(([, x]) => isBlock(x))),
+    targets: (b) => (b.rows || []).map((r) => r?.go).filter(Boolean),
+    render: (b, c) => {
+      const cell = (x) => (isBlock(x) ? c.block(x) : c.tx(x));
+      return `<table class="oi-table"><thead><tr>${(b.columns || []).map((x) => `<th>${c.tx(x)}</th>`).join("")}</tr></thead><tbody>${(b.rows || [])
+        .map((r) => `<tr${r?.go ? ` class="click" data-go="${c.esc(r.go)}"` : ""}>${cellsOf(r).map((x) => `<td>${cell(x)}</td>`).join("")}</tr>`)
+        .join("")}</tbody></table>`;
+    },
+  },
+];

package/src/render/blocks/feedback.js

@@ -0,0 +1,29 @@
+/** @type {import("./index.js").BlockDef[]} */
+export default [
+  {
+    name: "alert",
+    group: "Feedback",
+    summary: "Banner for information, success, warnings and errors.",
+    props: {
+      text: { type: "text", doc: "Message.", required: true },
+      title: { type: "text", doc: "Bold first line." },
+      kind: { type: "string", enum: ["info", "success", "warning", "error"], doc: "Type and colour (default `info`)." },
+    },
+    render: (b, c) => {
+      const kind = b.kind || "info";
+      const icon = { info: "info", success: "check", warning: "bell", error: "close" }[kind];
+      return `<div class="alert alert-${kind}">${c.icon(icon, 22)}<div>${b.title ? `<strong>${c.tx(b.title)}</strong> ` : ""}${c.tx(b.text)}</div></div>`;
+    },
+  },
+  {
+    name: "progress",
+    group: "Feedback",
+    summary: "Progress bar.",
+    props: {
+      value: { type: "number", doc: "Percent complete, 0 to 100.", required: true },
+      label: { type: "text", doc: "Caption above the bar." },
+    },
+    render: (b, c) =>
+      `<div class="field">${c.label(b)}<wired-progress value="${Math.min(100, Math.max(0, +b.value || 0))}" percentage></wired-progress></div>`,
+  },
+];