openink 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes are documented here. The format follows [Keep a Changelog](h
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-06
+
+### Added
+
+- `openink dev --open` opens the prototype in the default browser once the server is running (#25).
+- Spec errors and warnings start with the file, line and column (`spec.yaml:42:7`), in `validate`, `build`, `dev` and
+  the browser overlay. Most terminals and editors open that spot with a click (#24).
+- `openink dev` shows spec errors over the prototype in the browser, and hides them as soon as the spec builds again.
+  Before, a failed rebuild only showed in the terminal, and the browser kept the last good build (#23).
+
+### Fixed
+
+- `openink dev` prints each warning with its path and message, not only how many there are (#22).
+
 ## [0.3.0] - 2026-10-05
 
 ### Added

package/README.md

@@ -71,6 +71,7 @@ npx openink pdf                 # dist/<name>.pdf, one screen per page
 npx openink png                 # dist/png/<screen>.png
 npx openink blocks              # list every block and its props
 npx openink dev --theme dark    # try a colour theme without editing the spec
+npx openink dev --open          # also open the preview in your browser
 ```
 
 Or install it once and drop the `npx`:

package/docs/architecture.md

@@ -17,7 +17,7 @@ dist/ ──► http server + fs.watch + reload poller              (dev.js)
 
 **One definition per block.** `src/render/blocks/` is the single source of truth. The validator, the JSON Schema, `docs/blocks.md` and `openink blocks` are all generated from it, and tests fail when the generated files are stale. Adding a block is one object.
 
-**Validate everything, early.** Assistants and humans both make typos. The validator never throws; it returns `{ errors, warnings }` with a path into the spec and a suggestion, and `build` refuses to write output if there are errors.
+**Validate everything, early.** Assistants and humans both make typos. The validator never throws; it returns `{ errors, warnings }` with a path into the spec and a suggestion; the CLI adds the line and column from the YAML source. `build` refuses to write output if there are errors.
 
 **Bundled runtime.** wired-elements and RoughJS are bundled into `openink.js` at build time, so a prototype has no CDN dependency (except the Google Fonts stylesheet, which falls back to a system cursive font offline).
 

package/docs/getting-started.md

@@ -8,7 +8,7 @@ cd my-wireframes
 npx openink dev
 ```
 
-Open <http://localhost:3000>. Edit `spec.yaml` and the page reloads on save.
+Open <http://localhost:3000> (or start with `npx openink dev --open` to open it for you). Edit `spec.yaml` and the page reloads on save.
 
 **Skipping `npx`.** `npx openink` downloads the tool on first use. To pin a version per project, or to type just `openink`, install it:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openink",
-  "version": "0.3.0",
+  "version": "0.4.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",

package/src/build.js

@@ -19,17 +19,46 @@ export class SpecError extends Error {
   }
 }
 
-/** Find and parse the spec in a project directory. */
+/** The source range of a validator path such as `screens[3].blocks[2].type`, or of its nearest existing parent. */
+function rangeAt(doc, issuePath) {
+  const keys = (issuePath.match(/[^.[\]]+/g) || []).map((k) => (/^\d+$/.test(k) ? Number(k) : k));
+  let node = doc.contents;
+  let range = node?.range;
+  for (const key of keys) {
+    if (YAML.isAlias(node)) node = node.resolve(doc);
+    if (YAML.isMap(node)) {
+      // point at the key (`type:`), which is where an editor should put the cursor
+      const pair = node.items.find((p) => String(YAML.isScalar(p.key) ? p.key.value : p.key) === String(key));
+      if (!pair) break;
+      range = pair.key?.range ?? range;
+      node = pair.value;
+    } else if (YAML.isSeq(node) && typeof key === "number" && node.items[key]) {
+      node = node.items[key];
+      range = node.range ?? range;
+    } else break;
+  }
+  return range;
+}
+
+/**
+ * Find and parse the spec in a project directory.
+ * `locate(issue)` returns the issue with `loc` set to `file:line:col` (relative to the working 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 };
+  const lineCounter = new YAML.LineCounter();
+  const doc = YAML.parseDocument(fs.readFileSync(file, "utf8"), { lineCounter });
+  if (doc.errors.length) throw new SpecError(`${path.basename(file)} is not valid YAML: ${doc.errors[0].message}`);
+  const spec = doc.toJS();
+  const name = path.relative(process.cwd(), file) || path.basename(file);
+  const locate = (issue) => {
+    const range = rangeAt(doc, issue.path || "");
+    if (!range) return issue;
+    const { line, col } = lineCounter.linePos(range[0]);
+    return { ...issue, loc: `${name}:${line}:${col}` };
+  };
+  return { spec, file, locate };
 }
 
 let runtimeCache;
@@ -44,7 +73,7 @@ async function bundleRuntime() {
 /**
  * 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}[] }>}
+ * @returns {Promise<{ outDir: string, spec: object, warnings: {path:string,message:string,loc?:string}[] }>}
  */
 export async function build({ dir = ".", out = "dist", dev = false, theme } = {}) {
   const projectDir = path.resolve(dir);
@@ -53,14 +82,16 @@ export async function build({ dir = ".", out = "dist", dev = false, theme } = {}
     throw new Error(`Output directory ${outDir} would contain the project itself. Choose a different --out.`);
   }
 
-  const { spec } = loadSpec(projectDir);
+  const { spec, locate } = loadSpec(projectDir);
   if (theme) spec.theme = theme;
-  const { errors, warnings } = validate(spec);
+  const result = validate(spec);
+  const errors = result.errors;
   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);
+  if (errors.length) throw new SpecError(`${errors.length} problem${errors.length > 1 ? "s" : ""} in the spec`, errors.map(locate));
+  const warnings = result.warnings.map(locate);
 
   fs.rmSync(outDir, { recursive: true, force: true });
   fs.mkdirSync(outDir, { recursive: true });

package/src/cli.js

@@ -1,3 +1,4 @@
+import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -24,6 +25,7 @@ Commands:
 Options:
   --out <dir>      Output directory, relative to the project (default: dist)
   --port <n>       Dev server port (default: 3000; the next free port if taken)
+  --open           Open the prototype in the default browser when the dev server starts
   --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
@@ -40,6 +42,7 @@ function parse(argv) {
     const a = argv[i];
     if (a === "-h" || a === "--help") opts.help = true;
     else if (a === "-v" || a === "--version") opts.version = true;
+    else if (a === "--open") opts.open = 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];
@@ -49,8 +52,9 @@ function parse(argv) {
   return opts;
 }
 
+// `loc` (file:line:col) comes first, so terminals and editors can open the spot with a click
 const printIssues = (list, color, label) =>
-  list.forEach((i) => console.error(`  ${color(label)} ${dim(i.path || "spec")}: ${i.message}`));
+  list.forEach((i) => console.error(`  ${color(label)} ${i.loc ? `${i.loc} ` : ""}${dim(i.path || "spec")}: ${i.message}`));
 
 function init(dir = ".") {
   const target = path.resolve(dir);
@@ -65,6 +69,18 @@ function init(dir = ".") {
   console.log(green("✓") + ` Created ${rel || "."}/spec.yaml\n\nNext:\n  ${rel ? `cd ${rel} && ` : ""}npx openink dev`);
 }
 
+/** The command that opens a URL in the default browser on this platform. */
+export const openCommand = (url, platform = process.platform) =>
+  platform === "win32" ? ["cmd", ["/c", "start", '""', url]] : [platform === "darwin" ? "open" : "xdg-open", [url]];
+
+// a browser that fails to open is only worth a hint: the server keeps running
+function openBrowser(url) {
+  const [cmd, args] = openCommand(url);
+  const child = spawn(cmd, args, { stdio: "ignore", detached: true, windowsVerbatimArguments: process.platform === "win32" });
+  child.on("error", () => console.error(yellow(`Could not open a browser. Open ${url} yourself.`)));
+  child.unref();
+}
+
 /** @param {string[]} argv */
 export async function run(argv) {
   const opts = parse(argv);
@@ -81,8 +97,9 @@ export async function run(argv) {
       return console.log(blocksMarkdown());
 
     case "validate": {
-      const { spec } = loadSpec(dir);
-      const { errors, warnings } = validate(spec);
+      const { spec, locate } = loadSpec(dir);
+      const result = validate(spec);
+      const errors = result.errors.map(locate), warnings = result.warnings.map(locate);
       printIssues(warnings, yellow, "warn ");
       printIssues(errors, red, "error");
       if (errors.length) throw new SpecError(`${errors.length} error${errors.length > 1 ? "s" : ""}`);
@@ -109,8 +126,10 @@ export async function run(argv) {
         port: opts.port ? +opts.port : 3000,
         theme: opts.theme,
         onIssues: (e) => { console.error(red("✗ " + e.message)); printIssues(e.issues, red, "error"); },
+        onWarnings: (warnings) => printIssues(warnings, yellow, "warn "),
       });
       console.log(green("✓") + ` Serving ${server.url}  ${dim("(Ctrl+C to stop)")}`);
+      if (opts.open) openBrowser(server.url);
       process.on("SIGINT", () => { server.close(); process.exit(0); });
       return new Promise(() => {}); // keep running
     }

package/src/dev.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import http from "node:http";
 import path from "node:path";
 import { build, SpecError } from "./build.js";
+import { devErrorPage } from "./render/page.js";
 
 const MIME = {
   ".html": "text/html; charset=utf-8", ".js": "text/javascript", ".css": "text/css", ".json": "application/json",
@@ -11,21 +12,28 @@ const MIME = {
 
 const MAX_PORT_TRIES = 10;
 
+/** A failed build as plain text, for the overlay in the browser. */
+const describe = (e) => [e.message, ...(e.issues || []).map((i) => `  ${i.loc ? `${i.loc} ` : ""}${i.path || "spec"}: ${i.message}`)].join("\n");
+
 /**
  * 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]
+ * @param {{ dir?: string, out?: string, port?: number, theme?: string, log?: (msg: string) => void, onIssues?: (e: SpecError) => void, onWarnings?: (warnings: {path:string,message:string}[]) => void }} [opts]
  */
-export async function dev({ dir = ".", out = ".openink-dev", port = 3000, theme, log = console.log, onIssues = () => {} } = {}) {
+export async function dev({ dir = ".", out = ".openink-dev", port = 3000, theme, log = console.log, onIssues = () => {}, onWarnings = () => {} } = {}) {
   const projectDir = path.resolve(dir);
   const outDir = path.resolve(projectDir, out);
   let version = String(Date.now());
+  let error = null; // the last build's failure, shown in the browser until a build succeeds
 
   const rebuild = async () => {
     try {
       const { warnings } = await build({ dir, out, dev: true, theme });
       version = String(Date.now());
+      error = null;
       log(`✓ built${warnings.length ? ` (${warnings.length} warning${warnings.length > 1 ? "s" : ""})` : ""}`);
+      if (warnings.length) onWarnings(warnings);
     } catch (e) {
+      error = describe(e);
       if (e instanceof SpecError) onIssues(e);
       else log(`✗ ${e.message}`);
     }
@@ -34,8 +42,12 @@ export async function dev({ dir = ".", out = ".openink-dev", port = 3000, theme,
 
   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);
+    if (url === "/__version") {
+      return void res.writeHead(200, { "Content-Type": MIME[".json"], "Cache-Control": "no-store" }).end(JSON.stringify({ version, error }));
+    }
     const file = path.join(outDir, url === "/" ? "index.html" : url);
+    // no good build yet: a page that shows the errors and reloads once the spec builds
+    if (url === "/" && !fs.existsSync(file)) return void res.writeHead(200, { "Content-Type": MIME[".html"], "Cache-Control": "no-store" }).end(devErrorPage());
     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);
@@ -64,5 +76,5 @@ export async function dev({ dir = ".", out = ".openink-dev", port = 3000, theme,
   });
 
   const close = () => { watcher.close(); server.close(); fs.rmSync(outDir, { recursive: true, force: true }); };
-  return { url: `http://localhost:${port}`, close };
+  return { url: `http://localhost:${server.address().port}`, close };
 }

package/src/render/page.js

@@ -1,7 +1,23 @@
 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>`;
+// Dev mode: polls the dev server, reloads after a good build and shows the errors of a failed one.
+const DEV_RELOAD = `<script>(function(){var v,box;
+function show(e){if(!box){box=document.createElement("div");box.id="oi-dev-error";box.setAttribute("role","alert");box.style.cssText="position:fixed;inset:0;z-index:2147483647;overflow:auto;margin:0;padding:32px;background:rgba(40,0,0,.92);color:#fff;font:14px/1.6 ui-monospace,Menlo,Consolas,monospace;white-space:pre-wrap";document.body.appendChild(box)}box.textContent="\\u2717 "+e+"\\n\\nFix the spec and save: this page updates by itself."}
+function hide(){if(box){box.remove();box=null}}
+setInterval(function(){fetch("/__version").then(function(r){return r.json()}).then(function(s){if(v&&s.version!==v)return location.reload();v=s.version;s.error?show(s.error):hide()}).catch(function(){})},600)})()</script>`;
+
+/** The page the dev server shows when there is no good build yet: only the poller, which shows the errors. */
+export const devErrorPage = () => `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<title>openink</title>
+${DEV_RELOAD}
+</head>
+<body></body>
+</html>
+`;
 
 /**
  * Render a validated spec to a complete HTML document.