openink 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes are documented here. The format follows [Keep a Changelog](h
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-02
+
+### Added
+
+- A `wireframe` skill for AI coding agents that turns a description into a validated, screenshot-checked prototype in
+  any folder. Claude Code: `claude plugin marketplace add mediuswareltd/openink`, then
+  `claude plugin install openink@openink`. Cursor, Codex, Gemini CLI, GitHub Copilot and others:
+  `npx skills add mediuswareltd/openink`.
+
+### Fixed
+
+- An image, video, map, dropzone or chart placed directly in a `row` is drawn as a 4:3 thumbnail of its height. It
+  used to collapse to the width of its label and showed no box (#17).
+- The PDF button (and Ctrl+P) no longer prints image, video and map placeholders and charts as empty boxes with only
+  their label. Screens that had not been opened were printed before their sketches were drawn.
+
+## [0.1.1] - 2026-10-02
+
+### Added
+
+- Documentation website at <https://mediuswareltd.github.io/openink/> with search, live clickable demos of every example,
+  a recipes page of ready-to-paste specs (charts, forms, pricing, tables, modals, mobile) shown beside live previews, and an
+  About page.
+
+### Changed
+
+- `openink dev` uses the next free port (3001, 3002, … up to 10 tries) when the requested one is already in use, instead of failing with `EADDRINUSE`.
+
+### Fixed
+
+- A prototype embedded in an `<iframe>` no longer scrolls the surrounding page down to itself when it loads. Opening a
+  prototype without a `#screen` in the URL no longer adds one for the start screen.
+- A tall screen is no longer split across two PDF pages. Each screen is scaled down to fit one A4 landscape page, so the
+  PDF has exactly one page per screen. This applies to `openink pdf`, the prototype's PDF button and the browser's
+  own print (Ctrl+P).
+- The PDF button now draws the sketched outlines of screens that had never been opened, as `openink pdf` already did.
+
 ## [0.1.0]
 
 First release.

package/README.md

@@ -9,6 +9,11 @@
 
 Static HTML you can host or open from disk, plus PDF and PNG export. Built on [wired-elements](https://github.com/rough-stuff/wired-elements) and [RoughJS](https://github.com/rough-stuff/rough), so it looks like a sketch and nobody mistakes it for the final design. Keep it plain pencil, or turn on colour for a whole project or just one part.
 
+<p align="center">
+  <a href="https://mediuswareltd.github.io/openink/"><img src="assets/openink-explainer-poster.jpg" width="720" alt="Open Ink in 35 seconds: watch the explainer video" /></a><br />
+  <sub>&#9654; <a href="https://mediuswareltd.github.io/openink/">Watch Open Ink in 35 seconds</a> (<a href="assets/openink-explainer.mp4">MP4</a>)</sub>
+</p>
+
 <p>
   <img src="docs/img/photo-feed.png" width="32%" alt="Photo-sharing app: feed with stories, carousel and action icons" />
   <img src="docs/img/photo-mobile.png" width="32%" alt="The same feed inside a phone frame with a tab bar" />
@@ -77,6 +82,27 @@ openink dev
 
 Requires Node 20+. PDF and PNG export need Chrome, Chromium or Edge installed (set `CHROME_PATH` if it isn't found).
 
+### With an AI coding agent
+
+Give your agent the Open Ink skill once, then just describe what you want ("wireframe a booking app for a hair salon").
+
+**Claude Code**: install the plugin:
+
+```bash
+claude plugin marketplace add mediuswareltd/openink
+claude plugin install openink@openink
+```
+
+To get updates automatically, turn on auto-update for the **openink** marketplace in `/plugin` → **Marketplaces**.
+
+**Cursor, Codex, Gemini CLI, GitHub Copilot, Windsurf and other agents**: add the skill with the [skills](https://skills.sh) CLI, which asks which of your agents to install it for:
+
+```bash
+npx skills add mediuswareltd/openink
+```
+
+The agent writes and validates the spec, checks screenshots of every screen and tells you where the prototype is. See [docs/ai-assistants.md](docs/ai-assistants.md).
+
 ## What you can draw
 
 48 blocks in 10 groups; see the [block reference](docs/blocks.md) and the [gallery example](examples/gallery), which shows every one.
@@ -139,6 +165,8 @@ npx openink dev examples/photo-sharing
 
 ## Documentation
 
+**[mediuswareltd.github.io/openink](https://mediuswareltd.github.io/openink/)**: the full docs, with search and live demos of every example.
+
 - [Getting started](docs/getting-started.md)
 - [Spec reference](docs/spec.md): screens, colour, modals, navigation, languages, icons
 - [Block reference](docs/blocks.md)

package/docs/ai-assistants.md

@@ -6,6 +6,35 @@ Open Ink is designed so that an assistant (Claude Code, Cursor, Copilot, ChatGPT
 
 The assistant writes `spec.yaml`, the tool checks it, and you get a consistent hand-drawn result. Because the spec is small and validated, it is cheap to iterate: "add a second tab to the listing page" is a five-line diff.
 
+## Install the Open Ink skill
+
+Open Ink comes with a `wireframe` skill that teaches your agent the whole loop. Once it is installed, the agent uses it whenever you ask for a wireframe, mockup or clickable prototype, in any folder, so you do not need to mention Open Ink or run `init` first.
+
+The skill follows the same steps as the `AGENTS.md` below: it reads the block reference, edits only `spec.yaml`, validates until the spec is clean, checks a PNG of every screen and tells you where the result is. In a folder without a spec, it creates the project in a new subfolder so it does not overwrite your files.
+
+### Claude Code
+
+Install the plugin once:
+
+```bash
+claude plugin marketplace add mediuswareltd/openink
+claude plugin install openink@openink
+```
+
+Inside a session the same is `/plugin marketplace add mediuswareltd/openink` and `/plugin install openink@openink`. You can also call the skill directly with `/openink:wireframe`.
+
+For updates, turn on auto-update for the **openink** marketplace in `/plugin` → **Marketplaces**, or run `/plugin marketplace update openink`.
+
+### Cursor, Codex, Gemini CLI, GitHub Copilot and other agents
+
+Add the skill with the [skills](https://skills.sh) CLI:
+
+```bash
+npx skills add mediuswareltd/openink
+```
+
+It asks which of your agents to install it for, and whether to install it for this project or for your user. To skip the questions, name the agents and add `-y`, for example `npx skills add mediuswareltd/openink -a cursor -a codex -y`, and add `-g` to install it for every project. Run `npx skills update` to get the latest version.
+
 ## How it works
 
 `openink init` puts an `AGENTS.md` in your project. Most assistants read it automatically; it tells them to:

package/docs/blocks.md

@@ -43,7 +43,7 @@ Vertical stack of blocks.
 
 ### `row` · children
 
-Horizontal row that wraps on small screens.
+Horizontal row that wraps on small screens. Images, videos, maps and charts in a row are 4:3 thumbnails of their height.
 
 | Prop | Type | Description |
 |---|---|---|

package/package.json

@@ -1,24 +1,62 @@
 {
   "name": "openink",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Describe screens in YAML, get a clickable hand-drawn wireframe prototype (static HTML, PDF, PNG). Built on wired-elements and RoughJS.",
-  "keywords": ["wireframe", "prototype", "sketch", "mockup", "hand-drawn", "wired-elements", "roughjs", "ux", "static-site-generator"],
+  "keywords": [
+    "wireframe",
+    "prototype",
+    "sketch",
+    "mockup",
+    "hand-drawn",
+    "wired-elements",
+    "roughjs",
+    "ux",
+    "static-site-generator"
+  ],
   "license": "MIT",
   "author": "Mediusware",
-  "repository": { "type": "git", "url": "git+https://github.com/mediuswareltd/openink.git" },
-  "homepage": "https://github.com/mediuswareltd/openink#readme",
-  "bugs": { "url": "https://github.com/mediuswareltd/openink/issues" },
-  "publishConfig": { "access": "public" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mediuswareltd/openink.git"
+  },
+  "homepage": "https://mediuswareltd.github.io/openink/",
+  "bugs": {
+    "url": "https://github.com/mediuswareltd/openink/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
-  "bin": { "openink": "bin/openink.js" },
+  "bin": {
+    "openink": "bin/openink.js"
+  },
   "main": "./src/index.js",
   "exports": {
     ".": "./src/index.js",
     "./schema.json": "./schema/spec.schema.json",
     "./package.json": "./package.json"
   },
-  "files": ["bin", "src", "templates", "schema", "docs", "!docs/img", "LICENSE", "README.md", "CHANGELOG.md"],
-  "engines": { "node": ">=20" },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "schema",
+    "docs",
+    "!docs/img",
+    "!docs/.vitepress",
+    "!docs/public",
+    "!docs/index.md",
+    "!docs/examples.md",
+    "!docs/about.md",
+    "!docs/snippets",
+    "!docs/recipes.md",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "generate": "node scripts/generate.js",
     "test": "node --test \"test/*.test.js\"",
@@ -26,7 +64,12 @@
     "prepublishOnly": "npm test",
     "lint:commit": "node scripts/commit-lint.js",
     "screenshots": "node scripts/screenshots.js",
-    "dev": "node bin/openink.js dev examples/rental-portal"
+    "dev": "node bin/openink.js dev examples/rental-portal",
+    "docs:demos": "node scripts/build-demos.js",
+    "docs:dev": "npm run docs:demos && vitepress dev docs",
+    "docs:build": "npm run docs:demos && vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "docs:deploy": "npm run docs:build && node scripts/deploy-docs.js"
   },
   "dependencies": {
     "esbuild": "^0.28.2",
@@ -34,5 +77,8 @@
     "roughjs": "4.3.1",
     "wired-elements": "3.0.0-rc.6",
     "yaml": "^2.5.0"
+  },
+  "devDependencies": {
+    "vitepress": "^1.6.4"
   }
 }

package/schema/spec.schema.json

@@ -364,7 +364,7 @@
         },
         {
           "type": "object",
-          "description": "Horizontal row that wraps on small screens.",
+          "description": "Horizontal row that wraps on small screens. Images, videos, maps and charts in a row are 4:3 thumbnails of their height.",
           "required": [
             "type"
           ],

package/src/cli.js

@@ -23,7 +23,7 @@ Commands:
 
 Options:
   --out <dir>      Output directory, relative to the project (default: dist)
-  --port <n>       Dev server port (default: 3000)
+  --port <n>       Dev server port (default: 3000; the next free port if taken)
   --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

package/src/dev.js

@@ -9,6 +9,8 @@ const MIME = {
   ".webp": "image/webp", ".ico": "image/x-icon", ".woff2": "font/woff2", ".pdf": "application/pdf",
 };
 
+const MAX_PORT_TRIES = 10;
+
 /**
  * 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]
@@ -38,7 +40,20 @@ export async function dev({ dir = ".", out = ".openink-dev", port = 3000, theme,
     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));
+  // If the port is taken, try the next ones (3000 → 3001 → …) before giving up.
+  const wanted = port;
+  for (let attempt = 0; ; attempt++, port++) {
+    try {
+      await new Promise((resolve, reject) => server.once("error", reject).listen(port, () => { server.off("error", reject); resolve(); }));
+      break;
+    } catch (e) {
+      if (e.code !== "EADDRINUSE" || attempt >= MAX_PORT_TRIES - 1) {
+        fs.rmSync(outDir, { recursive: true, force: true });
+        throw e.code === "EADDRINUSE" ? new Error(`Ports ${wanted}–${port} are all in use. Pick another with --port.`) : e;
+      }
+    }
+  }
+  if (port !== wanted) log(`Port ${wanted} is in use, using ${port} instead.`);
 
   let timer;
   const watcher = fs.watch(projectDir, { recursive: true }, (_, name) => {

package/src/export.js

@@ -55,9 +55,9 @@ export async function exportFiles({ dir = ".", out = "dist", png = false, theme
       return { files };
     }
 
-    // Print media shows every screen; the ones that were hidden have never been drawn, so force a render.
+    // Lay the page out for print and shrink any screen too tall for one page, as the PDF button does.
     await page.emulateMediaType("print");
-    await page.evaluate(() => document.querySelectorAll("*").forEach((e) => e.wiredRender?.(true)));
+    await page.evaluate(() => window.openink.preparePrint());
     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 });

package/src/render/blocks/layout.js

@@ -13,7 +13,7 @@ export default [
   {
     name: "row",
     group: "Layout",
-    summary: "Horizontal row that wraps on small screens.",
+    summary: "Horizontal row that wraps on small screens. Images, videos, maps and charts in a row are 4:3 thumbnails of their height.",
     children: true,
     props: {
       between: { type: "boolean", doc: "Push the first and last child to opposite ends." },

package/src/runtime/chart.js

@@ -12,7 +12,7 @@ class Chart extends HTMLElement {
     const kind = this.getAttribute("kind") || "line";
     const values = (this.getAttribute("values") || "").split(",").map((s) => s.trim()).filter(Boolean).map(Number).filter(Number.isFinite);
     const data = values.length ? values : SAMPLE[kind] || SAMPLE.line;
-    this.style.cssText += `display:block;position:relative;height:${h}px`;
+    this.style.cssText += `display:block;position:relative;height:${h}px;--oi-w:${Math.round((h * 4) / 3)}px`;
 
     const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
     svg.style.cssText = "position:absolute;inset:0;width:100%;height:100%";
@@ -70,6 +70,7 @@ class Chart extends HTMLElement {
       }
     };
 
+    this.draw = draw; // print draws every screen at once, before a ResizeObserver would fire
     draw();
     new ResizeObserver(draw).observe(this);
     const label = this.getAttribute("label");

package/src/runtime/index.js

@@ -5,6 +5,7 @@ import "./chart.js";
 import { $$, redraw } from "./dom.js";
 import { go, toast, initNavigation } from "./navigation.js";
 import { setLang, initI18n } from "./i18n.js";
+import { initPrint } from "./print.js";
 
 function select(buttons, active) {
   buttons.forEach((b) => {
@@ -61,4 +62,5 @@ document.addEventListener("toggle", (e) => e.target.tagName === "DETAILS" && red
 window.addEventListener("DOMContentLoaded", () => {
   initI18n();
   initNavigation();
+  initPrint();
 });

package/src/runtime/navigation.js

@@ -1,14 +1,18 @@
 import { $$, config, redraw } from "./dom.js";
 
-/** Show one screen (and the header nav set it asks for). */
-export function go(id) {
+/**
+ * Show one screen (and the header nav set it asks for).
+ * `remember: false` leaves the URL alone: a "#screen" written before the page has loaded makes the
+ * browser scroll to it, and inside an iframe that scrolls the embedding page too.
+ */
+export function go(id, { remember = true } = {}) {
   const el = document.getElementById(id);
   if (!el || !el.classList.contains("screen")) return;
   $$(".screen").forEach((s) => s.classList.remove("on"));
   el.classList.add("on");
   $$("header nav").forEach((n) => (n.hidden = n.dataset.nav !== el.dataset.nav));
   document.title = el.dataset.title + " · " + document.title.split(" · ").pop();
-  history.replaceState(null, "", "#" + id);
+  if (remember) history.replaceState(null, "", "#" + id);
   window.scrollTo({ top: 0 });
   redraw();
 }
@@ -23,5 +27,6 @@ export function toast(message) {
 
 export function initNavigation() {
   window.addEventListener("hashchange", () => go(location.hash.slice(1)));
-  go(location.hash.slice(1) || config.first);
+  // The start screen: the URL already says which one, or it is the first screen.
+  go(location.hash.slice(1) || config.first, { remember: false });
 }

package/src/runtime/placeholder.js

@@ -11,7 +11,7 @@ class Placeholder extends HTMLElement {
     const h = +this.getAttribute("h") || 120;
     // A round placeholder (avatar) is square and must have a width of its own to sit in a flex row.
     const width = this.hasAttribute("round") ? `width:${h}px;flex:none;` : "";
-    this.style.cssText += `display:block;position:relative;height:${h}px;${width}`;
+    this.style.cssText += `display:block;position:relative;height:${h}px;--oi-w:${Math.round((h * 4) / 3)}px;${width}`;
 
     const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
     svg.style.cssText = "position:absolute;inset:0;width:100%;height:100%";
@@ -72,6 +72,7 @@ class Placeholder extends HTMLElement {
       }
     };
 
+    this.draw = draw; // print draws every screen at once, before a ResizeObserver would fire
     draw();
     new ResizeObserver(draw).observe(this);
 

package/src/runtime/print.js

@@ -0,0 +1,55 @@
+import { $$, redraw } from "./dom.js";
+
+// Printable height of the @page in openink.css (A4 landscape less 10mm margins), in CSS pixels.
+const PAGE_HEIGHT = (190 * 96) / 25.4;
+
+/**
+ * Lay the page out for print (every screen, one per page), shrink each screen that is taller than
+ * one printed page so it is not split across two, and draw the wired-elements that have never been
+ * visible. Runs on `beforeprint` (the PDF button, Ctrl+P) and from `openink export`.
+ */
+export function preparePrint() {
+  document.documentElement.classList.add("oi-print");
+  const screens = $$(".screen");
+  screens.forEach(unzoom);
+
+  // The header shares the first screen's page and the footer the last one's, so their height comes
+  // off that page's budget.
+  const docBottom = document.documentElement.scrollHeight;
+  const zooms = screens.map((s, i) => {
+    const r = s.getBoundingClientRect();
+    const top = r.top + scrollY;
+    const fixed = (i === 0 ? top : 0) + (i === screens.length - 1 ? docBottom - (top + r.height) : 0);
+    const room = (PAGE_HEIGHT - fixed) * 0.97; // a little slack for rounding and collapsed margins
+    return { zoom: r.height > room ? Math.max(room / r.height, 0.3) : 1, width: r.width };
+  });
+
+  // Draw everything now: the browser prints straight after this returns, before a ResizeObserver
+  // would draw the placeholders and charts on screens that were hidden.
+  // Draw before zooming: wired-elements size their sketch from the zoomed box, and the zoom then
+  // shrinks the sketch a second time. Keep the screen's unzoomed width so its layout (and so the
+  // sketches) only scales, and record the zoomed box as the size last drawn, so a resize
+  // (wired-card watches its own) does not redraw at that size.
+  $$("*").forEach((el) => (el.wiredRender ? el.wiredRender(true) : el.draw?.()));
+  screens.forEach((s, i) => {
+    const { zoom, width } = zooms[i];
+    if (zoom === 1) return;
+    Object.assign(s.style, { zoom: String(zoom), width: `${width}px`, marginInline: "auto" });
+    $$("*", s).forEach((el) => el.canvasSize && el.lastSize && (el.lastSize = el.canvasSize()));
+  });
+}
+
+/** Undo preparePrint and redraw the screen that is showing. */
+export function endPrint() {
+  document.documentElement.classList.remove("oi-print");
+  $$(".screen").forEach(unzoom);
+  redraw();
+}
+
+const unzoom = (s) => Object.assign(s.style, { zoom: "", width: "", marginInline: "" });
+
+export function initPrint() {
+  window.addEventListener("beforeprint", preparePrint);
+  window.addEventListener("afterprint", endPrint);
+  window.openink = { ...window.openink, preparePrint, endPrint };
+}

package/src/styles/openink.css

@@ -101,8 +101,10 @@ p { margin: 0; }
 .row { display: flex; gap: .6rem; align-items: center; flex-wrap: wrap; }
 .row.between { justify-content: space-between; }
 .row.center { justify-content: center; }
+/* placeholders and charts have no content width, so in a row they are a 4:3 thumbnail (--oi-w is set from their height) */
+.row > oi-placeholder:not([round]), .row > oi-chart { flex: none; width: var(--oi-w); max-width: 100%; }
 .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; } }
+@media (max-width: 720px) { html:not(.oi-print) .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; }
@@ -238,13 +240,16 @@ oi-placeholder[upload] .ph-label { inset: auto 0 22px 0; }
 .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 */
+/* print / PDF: every screen on its own page. The runtime adds .oi-print before printing (and removes
+   it after) so it can measure the print layout and shrink screens too tall for one page; the layout
+   width is the @page's printable width. */
 @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; }
 }
+html.oi-print { width: 277mm; }
+.oi-print .oi-bar nav, .oi-print .lang, .oi-print .print-btn, .oi-print .toast, .oi-print .nextbar, .oi-print .modal { display: none !important; }
+.oi-print .screen, .oi-print .screen.on { display: block !important; break-after: page; }
+.oi-print .screen:last-of-type { break-after: auto; }
+.oi-print .screen-title { display: block; font-family: "Caveat", cursive; font-size: 1.3rem; color: var(--muted); border-bottom: 2px dashed var(--line); }
+.oi-print .tab-panel { display: block; }