htmlboard 0.4.0 → 0.6.0

package/README.md

@@ -31,8 +31,11 @@ Modern AI agents and developers generate dozens of HTML mockups, layout variatio
 
 - 🛸 **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.
+- 🔄 **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 component, 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.
+- 🧩 **Components**: Each file in `components/` is a custom element named after it (`tx-item.html` is `<tx-item>`), so the sidebar every screen shares is written once and used as one tag: attributes, slots and scoped CSS, built in the light DOM with your `styles.css`, no build step.
+- 🗂️ **A Catalog for Agents**: `htmlboard catalog` reads the project and prints what the designs share in a few lines: each stylesheet's variables and classes, the scripts, every component with its attributes, an example and where it's used. An agent learns your styles and components without reading every file, and since it's read from the files, it is never out of date.
+- 🩺 **Checks for Agents**: `htmlboard check` has the canvas open in your browser load each design again and report, as text, what went wrong: script errors, missing files and components, fonts that didn't load, content cut at the frame's edge, text cut off or spilling out of its box. An agent checks its work without screenshots.
 - 📐 **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.
@@ -59,7 +62,7 @@ htmlboard
 
 ### Scaffold a Starter Project
 
-To start with sample designs (a folder of screens and a folder of components, each file describing itself, all sharing one `styles.css`):
+To start with sample designs (a folder of screens and a UI kit, each file describing itself, all sharing one `styles.css` and four components):
 
 ```bash
 npx htmlboard --init
@@ -75,6 +78,9 @@ Usage:
   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
+  htmlboard components [directory] [--force]       Add components.js: files in components/ become custom elements
+  htmlboard catalog [directory]                    What the designs share: stylesheets, scripts, components
+  htmlboard check [directory or file] [-p <port>]  What went wrong in the designs, from the canvas open in a browser
 
 Options:
   -p, --port <number>   Port to listen on (default: 3000)
@@ -87,6 +93,8 @@ Options:
   -h, --help            Display help message
 ```
 
+Running `htmlboard` for a folder it already shows (same folder and root, same version) doesn't start a second canvas on the next port: it prints the running one's URL, and opens it with `--open`.
+
 ### Examples
 
 ```bash
@@ -105,6 +113,15 @@ htmlboard design --root .
 # Start a new folder with sample designs
 htmlboard ./my-new-ui --init --open
 
+# Let the designs in ./design use components
+htmlboard components design
+
+# What the designs in ./design share, in a few lines (what the agent skill reads)
+htmlboard catalog design
+
+# What went wrong in them: script errors, missing files, cut-off text (the canvas must be open)
+htmlboard check design
+
 # See what moving ./design/designs.json into its files would do, then do it
 htmlboard migrate design
 htmlboard migrate design --write
@@ -116,31 +133,39 @@ htmlboard migrate design --write
 
 HtmlBoard is built from the ground up to pair with AI coding agents (Claude, Gemini, Codex, ChatGPT, Antigravity, Cursor).
 
-### Install the agent skill
+### Install the agent skills
 
-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:
+HtmlBoard ships [Agent Skills](https://agentskills.io) that teach your agent how to use it. An agent keeps only each skill's one-line description in mind and reads a skill when a task calls for it, so the ones it rarely needs cost almost nothing until then:
+
+| Skill | What it teaches | Read |
+| :--- | :--- | :--- |
+| `htmlboard` | Start the canvas; write, size, name and group designs; shared styles; size and state variants; the catalog and the check | For any design work |
+| `htmlboard-components` | The component file: attributes, slots, scoped CSS, a script, its first-line example | Before writing or changing a component |
+| `htmlboard-designs-json` | Curating the canvas with `designs.json`, and `htmlboard migrate` | When the designs folder has a `designs.json` |
+
+Install them in your project:
 
 ```bash
 npx htmlboard skills install
 ```
 
-This writes `.claude/skills/htmlboard/` (Claude Code) and `.agents/skills/htmlboard/` (Codex and other agents that read `.agents/skills`). Commit them so everyone working on the project gets the skill. Then start a new agent session and just ask for a design.
+This writes them in `.claude/skills/` (Claude Code) and `.agents/skills/` (Codex and other agents that read `.agents/skills`). Commit them so everyone working on the project gets them. Then start a new agent session and just ask for a design.
 
 ```bash
 npx htmlboard skills install --global         # for your user (~/.claude/skills, ~/.agents/skills), all projects
 npx htmlboard skills install --agent claude   # only one agent: claude | agents | all (default)
 npx htmlboard skills install --force          # update a copy you edited locally
-npx htmlboard skills uninstall                # remove it (accepts the same --global / --agent)
+npx htmlboard skills uninstall                # remove them (accepts the same --global / --agent)
 ```
 
-Running `install` again after upgrading HtmlBoard updates the skill; a copy you edited is kept unless you pass `--force`.
+Running `install` again after upgrading HtmlBoard updates the skills; a copy you edited is kept unless you pass `--force`.
 
 ### The workflow
 
 1. **Ask your LLM to generate artboards:**
    > *"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.
+   With the skills, 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
@@ -150,11 +175,70 @@ Running `install` again after upgrading HtmlBoard updates the skill; a copy you
 3. **Watch the canvas update live:**
    As the LLM writes or refines each HTML file, HtmlBoard detects the file change and reloads the iframe on the canvas immediately. You never have to refresh your browser or hunt for file URLs.
 
+### What the designs share: `htmlboard catalog`
+
+Before an agent writes a new design, it needs to know what the others use: the stylesheet's variables and classes, the components and how to write them. Reading every file for that costs tokens in every session. `htmlboard catalog` reads them instead and prints a summary (the skill runs it). On the samples, shortened:
+
+```text
+$ npx htmlboard catalog designs
+designs: 4 designs. Paths below are from this folder.
+
+Stylesheets
+  styles.css · all 4 designs
+    :root { --bg: #0b0d13; --surface: #141724; --surface-2: #1c2030; --border: #23283c;
+      --text: #f1f5f9; --text-muted: #94a3b8; --text-subtle: #64748b; --accent: #6366f1; … }
+    classes .muted .label .row .page-title .page-sub .app .app-main .app-content .card .btn
+      .btn-primary .btn-secondary .btn-outline .btn-danger .badge .badge-dot .badge-emerald …
+
+Scripts
+  components.js · all 4 designs
+
+Components (components/)
+  <stat-card label value trend [warn]> · 2 designs: 01-screens/01-dashboard.html, 02-ui-kit/01-overview.html
+    e.g. <stat-card label="Monthly Recurring Revenue" value="$184,290" trend="▲ +12.4% vs last mo"></stat-card> …
+  <tx-item icon name meta amount [positive]> · 2 designs: 01-screens/03-mobile.html, 02-ui-kit/01-overview.html
+    e.g. <tx-item icon="💼" name="Client Invoice #1042" meta="Yesterday • Wire Transfer" amount="+$3,450.00" positive></tx-item> …
+```
+
+It describes whatever the project has and asks for nothing:
+- **Stylesheets** with any name, in any folder: the ones the designs link or `@import` (CDN ones by their URL), and the ones at the top of the folder that no design links yet.
+- **Variables** under the selector that declares them, so a dark theme's values show too.
+- **Components**: their attributes come from their markup (`{{name}}`), their script and their CSS (`&[warn]` is a flag, `&[size="lg"]` a value).
+
+On the samples it is 2 KB instead of the 9 KB of `styles.css` and `components/`, and the gap grows with the project: a stylesheet's rules don't show, only what they define.
+
+### Checking the designs: `htmlboard check`
+
+An agent can't see the canvas, and a screenshot costs it many tokens, when it can take one at all. `htmlboard check` asks the canvas open in your browser to look instead: each design loads again, out of sight, in a frame of its size, and what went wrong comes back as text:
+
+```text
+$ npx htmlboard check designs
+Checked 6 designs in designs (the canvas at http://localhost:3000): 2 with problems, 1 with notes.
+
+01-screens/02-customers.html · Customers
+  error  TypeError: Cannot read properties of null (reading 'append') (01-screens/02-customers.html:88)
+  error  <org-cel> isn't built: there is no components/org-cel.html
+  error  missing file: img/acme.svg (<img>)
+  layout cut at the right edge (the frame is 1280 px wide): table.table reaches 1342
+  layout text cut off by p.plan (overflow: hidden): "Enterprise annual plan"
+
+01-screens/03-mobile.html · Mobile
+  layout text spills out of .btn: "Confirm and continue"
+
+02-print/01-flyer.html · Flyer
+  note   content goes on below the frame, down to 1460 px (the frame is 1350 px tall)
+```
+
+- **What it finds:** script errors and `console.error`; files that aren't there (a stylesheet's fonts and images, a fetch's data too); components that weren't built; fonts that didn't load; a page that shows nothing; content cut at the frame's right edge; text cut off by a box that hides its overflow, or spilling out of its box. A note says when content goes on below a frame of fixed height: fine for a screen that scrolls, not for a flyer.
+- **What it leaves alone:** what a design means to do, such as text that ends in an ellipsis or is clamped, boxes that scroll, and content hidden or moved off the page on purpose. It doesn't judge looks (colors, spacing, alignment).
+- **It runs in your browser**, so the canvas must be open there. Each check loads the files as they are on disk, so it can run right after a save. Pages shown in frames get a small script first in their `<head>` (`/__explorer/probe.js`) to hear what goes wrong from the start; it only listens in the frames the check loads, and a design opened on its own doesn't get it.
+- A file or a folder checks just those designs: `htmlboard check designs/01-screens/02-customers.html`. It finds the canvas on ports 3000 to 3020 (`-p` for another) and exits with 1 when there are problems, 2 when it can't check. `--json` gives the report as data.
+
 ---
 
 ## 📂 How Designs Are Found
 
-Every `.html` file under the folder is a design (hidden folders, `node_modules`, `dist` and `build` aside):
+Every `.html` file under the folder is a design (hidden folders, `node_modules`, `dist`, `build` and the [components](#-components) in `components/` aside):
 
 - **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.
@@ -166,6 +250,7 @@ Every `.html` file under the folder is a design (hidden folders, `node_modules`,
 <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" -->
+<meta name="htmlboard:variant" content="width=768, height=1024 · tablet">  <!-- and at a tablet's size -->
 ```
 
 | Tag | What it says |
@@ -174,13 +259,61 @@ Every `.html` file under the folder is a design (hidden folders, `node_modules`,
 | `<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. |
+| `<meta name="htmlboard:variant">` | One more frame of the same file: with a query string (`?theme=dark`), at another size (`width=390, height=844`, so a responsive page shows on a phone too), or both; 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**.
 
-**Shared styles.** Designs link one stylesheet for what they share (tokens, base styles, components) and keep only their own CSS in their `<style>`, so they stay consistent and each new design is shorter to write. The samples use a `styles.css` at the top of the folder (`<link rel="stylesheet" href="../styles.css">`), and the agent skill tells LLMs to read it, use it and grow it. Editing it reloads every design that links it.
+**Shared styles.** Designs link one stylesheet for what they share (tokens, base styles, classes like `.btn` and `.card`) and keep only their own CSS in their `<style>`, so they stay consistent and each new design is shorter to write. The samples use a `styles.css` at the top of the folder (`<link rel="stylesheet" href="../styles.css">`), and the agent skill tells LLMs to look it up (`htmlboard catalog`), use it and grow it. Editing it reloads every design that links it.
+
+---
+
+## 🧩 Components
+
+Designs repeat markup too: the same sidebar on every screen, a dozen rows of a list. Written as a component, it is one tag in each design, and one file to change. Every file in `components/` (at the top of the designs folder) is a custom element named after it, built by `components.js`, which designs load once next to their stylesheet:
+
+```html
+<link rel="stylesheet" href="../styles.css">
+<script type="module" src="../components.js"></script>
+…
+<app-sidebar active="Customers"></app-sidebar>
+<tx-item icon="☕" name="Blue Bottle Coffee" meta="Oct 26 • Food & Beverage" amount="-$6.75"></tx-item>
+```
+
+A component is a piece of HTML, `components/tx-item.html`:
+
+```html
+<!-- <tx-item icon="💼" name="Client Invoice #1042" meta="Yesterday" amount="+$3,450.00" positive></tx-item> -->
+<div class="icon">{{icon}}</div>
+<div class="what">
+  <div class="name">{{name}}</div>
+  <div class="muted">{{meta}}</div>
+</div>
+<div class="amount">{{amount}}</div>
+
+<style>
+  & { display: flex; align-items: center; gap: 14px; }
+  .icon { width: 40px; height: 40px; border-radius: 12px; background: var(--surface-2); }
+  &[positive] .amount { color: var(--emerald); }
+</style>
+```
+
+| In the file | What it does |
+| :--- | :--- |
+| A comment first | An example of use: the component's documentation, for people and agents, and its preview on the canvas. |
+| `{{name}}` | The element's `name="…"` attribute, as text. |
+| `<slot>`, `<slot name="x">` | The element's content; its children with `slot="x"`. What a slot holds shows when nothing fills it. |
+| `<style>` | CSS for this element only (`&` is the element, a block box by default), added once to the pages that use it. |
+| `<script>` | Runs for each element once it is built, with `this` as the element: for the little that markup and CSS can't do, like marking the current link. |
+
+- **They work with your stylesheet.** Components are built in the light DOM, with no shadow root in the way, so `styles.css` reaches inside: they use the same classes as the designs (`card`, `btn`, `muted`). A component's CSS comes after `styles.css` and before the design's own `<style>`, so a design can still adjust one element.
+- **Variants are attributes styled in CSS** (`&[positive]`). There is no template logic to learn; a list is several elements.
+- **Relative links start from the component's file**, so they work from every design.
+- **`components.js` is a file in your project**, so designs work on any static server. `--init` adds it; `htmlboard components [dir]` adds it to a designs folder. After upgrading htmlboard, `htmlboard components [dir] --force` replaces an older copy (and any edits you made to it).
+- **Saving a component reloads the designs that use it.** Component files aren't designs; `designs.json` can show them on the canvas (below).
+- **`htmlboard catalog` lists them** with their attributes, the example each one starts with and the designs that use them.
+- HTML has no self-closing custom elements: write `<tx-item …></tx-item>`, not `<tx-item />`. And a component can't be a table's row or cell itself (the browser moves it out of the `<table>`), but it works inside a cell: `<td><org-cell …></org-cell></td>`.
 
 ---
 
@@ -206,6 +339,7 @@ A `designs.json` in the folder curates the canvas when folders aren't enough: se
 - 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.
+- **Components show on the canvas with `"components": "show"`**, each alone in its frame, from the example its file starts with, in a "components" section after the designs. They are 480 wide, unless the component's file says `<meta name="htmlboard" content="width=1040">`. A section can also list them (`"components/tx-item.html"`) or bring them all (`"folder": "components"`). A `designs.json` that only says `{ "components": "show" }` leaves the rest of the canvas as the files make it.
 - `name` and `artboards` are synonyms of `title` and `designs`.
 
 ### Moving an existing `designs.json` into the files
@@ -279,6 +413,38 @@ installSkills({ dir: process.cwd(), agent: 'all' });
 // → [{ skill: 'htmlboard', path: '…/.claude/skills/htmlboard', status: 'installed' }, …]
 ```
 
+And so is the components installer:
+
+```javascript
+import { installComponents } from 'htmlboard';
+
+installComponents({ dir: './designs' });
+// → { path: '…/designs/components.js', status: 'installed' }
+```
+
+And the catalog, as data or as the text `htmlboard catalog` prints:
+
+```javascript
+import { buildCatalog, formatCatalog } from 'htmlboard';
+
+const catalog = buildCatalog('./designs'); // { root } for links that start with "/", like --root
+// → { designs: ['01-screens/01-dashboard.html', …],
+//     stylesheets: [{ path: 'styles.css', users: [{ design: '01-screens/01-dashboard.html' }, …], variables, classes, keyframes, fonts }, …],
+//     scripts: [{ path: 'components.js', users }],
+//     components: [{ tag: 'tx-item', attributes: [{ name: 'icon' }, …, { name: 'positive', flag: true }], slots, example, users }, …] }
+console.log(formatCatalog(catalog));
+```
+
+And the check, which needs the canvas open in a browser (the server answers it at `GET /api/check`, `?only=<file or folder>` for some of the designs):
+
+```javascript
+import { runCheck, formatReport } from 'htmlboard';
+
+const { canvas, report } = await runCheck('./designs'); // { port } when it isn't on 3000 to 3020
+// → report: { dir, root, designs: [{ file, title, width, height, problems: [{ level: 'error', kind: 'missing', path: '/img/logo.png', tag: 'img' }, …] }, …] }
+console.log(formatReport(report, { url: canvas.url }));
+```
+
 ---
 
 ## 📂 Project Structure
@@ -291,20 +457,29 @@ htmlboard/
 │   ├── index.js          # Library entry point & API exports
 │   ├── server.js         # HTTP server, SSE live reload
 │   ├── designs.js        # Which designs a folder holds: files, their tags, designs.json
+│   ├── components.js     # Components: their previews, `htmlboard components`
+│   ├── catalog.js        # What the designs share: `htmlboard catalog`
+│   ├── check.js          # `htmlboard check`: asks the canvas, prints its report
 │   ├── migrate.js        # `htmlboard migrate`
 │   ├── skills.js         # `htmlboard skills` installer
 │   ├── 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
+│   │   ├── check.js      # Checks the designs in frames out of sight, for `htmlboard check`
+│   │   ├── probe.js      # Notes script errors and failed loads in the frames the check loads
 │   │   ├── favicon.svg, logo.svg, mark.svg
 │   │   └── fonts/        # Inter and Bricolage Grotesque (OFL)
 │   └── templates/        # The sample designs `--init` adds
-│       ├── styles.css    # Their shared tokens and components
-│       ├── 01-screens/   # Desktop dashboard, mobile feed
-│       └── 02-components/
+│       ├── styles.css    # Their shared tokens and classes
+│       ├── components.js # Turns components/*.html into custom elements (copied into projects)
+│       ├── components/   # Sidebar, top bar, stat card, transaction row
+│       ├── 01-screens/   # Dashboard, customers, mobile feed
+│       └── 02-ui-kit/
 ├── skills/
-│   └── htmlboard/        # Agent skill (SKILL.md) copied by `htmlboard skills install`
+│   ├── htmlboard/        # Agent skills (SKILL.md each) copied by `htmlboard skills install`
+│   ├── htmlboard-components/
+│   └── htmlboard-designs-json/
 ├── 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

package/bin/htmlboard.js

@@ -7,6 +7,10 @@ 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';
+import { installComponents, COMPONENTS_FOLDER, COMPONENTS_SCRIPT } from '../src/components.js';
+import { buildCatalog, formatCatalog } from '../src/catalog.js';
+import { runCheck, formatReport, hasProblems, CheckError } from '../src/check.js';
+import { PORTS, findCanvases } from '../src/canvases.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -76,6 +80,9 @@ Usage:
   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
+  htmlboard components [directory] [--force]       Add components.js: files in components/ become custom elements
+  htmlboard catalog [directory]                    What the designs share: stylesheets, scripts, components
+  htmlboard check [directory or file] [-p <port>]  What went wrong in the designs, from the canvas open in a browser
 
 Options:
   -p, --port <number>   Port to listen on (default: 3000)
@@ -93,7 +100,10 @@ Examples:
   htmlboard ./designs -p 8080   # Serve ./designs on port 8080
   htmlboard design --root .     # Artboards in ./design that link to ../css/…
   htmlboard --init              # Add sample designs to the current folder
-  htmlboard skills install      # Add the HtmlBoard skill to this project's agents
+  htmlboard skills install      # Add the HtmlBoard skills to this project's agents
+  htmlboard components designs  # Let ./designs use components (components/tx-item.html is <tx-item>)
+  htmlboard catalog designs     # What ./designs share, in a few lines (for your AI agent)
+  htmlboard check designs       # Script errors, missing files, cut-off text in ./designs
 
 On the canvas:
   Drag, scroll          Move around
@@ -145,8 +155,8 @@ function scaffoldProject(targetDir) {
 function showSkillsHelp() {
   console.log(`
 Usage:
-  htmlboard skills install [options]     Copy the HtmlBoard skill into your agents' skill folders
-  htmlboard skills uninstall [options]   Remove it
+  htmlboard skills install [options]     Copy the HtmlBoard skills into your agents' skill folders
+  htmlboard skills uninstall [options]   Remove them
 
 Options:
   -g, --global          Install for your user (~/.claude/skills, ~/.agents/skills) instead of this project
@@ -202,7 +212,135 @@ function runSkills(args) {
     console.log(`  ${labels[status]}  ${path.relative(process.cwd(), dest) || dest}`);
   }
   if (action === 'install' && results.some((r) => r.status === 'installed' || r.status === 'updated')) {
-    console.log(`\n  Restart your agent session to load the skill, then ask it for a design.`);
+    console.log(`\n  Restart your agent session to load the skills, then ask it for a design.`);
+  }
+}
+
+function runComponents(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+Usage:
+  htmlboard components [directory] [--force]
+
+Adds ${COMPONENTS_SCRIPT} and a ${COMPONENTS_FOLDER}/ folder to the designs folder (default: the current one).
+Each file in ${COMPONENTS_FOLDER}/ is then a custom element named after it (${COMPONENTS_FOLDER}/tx-item.html is
+<tx-item>) in the designs that load ${COMPONENTS_SCRIPT}, once, beside their stylesheet:
+
+  <script type="module" src="../${COMPONENTS_SCRIPT}"></script>
+
+A ${COMPONENTS_SCRIPT} that differs from this version's (an older one, or one you edited) is kept;
+--force replaces it.
+`);
+    return;
+  }
+  const unknown = args.find((arg) => arg.startsWith('-') && arg !== '--force' && arg !== '-f');
+  if (unknown) {
+    console.error(`[htmlboard] Unknown option: ${unknown} (see htmlboard components --help)`);
+    process.exit(1);
+  }
+  const dirArg = args.find((arg) => !arg.startsWith('-'));
+  const { path: dest, status } = installComponents({
+    dir: dirArg || process.cwd(),
+    force: args.includes('--force') || args.includes('-f')
+  });
+  const labels = {
+    installed: '\x1b[32m✓ added\x1b[0m',
+    updated: '\x1b[32m✓ updated\x1b[0m',
+    unchanged: '\x1b[90m= up to date\x1b[0m',
+    skipped: '\x1b[33m! differs from this version, kept (use --force to replace)\x1b[0m'
+  };
+  console.log(`  ${labels[status]}  ${path.relative(process.cwd(), dest) || dest}`);
+  if (status === 'installed') {
+    const folder = path.relative(process.cwd(), path.join(path.dirname(dest), COMPONENTS_FOLDER)) || COMPONENTS_FOLDER;
+    console.log(`\n  Write components in ${folder}/ (tx-item.html is <tx-item>) and load ${COMPONENTS_SCRIPT} in the designs.`);
+  }
+}
+
+// A folder as the user would type it: from the current folder, unless that means going up
+function shownPath(dir) {
+  const rel = path.relative(process.cwd(), dir);
+  return !rel ? '.' : rel.startsWith('..') ? dir : rel;
+}
+
+function runCatalog(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+Usage:
+  htmlboard catalog [directory] [--root <path>]
+
+Prints what the designs in the folder (default: the current one) share, read from the files: the
+stylesheets and scripts they load, each local stylesheet's variables, classes, @keyframes and
+fonts, and the components in ${COMPONENTS_FOLDER}/ with their attributes, slots, example and where
+they are used. A few lines instead of every file, for the AI agent that writes the designs.
+
+Options:
+  -r, --root <path>   The folder the canvas serves (htmlboard … --root), for links that start
+                      with "/" (default: the designs folder)
+`);
+    return;
+  }
+  let root;
+  const dirs = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--root' || arg === '-r') root = args[++i];
+    else if (arg.startsWith('--root=')) root = arg.slice('--root='.length);
+    else if (arg.startsWith('-')) {
+      console.error(`[htmlboard] Unknown option: ${arg} (see htmlboard catalog --help)`);
+      process.exit(1);
+    } else dirs.push(arg);
+  }
+  let catalog;
+  try {
+    catalog = buildCatalog(dirs[0] || process.cwd(), { root });
+  } catch (err) {
+    console.error(`[htmlboard] ${err.message}`);
+    process.exit(1);
+  }
+  process.stdout.write(formatCatalog(catalog, { name: shownPath(catalog.dir) }));
+}
+
+async function runCheckCommand(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+Usage:
+  htmlboard check [directory or file] [-p <port>] [--json]
+
+Has the canvas running for the designs (open in a browser: the check runs there) load each one
+afresh and prints what went wrong, in a few lines of text: script errors and console.error, files
+that aren't there, components that weren't built, fonts that didn't load, content cut at the
+frame's edge, text cut off or spilling out of its box. A directory checks the designs in it, a
+file just that design (default: the current directory).
+
+Exits with 1 when it finds problems, 2 when it can't check (no canvas running, or none open).
+
+Options:
+  -p, --port <number>   The canvas's port (default: found on 3000 to 3020)
+      --json            The report as JSON
+`);
+    return;
+  }
+  let port;
+  let asJson = false;
+  const targets = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--port' || arg === '-p') port = parseInt(args[++i], 10);
+    else if (arg.startsWith('--port=')) port = parseInt(arg.slice('--port='.length), 10);
+    else if (arg === '--json') asJson = true;
+    else if (arg.startsWith('-')) {
+      console.error(`[htmlboard] Unknown option: ${arg} (see htmlboard check --help)`);
+      process.exit(2);
+    } else targets.push(arg);
+  }
+  try {
+    const { canvas, report } = await runCheck(targets[0], { port });
+    if (asJson) console.log(JSON.stringify(report, null, 2));
+    else process.stdout.write(formatReport(report, { name: shownPath(report.dir), url: canvas.url }));
+    process.exitCode = hasProblems(report) ? 1 : 0;
+  } catch (err) {
+    console.error(err instanceof CheckError ? err.message : `[htmlboard] ${err.message}`);
+    process.exitCode = 2;
   }
 }
 
@@ -266,11 +404,26 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'components') {
+    runComponents(args.slice(1));
+    return;
+  }
+
   if (args[0] === 'migrate') {
     runMigrate(args.slice(1));
     return;
   }
 
+  if (args[0] === 'catalog') {
+    runCatalog(args.slice(1));
+    return;
+  }
+
+  if (args[0] === 'check') {
+    await runCheckCommand(args.slice(1));
+    return;
+  }
+
   const options = parseArgs(args);
 
   if (options.help) {
@@ -301,6 +454,25 @@ async function main() {
     scaffoldProject(targetDir);
   }
 
+  // A canvas already running for this folder (same root, same version): say where, rather than
+  // starting a second one on the next port
+  const root = options.root ? path.resolve(options.root) : targetDir;
+  const running = (await findCanvases([...PORTS, ...Array.from({ length: 21 }, (_, i) => options.port + i)]))
+    .filter((canvas) => canvas.dir === targetDir && canvas.root === root);
+  const same = running.find((canvas) => canvas.version === pkg.version);
+  if (same) {
+    console.log(`
+  \x1b[90mhtml\x1b[0m\x1b[1mboard\x1b[0m is already running for this folder:
+
+  \x1b[32m➜\x1b[0m  \x1b[1mLocal:\x1b[0m   \x1b[36m${same.url}\x1b[0m
+`);
+    if (options.open) openBrowser(same.url);
+    return;
+  }
+  for (const canvas of running) {
+    console.log(`[htmlboard] v${canvas.version} is running for this folder at ${canvas.url}; starting v${pkg.version} too.`);
+  }
+
   try {
     const { url, rootDir } = await startServer({
       dir: targetDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "htmlboard",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Infinite canvas and design explorer for HTML artboards — designed for humans and LLMs",
   "type": "module",
   "bin": {