htmlboard 0.1.0 → 0.3.0

package/README.md

@@ -1,9 +1,14 @@
-# ✦ HtmlBoard
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/luizcarlos1405/htmlboard/main/brand/logo-dark.svg">
+    <img alt="htmlboard" src="https://raw.githubusercontent.com/luizcarlos1405/htmlboard/main/brand/logo-light.svg" height="56">
+  </picture>
+</h1>
 
 > **Infinite canvas and design explorer for HTML artboards — designed for humans and LLMs.**
 
-[![npm version](https://img.shields.io/npm/v/htmlboard.svg?style=flat-square&color=6366f1)](https://www.npmjs.com/package/htmlboard)
-[![license](https://img.shields.io/npm/l/htmlboard.svg?style=flat-square&color=10b981)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/htmlboard.svg?style=flat-square&color=3D9DFF)](https://www.npmjs.com/package/htmlboard)
+[![license](https://img.shields.io/npm/l/htmlboard.svg?style=flat-square&color=48484D)](LICENSE)
 [![node version](https://img.shields.io/node/v/htmlboard.svg?style=flat-square)](https://nodejs.org)
 [![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg?style=flat-square)](package.json)
 
@@ -24,15 +29,16 @@ Modern AI agents and developers generate dozens of HTML mockups, layout variatio
 
 ## ✨ Features
 
-- 🛸 **Infinite Canvas**: Smoothly pan, zoom (from 5% to 300%), and fly across dozens of artboards with trackpad or mouse.
-- ⚡ **Zero Dependencies**: Pure native Node.js ES modules. Runs instantly with `npx htmlboard` without installing heavy packages.
-- 🔄 **State-Preserving Live Reload**: Automatically watches files via Server-Sent Events (SSE). When you or an LLM edit an HTML file, the corresponding artboard updates instantly without resetting your canvas pan/zoom position; editing a shared CSS, script or image reloads them all.
-- 🔍 **Auto-Discovery**: Point HtmlBoard at any folder. It automatically discovers all HTML files, extracts their titles, classifies them by device type, and renders them onto the canvas.
-- 📐 **Declarative Manifest (`designs.json`)**: Optional structured schema to organize artboards into sections, define custom viewports (iPhone, iPad, MacBook, 4K), and attach metadata.
-- 📱 **Multi-Device Categories**: One-click filters for Mobile (390×844), Desktop (1280×820), Tablet (768×1024), and Component kits.
-- 🎯 **Focus & Zoom-to-Fit**: Instantly center any artboard with a click in the sidebar, or hit <kbd>F</kbd> to fit all designs on screen.
-- 🔗 **Deep Links**: The URL follows the focused artboard (`http://localhost:3000/#checkout-b`), so you can share or reload a view of one design.
-- ⌨️ **Keyboard-First Workflow**: Full suite of intuitive shortcuts matching design industry standards.
+- 🛸 **Infinite Canvas**: Drag or scroll to move, <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + scroll or pinch to zoom (2% to 800%), with a mouse, a trackpad or a touch screen. Names and section titles stay sharp at any zoom, and the dot grid keeps its spacing.
+- ⚡ **Zero Dependencies**: Pure native Node.js ES modules, fonts included. Runs instantly with `npx htmlboard`, offline too.
+- 🔄 **State-Preserving Live Reload**: The server watches the project and pushes every save (Server-Sent Events). Saving a design reloads its frame; saving a file designs use (a stylesheet, a script, an image, data) reloads just the designs that loaded it; new, removed and renamed designs show up by themselves. Your view never moves.
+- 📂 **Designs That Describe Themselves**: Every HTML file is a design, each folder a section, number prefixes the order. A file says its own size, category and variants in a `<meta>` tag or two, so adding a design means writing one file — nothing to keep in sync.
+- 📐 **Optional `designs.json`**: Curates when you want it (section titles, order, overrides); designs it doesn't list still show at the end, or don't (`"unlisted": "hide"`). `htmlboard migrate` moves an existing one into the files.
+- 📱 **Device Filters**: **Mobile**, **Tablet** and **Desktop** (and **Components**, or your own categories) lay out just those designs, side by side, to compare them.
+- 🔎 **Search**: Find designs by name, file, tags or section (case and accents don't matter); the others fade out in place.
+- 🎯 **Focus & Zoom-to-Fit**: Click a design in the list or double-click it on the canvas to fit it, <kbd>Shift</kbd> + <kbd>1</kbd> fits everything, <kbd>←</kbd> <kbd>→</kbd> step through the designs.
+- 🔗 **Deep Links**: The URL follows the selected design (`http://localhost:3000/#checkout-b`), so you can share or reload a view of one design.
+- ⌨️ **Keyboard-First Workflow**: Figma-like shortcuts; <kbd>?</kbd> lists them.
 
 ---
 
@@ -53,7 +59,7 @@ htmlboard
 
 ### Scaffold a Starter Project
 
-To create a new workspace with starter templates (mobile screen, desktop dashboard, and component library):
+To start with sample designs (a folder of screens and a folder of components, each file describing itself):
 
 ```bash
 npx htmlboard --init
@@ -68,6 +74,7 @@ Usage:
   htmlboard [directory] [options]
   npx htmlboard [directory] [options]
   htmlboard skills <install|uninstall> [options]   Teach your AI agent to use HtmlBoard
+  htmlboard migrate [directory] [--write]          Move designs.json's sizes, titles and variants into the files
 
 Options:
   -p, --port <number>   Port to listen on (default: 3000)
@@ -75,7 +82,7 @@ Options:
   -r, --root <path>     Serve files from this parent folder, so artboards can link to
                         shared files outside the designs folder (default: the designs folder)
   -o, --open            Open the explorer automatically in default browser
-      --init            Scaffold starter designs.json and sample artboards
+      --init            Add sample designs (two folders of artboards)
   -v, --version         Display HtmlBoard version
   -h, --help            Display help message
 ```
@@ -95,8 +102,12 @@ htmlboard ./src/designs -p 8080
 # Artboards in ./design that link to the site's own ../css and ../js
 htmlboard design --root .
 
-# Initialize sample templates in a new folder
+# Start a new folder with sample designs
 htmlboard ./my-new-ui --init --open
+
+# See what moving ./design/designs.json into its files would do, then do it
+htmlboard migrate design
+htmlboard migrate design --write
 ```
 
 ---
@@ -107,7 +118,7 @@ HtmlBoard is built from the ground up to pair with AI coding agents (Claude, Gem
 
 ### Install the agent skill
 
-HtmlBoard ships an [Agent Skill](https://agentskills.io) that teaches your agent how to use it: where to put artboards, how to size and name them, how `designs.json` works and how to start the canvas. Install it in your project:
+HtmlBoard ships an [Agent Skill](https://agentskills.io) that teaches your agent how to use it: where to put artboards, how to size, name and group them (files describe themselves; `designs.json` is optional) and how to start the canvas. Install it in your project:
 
 ```bash
 npx htmlboard skills install
@@ -127,7 +138,9 @@ Running `install` again after upgrading HtmlBoard updates the skill; a copy you
 ### The workflow
 
 1. **Ask your LLM to generate artboards:**
-   > *"Create 3 design explorations for our checkout flow in `artboards/checkout-v1.html`, `artboards/checkout-v2.html`, and `artboards/checkout-v3.html`."*
+   > *"Create 3 design explorations for our checkout flow in `designs/03-checkout/`."*
+
+   With the skill, the agent writes `01-one-page.html`, `02-steps.html`, `03-express.html`, each with its size in a `<meta>` tag. They show up as a new "checkout" row, in that order.
 
 2. **Run HtmlBoard in the background:**
    ```bash
@@ -139,94 +152,92 @@ Running `install` again after upgrading HtmlBoard updates the skill; a copy you
 
 ---
 
-## 📋 The `designs.json` Manifest
+## 📂 How Designs Are Found
 
-While HtmlBoard automatically discovers HTML files, you can add a `designs.json` file in your designs folder for custom layout and organization. Only `sections[].designs[].file` is required; the short form is enough:
+Every `.html` file under the folder is a design (hidden folders, `node_modules`, `dist` and `build` aside):
 
-```json
-{
-  "sections": [
-    {
-      "title": "Home",
-      "designs": [
-        { "file": "home-mobile.html", "title": "Home · phone", "width": 390, "height": 844 },
-        { "file": "home-mobile.html?theme=dark", "title": "Home · phone · dark", "width": 390, "height": 844 },
-        { "file": "home-desktop.html", "title": "Home · desktop", "width": 1440 }
-      ]
-    }
-  ]
-}
+- **Sections are folders.** Each folder is a row on the canvas, named after the folder; the files at the top of the folder make a first row without a title.
+- **Number prefixes set the order** of files and folders: `01-…`, `02-…`, `10-…` (up to three digits; `2` comes before `10`). They don't show in names or in links, so reordering breaks nothing.
+- **A file describes itself** in its `<head>`:
+
+```html
+<title>Checkout</title>                                         <!-- its name -->
+<meta name="description" content="One page, address first">    <!-- its description -->
+<meta name="htmlboard" content="width=390, height=844">         <!-- its size (and category=…) -->
+<meta name="htmlboard:label" content="light">                   <!-- added to its name: "Checkout · light" -->
+<meta name="htmlboard:variant" content="?theme=dark · dark">    <!-- one more frame: "Checkout · dark" -->
 ```
 
-Sections are rows (top to bottom) and designs run left to right. A `file` may carry a query string, so one HTML file can show several states. Leave `height` out to let the frame grow with its page. `id` and `category` are derived from the file when left out.
+| Tag | What it says |
+| :--- | :--- |
+| `<title>` | The design's name (without one: the file's name, prefix and extension off). |
+| `<meta name="description">` | Its description, shown in the list and found by the search. |
+| `<meta name="htmlboard" content="…">` | `width=…`, `height=…`, `category=…` (`mobile`, `tablet`, `desktop`, `components` or your own word), or `skip` to leave the file out (partials, templates). |
+| `<meta name="htmlboard:label">` | Text added to the name of the file's own frame, when it has variants. |
+| `<meta name="htmlboard:variant">` | One more frame of the same file with that query string, then its label. As many as you like; they follow the file. |
+
+**Sizes.** The width is the frame's viewport: the page's CSS needs it before it renders. Give the height for designs of a fixed size (a phone screen, a flyer: the frame is that tall and cuts the rest); leave it out and the frame grows with the page. Without a size, words in the path decide (`mobile` → 390 × 844, `tablet` → 768 × 1024, `desktop` → 1280 × 800, `component` → 720 × 600), else 1200 wide.
+
+**Categories** drive the filters. Left out, they come from words in the path, then from the size when it is a screen's (a phone's width, a tablet's 3:4, a desktop's landscape); flyers, boards and other formats get none and show under **All**.
+
+---
 
-The full form adds ids, descriptions, categories (for the toolbar filters) and searchable tags (`name`/`artboards` are synonyms of `title`/`designs`):
+## 📋 `designs.json` (Optional)
+
+A `designs.json` in the folder curates the canvas when folders aren't enough: section titles with accents and capitals, an order across folders, a name or size the file doesn't give. The files still say the rest:
 
 ```json
 {
-  "title": "Fintech Mobile & Web App",
-  "description": "Exploration of screen flows, responsive layouts, and UI components",
+  "title": "Wallet app",
   "sections": [
+    { "title": "Onboarding", "designs": ["01-onboarding/01-welcome.html", "01-onboarding/02-sign-up.html"] },
+    { "title": "Checkout · round 2", "folder": "03-checkout" },
     {
-      "id": "screens",
-      "name": "Screen Layouts",
-      "description": "Full page layouts across mobile and desktop viewports",
-      "artboards": [
-        {
-          "id": "desktop-dashboard",
-          "title": "Desktop Dashboard",
-          "file": "artboards/desktop.html",
-          "width": 1280,
-          "height": 820,
-          "category": "desktop",
-          "tags": ["desktop", "dashboard", "analytics"]
-        },
-        {
-          "id": "mobile-app",
-          "title": "Mobile App Feed",
-          "file": "artboards/mobile.html",
-          "width": 390,
-          "height": 844,
-          "category": "mobile",
-          "tags": ["mobile", "ios", "finance"]
-        }
-      ]
-    },
-    {
-      "id": "components",
-      "name": "Component Library",
-      "artboards": [
-        {
-          "id": "ui-primitives",
-          "title": "UI Kit Elements",
-          "file": "artboards/components.html",
-          "width": 780,
-          "height": 720,
-          "category": "components",
-          "tags": ["design-system", "buttons", "inputs"]
-        }
-      ]
+      "title": "Print",
+      "description": "Flyers for the launch",
+      "designs": [{ "file": "flyer.html", "title": "Launch flyer", "height": 1350 }]
     }
   ]
 }
 ```
 
+- Sections come in their order, designs in theirs. An entry is a file name, or `{ "file", … }` with values that win over the file's (`title`, `description`, `width`, `height`, `category`, `tags`, `id`). A `file` may carry a query string to place a variant itself.
+- A file's variants follow it unless designs.json lists them. `"folder"` brings a whole folder (in prefix order).
+- **Designs it doesn't list still show**, after the ones it does: in the section that holds their folder, else in their folder's own section (the files at the top in "Unlisted"). `"unlisted": "hide"` shows only what it lists.
+- `name` and `artboards` are synonyms of `title` and `designs`.
+
+### Moving an existing `designs.json` into the files
+
+```bash
+npx htmlboard migrate design          # shows what it would do, and checks the canvas stays the same
+npx htmlboard migrate design --write  # does it
+```
+
+It writes each file's size, category, label, variants and description as tags after its `<title>`, and leaves designs.json with the sections, their titles and order, and the values the files can't say (a name that isn't the file's `<title>` plus a label, say).
+
 ---
 
 ## ⌨️ Keyboard Shortcuts
 
 | Shortcut | Action |
 | :--- | :--- |
-| <kbd>Space</kbd> + <kbd>Drag</kbd> | Pan the canvas freely |
-| <kbd>Ctrl</kbd> / <kbd>⌘</kbd> + <kbd>Wheel</kbd> | Zoom in/out anchored to cursor |
-| <kbd>+</kbd> / <kbd>-</kbd> | Zoom in / Zoom out |
-| <kbd>0</kbd> | Reset zoom to 100% |
-| <kbd>F</kbd> or <kbd>Shift</kbd> + <kbd>1</kbd> | Fit all artboards in viewport |
-| <kbd>/</kbd> or <kbd>⌘</kbd> + <kbd>K</kbd> | Search artboards by title, tag, or path |
-| <kbd>[</kbd> or <kbd>]</kbd> | Toggle navigation sidebar |
-| <kbd>1</kbd> – <kbd>5</kbd> | Quick filter by device category |
-| <kbd>?</kbd> | Show keyboard shortcuts modal |
-| <kbd>Esc</kbd> | Close modals or blur search |
+| Drag, <kbd>Space</kbd> + drag | Move around |
+| Scroll (<kbd>Shift</kbd>: sideways) | Move around |
+| <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + scroll, pinch | Zoom, anchored to the pointer |
+| <kbd>+</kbd> / <kbd>−</kbd> | Zoom in / out |
+| <kbd>Shift</kbd> + <kbd>0</kbd> | Zoom to 100% |
+| <kbd>Shift</kbd> + <kbd>1</kbd> | Fit everything (what the search keeps) |
+| <kbd>Shift</kbd> + <kbd>2</kbd>, double-click | Fit the design |
+| <kbd>←</kbd> / <kbd>→</kbd> | Previous / next design |
+| <kbd>Enter</kbd> | Open the selected design on its own |
+| <kbd>/</kbd> | Search (<kbd>Enter</kbd> fits the first match, <kbd>Esc</kbd> clears) |
+| <kbd>1</kbd> – <kbd>4</kbd> | Show all, mobile, tablet, desktop (<kbd>5</kbd> on: the other categories) |
+| <kbd>R</kbd> | Reload the designs |
+| <kbd>\</kbd> | Show or hide the list |
+| <kbd>?</kbd> | Show the shortcuts |
+| <kbd>Esc</kbd> | Deselect, then clear the search, then the filter |
+
+On the canvas the designs are pictures: the canvas takes every click and scroll, so <kbd>Ctrl</kbd> + scroll never zooms the page itself. Use **Open** (or <kbd>Enter</kbd>) to try a design's links and hover states on its own.
 
 ---
 
@@ -248,6 +259,15 @@ console.log(`HtmlBoard running at ${instance.url}`);
 // await instance.close();
 ```
 
+The list of designs is there too, as the explorer gets it:
+
+```javascript
+import { loadDesignsManifest } from 'htmlboard';
+
+const { sections } = loadDesignsManifest('./designs');
+// → [{ id: 'screens', name: 'screens', artboards: [{ id, title, file, width, height, category }, …] }, …]
+```
+
 The skill installer is exported too:
 
 ```javascript
@@ -267,17 +287,23 @@ htmlboard/
 │   └── htmlboard.js      # CLI executable
 ├── src/
 │   ├── index.js          # Library entry point & API exports
-│   ├── server.js         # HTTP server, SSE live reload, auto-discovery
+│   ├── server.js         # HTTP server, SSE live reload
+│   ├── designs.js        # Which designs a folder holds: files, their tags, designs.json
+│   ├── migrate.js        # `htmlboard migrate`
 │   ├── skills.js         # `htmlboard skills` installer
-│   ├── client/           # The infinite canvas frontend
-│   │   ├── index.html    # Explorer shell & canvas DOM
-│   │   ├── explorer.css  # Dark theme styles & canvas grid
-│   │   └── explorer.js   # Pan/zoom engine, SSE listener, auto-measure
-│   └── templates/        # Starter scaffold templates
-│       ├── designs.json  # Starter manifest
-│       └── artboards/    # Sample mobile, desktop, & component screens
+│   ├── client/           # The canvas
+│   │   ├── index.html    # Explorer shell: list, canvas, toolbar, shortcuts
+│   │   ├── explorer.css  # Dark chrome, dot grid
+│   │   ├── explorer.js   # Layout, pan/zoom, search, live reload
+│   │   ├── favicon.svg, logo.svg, mark.svg
+│   │   └── fonts/        # Inter and Bricolage Grotesque (OFL)
+│   └── templates/        # The sample designs `--init` adds
+│       ├── 01-screens/   # Desktop dashboard, mobile feed
+│       └── 02-components/
 ├── skills/
 │   └── htmlboard/        # Agent skill (SKILL.md) copied by `htmlboard skills install`
+├── brand/                # The logo's files (from design/tools/logo.py)
+├── design/               # htmlboard's own designs, on its own canvas: `npx htmlboard design --root .`
 ├── package.json
 ├── README.md
 └── LICENSE
@@ -288,3 +314,5 @@ htmlboard/
 ## 📄 License
 
 MIT © Luiz Carlos & Contributors
+
+The explorer ships the Inter and Bricolage Grotesque fonts under the SIL Open Font License 1.1 (see `src/client/fonts/`).

package/bin/htmlboard.js

@@ -6,6 +6,7 @@ import { exec } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { startServer } from '../src/server.js';
 import { installSkills, uninstallSkills } from '../src/skills.js';
+import { planMigration, checkMigration, applyMigration } from '../src/migrate.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -67,13 +68,14 @@ function parseArgs(args) {
 
 function showHelp() {
   console.log(`
-HtmlBoard v${pkg.version}
+htmlboard v${pkg.version}
 Infinite canvas and design explorer for HTML artboards — designed for humans and LLMs
 
 Usage:
   htmlboard [directory] [options]
   npx htmlboard [directory] [options]
   htmlboard skills <install|uninstall> [options]   Teach your AI agent to use HtmlBoard
+  htmlboard migrate [directory] [--write]          Move designs.json's sizes, titles and variants into the files
 
 Options:
   -p, --port <number>   Port to listen on (default: 3000)
@@ -81,8 +83,8 @@ Options:
   -r, --root <path>     Serve files from this parent folder, so artboards can link to
                         shared files outside the designs folder (default: the designs folder)
   -o, --open            Open the explorer automatically in your default browser
-      --init            Scaffold starter designs.json and sample artboards in target directory
-  -v, --version         Display HtmlBoard version
+      --init            Add sample designs (two folders of artboards) to the directory
+  -v, --version         Display the version
   -h, --help            Display this help message
 
 Examples:
@@ -90,18 +92,16 @@ Examples:
   htmlboard --open              # Run and launch browser automatically
   htmlboard ./designs -p 8080   # Serve ./designs on port 8080
   htmlboard design --root .     # Artboards in ./design that link to ../css/…
-  htmlboard --init              # Initialize starter templates in current folder
+  htmlboard --init              # Add sample designs to the current folder
   htmlboard skills install      # Add the HtmlBoard skill to this project's agents
 
-Keyboard Shortcuts in Canvas:
-  Space + Drag          Pan canvas
-  Ctrl/Cmd + Wheel      Zoom into focal point
-  + / -                 Zoom in / Zoom out
-  0                     Reset zoom to 100%
-  F                     Zoom to fit all artboards
-  / or Cmd+K            Search artboards
-  [ or ]                Toggle navigation sidebar
-  ?                     Show shortcuts help dialog
+On the canvas:
+  Drag, scroll          Move around
+  Ctrl/Cmd + scroll     Zoom (or pinch)
+  Double-click          Fit a design (Shift + 1 fits everything)
+  /                     Search
+  1 – 4                 Show all, mobile, tablet, desktop
+  ?                     All the shortcuts
 `);
 }
 
@@ -121,42 +121,25 @@ function openBrowser(url) {
 
 function scaffoldProject(targetDir) {
   const templatesDir = path.join(__dirname, '..', 'src', 'templates');
-  const targetConfig = path.join(targetDir, 'designs.json');
-  const targetArtboardsDir = path.join(targetDir, 'artboards');
-
-  console.log(`[htmlboard] Scaffolding starter project in ${targetDir}...`);
-
-  if (!fs.existsSync(targetDir)) {
-    fs.mkdirSync(targetDir, { recursive: true });
-  }
-
-  if (!fs.existsSync(targetArtboardsDir)) {
-    fs.mkdirSync(targetArtboardsDir, { recursive: true });
-  }
-
-  // Copy designs.json if not present
-  if (!fs.existsSync(targetConfig)) {
-    const srcConfig = path.join(templatesDir, 'designs.json');
-    if (fs.existsSync(srcConfig)) {
-      fs.copyFileSync(srcConfig, targetConfig);
-      console.log(`  ✓ Created designs.json`);
-    }
-  } else {
-    console.log(`  ℹ designs.json already exists (skipped)`);
-  }
-
-  // Copy starter artboards
-  const starterFiles = ['mobile.html', 'desktop.html', 'components.html'];
-  for (const file of starterFiles) {
-    const srcFile = path.join(templatesDir, 'artboards', file);
-    const destFile = path.join(targetArtboardsDir, file);
-    if (!fs.existsSync(destFile) && fs.existsSync(srcFile)) {
-      fs.copyFileSync(srcFile, destFile);
-      console.log(`  ✓ Created artboards/${file}`);
+  console.log(`[htmlboard] Adding sample designs to ${targetDir}...`);
+  // Folders are sections and number prefixes the order; each file says its own size
+  const copy = (from, rel) => {
+    for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+      const relPath = path.join(rel, entry.name);
+      const dest = path.join(targetDir, relPath);
+      if (entry.isDirectory()) {
+        fs.mkdirSync(dest, { recursive: true });
+        copy(path.join(from, entry.name), relPath);
+      } else if (fs.existsSync(dest)) {
+        console.log(`  ℹ ${relPath} already exists (skipped)`);
+      } else {
+        fs.copyFileSync(path.join(from, entry.name), dest);
+        console.log(`  ✓ Created ${relPath}`);
+      }
     }
-  }
-
-  console.log(`\n🎉 Starter templates created successfully!`);
+  };
+  fs.mkdirSync(targetDir, { recursive: true });
+  copy(templatesDir, '');
 }
 
 function showSkillsHelp() {
@@ -223,6 +206,58 @@ function runSkills(args) {
   }
 }
 
+function runMigrate(args) {
+  const write = args.includes('--write');
+  const dirArg = args.find((arg) => !arg.startsWith('-'));
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+Usage:
+  htmlboard migrate [directory] [--write]
+
+Moves what designs.json says about each design into the design's own file (its size, category,
+label, variants and description, as <meta> tags after its <title>) and leaves designs.json with
+the sections, their titles and order, and the values that differ from the files'.
+
+Without --write it only shows what it would do, and checks that the canvas stays the same.
+`);
+    return;
+  }
+  const dir = path.resolve(dirArg || process.cwd());
+  let plan;
+  try {
+    plan = planMigration(dir);
+  } catch (err) {
+    console.error(`[htmlboard] Can't read ${path.join(dir, 'designs.json')}: ${err.message}`);
+    process.exit(1);
+  }
+  const differences = checkMigration(dir, plan);
+  const [before, after] = plan.entries;
+
+  console.log(`\n  \x1b[1m${path.relative(process.cwd(), dir) || '.'}\x1b[0m`);
+  if (!plan.files.length) console.log('  \x1b[90mNo file to change.\x1b[0m');
+  for (const { file, lines } of plan.files) {
+    console.log(`\n  ${file}`);
+    for (const line of lines) console.log(`    \x1b[32m+\x1b[0m ${line}`);
+  }
+  console.log(`\n  designs.json: ${before} entries → ${after}`);
+  if (differences.length) {
+    console.log(`\n  \x1b[33mThe canvas would change:\x1b[0m`);
+    for (const { before: was, after: will } of differences.slice(0, 20)) {
+      if (was) console.log(`    \x1b[31m-\x1b[0m ${was}`);
+      if (will) console.log(`    \x1b[32m+\x1b[0m ${will}`);
+    }
+  } else {
+    console.log(`  \x1b[32m✓\x1b[0m The canvas stays the same.`);
+  }
+
+  if (!write) {
+    console.log(`\n  Nothing written. Run again with --write to apply.\n`);
+    return;
+  }
+  applyMigration(dir, plan);
+  console.log(`\n  \x1b[32m✓ Written:\x1b[0m ${plan.files.length} file${plan.files.length === 1 ? '' : 's'} and designs.json.\n`);
+}
+
 async function main() {
   const args = process.argv.slice(2);
 
@@ -231,6 +266,11 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'migrate') {
+    runMigrate(args.slice(1));
+    return;
+  }
+
   const options = parseArgs(args);
 
   if (options.help) {
@@ -249,21 +289,15 @@ async function main() {
     scaffoldProject(targetDir);
   }
 
-  // If directory is empty, auto-prompt or auto-scaffold
+  // An empty folder (or a new one) gets the sample designs
   let entries = [];
   try {
     entries = fs.readdirSync(targetDir);
   } catch (_) {
     fs.mkdirSync(targetDir, { recursive: true });
   }
-
-  const hasHtml = entries.some((e) => e.endsWith('.html')) ||
-    (fs.existsSync(path.join(targetDir, 'artboards')) &&
-     fs.readdirSync(path.join(targetDir, 'artboards')).some((e) => e.endsWith('.html')));
-  const hasDesignsJson = fs.existsSync(path.join(targetDir, 'designs.json'));
-
-  if (!hasHtml && !hasDesignsJson && entries.filter((e) => !e.startsWith('.')).length === 0) {
-    console.log(`[htmlboard] Directory is empty. Initializing starter artboards...`);
+  if (!options.init && !entries.some((e) => !e.startsWith('.'))) {
+    console.log(`[htmlboard] Directory is empty. Adding sample designs...`);
     scaffoldProject(targetDir);
   }
 
@@ -275,8 +309,8 @@ async function main() {
     });
 
     console.log(`
-  ✦ \x1b[1m\x1b[36mHtmlBoard\x1b[0m \x1b[90mv${pkg.version}\x1b[0m
-  \x1b[90mInfinite Canvas & Design Explorer for HTML Artboards\x1b[0m
+  \x1b[90mhtml\x1b[0m\x1b[1mboard\x1b[0m \x1b[90mv${pkg.version}\x1b[0m
+  \x1b[90mInfinite canvas for HTML designs\x1b[0m
 
   \x1b[32m➜\x1b[0m  \x1b[1mLocal:\x1b[0m   \x1b[36m${url}\x1b[0m
   \x1b[32m➜\x1b[0m  \x1b[1mTarget:\x1b[0m  \x1b[90m${targetDir}\x1b[0m${rootDir !== targetDir ? `\n  \x1b[32m➜\x1b[0m  \x1b[1mRoot:\x1b[0m    \x1b[90m${rootDir}\x1b[0m` : ''}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "htmlboard",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Infinite canvas and design explorer for HTML artboards — designed for humans and LLMs",
   "type": "module",
   "bin": {
@@ -45,6 +45,6 @@
     "url": "https://github.com/luizcarlos1405/htmlboard/issues"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18"
   }
 }