openink 0.1.0

package/src/spec/validate.js

@@ -0,0 +1,219 @@
+import { getBlock, blockNames } from "../render/blocks/index.js";
+import { COMMON, TONES } from "../render/blocks/shared.js";
+import { ICON_NAMES } from "../icons.js";
+import { THEME_PRESETS, COLOR_KEYS } from "../themes.js";
+
+const ID = /^[A-Za-z][\w-]*$/;
+const WIDTHS = ["narrow", "medium", "wide"];
+const isObj = (v) => v && typeof v === "object" && !Array.isArray(v);
+
+/** Levenshtein distance, for "did you mean" hints. */
+function distance(a, b) {
+  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++) d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+  return d[a.length][b.length];
+}
+const suggest = (word, options) => {
+  const best = options.map((o) => [o, distance(word, o)]).sort((x, y) => x[1] - y[1])[0];
+  return best && best[1] <= Math.max(2, Math.floor(word.length / 3)) ? ` Did you mean "${best[0]}"?` : "";
+};
+
+/**
+ * Check a parsed spec. Never throws.
+ * @returns {{ errors: {path:string,message:string}[], warnings: {path:string,message:string}[] }}
+ */
+export function validate(spec) {
+  const errors = [];
+  const warnings = [];
+  const err = (path, message) => errors.push({ path, message });
+  const warn = (path, message) => warnings.push({ path, message });
+
+  if (!isObj(spec)) return { errors: [{ path: "", message: "Spec must be a YAML/JSON object." }], warnings };
+
+  if (typeof spec.name !== "string" || !spec.name.trim()) err("name", "`name` is required (a non-empty string).");
+  const languages = spec.languages ?? [];
+  if (!Array.isArray(languages) || languages.some((l) => typeof l !== "string" || !/^[a-z]{2,3}$/i.test(l))) {
+    err("languages", "`languages` must be a list of 2-3 letter codes, e.g. [en, de].");
+  }
+  const langs = Array.isArray(languages) ? languages.filter((l) => typeof l === "string") : [];
+
+  const topKnown = ["name", "languages", "footer", "theme", "colors", "nav", "modals", "screens"];
+  // `x-*` keys are free-form: a place to define YAML anchors (&name) that screens reuse (*name)
+  for (const k of Object.keys(spec)) if (!topKnown.includes(k) && !k.startsWith("x-")) warn(k, `Unknown top-level field "${k}".${suggest(k, topKnown)}`);
+
+  // ---- theme + colors
+  if (spec.theme !== undefined) {
+    if (typeof spec.theme !== "string") err("theme", "`theme` must be a preset name or the path of a .css file.");
+    else if (!THEME_PRESETS.includes(spec.theme) && !spec.theme.endsWith(".css")) {
+      err("theme", `Unknown theme "${spec.theme}". Use a preset (${THEME_PRESETS.join(", ")}) or a path ending in .css.${suggest(spec.theme, THEME_PRESETS)}`);
+    }
+  }
+  if (spec.colors !== undefined) {
+    if (!isObj(spec.colors)) err("colors", "`colors` must be an object such as { accent: \"#e11d48\" }.");
+    else for (const [k, v] of Object.entries(spec.colors)) {
+      if (!COLOR_KEYS.includes(k)) err(`colors.${k}`, `Unknown colour "${k}". Available: ${COLOR_KEYS.join(", ")}.${suggest(k, COLOR_KEYS)}`);
+      else if (typeof v !== "string" || /[;{}<>]/.test(v)) err(`colors.${k}`, `\`${k}\` must be a CSS colour such as "#e11d48" or "tomato".`);
+    }
+  }
+
+  // ---- screens
+  const screens = Array.isArray(spec.screens) ? spec.screens : [];
+  if (!screens.length) {
+    err("screens", "`screens` must be a non-empty list.");
+    return { errors, warnings };
+  }
+  const ids = new Set();
+  screens.forEach((s, i) => {
+    const p = `screens[${i}]`;
+    if (!isObj(s)) return err(p, "A screen must be an object with `id` and `blocks`.");
+    if (typeof s.id !== "string" || !ID.test(s.id)) err(`${p}.id`, `Screen \`id\` must start with a letter and use letters, digits, "_" or "-" (got ${JSON.stringify(s.id)}).`);
+    else if (ids.has(s.id)) err(`${p}.id`, `Duplicate screen id "${s.id}".`);
+    else ids.add(s.id);
+    const screenKeys = ["id", "title", "nav", "note", "width", "tone", "blocks"];
+    for (const k of Object.keys(s)) if (!screenKeys.includes(k)) warn(`${p}.${k}`, `Unknown screen field "${k}".${suggest(k, screenKeys)}`);
+    if (!Array.isArray(s.blocks)) err(`${p}.blocks`, "`blocks` must be a list.");
+    if (s.tone !== undefined && !TONES.includes(s.tone)) err(`${p}.tone`, `\`tone\` must be one of: ${TONES.join(", ")} (got ${JSON.stringify(s.tone)}).`);
+    if (s.width !== undefined && !WIDTHS.includes(s.width)) err(`${p}.width`, `\`width\` must be one of: ${WIDTHS.join(", ")} (got ${JSON.stringify(s.width)}).`);
+    if (s.title !== undefined) checkText(s.title, `${p}.title`);
+    if (s.note !== undefined) checkText(s.note, `${p}.note`);
+  });
+
+  // ---- text values
+  function checkText(v, path) {
+    if (typeof v === "string" || typeof v === "number") return true;
+    if (isObj(v)) {
+      if (!langs.length) warn(path, "Translation object used but the spec has no `languages`; only the first value is shown.");
+      else {
+        for (const k of Object.keys(v)) if (!langs.includes(k)) warn(path, `Language "${k}" is not listed in \`languages\`.`);
+        const missing = langs.filter((l) => v[l] == null);
+        if (missing.length) warn(path, `Missing translation: ${missing.join(", ")} (falls back to ${langs[0]}).`);
+      }
+      return Object.values(v).every((x) => typeof x === "string" || typeof x === "number") || (err(path, "Translation values must be strings."), false);
+    }
+    err(path, `Expected text (string, number or { lang: text }), got ${Array.isArray(v) ? "a list" : typeof v}.`);
+    return false;
+  }
+
+  const links = []; // [path, screenId]
+  const modalRefs = []; // [path, modalId] from `open:`
+  const modalIds = new Set();
+  const checkProp = (name, def, v, path) => {
+    switch (def.type) {
+      case "text": checkText(v, path); break;
+      case "string":
+        if (typeof v !== "string") err(path, `\`${name}\` must be a string.`);
+        else if (def.enum && !def.enum.includes(v)) {
+          err(path, def.enum.length > 12 ? `Unknown ${name} "${v}".${suggest(v, def.enum)} See docs/blocks.md for the list.` : `\`${name}\` must be one of: ${def.enum.join(", ")} (got "${v}").`);
+        }
+        break;
+      case "number": if (typeof v !== "number") err(path, `\`${name}\` must be a number.`); break;
+      case "boolean": if (typeof v !== "boolean") err(path, `\`${name}\` must be true or false.`); break;
+      case "text[]":
+        if (!Array.isArray(v)) err(path, `\`${name}\` must be a list.`);
+        else v.forEach((x, i) => checkText(x, `${path}[${i}]`));
+        break;
+      case "number[]":
+        if (!Array.isArray(v) || v.some((x) => typeof x !== "number")) err(path, `\`${name}\` must be a list of numbers.`);
+        break;
+      case "sections":
+        if (!Array.isArray(v)) err(path, `\`${name}\` must be a list of { label, children }.`);
+        else v.forEach((t, i) => {
+          if (!isObj(t) || t.label == null) err(`${path}[${i}]`, "Each entry needs a `label`.");
+          else { checkText(t.label, `${path}[${i}].label`); if (t.children !== undefined && !Array.isArray(t.children)) err(`${path}[${i}].children`, "`children` must be a list."); }
+        });
+        break;
+      case "links":
+        if (!Array.isArray(v)) err(path, `\`${name}\` must be a list of { icon, label, go }.`);
+        else v.forEach((n, i) => {
+          if (!isObj(n) || (n.label == null && n.icon == null)) return err(`${path}[${i}]`, "Each item needs an `icon` or a `label`.");
+          if (n.label != null) checkText(n.label, `${path}[${i}].label`);
+          if (n.icon != null && !ICON_NAMES.includes(n.icon)) err(`${path}[${i}].icon`, `Unknown icon "${n.icon}".${suggest(String(n.icon), ICON_NAMES)}`);
+          if (n.go) links.push([`${path}[${i}].go`, n.go]);
+          if (n.open) modalRefs.push([`${path}[${i}].open`, n.open]);
+        });
+        break;
+      case "rows":
+        if (!Array.isArray(v)) err(path, "`rows` must be a list.");
+        else v.forEach((r, i) => {
+          if (!Array.isArray(r) && !(isObj(r) && Array.isArray(r.cells))) err(`${path}[${i}]`, "A row must be a list of cells, or { cells: [...], go: screenId }.");
+        });
+        break;
+    }
+  };
+
+  function visit(b, path) {
+    if (typeof b === "string") return;
+    if (!isObj(b)) return err(path, "A block must be an object with a `type` (or a plain string).");
+    if (typeof b.type !== "string") return err(path, `Block is missing \`type\`. Known types: ${blockNames().join(", ")}.`);
+    const def = getBlock(b.type);
+    if (!def) return err(`${path}.type`, `Unknown block type "${b.type}".${suggest(b.type, blockNames())}`);
+
+    const known = new Set(["type", ...Object.keys(def.props), ...Object.keys(COMMON), ...(def.children ? ["children"] : [])]);
+    for (const k of Object.keys(b)) {
+      if (known.has(k)) continue;
+      // "Search a, b" as a key means an unquoted comma inside { } ended the previous value early
+      if (/[^\w-]/.test(k)) warn(`${path}.${k}`, `Unexpected "${k}". A comma inside { ... } ends the value, so wrap text that contains commas in quotes.`);
+      else warn(`${path}.${k}`, `"${b.type}" has no property "${k}".${suggest(k, [...known])}`);
+    }
+    for (const [name, pd] of Object.entries({ ...def.props, ...COMMON })) {
+      if (b[name] === undefined) { if (pd.required) err(`${path}.${name}`, `"${b.type}" requires \`${name}\`.`); continue; }
+      checkProp(name, pd, b[name], `${path}.${name}`);
+    }
+    if (b.go !== undefined && typeof b.go === "string") links.push([`${path}.go`, b.go]);
+    if (typeof b.open === "string") modalRefs.push([`${path}.open`, b.open]);
+    if (b.type === "modal" && typeof b.id === "string") {
+      if (modalIds.has(b.id)) err(`${path}.id`, `Duplicate modal id "${b.id}".`);
+      modalIds.add(b.id);
+    }
+    for (const t of def.targets?.(b) ?? []) links.push([path, t]);
+
+    if (b.children !== undefined) {
+      if (!def.children) err(`${path}.children`, `"${b.type}" cannot have children.`);
+      else if (!Array.isArray(b.children)) err(`${path}.children`, "`children` must be a list.");
+      else b.children.forEach((x, i) => visit(x, `${path}.children[${i}]`));
+    }
+    if (def.nested) for (const [suffix, x] of def.nested(b)) visit(x, path + suffix);
+  }
+  screens.forEach((s, i) => Array.isArray(s?.blocks) && s.blocks.forEach((b, j) => visit(b, `screens[${i}].blocks[${j}]`)));
+
+  // global modals: same as a `modal` block, listed once and openable from any screen
+  if (spec.modals !== undefined) {
+    if (!Array.isArray(spec.modals)) err("modals", "`modals` must be a list of modal definitions ({ id, title, children }).");
+    else spec.modals.forEach((m, i) => (isObj(m) ? visit({ ...m, type: "modal" }, `modals[${i}]`) : err(`modals[${i}]`, "A modal must be an object with an `id`.")));
+  }
+
+  // ---- nav
+  const navSets = Array.isArray(spec.nav) ? { default: spec.nav } : isObj(spec.nav) ? spec.nav : {};
+  if (spec.nav !== undefined && !Array.isArray(spec.nav) && !isObj(spec.nav)) err("nav", "`nav` must be a list, or an object of named lists.");
+  for (const [key, items] of Object.entries(navSets)) {
+    if (!Array.isArray(items)) { err(`nav.${key}`, "A nav set must be a list of { label, go }."); continue; }
+    items.forEach((n, i) => {
+      const p = Array.isArray(spec.nav) ? `nav[${i}]` : `nav.${key}[${i}]`;
+      if (!isObj(n) || (n.label == null && n.icon == null)) return err(p, "A nav item needs a `label` or an `icon`.");
+      if (n.label != null) checkText(n.label, `${p}.label`);
+      if (n.icon != null && !ICON_NAMES.includes(n.icon)) err(`${p}.icon`, `Unknown icon "${n.icon}".${suggest(String(n.icon), ICON_NAMES)}`);
+      if (n.go) links.push([`${p}.go`, n.go]);
+      if (n.open) modalRefs.push([`${p}.open`, n.open]);
+    });
+  }
+  screens.forEach((s, i) => {
+    if (isObj(s) && s.nav && !navSets[s.nav]) err(`screens[${i}].nav`, `Screen uses nav set "${s.nav}" which is not defined under \`nav\`.${suggest(s.nav, Object.keys(navSets))}`);
+  });
+
+  // ---- links
+  for (const [path, target] of links) {
+    if (!ids.has(target)) err(path, `Links to unknown screen "${target}".${suggest(target, [...ids])}`);
+  }
+
+  for (const [path, id] of modalRefs) {
+    if (!modalIds.has(id)) err(path, `Opens unknown modal "${id}".${suggest(String(id), [...modalIds])} Define it with { type: modal, id: ${id} }.`);
+  }
+
+  // ---- reachability (warning only)
+  const linked = new Set([screens[0].id, ...links.map(([, target]) => target)]);
+  for (const id of ids) if (!linked.has(id)) warn("screens", `Screen "${id}" is not linked from anywhere (no \`go: ${id}\`).`);
+
+  return { errors, warnings };
+}

package/src/styles/openink.css

@@ -0,0 +1,250 @@
+@import url("https://fonts.googleapis.com/css2?family=Caveat:wght@500;700&family=Patrick+Hand&display=swap");
+
+/* ------------------------------------------------------------------ design tokens
+   Override any of these with `colors:` in the spec, a theme preset, or your own CSS file. */
+:root {
+  --ink: #2b2b2b;          /* text and lines */
+  --paper: #fdfcf8;        /* page background */
+  --muted: #8a8a85;        /* secondary text, outlines of placeholders */
+  --line: #cfcfc8;         /* dashed dividers */
+  --accent: #c2410c;       /* pins, sliders, active states */
+  --note: #fff3b0;         /* sticky notes */
+  --card-bg: #ffffff;      /* cards and dialogs */
+  --ok: #15803d;           /* "on" badges, success */
+  --gap: 1rem;
+
+  /* used by hand-drawn shapes (placeholders, charts) */
+  --oi-stroke: var(--muted);
+  --oi-fill: #f3f1ea;
+  --oi-line: var(--line);
+  --oi-chart: var(--accent);
+  --tone-bg: #f1efe8;      /* background used by `fill: true` without a tone */
+
+  --wired-item-selected-bg: #eee;
+  --wired-toggle-on-color: var(--ink);
+  --wired-toggle-off-color: var(--muted);
+  --wired-slider-knob-color: var(--accent);
+  --wired-slider-bar-color: var(--ink);
+  --wired-radio-icon-color: var(--ink);
+  --wired-checkbox-icon-color: var(--ink);
+  --wired-progress-color: var(--accent);
+  --wired-progress-label-color: var(--ink);
+  --wired-progress-label-background: var(--card-bg);
+
+  /* tone palette: strong colour + light tint */
+  --blue: #1d4ed8;   --blue-bg: #dbeafe;
+  --green: #15803d;  --green-bg: #dcfce7;
+  --yellow: #a16207; --yellow-bg: #fef3c7;
+  --red: #b91c1c;    --red-bg: #fee2e2;
+  --purple: #7e22ce; --purple-bg: #f3e8ff;
+  --pink: #be185d;   --pink-bg: #fce7f3;
+  --orange: #c2410c; --orange-bg: #ffedd5;
+  --teal: #0f766e;   --teal-bg: #ccfbf1;
+  --gray: #475569;   --gray-bg: #e2e8f0;
+}
+
+/* ------------------------------------------------------------------ tones
+   `tone: blue` on a block (or screen) recolours it and everything inside it. */
+[data-tone="blue"]   { --tone: var(--blue);   --tone-bg: var(--blue-bg); }
+[data-tone="green"]  { --tone: var(--green);  --tone-bg: var(--green-bg); }
+[data-tone="yellow"] { --tone: var(--yellow); --tone-bg: var(--yellow-bg); }
+[data-tone="red"]    { --tone: var(--red);    --tone-bg: var(--red-bg); }
+[data-tone="purple"] { --tone: var(--purple); --tone-bg: var(--purple-bg); }
+[data-tone="pink"]   { --tone: var(--pink);   --tone-bg: var(--pink-bg); }
+[data-tone="orange"] { --tone: var(--orange); --tone-bg: var(--orange-bg); }
+[data-tone="teal"]   { --tone: var(--teal);   --tone-bg: var(--teal-bg); }
+[data-tone="gray"]   { --tone: var(--gray);   --tone-bg: var(--gray-bg); }
+[data-tone] {
+  color: var(--tone);
+  --ink: var(--tone);
+  --muted: color-mix(in srgb, var(--tone) 65%, white);
+  --line: color-mix(in srgb, var(--tone) 35%, white);
+  --accent: var(--tone);
+  --ok: var(--tone);
+  --oi-stroke: var(--tone);
+  --oi-fill: var(--tone-bg);
+  --oi-line: color-mix(in srgb, var(--tone) 30%, white);
+  --oi-chart: var(--tone);
+  --wired-toggle-on-color: var(--tone);
+  --wired-slider-knob-color: var(--tone);
+  --wired-slider-bar-color: var(--tone);
+  --wired-radio-icon-color: var(--tone);
+  --wired-checkbox-icon-color: var(--tone);
+  --wired-progress-color: var(--tone);
+  --wired-progress-label-background: color-mix(in srgb, var(--tone-bg) 55%, white);
+}
+[data-tone] .card, [data-tone].card { background: color-mix(in srgb, var(--tone-bg) 55%, white); }
+[data-tone] wired-button { background: color-mix(in srgb, var(--tone-bg) 45%, white); }
+[data-tone] wired-button[elevation="3"] { background: var(--tone); color: #fff; }
+.screen[data-tone] { background: color-mix(in srgb, var(--tone-bg) 40%, var(--paper)); padding: 1rem; border-radius: 12px; }
+/* the wrapper the renderer puts around any block with `tone` / `fill` */
+.tone { display: contents; }
+.tone[data-fill] { display: block; background: var(--tone-bg); padding: .75rem .9rem; border-radius: 6px 14px 8px 12px; }
+
+/* ------------------------------------------------------------------ base */
+* { box-sizing: border-box; }
+body { margin: 0; font-family: "Patrick Hand", "Caveat", cursive; font-size: 1.1rem; color: var(--ink); background: var(--paper); }
+h1, h2, h3 { font-family: "Caveat", cursive; margin: 0 0 .4rem; line-height: 1.1; }
+h1 { font-size: 2.4rem; } h2 { font-size: 1.9rem; } h3 { font-size: 1.4rem; }
+p { margin: 0; }
+.bold { font-weight: 700; }
+.lead { font-size: 1.15rem; }
+.muted { color: var(--muted); font-size: .95rem; }
+.center { text-align: center; }
+[data-go], [data-open], .click { cursor: pointer; }
+
+.shell { max-width: 1000px; margin: 0 auto; padding: var(--gap); }
+
+/* layout blocks */
+.stack { display: grid; gap: var(--gap); align-content: start; }
+.stack.tight { gap: .2rem; }
+.row { display: flex; gap: .6rem; align-items: center; flex-wrap: wrap; }
+.row.between { justify-content: space-between; }
+.row.center { justify-content: center; }
+.grid { display: grid; grid-template-columns: repeat(var(--cols), 1fr); gap: var(--gap); align-items: start; }
+@media (max-width: 720px) { .grid { grid-template-columns: 1fr; } }
+.card { display: block; padding: 1rem; background: var(--card-bg); }
+.card.dash { background: transparent; }
+.center-items { justify-items: center; text-align: center; }
+.center-items > * { justify-self: center; }
+.field { display: grid; gap: .2rem; }
+.fl { font-size: .9rem; color: var(--muted); }
+wired-input, wired-textarea, wired-combo, wired-search-input, wired-progress { width: 100%; }
+wired-progress { display: block; }
+wired-textarea { display: block; min-height: 6rem; }
+wired-combo { display: block; border: 2px solid var(--muted); border-radius: 255px 8px 225px 8px/8px 225px 8px 255px; padding: .1rem .3rem; }
+wired-button oi-icon + .btn-label { margin-left: .4rem; }
+/* a button is as wide as its label, not as wide as the column (matters once themes give buttons a background) */
+.stack > wired-button, .stack > .tone > wired-button { justify-self: start; }
+.oi-list { margin: 0; padding-left: 1.2rem; display: grid; gap: .25rem; }
+.oi-link { color: var(--accent); text-decoration: underline wavy; text-underline-offset: 4px; }
+
+/* header */
+.oi-bar { display: flex; align-items: center; gap: .75rem; flex-wrap: wrap; padding: .5rem 0 1rem; border-bottom: 2px dashed var(--line); margin-bottom: var(--gap); }
+.oi-bar .brand { font-family: "Caveat", cursive; font-size: 1.9rem; font-weight: 700; margin-right: auto; }
+.oi-bar nav { display: flex; gap: .4rem; flex-wrap: wrap; }
+.oi-bar nav[hidden] { display: none; }
+.lang { display: flex; gap: .2rem; }
+[data-lang].on { --wired-item-selected-bg: #eee; font-weight: 700; }
+
+/* screens */
+.screen { display: none; }
+.screen.on { display: block; }
+.screen > * + * { margin-top: var(--gap); }
+.screen-title { display: none; }
+.screen[data-width="narrow"] { max-width: 520px; margin-inline: auto; }
+.screen[data-width="medium"] { max-width: 760px; margin-inline: auto; }
+main { min-height: 40vh; }
+footer { margin-top: 2.5rem; }
+
+/* sticky-note annotations */
+.note { background: var(--note); color: #2b2b2b; padding: .55rem .8rem; transform: rotate(-.4deg); box-shadow: 2px 3px 0 rgba(0,0,0,.08); font-size: .98rem; max-width: 60ch; }
+
+/* next bar */
+.nextbar { display: flex; justify-content: space-between; align-items: center; gap: 1rem; flex-wrap: wrap; border-top: 2px dashed var(--line); padding-top: var(--gap); margin-top: 1.5rem; }
+
+/* table */
+.oi-table { width: 100%; border-collapse: collapse; }
+.oi-table th, .oi-table td { text-align: left; padding: .45rem .5rem; border-bottom: 1px dashed var(--line); }
+.oi-table th { font-family: "Caveat", cursive; font-size: 1.25rem; }
+.oi-table tr.click:hover { background: color-mix(in srgb, var(--ink) 6%, transparent); }
+/* a column that only holds an avatar shrinks to the avatar */
+.oi-table td:has(> oi-placeholder[round]) { width: 1%; white-space: nowrap; }
+
+/* badge */
+.badge { display: inline-block; padding: .05rem .55rem; border: 2px solid var(--muted); border-radius: 255px 15px 225px 15px/15px 225px 15px 255px; font-size: .9rem; }
+.badge.on { border-color: var(--ok); color: var(--ok); }
+.badge.wait { border-color: var(--accent); color: var(--accent); }
+.badge.off { border-color: var(--muted); color: var(--muted); }
+.stack > .badge { justify-self: start; }
+
+/* placeholder / chart labels */
+.ph-label { position: absolute; inset: 0; margin: auto; width: max-content; height: max-content; padding: 0 .5rem; color: var(--muted); background: color-mix(in srgb, var(--oi-fill) 60%, var(--paper)); }
+oi-placeholder[pin] .ph-label, oi-placeholder[play] .ph-label { inset: auto 0 10px 0; }
+oi-placeholder[dots] .ph-label { inset: 12px 0 auto 0; }
+oi-placeholder[upload] .ph-label { inset: auto 0 22px 0; }
+.ph-corner { inset: 4px auto auto 40px; margin: 0; background: transparent; }
+
+/* tabs */
+.tab-panel { display: none; margin-top: var(--gap); }
+.tab-panel.on { display: block; }
+
+/* ------------------------------------------------------------------ content blocks */
+.avatar { display: flex; align-items: center; gap: .6rem; }
+.avatar-text { display: grid; line-height: 1.15; }
+.hero { text-align: center; padding: 2.5rem 1rem; display: grid; gap: .8rem; justify-items: center; }
+.hero.left { text-align: left; justify-items: start; padding-inline: 0; }
+.hero h1 { font-size: 3.2rem; margin: 0; }
+.hero .lead { max-width: 48ch; color: var(--muted); font-size: 1.25rem; }
+.hero-body { justify-items: inherit; width: 100%; }
+.stat-value { font-family: "Caveat", cursive; font-size: 2.6rem; line-height: 1; }
+.rating { gap: .1rem; }
+.rating oi-icon { color: var(--accent); }
+.rating .muted { margin-left: .4rem; }
+
+/* feedback */
+.alert { --k: #1d4ed8; display: flex; gap: .7rem; align-items: flex-start; padding: .7rem .9rem; border: 2px solid var(--k);
+  border-radius: 255px 15px 225px 15px/15px 225px 15px 255px; background: color-mix(in srgb, var(--k) 10%, var(--paper)); }
+.alert oi-icon { color: var(--k); flex: none; }
+.alert-success { --k: #15803d; } .alert-warning { --k: #b45309; } .alert-error { --k: #b91c1c; }
+
+/* navigation */
+.crumbs { display: flex; gap: .4rem; flex-wrap: wrap; color: var(--muted); }
+.crumbs .current { color: var(--ink); font-weight: 700; }
+.crumbs .sep { opacity: .6; }
+.steps { list-style: none; display: flex; padding: 0; margin: 0; }
+.steps li { flex: 1; display: flex; align-items: center; gap: .5rem; color: var(--muted); }
+.steps li:not(:last-child)::after { content: ""; flex: 1; border-top: 2px dashed var(--line); margin: 0 .6rem; }
+.steps li:last-child { flex: none; }
+.steps .dot { width: 28px; height: 28px; border: 2px solid currentColor; border-radius: 50%; display: grid; place-items: center; font-size: .85rem; flex: none; }
+.steps .on { color: var(--ink); font-weight: 700; }
+.steps .on .dot { background: var(--accent); border-color: var(--accent); color: #fff; }
+.steps .done { color: var(--ink); }
+.steps .done .dot { background: var(--ink); color: var(--paper); }
+.tabbar { display: flex; justify-content: space-around; gap: .25rem; border-top: 2px dashed var(--line); padding-top: .6rem; }
+.tabbar wired-button { display: inline-flex; }
+.tab-label { display: block; font-size: .72rem; line-height: 1; margin-top: .15rem; }
+
+/* accordion */
+.accordion details { border: 2px dashed var(--line); border-radius: 10px; padding: .1rem .9rem; margin-bottom: .5rem; }
+.accordion summary { cursor: pointer; display: flex; justify-content: space-between; align-items: center; padding: .5rem 0; font-family: "Caveat", cursive; font-size: 1.4rem; list-style: none; }
+.accordion summary::-webkit-details-marker { display: none; }
+.accordion details[open] summary oi-icon { transform: rotate(180deg); }
+.accordion details > .stack { padding: .3rem 0 .9rem; }
+
+/* device frames */
+.device { margin-inline: auto; width: 100%; }
+.device-phone { max-width: 390px; }
+.device-tablet { max-width: 720px; }
+.device-frame { display: block; background: var(--card-bg); padding: 0; }
+.device-body { padding: .9rem; }
+.device-phone .device-body { min-height: 520px; }
+.device-tablet .device-body { min-height: 420px; }
+.device-notch { width: 90px; height: 8px; border-radius: 8px; background: var(--line); margin: 12px auto 0; }
+.device-bar { display: flex; align-items: center; gap: 6px; padding: .55rem .9rem; border-bottom: 2px dashed var(--line); }
+.device-bar i { width: 10px; height: 10px; border: 2px solid var(--muted); border-radius: 50%; display: block; }
+.device-bar span { margin-left: .6rem; flex: 1; border: 2px solid var(--line); border-radius: 12px; padding: 0 .8rem; font-size: .9rem; color: var(--muted); }
+
+/* modal */
+.modal { position: fixed; inset: 0; display: none; place-items: center; z-index: 50; padding: 1rem; margin: 0 !important; }
+.modal.on { display: grid; }
+.modal-backdrop { position: absolute; inset: 0; background: rgba(0, 0, 0, .4); }
+.modal-card { position: relative; display: block; background: var(--card-bg); width: min(100%, 560px); max-height: 88vh; overflow: auto; padding: 1rem; }
+.modal[data-width="narrow"] .modal-card { width: min(100%, 380px); }
+.modal[data-width="wide"] .modal-card { width: min(100%, 820px); }
+
+/* language switching rules ([data-l]) are generated per spec into the page <style> */
+
+.toast { position: fixed; bottom: 1rem; left: 50%; transform: translateX(-50%); background: var(--ink); color: var(--paper); padding: .5rem 1rem; border-radius: 6px; opacity: 0; transition: opacity .2s; pointer-events: none; z-index: 100; }
+.toast.show { opacity: 1; }
+
+/* print / PDF: every screen on its own page */
+@page { size: A4 landscape; margin: 10mm; }
+@media print {
+  body { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
+  .oi-bar nav, .lang, .print-btn, .toast, .nextbar, .modal { display: none !important; }
+  .screen, .screen.on { display: block !important; break-after: page; }
+  .screen:last-of-type { break-after: auto; }
+  .screen-title { display: block; font-family: "Caveat", cursive; font-size: 1.3rem; color: var(--muted); border-bottom: 2px dashed var(--line); }
+  .tab-panel { display: block; }
+}

package/src/styles/themes/blueprint.css

@@ -0,0 +1,31 @@
+/* blueprint: white lines on blue paper. Looks like an architect's drawing. */
+:root {
+  --ink: #f1f6ff;
+  --paper: #0f3b8c;
+  --muted: #a9c4f5;
+  --line: #4b78d6;
+  --accent: #ffd166;
+  --note: #ffe08a;
+  --card-bg: rgba(255, 255, 255, 0.07);
+  --ok: #7ee2a8;
+  --oi-stroke: #cfe0ff;
+  --oi-fill: rgba(255, 255, 255, 0.08);
+  --oi-line: #6c93e0;
+  --oi-chart: #ffd166;
+  --wired-toggle-on-color: #ffd166;
+  --wired-slider-knob-color: #ffd166;
+  --wired-slider-bar-color: #f1f6ff;
+  --wired-progress-color: #ffd166;
+  --wired-progress-label-color: #f1f6ff;
+  --wired-progress-label-background: transparent;
+  --wired-radio-icon-color: #f1f6ff;
+  --wired-checkbox-icon-color: #f1f6ff;
+  --wired-item-selected-bg: #1f56b8;
+  --wired-item-selected-color: #fff;
+  --tone-bg: rgba(255, 255, 255, 0.12);
+}
+body { background-image: linear-gradient(rgba(255,255,255,.05) 1px, transparent 1px), linear-gradient(90deg, rgba(255,255,255,.05) 1px, transparent 1px); background-size: 28px 28px; }
+wired-input, wired-textarea, wired-search-input { color: var(--ink); }
+wired-combo { border-color: var(--muted); }
+.toast { background: #f1f6ff; color: #0f3b8c; }
+.alert { background: rgba(255,255,255,.08); }

package/src/styles/themes/color.css

@@ -0,0 +1,28 @@
+/* color: a confident, colourful look. Indigo and rose on warm white. */
+:root {
+  --ink: #1f2340;
+  --paper: #fffdf8;
+  --muted: #6b7099;
+  --line: #d9dcf0;
+  --accent: #e11d48;
+  --note: #fde68a;
+  --card-bg: #ffffff;
+  --ok: #059669;
+  --oi-fill: #eef0ff;
+  --oi-chart: #4f46e5;
+  --wired-toggle-on-color: #4f46e5;
+  --wired-slider-knob-color: #e11d48;
+  --wired-slider-bar-color: #4f46e5;
+  --wired-progress-color: #4f46e5;
+  --wired-radio-icon-color: #4f46e5;
+  --wired-checkbox-icon-color: #4f46e5;
+  --tone-bg: #eef0ff;
+}
+h1, h2 { color: #312e81; }
+.oi-bar .brand { color: #4f46e5; }
+wired-button { background: #eef0ff; color: #312e81; }
+wired-button[elevation="3"] { background: #4f46e5; color: #fff; }
+.badge.wait { background: #ffe4e6; }
+.badge.on { background: #d1fae5; }
+.card { border-radius: 8px; }
+.steps .on .dot { background: #4f46e5; border-color: #4f46e5; }

package/src/styles/themes/dark.css

@@ -0,0 +1,31 @@
+/* dark: for dashboards, dev tools, media apps. */
+:root {
+  --ink: #e8eaf0;
+  --paper: #14161c;
+  --muted: #8b90a0;
+  --line: #2f3340;
+  --accent: #ff7a59;
+  --note: #4a4320;
+  --card-bg: #1c1f28;
+  --ok: #4ade80;
+  --oi-stroke: #6b7080;
+  --oi-fill: #1f232d;
+  --oi-line: #3a3f4e;
+  --oi-chart: #ff7a59;
+  --wired-toggle-on-color: #ff7a59;
+  --wired-toggle-off-color: #6b7080;
+  --wired-slider-knob-color: #ff7a59;
+  --wired-slider-bar-color: #8b90a0;
+  --wired-progress-color: #ff7a59;
+  --wired-radio-icon-color: #e8eaf0;
+  --wired-checkbox-icon-color: #e8eaf0;
+  --wired-item-selected-bg: #2f3340;
+  --wired-item-selected-color: #fff;
+  --tone-bg: #262a36;
+}
+.note { color: #f5e9a8; }
+wired-button[elevation="3"] { background: #ff7a59; color: #14161c; }
+wired-input, wired-textarea, wired-search-input { color: var(--ink); }
+wired-combo { border-color: #4a4f60; }
+.modal-backdrop { background: rgba(0, 0, 0, .65); }
+.alert { background: color-mix(in srgb, var(--k) 16%, var(--paper)); }

package/src/styles/themes/pastel.css

@@ -0,0 +1,26 @@
+/* pastel: soft and friendly. Good for consumer apps and kids' products. */
+:root {
+  --ink: #4a3f55;
+  --paper: #fff9f5;
+  --muted: #9a8fa5;
+  --line: #eadcf0;
+  --accent: #ec4899;
+  --note: #fef3c7;
+  --card-bg: #ffffff;
+  --ok: #10b981;
+  --oi-fill: #fdf2f8;
+  --oi-chart: #c084fc;
+  --wired-toggle-on-color: #c084fc;
+  --wired-slider-knob-color: #ec4899;
+  --wired-slider-bar-color: #c084fc;
+  --wired-progress-color: #f9a8d4;
+  --wired-radio-icon-color: #c084fc;
+  --wired-checkbox-icon-color: #c084fc;
+  --tone-bg: #fdf2f8;
+}
+h1, h2 { color: #7e3aa1; }
+wired-button { background: #fde2f3; color: #6b2a7a; }
+wired-button[elevation="3"] { background: #f9a8d4; color: #4a1d5c; }
+.badge.wait { background: #fde2f3; }
+.badge.on { background: #d1fae5; }
+.steps .on .dot { background: #ec4899; border-color: #ec4899; }

package/src/themes.js

@@ -0,0 +1,10 @@
+/** Built-in colour themes. `sketch` is the default (pencil grey with one orange accent). */
+export const THEME_PRESETS = ["sketch", "color", "pastel", "blueprint", "dark"];
+
+/** Design tokens a spec can override with `colors:`. */
+export const COLOR_KEYS = ["ink", "paper", "muted", "line", "accent", "note", "card"];
+
+/** Map a `colors:` key to the CSS variable it sets. */
+export const colorVar = (key) => (key === "card" ? "--card-bg" : `--${key}`);
+
+export const isPreset = (theme) => THEME_PRESETS.includes(theme);

package/templates/starter/AGENTS.md

@@ -0,0 +1,18 @@
+# Wireframe project: instructions for AI assistants
+
+This folder is a [openink](https://github.com/mediuswareltd/openink) project. The whole prototype is described in `spec.yaml`. Never write HTML by hand.
+
+When the user describes a product or a change:
+
+1. Run `npx openink blocks` to see every block type and its props (or read the JSON Schema at `node_modules/openink/schema/spec.schema.json`).
+2. Edit `spec.yaml`. One entry in `screens:` per real page or state. Give each a `title`, and use `note:` for behaviour a sketch cannot show.
+3. Run `npx openink validate`. Fix every error; read the warnings (they catch typos and unreachable screens).
+4. Run `npx openink png` and look at `dist/png/*.png` to check the layout. `npx openink dev` gives a live preview.
+5. Tell the user where the result is: `dist/index.html` (and `npx openink pdf` for a PDF).
+
+Rules:
+- It is a wireframe: hand-drawn look, image and map placeholders, no real content, no colour beyond the theme.
+- Every screen must be reachable through `go:` links; end a flow with a `nextbar`.
+- Use `icon:` on buttons, `avatar`, `stat`, `chart`, `modal` (open with `open: <id>`) and `device` for mobile screens where they fit. `theme: color` colours the whole project; `tone: blue` colours a single block.
+- For several languages set `languages: [en, de]` and give every visible string as `{ en: …, de: … }`.
+- Do not edit `dist/`; it is regenerated.

package/templates/starter/README.md

@@ -0,0 +1,11 @@
+# {{name}}
+
+Wireframes built with [openink](https://github.com/mediuswareltd/openink).
+
+```bash
+npx openink dev        # live preview at http://localhost:3000
+npx openink build      # static site in dist/
+npx openink pdf        # dist/{{name}}.pdf
+```
+
+Edit `spec.yaml`; `npx openink blocks` lists every block you can use.

package/templates/starter/gitignore

@@ -0,0 +1,3 @@
+dist/
+.openink-dev/
+node_modules/