openink 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ 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
+
+- 73 more icons, 110 in all: arrows, status, files, shopping, weather and 20 brand logos (Google, Apple, GitHub,
+  Facebook, X, Instagram, LinkedIn, YouTube, TikTok, WhatsApp and more) for sign-in buttons, share bars and footers.
+  The gallery has a new Icons screen that shows every icon with its name (#20).
+
 ## [0.2.0] - 2026-10-02
 
 ### 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`:
@@ -111,7 +112,7 @@ The agent writes and validates the spec, checks screenshots of every screen and
 |---|---|
 | **Layout** | `stack` `row` `grid` `card` `accordion` `device` (phone / tablet / browser frame) `divider` `spacer` |
 | **Text** | `h1` `h2` `h3` `text` `list` `note` `badge` |
-| **Content** | `icon` (37 hand-drawn icons) `avatar` `hero` `stat` `rating` `link` |
+| **Content** | `icon` (110 hand-drawn icons, brand logos included) `avatar` `hero` `stat` `rating` `link` |
 | **Media** | `image` `map` `video` `carousel` `dropzone` `box` `chart` (line, area, bar, pie, donut) |
 | **Forms** | `input` `search` `textarea` `select` `checkbox` `toggle` `radio` `slider` |
 | **Actions** | `button` (with icon) `chips` `tabs` `nextbar` |
@@ -190,3 +191,5 @@ Issues and pull requests are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Ad
 ## License
 
 [MIT](LICENSE)
+
+Brand names and logos are trademarks of their owners. Open Ink's brand icons are simplified sketches for wireframes only and do not imply endorsement. Use each brand's official assets in production.

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/blocks.md

@@ -27,7 +27,9 @@ Blocks that list `go`, `toast`, `open` or `close` in their props are clickable (
 
 Used by `icon`, `button.icon`, nav items and `tabbar`:
 
-`home` · `search` · `heart` · `comment` · `share` · `bookmark` · `plus` · `bell` · `user` · `users` · `mail` · `settings` · `camera` · `image` · `video` · `star` · `menu` · `more` · `close` · `check` · `arrow-right` · `arrow-left` · `chevron-down` · `chevron-right` · `play` · `pin` · `trash` · `edit` · `upload` · `download` · `lock` · `cart` · `chart` · `calendar` · `filter` · `info` · `send`
+`home` · `search` · `heart` · `comment` · `share` · `bookmark` · `plus` · `bell` · `user` · `users` · `mail` · `settings` · `camera` · `image` · `video` · `star` · `menu` · `more` · `close` · `check` · `arrow-right` · `arrow-left` · `chevron-down` · `chevron-right` · `play` · `pin` · `trash` · `edit` · `upload` · `download` · `lock` · `cart` · `chart` · `calendar` · `filter` · `info` · `send` · `minus` · `arrow-up` · `arrow-down` · `chevron-up` · `chevron-left` · `external` · `link` · `refresh` · `login` · `logout` · `grid` · `list` · `pause` · `check-circle` · `warning` · `help` · `eye` · `eye-off` · `unlock` · `key` · `thumbs-up` · `smile` · `flag` · `zap` · `phone` · `inbox` · `paperclip` · `mic` · `volume` · `music` · `wifi` · `hash` · `at` · `rss` · `file` · `folder` · `copy` · `book` · `briefcase` · `printer` · `code` · `clock` · `bag` · `tag` · `gift` · `credit-card` · `dollar` · `truck` · `globe` · `map` · `sun` · `moon` · `cloud` · `facebook` · `x` · `instagram` · `linkedin` · `youtube` · `github` · `tiktok` · `whatsapp` · `telegram` · `discord` · `pinterest` · `reddit` · `snapchat` · `slack` · `spotify` · `apple` · `google` · `microsoft` · `dribbble` · `twitch`
+
+Brand names and logos are trademarks of their owners. Open Ink's brand icons are simplified sketches for wireframes only and do not imply endorsement. Use each brand's official assets in production.
 
 ## Layout
 
@@ -198,7 +200,7 @@ Hand-drawn icon.
 
 | Prop | Type | Description |
 |---|---|---|
-| `name` * | `home` \| `search` \| `heart` \| `comment` \| `share` \| `bookmark` \| `plus` \| `bell` \| `user` \| `users` \| `mail` \| `settings` \| `camera` \| `image` \| `video` \| `star` \| `menu` \| `more` \| `close` \| `check` \| `arrow-right` \| `arrow-left` \| `chevron-down` \| `chevron-right` \| `play` \| `pin` \| `trash` \| `edit` \| `upload` \| `download` \| `lock` \| `cart` \| `chart` \| `calendar` \| `filter` \| `info` \| `send` | Icon name. |
+| `name` * | `home` \| `search` \| `heart` \| `comment` \| `share` \| `bookmark` \| `plus` \| `bell` \| `user` \| `users` \| `mail` \| `settings` \| `camera` \| `image` \| `video` \| `star` \| `menu` \| `more` \| `close` \| `check` \| `arrow-right` \| `arrow-left` \| `chevron-down` \| `chevron-right` \| `play` \| `pin` \| `trash` \| `edit` \| `upload` \| `download` \| `lock` \| `cart` \| `chart` \| `calendar` \| `filter` \| `info` \| `send` \| `minus` \| `arrow-up` \| `arrow-down` \| `chevron-up` \| `chevron-left` \| `external` \| `link` \| `refresh` \| `login` \| `logout` \| `grid` \| `list` \| `pause` \| `check-circle` \| `warning` \| `help` \| `eye` \| `eye-off` \| `unlock` \| `key` \| `thumbs-up` \| `smile` \| `flag` \| `zap` \| `phone` \| `inbox` \| `paperclip` \| `mic` \| `volume` \| `music` \| `wifi` \| `hash` \| `at` \| `rss` \| `file` \| `folder` \| `copy` \| `book` \| `briefcase` \| `printer` \| `code` \| `clock` \| `bag` \| `tag` \| `gift` \| `credit-card` \| `dollar` \| `truck` \| `globe` \| `map` \| `sun` \| `moon` \| `cloud` \| `facebook` \| `x` \| `instagram` \| `linkedin` \| `youtube` \| `github` \| `tiktok` \| `whatsapp` \| `telegram` \| `discord` \| `pinterest` \| `reddit` \| `snapchat` \| `slack` \| `spotify` \| `apple` \| `google` \| `microsoft` \| `dribbble` \| `twitch` | Icon name. |
 | `size` | number | Size in px (default 22). |
 | `filled` | boolean | Solid instead of outline (heart, star, bookmark…). |
 
@@ -458,7 +460,7 @@ Button, optionally with an icon. Navigates with `go`, opens a `modal` with `open
 | Prop | Type | Description |
 |---|---|---|
 | `label` | text | Button text. Leave out for an icon-only button. |
-| `icon` | `home` \| `search` \| `heart` \| `comment` \| `share` \| `bookmark` \| `plus` \| `bell` \| `user` \| `users` \| `mail` \| `settings` \| `camera` \| `image` \| `video` \| `star` \| `menu` \| `more` \| `close` \| `check` \| `arrow-right` \| `arrow-left` \| `chevron-down` \| `chevron-right` \| `play` \| `pin` \| `trash` \| `edit` \| `upload` \| `download` \| `lock` \| `cart` \| `chart` \| `calendar` \| `filter` \| `info` \| `send` | Icon shown before the label. |
+| `icon` | `home` \| `search` \| `heart` \| `comment` \| `share` \| `bookmark` \| `plus` \| `bell` \| `user` \| `users` \| `mail` \| `settings` \| `camera` \| `image` \| `video` \| `star` \| `menu` \| `more` \| `close` \| `check` \| `arrow-right` \| `arrow-left` \| `chevron-down` \| `chevron-right` \| `play` \| `pin` \| `trash` \| `edit` \| `upload` \| `download` \| `lock` \| `cart` \| `chart` \| `calendar` \| `filter` \| `info` \| `send` \| `minus` \| `arrow-up` \| `arrow-down` \| `chevron-up` \| `chevron-left` \| `external` \| `link` \| `refresh` \| `login` \| `logout` \| `grid` \| `list` \| `pause` \| `check-circle` \| `warning` \| `help` \| `eye` \| `eye-off` \| `unlock` \| `key` \| `thumbs-up` \| `smile` \| `flag` \| `zap` \| `phone` \| `inbox` \| `paperclip` \| `mic` \| `volume` \| `music` \| `wifi` \| `hash` \| `at` \| `rss` \| `file` \| `folder` \| `copy` \| `book` \| `briefcase` \| `printer` \| `code` \| `clock` \| `bag` \| `tag` \| `gift` \| `credit-card` \| `dollar` \| `truck` \| `globe` \| `map` \| `sun` \| `moon` \| `cloud` \| `facebook` \| `x` \| `instagram` \| `linkedin` \| `youtube` \| `github` \| `tiktok` \| `whatsapp` \| `telegram` \| `discord` \| `pinterest` \| `reddit` \| `snapchat` \| `slack` \| `spotify` \| `apple` \| `google` \| `microsoft` \| `dribbble` \| `twitch` | Icon shown before the label. |
 | `primary` | boolean | Heavier border: the main action on the screen. |
 | `disabled` | boolean | Grey out the button. |
 | `go` | string | Id of the screen to open when clicked. |

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/docs/spec.md

@@ -190,6 +190,8 @@ screens:
 
 `icon` blocks, `button.icon`, nav items and tab-bar items use a built-in set of hand-drawn icons (`home`, `search`, `heart`, `comment`, `send`, `bell`, `user`, `camera`, …). The full list is at the end of the [block reference](blocks.md#icons). An unknown name is an error with a "did you mean" hint.
 
+The set includes brand logos (`google`, `apple`, `github`, `facebook`, `x`, `linkedin`, …) for sign-in buttons, share bars and footers. Brand names and logos are trademarks of their owners. Open Ink's brand icons are simplified sketches for wireframes only and do not imply endorsement. Use each brand's official assets in production.
+
 ## Quoting text with commas
 
 Inside `{ ... }` a comma ends the value, so YAML reads `{ type: text, text: Hello, world }` as text `Hello` plus a stray key `world`. Wrap such text in quotes: `text: "Hello, world"`. `validate` warns when it sees this.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openink",
-  "version": "0.2.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/schema/spec.schema.json

@@ -275,7 +275,80 @@
             "calendar",
             "filter",
             "info",
-            "send"
+            "send",
+            "minus",
+            "arrow-up",
+            "arrow-down",
+            "chevron-up",
+            "chevron-left",
+            "external",
+            "link",
+            "refresh",
+            "login",
+            "logout",
+            "grid",
+            "list",
+            "pause",
+            "check-circle",
+            "warning",
+            "help",
+            "eye",
+            "eye-off",
+            "unlock",
+            "key",
+            "thumbs-up",
+            "smile",
+            "flag",
+            "zap",
+            "phone",
+            "inbox",
+            "paperclip",
+            "mic",
+            "volume",
+            "music",
+            "wifi",
+            "hash",
+            "at",
+            "rss",
+            "file",
+            "folder",
+            "copy",
+            "book",
+            "briefcase",
+            "printer",
+            "code",
+            "clock",
+            "bag",
+            "tag",
+            "gift",
+            "credit-card",
+            "dollar",
+            "truck",
+            "globe",
+            "map",
+            "sun",
+            "moon",
+            "cloud",
+            "facebook",
+            "x",
+            "instagram",
+            "linkedin",
+            "youtube",
+            "github",
+            "tiktok",
+            "whatsapp",
+            "telegram",
+            "discord",
+            "pinterest",
+            "reddit",
+            "snapchat",
+            "slack",
+            "spotify",
+            "apple",
+            "google",
+            "microsoft",
+            "dribbble",
+            "twitch"
           ]
         },
         "label": {
@@ -1011,7 +1084,80 @@
                 "calendar",
                 "filter",
                 "info",
-                "send"
+                "send",
+                "minus",
+                "arrow-up",
+                "arrow-down",
+                "chevron-up",
+                "chevron-left",
+                "external",
+                "link",
+                "refresh",
+                "login",
+                "logout",
+                "grid",
+                "list",
+                "pause",
+                "check-circle",
+                "warning",
+                "help",
+                "eye",
+                "eye-off",
+                "unlock",
+                "key",
+                "thumbs-up",
+                "smile",
+                "flag",
+                "zap",
+                "phone",
+                "inbox",
+                "paperclip",
+                "mic",
+                "volume",
+                "music",
+                "wifi",
+                "hash",
+                "at",
+                "rss",
+                "file",
+                "folder",
+                "copy",
+                "book",
+                "briefcase",
+                "printer",
+                "code",
+                "clock",
+                "bag",
+                "tag",
+                "gift",
+                "credit-card",
+                "dollar",
+                "truck",
+                "globe",
+                "map",
+                "sun",
+                "moon",
+                "cloud",
+                "facebook",
+                "x",
+                "instagram",
+                "linkedin",
+                "youtube",
+                "github",
+                "tiktok",
+                "whatsapp",
+                "telegram",
+                "discord",
+                "pinterest",
+                "reddit",
+                "snapchat",
+                "slack",
+                "spotify",
+                "apple",
+                "google",
+                "microsoft",
+                "dribbble",
+                "twitch"
               ],
               "description": "Icon name."
             },
@@ -1996,7 +2142,80 @@
                 "calendar",
                 "filter",
                 "info",
-                "send"
+                "send",
+                "minus",
+                "arrow-up",
+                "arrow-down",
+                "chevron-up",
+                "chevron-left",
+                "external",
+                "link",
+                "refresh",
+                "login",
+                "logout",
+                "grid",
+                "list",
+                "pause",
+                "check-circle",
+                "warning",
+                "help",
+                "eye",
+                "eye-off",
+                "unlock",
+                "key",
+                "thumbs-up",
+                "smile",
+                "flag",
+                "zap",
+                "phone",
+                "inbox",
+                "paperclip",
+                "mic",
+                "volume",
+                "music",
+                "wifi",
+                "hash",
+                "at",
+                "rss",
+                "file",
+                "folder",
+                "copy",
+                "book",
+                "briefcase",
+                "printer",
+                "code",
+                "clock",
+                "bag",
+                "tag",
+                "gift",
+                "credit-card",
+                "dollar",
+                "truck",
+                "globe",
+                "map",
+                "sun",
+                "moon",
+                "cloud",
+                "facebook",
+                "x",
+                "instagram",
+                "linkedin",
+                "youtube",
+                "github",
+                "tiktok",
+                "whatsapp",
+                "telegram",
+                "discord",
+                "pinterest",
+                "reddit",
+                "snapchat",
+                "slack",
+                "spotify",
+                "apple",
+                "google",
+                "microsoft",
+                "dribbble",
+                "twitch"
               ],
               "description": "Icon shown before the label."
             },
@@ -2376,7 +2595,80 @@
                       "calendar",
                       "filter",
                       "info",
-                      "send"
+                      "send",
+                      "minus",
+                      "arrow-up",
+                      "arrow-down",
+                      "chevron-up",
+                      "chevron-left",
+                      "external",
+                      "link",
+                      "refresh",
+                      "login",
+                      "logout",
+                      "grid",
+                      "list",
+                      "pause",
+                      "check-circle",
+                      "warning",
+                      "help",
+                      "eye",
+                      "eye-off",
+                      "unlock",
+                      "key",
+                      "thumbs-up",
+                      "smile",
+                      "flag",
+                      "zap",
+                      "phone",
+                      "inbox",
+                      "paperclip",
+                      "mic",
+                      "volume",
+                      "music",
+                      "wifi",
+                      "hash",
+                      "at",
+                      "rss",
+                      "file",
+                      "folder",
+                      "copy",
+                      "book",
+                      "briefcase",
+                      "printer",
+                      "code",
+                      "clock",
+                      "bag",
+                      "tag",
+                      "gift",
+                      "credit-card",
+                      "dollar",
+                      "truck",
+                      "globe",
+                      "map",
+                      "sun",
+                      "moon",
+                      "cloud",
+                      "facebook",
+                      "x",
+                      "instagram",
+                      "linkedin",
+                      "youtube",
+                      "github",
+                      "tiktok",
+                      "whatsapp",
+                      "telegram",
+                      "discord",
+                      "pinterest",
+                      "reddit",
+                      "snapchat",
+                      "slack",
+                      "spotify",
+                      "apple",
+                      "google",
+                      "microsoft",
+                      "dribbble",
+                      "twitch"
                     ]
                   },
                   "label": {

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/icons.js

@@ -3,6 +3,9 @@
 // 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`;
+// A rectangle with rounded corners.
+const box = (x, y, w, h, r) =>
+  `M${x + r} ${y}h${w - 2 * r}a${r} ${r} 0 0 1 ${r} ${r}v${h - 2 * r}a${r} ${r} 0 0 1 ${-r} ${r}h${2 * r - w}a${r} ${r} 0 0 1 ${-r} ${-r}v${2 * r - h}a${r} ${r} 0 0 1 ${r} ${-r}z`;
 
 export const ICONS = {
   home: ["M3 11.5L12 3l9 8.5", "M5.5 10v10.5h13V10", "M10 20.5v-6h4v6"],
@@ -42,6 +45,113 @@ export const ICONS = {
   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"],
+
+  // arrows and controls
+  minus: ["M4 12h16"],
+  "arrow-up": ["M12 20V4M6 10l6-6 6 6"],
+  "arrow-down": ["M12 4v16M6 14l6 6 6-6"],
+  "chevron-up": ["M6 15l6-6 6 6"],
+  "chevron-left": ["M15 6l-6 6 6 6"],
+  external: ["M14 4h6v6", "M20 4l-9 9", "M18 14v6H4V6h6"],
+  link: ["M10 14a4 4 0 0 0 5.7 0l3-3a4 4 0 0 0-5.7-5.7l-1 1", "M14 10a4 4 0 0 0-5.7 0l-3 3a4 4 0 0 0 5.7 5.7l1-1"],
+  refresh: ["M20 12a8 8 0 1 1-2.3-5.7", "M20 3.5V8h-4.5"],
+  login: ["M15 4h5v16h-5", "M10 8l4 4-4 4", "M14 12H3"],
+  logout: ["M9 4H4v16h5", "M16 8l4 4-4 4", "M20 12H9"],
+  grid: ["M4 4h7v7H4z", "M13 4h7v7h-7z", "M4 13h7v7H4z", "M13 13h7v7h-7z"],
+  list: ["M9 6h12M9 12h12M9 18h12", dot(4.5, 6), dot(4.5, 12), dot(4.5, 18)],
+  pause: ["M7 4h3v16H7z", "M14 4h3v16h-3z"],
+
+  // status
+  "check-circle": [dot(12, 12, 9), "M8 12.5l3 3 5-6"],
+  warning: ["M12 3L2 20h20z", "M12 10v4", dot(12, 17, 0.6)],
+  help: [dot(12, 12, 9), "M9.5 9a2.5 2.5 0 1 1 3.5 2.3c-.7.3-1 .9-1 1.7v.5", dot(12, 17, 0.6)],
+  eye: ["M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7S2 12 2 12z", dot(12, 12, 3)],
+  "eye-off": ["M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7S2 12 2 12z", dot(12, 12, 3), "M4 4l16 16"],
+  unlock: ["M6 11h12v10H6z", "M8.5 11V8a3.5 3.5 0 0 1 6.8-1.2"],
+  key: [dot(7.5, 16.5, 4), "M10.5 13.5L20 4", "M16.5 7.5l2.5 2.5", "M18.5 5.5l2 2"],
+  "thumbs-up": ["M7 10v11H3V10z", "M7 10l4-8a2.5 2.5 0 0 1 3 2.5V9h5.5a2 2 0 0 1 2 2.3l-1.4 8A2 2 0 0 1 18 21H7"],
+  smile: [dot(12, 12, 9), "M8 14.5a5 5 0 0 0 8 0", dot(9, 9.5, 0.6), dot(15, 9.5, 0.6)],
+  flag: ["M5 21V4", "M5 4h12l-2.5 4.5L17 13H5"],
+  zap: ["M13 2L4 14h7l-1 8 9-12h-7z"],
+
+  // communication and media
+  phone: ["M5 4h4l2 5-2.5 1.5a11 11 0 0 0 5 5L15 13l5 2v4a2 2 0 0 1-2 2A16 16 0 0 1 3 6a2 2 0 0 1 2-2z"],
+  inbox: ["M3 13l3-8h12l3 8v6H3z", "M3 13h5l1 3h6l1-3h5"],
+  paperclip: ["M20 11l-8.5 8.5a5 5 0 0 1-7-7L13 4a3.5 3.5 0 0 1 5 5l-8.5 8.5a2 2 0 0 1-3-3L14 7"],
+  mic: [box(9, 2, 6, 12, 3), "M5 11a7 7 0 0 0 14 0", "M12 18v4M8 22h8"],
+  volume: ["M4 9h4l5-4v14l-5-4H4z", "M16 9a4 4 0 0 1 0 6", "M18.5 6.5a7.5 7.5 0 0 1 0 11"],
+  music: ["M9 18V5l12-2v13", dot(6, 18, 3), dot(18, 16, 3)],
+  wifi: ["M2 8.5a15 15 0 0 1 20 0", "M5 12a10 10 0 0 1 14 0", "M8.5 15.5a5 5 0 0 1 7 0", dot(12, 19)],
+  hash: ["M4 9h16M4 15h16", "M10 3L8 21M16 3l-2 18"],
+  at: [dot(12, 12, 4), "M16 8v5a2.5 2.5 0 0 0 5 0v-1a9 9 0 1 0-3.5 7.1"],
+  rss: ["M5 11a8 8 0 0 1 8 8", "M5 5a14 14 0 0 1 14 14", dot(6, 18, 1.2)],
+
+  // files and work
+  file: ["M5 2h9l5 5v15H5z", "M14 2v5h5"],
+  folder: ["M3 5h6l2 3h10v12H3z"],
+  copy: ["M9 9h11v11H9z", "M5 15H4V4h11v1"],
+  book: ["M4 4h6a2 2 0 0 1 2 2v14a2 2 0 0 0-2-2H4z", "M20 4h-6a2 2 0 0 0-2 2v14a2 2 0 0 1 2-2h6z"],
+  briefcase: ["M3 7h18v13H3z", "M9 7V4h6v3", "M3 13h18"],
+  printer: ["M6 9V3h12v6", "M6 17H3V9h18v8h-3", "M6 14h12v7H6z"],
+  code: ["M8 7l-5 5 5 5", "M16 7l5 5-5 5", "M14 4l-4 16"],
+  clock: [dot(12, 12, 9), "M12 7v5l3.5 2"],
+
+  // shopping and places
+  bag: ["M4 7h16l-1 14H5z", "M8.5 10V6a3.5 3.5 0 0 1 7 0v4"],
+  tag: ["M3 3h8l10 10-8 8L3 11z", dot(7.5, 7.5, 1.5)],
+  gift: ["M3 8h18v4H3z", "M5 12v9h14v-9", "M12 8v13", "M12 8C10 4 6.5 4.5 7.5 7c.5 1 2.5 1 4.5 1z", "M12 8c2-4 5.5-3.5 4.5-1-.5 1-2.5 1-4.5 1z"],
+  "credit-card": ["M2 6h20v13H2z", "M2 10h20", "M5 15h4"],
+  dollar: ["M12 2v20", "M17 6H9.5a3.5 3.5 0 0 0 0 7h5a3.5 3.5 0 0 1 0 7H6"],
+  truck: ["M2 5h12v11H2z", "M14 9h4l4 4v3h-8", dot(6, 18, 2), dot(18, 18, 2)],
+  globe: [dot(12, 12, 9), "M3 12h18", "M12 3a4.5 9 0 0 1 0 18a4.5 9 0 0 1 0-18"],
+  map: ["M3 6l6-2 6 2 6-2v14l-6 2-6-2-6 2z", "M9 4v14M15 6v14"],
+
+  // weather
+  sun: [dot(12, 12, 4), "M12 2v2M12 20v2M2 12h2M20 12h2", "M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"],
+  moon: ["M20 14.5A8.5 8.5 0 1 1 9.5 4a7 7 0 0 0 10.5 10.5z"],
+  cloud: ["M7 19a5 5 0 0 1-.5-10A6 6 0 0 1 18 9a5 5 0 0 1 0 10z"],
+
+  // brands: simplified outlines for "sign in with" buttons, share bars and footers. The names and logos are
+  // trademarks of their owners; these are wireframe sketches drawn for Open Ink, not the official artwork.
+  facebook: [dot(12, 12, 9), "M15.5 8H14a2 2 0 0 0-2 2v11", "M9.5 13h5"],
+  x: ["M4 4h4.5L20 20h-4.5z", "M20 4l-6.5 7.5M10.5 13.5L4 20"],
+  instagram: [box(3, 3, 18, 18, 5), dot(12, 12, 4), dot(17, 7, 0.7)],
+  linkedin: [box(3, 3, 18, 18, 2), "M7.5 10.5v6", dot(7.5, 7.5, 0.8), "M11 16.5v-6M11 13a2.5 2.5 0 0 1 5 0v3.5"],
+  youtube: [box(2, 5, 20, 14, 4), "M10 9l5 3-5 3z"],
+  github: [
+    "M8 21v-3.5c-3.5-.5-5-2.5-5-6 0-1.3.4-2.4 1.2-3.3-.3-1.2-.2-2.4.3-3.7 1.4 0 2.6.7 3.7 1.5a10 10 0 0 1 7.6 0c1.1-.8 2.3-1.5 3.7-1.5.5 1.3.6 2.5.3 3.7.8.9 1.2 2 1.2 3.3 0 3.5-1.5 5.5-5 6V21",
+    "M8 18.5c-2.5.5-3.5-1-4.5-2",
+  ],
+  tiktok: ["M14 3v12.5a3.5 3.5 0 1 1-3.5-3.5", "M14 3c.5 2.5 2.5 4.5 5 4.5"],
+  whatsapp: ["M4.6 16.3A8.5 8.5 0 1 1 7.8 19.4L3.5 20.5z", "M9 8.5c0 3.5 3 6.5 6.5 6.5l1-1.5-2-1-1 .8c-1-.5-2-1.5-2.5-2.5l.8-1-1-2z"],
+  telegram: [dot(12, 12, 9), "M6.5 12L17 7.5 15 17l-4.5-3.5z", "M10.5 13.5L14 10.5"],
+  discord: [
+    "M5 17c0-4 1-7.5 3-10.5 1.2-.5 2.5-.8 3-.8l.5 1h1l.5-1c.5 0 1.8.3 3 .8 2 3 3 6.5 3 10.5-1.3 1.2-2.8 1.8-4.2 2.2l-1-2c-1.3.3-3.3.3-4.6 0l-1 2C7.8 18.8 6.3 18.2 5 17z",
+    dot(9.5, 13, 1.2),
+    dot(14.5, 13, 1.2),
+  ],
+  pinterest: [dot(12, 12, 9), "M9 13c-.7-.8-1-1.7-1-2.8a4 4 0 0 1 8 .3c0 2.5-1.5 4.5-3.5 4.5-1 0-1.8-.6-1.6-1.6l.8-3.4", "M11.5 12l-2 9"],
+  reddit: [
+    "M3.5 14a8.5 5.5 0 1 0 17 0a8.5 5.5 0 1 0-17 0",
+    "M12 8.5l1.5-5 4 1",
+    dot(18.5, 4.5, 1.3),
+    dot(9, 13.5, 0.9),
+    dot(15, 13.5, 0.9),
+    "M9 16.5c1.8 1.2 4.2 1.2 6 0",
+  ],
+  snapchat: [
+    "M12 3c3 0 5 2.2 5 5v2.5l2-.5c.5 0 .8.6.3 1l-2.3 1.3c.6 2 2 3.3 4 3.8-.3.8-1.5 1-2.5 1.2l-.5 1.4-2-.2c-1 .3-2 1.5-4 1.5s-3-1.2-4-1.5l-2 .2-.5-1.4c-1-.2-2.2-.4-2.5-1.2 2-.5 3.4-1.8 4-3.8L4.7 11c-.5-.4-.2-1 .3-1l2 .5V8c0-2.8 2-5 5-5z",
+  ],
+  slack: [box(8.5, 2, 3, 9, 1.5), box(13, 8.5, 9, 3, 1.5), box(12.5, 13, 3, 9, 1.5), box(2, 12.5, 9, 3, 1.5)],
+  spotify: [dot(12, 12, 9), "M7 9.5c3.5-1 7.5-.7 10.5 1", "M7.5 12.8c3-.8 6-.5 8.5 1", "M8 15.8c2.5-.6 4.5-.4 6.5.7"],
+  apple: [
+    "M12 7.5c1-.6 2-.9 3-.9 2 0 3.5 1 4.3 2.4-1.7 1-2.6 2.6-2.3 4.6.2 1.5 1 2.6 2.3 3.2-.8 2.3-2.4 4.7-4.3 4.7-1 0-1.8-.6-3-.6s-2 .6-3 .6c-2.3 0-5-4.5-5-8.5 0-3.2 2-5.4 4.5-5.4 1.3 0 2.5.6 3.5.9z",
+    "M12 6.5c0-2 1.3-3.5 3.3-3.8 0 2-1.3 3.6-3.3 3.8z",
+  ],
+  google: ["M20 12h-8", "M20 12a8 8 0 1 1-2.3-5.7"],
+  microsoft: ["M3 3h8.5v8.5H3z", "M12.5 3H21v8.5h-8.5z", "M3 12.5h8.5V21H3z", "M12.5 12.5H21V21h-8.5z"],
+  dribbble: [dot(12, 12, 9), "M3.2 10.5c6 .5 11.5-1.5 14-5.5", "M8.5 3.7c3.5 4 6 10 7 16.5", "M5.5 18.5c2.5-4 7-6 15.3-4.2"],
+  twitch: ["M4 6l1.5-3H20v11l-4 4h-4l-3 3v-3H4z", "M11 7v4M15 7v4"],
 };
 
 export const ICON_NAMES = Object.keys(ICONS);

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.

package/src/spec/docs.js

@@ -45,6 +45,8 @@ export function blocksMarkdown() {
     "",
     ICON_NAMES.map((n) => `\`${n}\``).join(" · "),
     "",
+    "Brand names and logos are trademarks of their owners. Open Ink's brand icons are simplified sketches for wireframes only and do not imply endorsement. Use each brand's official assets in production.",
+    "",
   ];
   for (const g of groups) {
     out.push(`## ${g}`, "");