openink 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0]
+
+First release.
+
+- `openink` CLI: `init`, `build`, `dev` (live reload), `validate`, `pdf`, `png`, `blocks`; `--theme` to try a theme.
+- YAML spec with 48 block types across layout, text, content, media, forms, actions, navigation, feedback, overlays and data.
+- New blocks beyond the basics: `icon` (37 hand-drawn icons, also on buttons, nav and tab-bar items), `avatar`, `hero`, `stat`,
+  `rating`, `link`, `video`, `carousel`, `dropzone`, `chart` (line, area, bar, pie, donut), `search`, `alert`, `progress`,
+  `breadcrumb`, `pagination`, `steps`, `tabbar`, `accordion`, `device` (phone / tablet / browser frames), `modal`.
+- Colour: themes (`sketch`, `color`, `pastel`, `blueprint`, `dark`), `colors:` token overrides, and `tone:` / `fill:` on any block or screen.
+- Global `modals:` list, opened from any screen with `open:` and closed with `close:`, the X, Escape or a click outside.
+- Hand-drawn look from wired-elements and RoughJS; image, map and generic placeholders.
+- Optional multi-language prototypes (`languages:` + `{ en, de }` text values).
+- Named header nav sets per screen, sticky-note annotations, custom theme CSS, assets folder, screen widths, YAML anchors via `x-*` keys.
+- Spec validation with paths, "did you mean" hints and dead-link detection.
+- JSON Schema (`openink/schema.json`) for editor autocomplete, generated from the block registry.
+- PDF export (one screen per page) and per-screen PNG export.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Open Ink contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+<h1 align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-white.svg">
+    <img src="assets/logo-black.svg" alt="Open Ink" width="340">
+  </picture>
+</h1>
+
+<p align="center"><strong>Describe screens in YAML. Get a clickable, hand-drawn wireframe prototype.</strong></p>
+
+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>
+  <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" />
+  <img src="docs/img/saas-overview.png" width="32%" alt="SaaS dashboard in the colour theme with stats and charts" />
+</p>
+
+```yaml
+name: Shop
+theme: color                                   # optional: sketch (default) | color | pastel | blueprint | dark
+nav:
+  - { icon: home, label: Home, go: home }
+screens:
+  - id: home
+    title: Home
+    blocks:
+      - { type: h1, text: Welcome }
+      - type: card
+        go: product                            # click → opens the product screen
+        children:
+          - { type: image, h: 120, label: Photo }
+          - { type: h3, text: Blue shirt }
+          - { type: rating, value: 4, text: (128 reviews) }
+  - id: product
+    title: Product
+    blocks:
+      - { type: button, label: Add to cart, icon: cart, primary: true, open: added }
+modals:
+  - id: added
+    title: Added to cart
+    children:
+      - { type: button, label: Keep shopping, close: true, go: home }
+```
+
+## Why
+
+- **Fast to write and change.** A screen is a dozen lines of YAML, not a page of HTML or an hour in a design tool.
+- **Clickable.** Buttons, cards, table rows, tab bars and nav items link between screens; forms, tabs, accordions, modals, chips and toggles respond, so stakeholders can walk through a flow.
+- **Looks like a sketch on purpose.** Feedback goes to structure and flow, not fonts and pixels.
+- **Colour when you want it.** Themes for a whole project, `tone: pink` for one card, `fill: true` for a tinted panel.
+- **Safe for AI to write.** Generate a spec with an assistant; `validate` catches typos, dead links and bad icon names with exact locations. See [docs/ai-assistants.md](docs/ai-assistants.md).
+- **Easy to share.** One static folder, one PDF, or one PNG per screen. Multi-language prototypes are built in.
+
+## Quick start
+
+```bash
+npx openink init my-wireframes
+cd my-wireframes
+npx openink dev                 # live preview at http://localhost:3000
+```
+
+```bash
+npx openink validate            # check the spec
+npx openink build               # static site → dist/
+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
+```
+
+Or install it once and drop the `npx`:
+
+```bash
+npm install -g openink
+openink dev
+```
+
+Requires Node 20+. PDF and PNG export need Chrome, Chromium or Edge installed (set `CHROME_PATH` if it isn't found).
+
+## 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.
+
+| | |
+|---|---|
+| **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` |
+| **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` |
+| **Navigation** | `breadcrumb` `pagination` `steps` `tabbar` |
+| **Feedback** | `alert` `progress` |
+| **Overlays** | `modal` (global, opened from any screen) |
+| **Data** | `table` |
+
+<p>
+  <img src="docs/img/gallery-media.png" width="49%" alt="Media blocks and hand-drawn charts" />
+  <img src="docs/img/gallery-colours.png" width="49%" alt="Nine tones on cards" />
+</p>
+
+## Colour
+
+Plain pencil is the default. Colour is opt-in, at three levels:
+
+| Level | How |
+|---|---|
+| Whole project | `theme: color \| pastel \| blueprint \| dark` and `colors: { accent: "#f97316" }` |
+| One screen | `tone: blue` on the screen |
+| One part | `tone: red` and `fill: true` on any block, e.g. only the "Delete" button, or a highlighted card |
+
+<table>
+  <tr>
+    <td><img src="docs/img/theme-sketch.png" alt="sketch theme" /><br /><sub><code>sketch</code> (default)</sub></td>
+    <td><img src="docs/img/theme-color.png" alt="color theme" /><br /><sub><code>color</code></sub></td>
+    <td><img src="docs/img/theme-pastel.png" alt="pastel theme" /><br /><sub><code>pastel</code></sub></td>
+  </tr>
+  <tr>
+    <td><img src="docs/img/theme-blueprint.png" alt="blueprint theme" /><br /><sub><code>blueprint</code></sub></td>
+    <td><img src="docs/img/theme-dark.png" alt="dark theme" /><br /><sub><code>dark</code></sub></td>
+    <td></td>
+  </tr>
+</table>
+
+Details: [docs/spec.md#colour](docs/spec.md#colour).
+
+## Examples
+
+| Example | Shows |
+|---|---|
+| [`photo-sharing`](examples/photo-sharing) | 17 screens: feed, stories, reels, explore, messages, profile, a phone-frame mobile view, global modals, and colour on only a few parts |
+| [`saas-admin`](examples/saas-admin) | The `color` theme: stat cards, area/bar/donut charts, tables, an invite modal |
+| [`rental-portal`](examples/rental-portal) | Two languages and two header nav sets (public vs owner) |
+| [`gallery`](examples/gallery) | Every block on one screen per family; try it with `--theme dark` |
+
+```bash
+npx openink dev examples/photo-sharing
+```
+
+## Documentation
+
+- [Getting started](docs/getting-started.md)
+- [Spec reference](docs/spec.md): screens, colour, modals, navigation, languages, icons
+- [Block reference](docs/blocks.md)
+- [Working with AI assistants](docs/ai-assistants.md)
+- [Extending](docs/extending.md): add a block, change the look, use the API
+- [Architecture](docs/architecture.md)
+
+## Use it from code
+
+```js
+import { build, validate, exportFiles } from "openink";
+
+await build({ dir: "./my-project", out: "dist", theme: "dark" });
+await exportFiles({ dir: "./my-project", png: true });
+```
+
+## Contributing
+
+Issues and pull requests are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Adding a block is one object in `src/render/blocks/`.
+
+## License
+
+[MIT](LICENSE)

package/bin/openink.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+main();

package/docs/ai-assistants.md

@@ -0,0 +1,35 @@
+# Working with AI assistants
+
+Open Ink is designed so that an assistant (Claude Code, Cursor, Copilot, ChatGPT…) can turn a description into a prototype **without writing HTML**:
+
+> "Wireframe a marketplace for used bikes: search with filters, listing page with a contact form, seller dashboard."
+
+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.
+
+## How it works
+
+`openink init` puts an `AGENTS.md` in your project. Most assistants read it automatically; it tells them to:
+
+1. Run `npx openink blocks` to learn the available blocks.
+2. Edit `spec.yaml` only.
+3. Run `npx openink validate` and fix what it reports.
+4. Run `npx openink png` and look at `dist/png/*.png` to check the layout.
+
+If your assistant uses a different filename (`CLAUDE.md`, `.cursorrules`, …), copy or rename `AGENTS.md`.
+
+## Why validation matters here
+
+Assistants make small mistakes: a misspelt prop, a link to a screen they renamed, a translation missing in one language. `validate` reports each with its exact location in the spec and a "did you mean" hint, so the fix-and-retry loop is short and mechanical:
+
+```
+✗ 2 problems in the spec
+  error screens[1].blocks[3].type: Unknown block type "buton". Did you mean "button"?
+  error screens[0].blocks[0].go: Links to unknown screen "checkout". Did you mean "check-out"?
+```
+
+## Tips for good prompts
+
+- Name the **users** and their **goals**, not the widgets: "a tenant who wants to find a flat in Zurich".
+- Say which **states** matter (empty, error, paid, unpaid); each becomes a screen or a `note:`.
+- Ask for `note:` on anything a sketch can't show ("results update live, there is no search button").
+- Mention languages up front if you need them.

package/docs/architecture.md

@@ -0,0 +1,50 @@
+# Architecture
+
+```
+spec.yaml ──► load + parse ──► validate ──► render ──► write dist/
+                (yaml)        (spec/validate)  (render/)     │
+                                                              ├─ index.html        (render/page.js)
+                                                              ├─ openink.js    (runtime/ bundled by esbuild)
+                                                              └─ openink.css  (styles/)
+
+dist/ ──► puppeteer-core + Chrome/Edge ──► PDF / PNG          (export.js)
+dist/ ──► http server + fs.watch + reload poller              (dev.js)
+```
+
+## Design decisions
+
+**Spec in, static files out.** The prototype is a single HTML page holding every screen; JavaScript only shows one at a time. That makes the output trivially hostable, printable and shareable by link (`#screen-id`), and it works from `file://`.
+
+**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.
+
+**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).
+
+**No framework in the output.** The runtime is about a hundred lines of plain JavaScript plus the web components from wired-elements.
+
+## Layout
+
+```
+bin/openink.js      CLI entry
+src/
+  cli.js                argument parsing, commands, output formatting
+  build.js              load spec → validate → write dist
+  dev.js                dev server with live reload
+  export.js             PDF / PNG via headless Chrome
+  index.js              public API
+  spec/                 validate.js, schema.js, docs.js
+  render/               context.js, page.js, blocks/*
+  runtime/              browser code (navigation, i18n, placeholder, redraw)
+  styles/               openink.css
+templates/starter/      copied by `openink init`
+examples/               example projects (also test fixtures and README screenshots)
+test/                   node:test suites
+scripts/                generate.js (docs + schema), screenshots.js
+```
+
+## Known limitations
+
+- wired-elements 3.0 is a release candidate and has not been updated for some time. Its dependency on `roughjs` is pinned to 4.3.1 for that reason (see CONTRIBUTING.md).
+- Form controls are visual only; nothing is validated or submitted.
+- One page per project: very large specs (hundreds of screens) load everything up front.