@heycys/gallery 0.0.0-stage → 0.1.1

package/skill/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: gallery
+description: "Gallery: turn supplied materials into a polished, interactive HTML document whose claims and numbers trace back to them (experiment and project write-ups, research findings, meeting summaries, explainers, comparisons), with charts, tables and formulas where they help. The user edits it in the browser as you write it and gets one offline HTML file. Use when the user asks for Gallery (or $gallery); not for general front-end development."
+---
+
+# Gallery
+
+Create a self-contained HTML document whose claims, numbers, and visual encodings can be traced back to the supplied materials. You write it as an ordinary web page. Gallery's command, `gallery`, turns it into the kit's blocks, checks it and exports it as one offline file; meanwhile the user can watch and edit it in the browser.
+
+## Before anything: the gallery command
+
+This skill holds the instructions; the tools are the npm package `@heycys/gallery`, the `gallery` command. This skill needs `@heycys/gallery` ^0.1.1: a version npm's range `^0.1.1` takes, 0.1.1 or a later 0.1.x.
+
+1. Run `gallery --version`. When it prints such a version, go on to step 3.
+2. When `gallery` is not found, or prints a version older than `^0.1.1` takes, install it with `npm i -g @heycys/gallery@^0.1.1`, then run `gallery --version` again. When the user has already said to install it (in this request or earlier in the conversation), run it without asking again; otherwise ask the user before you install anything: say that Gallery's command is missing (or which version it is) and that you would run that command, and run it once they agree.
+   - When it prints a version newer than `^0.1.1` takes, install nothing (that would take Gallery back to an older version): tell the user this skill is older than their Gallery and ask them to run `gallery skill install` (with `--project` when the skill is the project's, in its `.claude/skills/`), then to start a new Agent session, which reads the new skill.
+   - No Node, or `node --version` older than 22.13: tell the user to install the current LTS from https://nodejs.org (or with their system's package manager), then start again.
+   - npm says `EACCES` (macOS and Linux, where npm's global folder belongs to the system): never use `sudo`. Tell the user, and offer either of these: give npm a folder of their own (`npm config set prefix ~/.npm-global`, add `~/.npm-global/bin` to `PATH` in their shell profile, open a new terminal, install again); or run every command as `npx -y @heycys/gallery@^0.1.1 <command> …` instead of `gallery <command> …`.
+   - Use `npx -y @heycys/gallery@^0.1.1 <command> …` likewise wherever a global install is not allowed (a sandbox, CI). It is slower: a few seconds more per command.
+   - On Windows, `gallery` works in PowerShell right after the install, in the same terminal. Only when PowerShell says running scripts is disabled (`gallery.ps1`): run `gallery.cmd` with the same arguments, or ask the user to run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once.
+   - After an upgrade, run `gallery open --no-browser` once: the server of the version before stops by itself, and this starts the new one. Tell the user that `gallery skill install` brings this skill to the new version too (an Agent session started after it reads it).
+3. The documents live in a workspace, a folder: `--workspace <dir>` (every command takes it), else `GALLERY_WORKSPACE`, else the nearest folder up from the current one holding `gallery.json`, else `Gallery` in the user's Documents folder, `~/Documents/Gallery` (made on first use; on Windows the Documents folder Explorer shows, OneDrive's when OneDrive backs it up). `gallery new`, `gallery import`, `gallery list` and `gallery open` print it as `工作区：<path>`. When a command prints `Cannot write the workspace <path> (…)` (a sandbox that allows writes only in the project, or a system that has not let the terminal into Documents), ask the user to allow Gallery to write there, or pass `--workspace <a folder in the project>` to every command.
+4. The browser service: `gallery new` and `gallery import` start the workspace's local server (or use the one running) and open the user's browser at the document, `gallery open [<slug>]` starts or reuses it and opens the user's browser (each takes `--no-browser`: the address without a tab), and each prints the address on its `交给用户` line: give it to the user all the same (the browser opened may not be Chrome or Edge, or not in front of them). Editing in the browser and `gallery qa` need Chrome or Edge. In a cloud sandbox the user cannot reach (`127.0.0.1` there is not their computer), skip the address: hand over the exported file instead. `gallery stop` stops the server (`Stopped the server on port …`, or `No Gallery server runs for <workspace>.`).
+5. Every command but `gallery serve` returns by itself, the server's included (it runs on after the command; `gallery serve` runs it in the foreground, for the user's own terminal: you start it with `gallery open --no-browser`): run each in the foreground, with no `timeout` wrapper, background job or `Start-Process`. When you ask the user to allow commands, `gallery *` covers them all (`gallery.cmd *` in PowerShell). In Windows PowerShell 5.1, give a command no `2>&1` (it makes its warnings errors) and read files with the file tool or `Get-Content -Encoding UTF8`. Resolve `references/` and `sdk/` from the folder holding this `SKILL.md`.
+
+**写作偏好** (`<workspace>/preferences.md`) holds the user's rules for writing a document: what to write and in what order, the opening summary, titles, fidelity to the materials, evidence and data. Read it before you write and follow it. When instructions differ, the user's request comes first, then 写作偏好, then this skill. Only the user changes 写作偏好: never edit it unless asked, and never write `"instructions": true` in a document's `doc.json` (it marks the page holding 写作偏好). Where 写作偏好 says `report.json`, a document made by Gallery 0.1 or later has `doc.json`; an older one keeps `report.json`.
+
+A document has one writer at a time: never let two Agents, or an Agent and a script, write the same `doc.html` at once. The user may edit it in the browser meanwhile; Gallery merges their edits with yours.
+
+A document is the folder `<workspace>/<slug>/`: `doc.html`, the page you write, and `doc.json`, its title and description (and the reader's 字体与布局 as `look`, which you keep when you rewrite it, as you keep the workspace's default `look` in `gallery.json`: writing-html.md). Documents link to each other by ordinary relative links between these files (`../<slug>/doc.html`: writing-html.md). A document made before Gallery 0.1 has `report.html` and `report.json` instead: write those (Gallery reads and writes them under their names; never rename them). Below, `doc.html` and `doc.json` stand for either.
+
+## Workflow
+
+1. Read 写作偏好 before anything else. When `<workspace>/preferences.md` is not there yet, `gallery new` (step 2) makes it from Gallery's defaults and prints its path (`gallery import` and `gallery list` print it too; `gallery open` does not): read it then, before you write. When `gallery new` prints `写作偏好：空`, the user emptied it: write from the request, this skill and the materials, and leave the file as it is.
+2. Create the document as soon as you know its title: `gallery new <slug> "<title>" "<description>"` (a lowercase kebab-case slug).
+   - Its place in the sidebar's tree ([Organizing documents](#organizing-documents)): where the user says, with `--under <document>` or `--after <document>`; when they say none and the workspace has documents, run `gallery list --tree` first and put it under the document whose topic it belongs to; at the top level when none fits.
+   - It prints where it wrote, the workspace, the path of 写作偏好 and the next steps, starts the browser service (or uses the one running), and ends with its `交给用户` line: the address where the user watches and edits the document (step 3). The line before it, the page alone, is yours.
+   - If the server could not start, it says why; once that is fixed, `gallery open <slug>` starts it and prints the address.
+   - The page renders straight from `doc.html`, reloads on every save, notes failing checks at its bottom left, and lets the user edit the document in place ([Revising a document](#revising-a-document)).
+   - When 写作偏好 asks for another title or description than the ones you gave, change them with `gallery set <slug> --title "…" --description "…"`.
+   - When the material is a file to be turned into the document (Markdown, HTML, Word, PDF, CSV, EPUB, or a ZIP of pages), create it with `gallery import <file> [<slug> ["<title>"]]` instead (it says the same, and what of the file it could not bring, by line), then edit what it made.
+3. Now, before you read further, send the user the address from the `交给用户` line in a message of its own, in the user's language: they watch the document being written there. In a cloud sandbox they cannot reach, skip it.
+4. Write `<workspace>/<slug>/doc.html` as ordinary HTML, replacing the starter section.
+   - Read [references/example-report.html](references/example-report.html) first: a catalogue of every block once, each written the way the tools read it, its words saying what the block is; take the blocks you need. Then read [references/writing-html.md](references/writing-html.md), whole.
+   - Write so that the user watches the document grow: as soon as you can outline it, replace the starter section with its skeleton (the opening summary's place and each section's heading), then write it a section at a time, one edit each. The page shows each save; one write of the whole document at the end leaves the user looking at the starter page until then.
+   - Materials can be large: list a folder before you read in it, and read what the document needs; no `du` or glob over a whole disk or tree.
+   - Take numbers and conclusions from the materials themselves: a summary of them, a subagent's too, is a lead to check, not a source.
+   - The document's data stays in `doc.html`. Its pictures and files go right in `<workspace>/<slug>/assets/` (writing-html.md's [Pictures](references/writing-html.md#pictures) says how to name and size them). Raw inputs that should travel with it go in `<workspace>/<slug>/materials/`.
+5. Export, check and look:
+   - `gallery export <slug>` makes the plain HTML of `doc.html` the kit's markup, gives every block its `data-block-id`, checks the document and writes the deliverable `<workspace>/exports/<slug>.html` ([what its lines mean](#what-the-commands-print)).
+   - `gallery qa <slug>` exports first when needed, opens the export in Chrome or Edge at 1024, 736 and 360px (every disclosure, Sheet panel and detail card in turn), prints each failure and warning with its place in the document's file (`doc.html:<line>`, `report.html:<line>` in an older document), and pictures what it flags and, in a plain run, up to 12 blocks (what you changed first, then the cards; a `--blocks` run pictures every block it names) in the folder its `Pictures of this run in <path>` line names (a run with nothing to picture, no block changed and no card, says so in its verdict and names the `--tiles` run to make instead). Read its whole output (the verdict comes last, then the deliverable's line) and look at the pictures: `changed/` holds what you changed or moved; `cards/` the cards no look has pictured yet, your own drawings, charts and components first, tables last (not your edits); `blocks/` and `tiles/` what you ask for with `gallery qa <slug> --blocks a,b` or `--tiles` (the whole page, each panel and card). A picture shows all an element draws: a mark cut at its edge is cut on the page too.
+   - Open at least every picture of `flagged/` and of `changed/`, at each width, then those of `cards/` that show what you drew yourself (your charts, drawings and flowcharts); open the rest as the document needs. In the handoff name the pictures you opened: a width or a block whose pictures you did not open is not one you looked at.
+   - Each run empties only its own folders before it pictures: `flagged/` every run; `changed/` and `cards/` a plain run; `blocks/` a `--blocks` run; `tiles/` a `--tiles` run. Open a run's pictures before you run the same kind again.
+   - After your last edit, run a plain `gallery qa <slug>`; then, when a line of it says `not pictured` and gives a `gallery qa <slug> --blocks …` command (blocks past a run's twelve, at a list's end; or blocks a tall moved block holds that none of its pictures showed at a width, `N of them not pictured at 360px: …`), run that command too, not instead of it. A `--blocks` run pictures the blocks named alone: its `Not pictured by this run …` line, before the verdict, names the changed blocks and the cards it left, which a plain run pictures.
+   - In the pictures, fix what reads badly though nothing flagged it, such as a single character alone on a line (a heading's or a label's last character wrapped), a line or a mark drawn through text, or one cell or metric left alone on a row of a grid.
+   - To fix what either finds, re-read what the `Re-read` line names, change `doc.html` (never a generated file) and run `gallery qa` again until nothing fails.
+   - Exit 3 is one of two things. `UNVERIFIED <why>: nothing was looked at`: there is no Chrome or Edge, or the one installed did not start (qa tries it twice, with a fresh profile each time). When a browser is installed, run `gallery qa` once more; if it says `UNVERIFIED` again, or there is none, look at the export at those widths yourself, its disclosures and detail cards opened (the page does not scroll sideways, only tables and formula blocks do; no label of a chart or a drawing is clipped, overlaps another or reads under 11px; leave the controls at its top right alone unless the user asks), and say so in the handoff. Or a verdict `nothing failed …; not verified at N places`, with an `UNVERIFIED` line for each place (a wait that ran out, a detail card that did not open, a Sheet panel that stayed hidden, a picture not taken): the rest was looked at; run `gallery qa` once more, then look yourself only at the places those lines name, and say so in the handoff.
+   - `gallery check <slug>` runs the checks alone and changes nothing.
+
+## What the commands print
+
+Paths are absolute, as this system writes them: use them as they are.
+
+| Line | Means |
+| --- | --- |
+| `工作区：<path>` | the workspace the command worked in (`gallery new`, `gallery import`, `gallery list`, `gallery open`, `gallery init`) |
+| `写作偏好：…（<path>）` | where 写作偏好 is (`gallery new`, `gallery import`, `gallery list`): read it before you write (`空`: the user emptied it) |
+| `交给用户（…）：<address>` | the address where the user watches and edits the document: send it to them now, in a message of its own (`gallery new`, `gallery import`, `gallery open`), and again in the handoff |
+| `Agent 自用（…）：<address>` | the document's page alone, editable, with no frame: yours (to try a component in), not for the user |
+| `Wrote: …`, `Undone: …`, `Kept (--keep): …` | `gallery component try`'s: what the gesture wrote to `doc.html`, each part of the instance with the lines it took out and put in, and that one Ctrl+Z gave the file back (`--keep`: the write left); `Picture of the instance after the …` names a picture to open; a `note` line asks what the check's do. In the handoff name each gesture tried and what it wrote |
+| `gallery component try`'s exit code | 0 the gesture wrote and one Ctrl+Z took it back · 1 a problem of the package's (a gesture that wrote nothing, said with what came of it; an undo that left part of the write): fix it, check it, try again; or a `FAIL` saying `doc.html` holds what the gesture wrote, the trial cut off after it: put that back yourself, `doc.html` read again first · 2 a mistake in the command (a selector that finds nothing: the line lists the classes the instance shows) · 3 `UNVERIFIED`, the trial not seen through (no browser or server, a card waiting for the reader, someone else's write meanwhile) and nothing of the gesture left in `doc.html`, its line saying what the file holds: run it once more |
+| `This workspace's Gallery server runs on port …` | the server started or reused: nothing to wait for or keep running |
+| `Preview: not started …` | no server, so no `交给用户` address: run `gallery open <slug> --no-browser` and give the user the address it prints (not in a cloud sandbox they cannot reach) |
+| `Next: …`, `Hand in: …` | the steps after `gallery new` or `gallery import`: follow them |
+| `Placed it …`, `Moved …`, `位置：…` | where `gallery new --under`/`--after` or `gallery move` put the document in the sidebar's tree, and where a document is (`gallery list`): say it in the handoff |
+| `Set <slug>:` and its lines | what `gallery set` changed; re-read the files its `Re-read` line names before you edit them |
+| `Cannot write the workspace <path> (…)` | ask the user to allow it, or pass `--workspace <a folder you may write>` |
+| `FAIL <slug>: N problems` | the checks failed, nothing exported (exit 1): fix each |
+| `OK <slug>`, `Checked N documents: …` | `gallery check`'s tally: those passed |
+| `fix …` | act on it (a path of this machine, a heavy picture) |
+| `note …` | advice, never a failure |
+| `note … kept by the script: .x` | your script selects that block by these names, so the user cannot delete or convert it: rename a class or id the script does not select it by |
+| `icon … the page's header none` | `gallery set <slug> --icon <that icon>` writes it in the header too, `--icon none` takes it out of both |
+| `Re-read <files> …` | the tools wrote these: re-read exactly them before editing |
+| `preview …`, `annotations …` | said once: which of your plain HTML the browser page made the kit's markup (never the user's edits); 批注 Gallery's server deleted, their words gone from the blocks they are on (`gallery export`, `gallery check` and `gallery qa` say it right after the write) |
+| `交给用户（离线文件）：<path>` | the deliverable (the export's last line; qa's last lines, after its verdict) |
+| `natural <file>: … rewritten in this file as the kit's markup` | the export rewrote those elements of `doc.html`, by line, into the kit's markup (a `<pre>` became `div.doc-code`, its `language-x` moved to `data-language`): nothing to fix, but the file is not what you wrote: re-read it, as the `Re-read` line names it, before you edit it (from `gallery check`: `not rewritten yet`, the export will). The indented lines under it say, by line, what the conversion did with an element (`line 12, code: tabindex kept on its <pre>`): nothing to fix, unless a line says what to write |
+| `Exported <path> …` and other `title`, `icon`, `ids` lines | what the export did (or, from `gallery check`, will do): nothing to do |
+| `chart …` | how a chart drawn from a table reads it (its rows, each column numbers or words): nothing to do |
+| qa `FAIL` · `WARN` · `INFO` | fix it · look at its picture and fix what reads badly, never cutting words or columns · nothing to do |
+| qa `UNVERIFIED <why>: nothing was looked at` · an `UNVERIFIED` line among the findings | nothing looked at: run qa once more, then look at the export yourself and say so · that place alone not looked at (the rest was): run qa once more, then look yourself at that place and say so |
+| `Not pictured by this run …` | a `--blocks` run's: blocks changed and cards it did not picture (with `no earlier look`, every card outside those named); the plain `gallery qa <slug>` it names pictures them |
+| `gallery qa`'s exit code | 0 nothing failed (warnings may remain) · 1 a failure, or the export it ran first failed · 2 an export missing or stale with `--no-export`, or `--blocks` naming an id the document has not (nothing looked at, no picture removed: name ids as qa printed them) · 3 something not verified: nothing at all (`UNVERIFIED <why>`: no Chrome or Edge, or one that did not start), or the places its `UNVERIFIED` lines name |
+| qa's lines per width (`1024px  fail 0 · …`) | what that look found; `1024×768` is the 1024px page in a shorter window |
+
+## Revising a document
+
+When the user names a document by its title or topic, find it with `gallery list <words>` (words of its title or topic; those whose title, description or slug holds them come first, then those whose text does, with `正文：` and the first place; `gallery list` alone lists every document, the one edited last first): it prints each document's slug, title, description, place in the tree, address, last edit and file. A search of the `doc.html` files themselves (grep) is fine too. An address the user gives (`http://127.0.0.1:<port>/#<title words>-<page id>`, the workbench's address bar or 复制块链接, `/<block id>` after it for a block) names its document by the id at its end, and the words before it may be out of date: `gallery list <address>` prints that document, or says it is in the trash, and every command that takes a slug takes the address, or the link after its `#`, as well. The id comes from the folder's name, so an address from another workspace can name this workspace's folder of that name: before you change anything, compare the title `gallery list <address>` prints, and its `工作区：` line, with what the user means. A path the user gives (the workbench's 复制底稿路径 copies one) is that document's `doc.html`; its folder's name is its slug, the folder holding it the workspace (pass it as `--workspace` when it is not the one the commands find).
+
+Before you change anything, run `gallery open <slug> --no-browser` and give the user the address on its `交给用户` line, even when they say the page is open: it reuses the running server without opening another tab, and it keeps the document as it stands so that the first `gallery qa` pictures what you change. It prints no `写作偏好` line: read `<workspace>/preferences.md` before you change anything.
+
+A long `doc.html` may not fit one read: map it first with a search of its headings and ids (`<h2`, `<h3`, `data-block-id`, with line numbers), then read the part you change by its lines. Right before each change, re-read the part you change and replace only it; never rewrite the whole file from an earlier read or regenerate it with a script. A script may read the file at that moment, replace several exact spans, each found once in it, and write it once (its read is the re-read); it stops without writing when a span is missing or repeated. Write it for Node (`node`), which Gallery runs on and so is always there: `python` may be missing, or a stub that runs nothing and says nothing (Windows' app alias). Keep the start tag of each block you change: its `data-block-id`, `style` and classes may be the user's edits.
+
+Write a block you add or convert as [the example](references/example-report.html) and [writing-html.md](references/writing-html.md) write it: read its part in both first.
+
+- `data-block-id` is a block's identity: never invent one or put one on another element. A moved block, or one wrapped in a new container, keeps its id (cut and paste the element as it is; the container gets none). An added or copied block has none: strip a copy's ids. A split keeps the id on the first part, a merge the first block's; a deleted id is never reused.
+- Words that stay a block's own through a change of type keep its id on the element holding them (a paragraph made an `h3` or `li`: on it); words that become part of another component (a table's numbers moved into a chart's JSON, items a disclosure's title) are a new block, without one. A table given `data-doc-chart` stays its block; its chart card is new. A list made a flowchart, or a flowchart a list, is new as the browser page makes it: no id on it, its nodes or items, or their titles; the blocks its items held keep theirs. Never move an id from an item or a container onto a paragraph in it.
+- When unsure, drop the id: a missing one costs the user at most a choice card, a misplaced one can send their undo to the wrong block. When a check says an id repeats, remove it from the copy.
+- A block made another (a table made Sheet tabs, a list a flowchart) carries every fact of the old one: its numbers, units, scope line and colors, the specific values where the document has them, not a vaguer word. Say in the handoff what could not go.
+- After `gallery export` or the user's first edit in the browser, the file holds the kit's markup and ids: re-read it. The user's edits are in the file itself; no command lists them.
+- A change that takes several edits (blocks wrapped in a disclosure, a section moved, a Sheet area's tabs and panels): make them one right after another. The browser page waits until the file is whole again before it shows it or merges the user's edits into it. A script as above may make a move in one write, cutting and pasting, when every span it cuts and every anchor it pastes at appears once in the file.
+- A revision may need changes the user did not name: a term defined where it now first appears, a reference to what was renamed. You may make them; name each in the handoff.
+- When the change touches data, recheck the summary, charts, units and denominators using it. A summary made simpler still rests each comparison on a number the document shows, and keeps what each number is (a range, a basin, one seed's value, a mean), not only the number. Then export and run `gallery qa`; name the changed blocks in the handoff.
+- The user's 批注 on a document are in `<workspace>/<slug>/annotations.json` (also what the workbench's 复制批注 hands over): `items`, each `{ id, text, anchor: { blocks, quote, … } }`, `text` the user's suggestion, `quote` the words it is on. When the user asks you to work through them, carry out each `text` where it is anchored; leave one that does not fit its words and ask about it in the handoff; where one conflicts with the request, the request wins: name it. Never edit `annotations.json`. Gallery's server deletes a 批注 whose words are gone, whether the page is open or not: its words must stay in the blocks it is on (`anchor.blocks`), and words moved into another block, a new callout for one, are gone for it (only a 批注 whose blocks are all gone, a block replaced whole, follows its words to where they appear once in the document). `gallery export`, `gallery check` and `gallery qa` list each deleted, once, right after the write that deleted it; run `gallery check <slug>` once more right before the handoff. One you carried out whose words remain stays until the user deletes it. In the handoff, say which you carried out (those still shown, for the user to delete), which you left and which went with their words.
+
+## Organizing documents
+
+The workbench's sidebar shows the documents as a tree: a document may sit under another. `gallery list --tree` prints it as the sidebar shows it (`gallery list --tree <document>`: that one and those under it); `gallery list` prints a `位置：` line for a document under another. A document is named as every command names one: its slug, its link or the user's address.
+
+- A new document goes where the user says: `gallery new <slug> "<title>" "<description>" --under <document>` (last under it; `--first`, first) or `--after <document>` (right after it, at its level). When they name no place, run `gallery list --tree` first when the workspace has documents, and put it under the document whose topic it belongs to (a week's notes under their project); at the top level when none fits. Say in the handoff where it went.
+- Move documents only when the user asks you to organize them: `gallery move <document> --under <document>` (or `--top`), `--after <document>` or `--first` for its place there, each with the documents under it. No file changes, and links between documents still work. Name every move in the handoff.
+- Change a document's title, page icon or description with `gallery set <document> --title "…" --icon <emoji, or none> --description "…"` (any of them): it writes the header of `doc.html` and `doc.json` in step, and the open page and the sidebar show it. Never edit `doc.json`'s title or icon, or the header, by hand for that. Re-read `doc.html` after it before you edit it.
+
+## Output contract
+
+- `<workspace>/<slug>/doc.html` and `doc.json` are the editable sources; what Gallery keeps of its own is under `<workspace>/.gallery/`, never yours to edit; `<workspace>/components/` holds component packages, no document, and is no slug a new document can take; `<workspace>/exports/<slug>.html` is the offline, single-file deliverable. Re-export after the last source edit. In the handoff the clickable HTML is the export or a verified byte-identical copy of it, never a source or a page of the local server.
+- Everything document-specific (data, visuals, styles, scripts) stays in `doc.html` and its `assets/`. Gallery's shared kit (its blocks, styles and `sdk/` types) is not yours to change; the workspace's component packages are. A document uses the kit's blocks and whole blocks. Make a package only when the user clearly wants a block to use again, never one per document: run `gallery component list` first, then read [references/building-components.md](references/building-components.md). When the user wants a document that uses it too, create that document first, even when they say to make the block first: Workflow steps 1–3 (`gallery new`, the address sent), then its skeleton with the heading of the section the instance goes in. Then make the package, and write the instance into its section last. An instance of a package `gallery component list` gives is written as `gallery component show <id>` prints.
+
+## Handoff
+
+In the handoff, give:
+
+- the deliverable: the path on the `交给用户（离线文件）：` line that `gallery export` prints last and `gallery qa` prints after its verdict, copied whole (no `…`, never rebuilt in another folder); and the address on the `交给用户` line of `gallery new` or `gallery open` again (you sent it at the start), where the user edits the document (not in a cloud sandbox they cannot reach). The export holds the document as of your last export: an edit after it, the user's in the browser included, needs another export;
+- what `gallery qa` flagged and what you fixed, and the pictures you opened, by name (never a width or a block whose pictures you did not open); or that it could not run;
+- the sentences that are your own inference and not stated by the materials, with where they are;
+- where a document you made sits in the sidebar's tree when you chose its place, and every move you made;
+- for a revision, the blocks you changed, the changes the user did not name, what a conversion dropped, and what a change of structure left side by side (two headings of one name, one right after the other, after a move).
+
+Before you hand over, do the review 写作偏好 asks for before handing in (a reading by a subagent, a check of the numbers), when it asks for one.
+
+## References
+
+| Need | Read |
+| --- | --- |
+| The user's rules for writing: what to write, the opening summary, titles, fidelity, evidence and data | 写作偏好, `<workspace>/preferences.md` |
+| How a block is written | [references/example-report.html](references/example-report.html) |
+| The rules behind the blocks: the page, what plain HTML becomes, figures and charts you draw yourself | [references/writing-html.md](references/writing-html.md) |
+| A block to use again, when the user asks for one | [references/building-components.md](references/building-components.md) |
+| Exact API types | `sdk/*.d.ts`, from [`sdk/index.d.ts`](sdk/index.d.ts) |
+| What each command does and prints | `gallery help`, `gallery <command> --help` |

package/skill/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Gallery"
+  short_description: "Turn materials into polished interactive HTML documents"
+  brand_color: "#2678D8"
+  default_prompt: "Use $gallery to turn these materials into a polished interactive HTML document."

package/skill/references/building-components.md

@@ -0,0 +1,367 @@
+# Building a component
+
+A component package is a block to use again: it lives in the workspace, the user finds it in the "/" menu of every document there, and a document holds its instances as ordinary elements.
+
+Make one only when the user clearly wants a block to use again ("做一个以后还能用的组件"). A document is written with the kit's blocks and, for a layout of its own, a whole block ([writing-html.md](writing-html.md#kit-blocks)): never make a package for one document, and never to get a look or a chart a document's own `<style>` and `<script>` can give it.
+
+The interface is experimental in Gallery 0.x: what this page says may change between versions, and a package may need changing with it.
+
+## The flow
+
+When the user wants a document that uses the block too, the document comes first: `gallery new`, its address sent, its skeleton written (SKILL.md, Workflow steps 1–4). Then make the package as below, and write the instance in its section at step 6.
+
+1. `gallery component list` first: what the workspace has now, each with its version, whether the menus can insert it, and what is there and cannot be used, with why. When one does what the user asks, use it: `gallery component show <id>` prints its parts, how to write it and its example.
+2. `gallery component new <id>`: a new package in `<workspace>/components/<scope>/<name>/`, its `id` being `<scope>/<name>`, the scope `local` when you name none. It writes a block that passes the check, for you to replace. Add `--script` only when the block must do something when a reader uses it: a static block runs no code, is the one to start with, and is all most blocks need. Add `--flow` when it holds blocks of the document's own under its markup (a card around any content): a slot, `body` (Slots, below).
+3. Write its files (below): the manifest, `template.html`, `example.html`, its style and, with `--script`, `kit.js`, then what a writer needs to know.
+4. `gallery component check <id>`, until it prints `OK`. It says each problem at its file and line; one with no line is of that file, or of the page, as a whole. Then open `overview-light.png` and `overview-dark.png` in the folder it prints, each the pictures of 360, 736 and 1024px wide of a theme side by side, `example.html` above the line and `template.html` below it, then at full size each width where they show something to fix, and `edit-1024-light.png` and `edit-360-light.png`, as the editing page draws it, `context.canEdit()` true: what the block draws only where a reader can edit (a handle, a button), which an export leaves out. A block that draws nothing more there gives the export's pictures again, and the check says so. It has run them and looked at nothing for you. In the handoff name the pictures you opened.
+5. Try each gesture a reader makes, in the page, with `gallery component try`, one command for each: `--drag <selector> --to <selector>` (a card dragged to another column or place), `--press <selector>` (a dot, a button) or `--key <selector> <key>` (Enter, Space or an arrow on a control the block draws), as `gallery component try <slug> --drag .kanban-card --to ".kanban-column:nth-child(3)"`. Write the instance into the document first, where step 6 puts it (when the user wants no document, into one of its own made with `gallery new`, named in the handoff), and copy `doc.html`; name the instance after the slug by its `data-block-id` when the document holds more than one. Each selector is the first element of the instance that it finds, as `kit.js` draws it: `Nothing in the instance is …` lists the classes the instance shows. The command opens the document's page alone, editable, in a Chrome or Edge of its own, headless, makes the gesture there with the pointer or the keys (a drag in steps, released as it comes onto its target), waits until `doc.html` has it, and prints what it wrote: `Wrote: tasks (-1 +1 of its 8 lines); nothing outside the instance changed (data-block-id aside)`, each part with the lines the gesture took out and put in. Then it presses Ctrl+Z once and says `Undone: one Ctrl+Z, and doc.html is as it was (data-block-id aside)`: the document is left as it was, and `--keep` leaves the write instead. Open the picture its `Picture of the instance after the …` line names. A `note` line asks what the check's notes ask (a write that lays a part out anew: change the write as Writing back says). Exit 1 is a problem to fix in the package: a gesture that wrote nothing says what came of it (no `context.edit` came of it, the page refused one and the console says why, an HTML5 drag was dropped nowhere: a list a card is dropped on cancels `dragenter` as well as `dragover`), and an undo that did not give the file back says what still differs; fix it, run `gallery component check <id>`, and try the gesture again. A `FAIL` that says `doc.html` holds what the gesture wrote is a trial cut off after its write (the page offline, a card held for the reader, a load of its own): that write is yours to put back, `doc.html` read again first, as the next paragraph says, before you try again. Exit 2 is a mistake in the command. Exit 3 (`UNVERIFIED`) is a trial not seen through that left nothing of the gesture in `doc.html`, its line saying what the file holds, what someone else wrote meanwhile included, which stays: run it once more. Each try shows on every page open on the document, the user's at the address you sent too: the write, then the undo. Say so in the handoff when the user may have watched it.
+   A gesture the command cannot make (the block inserted from "/" by its name, or a word of `words`, the pinyin of its name; words typed in its text parts or in a field it draws; a gesture of several steps), make yourself when you can drive Chrome or Edge by its DevTools protocol, from Node 22's own `fetch` and `WebSocket`, with nothing to install. Start one of its own at the `Agent 自用` address that `gallery new`, `gallery import` or `gallery open` prints: the document's page alone, editable, with no frame around it (`--headless=new --remote-debugging-port=<port> --user-data-dir=<a new folder> <address>`; `http://127.0.0.1:<port>/json/list` gives the tab's `webSocketDebuggerUrl`, and `Input.dispatchMouseEvent`, `Input.dispatchKeyEvent` and `Runtime.evaluate` do the rest). Copy `doc.html` first. A gesture's write goes to the file by itself: `<html>`'s `data-ge-save` leaves `saved` (`waiting`, then `syncing`) and says `saved` again once the file has it (`held`: a card waits for the reader; `offline` or `stopped`: the server). Then read the part in `doc.html`: it holds what the gesture meant, and nothing outside it changed but `data-block-id`: the page gives a block it saves a change of one where it has none (the instance, the section it stands in), and an undo leaves it, so compare `doc.html` with your copy with every `data-block-id` taken out. Press Ctrl+Z once with the focus in no field the block draws (in an `input`, a `select`, a `textarea` or an editable element of its own, Ctrl+Z is that field's: a click on a paragraph beside the block takes the focus off it), wait for `saved`, and see the part as it was. At the end `doc.html` is your copy again, but for those ids and what the user changed meanwhile at the address you sent: undo each step, the insert too, then close your Chrome. Anything of the trial an undo left (the page was loaded again, a card held a step), take out yourself once your Chrome is closed, as any change of yours, `doc.html` read again first: the instance, and an empty paragraph you made for it, keeping the rest and the ids. Write the whole copy back only where `doc.html` differs from it in what the trial left alone, ids aside, and never while a page of yours is open on the document: over more, it takes away what the user wrote meanwhile and shows them a card saying so, and a page of yours open on it holds on a card of its own.
+   In the handoff name the gestures you tried, and only those, each by its command or its steps and what it wrote, and what the user changed meanwhile, which stays. When you could not try one, by the command or yourself, say plainly in the handoff that you did not try it in the page.
+6. Use it where the user asked: in a document, write the element as `example.html` does. The user finds it in "/" under its name. `gallery export <slug>` exports it as any block, and `gallery qa <slug>` pictures it among the cards. Around an instance, the document's words say what the block is and where its data comes from. A value that a reader's gesture changes (a count by column, a status, a score, a total) goes in the document's words only with when it held ("截至 11 月 5 日，…"), as an opening summary may need it; otherwise point to the block, which shows it as it is now. How to use the block on the editing page (drag a card, press a dot) goes in the handoff and in writing.md, not in the document: its export and PDF show the block read-only.
+
+Tell the user the component's name and where it is. A change to a package reaches every page open on it, by itself.
+
+## The files
+
+| File | What it is |
+| --- | --- |
+| `component.json` | the manifest, plain data: all that Gallery itself reads of the package |
+| `template.html` | what "/" puts in a document: one instance, with what a new one holds. `gallery component check` requires it: with none, or one a new block cannot be, no menu offers the block, and `gallery component list` and 设置 › 组件列表 say so |
+| `example.html` | an instance as a writer would fill it: what `gallery component show` prints and what `gallery component check` runs |
+| writing.md | how to write it, for an Agent: what it is for, when to use it, what goes in each part. `gallery component show` prints it |
+| `style.css` | its look, optional |
+| `kit.js` | its script, optional, one classic script |
+| `preview.svg` | a picture for the menu, optional: a reader resting on its row sees it beside the description, or the description alone |
+
+## The manifest
+
+```json
+{
+  "id": "local/metrics",
+  "apiVersion": 1,
+  "version": "1.0.0",
+  "name": { "zh": "指标条", "en": "Metric strip" },
+  "description": { "zh": "一排数字和它们的说明", "en": "A row of numbers and what they say" },
+  "words": "zhibiaotiao kpi metrics 指标 数字",
+  "parts": {
+    "title": { "at": ":scope > h3", "edit": "text" },
+    "numbers": { "at": ":scope > dl", "edit": "none" }
+  },
+  "markdown": "parts"
+}
+```
+
+| Field | What it holds |
+| --- | --- |
+| `id` | `<scope>/<name>`, as its folder is, each in lowercase letters, digits and hyphens |
+| `apiVersion` | 1 |
+| `version` | which version of it this is: shown, never compared |
+| `name`, `description` | `{ "zh": …, "en": … }`, both: what the menu shows |
+| `words` | optional: what the menu finds it by, besides its name. Write the pinyin of a Chinese name here, the whole name in one word (`任务看板 renwukanban kanban`): "/" goes by the letters an input method is composing, and finds the block while all of them are being composed only by a word that holds them. The check gives a note on a Chinese name no word here spells whole, a syllable a character: it counts how many syllables of pinyin a word reads as, and does not know which characters they spell |
+| `parts` | its parts by name, below |
+| `runtime` | optional: what its script leaves on a page, `{ "generated": [selectors], "attrs": { selector: [names] } }` |
+| `assets` | optional: what it needs besides its script and style: the kit's files by id (`d3`, `charts`, `tables`, `dialogs`, `sheets`, `state`, `tokens`, `code`, `math`, `katex`, `katex-styles`, `katex-auto-render`), and files of its own folder a style names, by their path. `katex` gives a script the name `katex`, and what it draws needs `katex-styles` beside it, or a formula shows twice |
+| `markdown` | optional: `parts` (the default: a table part as a table, a text part as a paragraph) or `text` (its words alone), how it exports to Markdown |
+| `schema` | optional: the whole number of the newest shape of content its script reads, 1 when it says none: "When the content's shape changes", below |
+
+A package's manifest holds nothing else: a field it does not know keeps the package from loading, and `gallery component list` says why.
+
+## Parts
+
+A part is an element of an instance that the file means something by. `at` finds it: `:scope > h3`, `:scope > div.note > p`, step by step from the instance, or one selector for any depth, or a list of those with commas; each step a tag, `.class`, `[attr]` or `[attr=value]`. A part counts the elements `at` finds in one instance, each once: an instance holds at least `min` of them (1 when the manifest says none) and at most `max` (any number when it says none); `optional: true` lets it hold none, whatever `min` says. An instance with too few or too many fails `gallery check` for every document that holds one, and a `template.html` with too few or too many is in no menu.
+
+A group of parts repeated, an item of three parts three or four times, is its three parts, each reaching into the item and each with the same `min` and `max`:
+
+```json
+"parts": {
+  "name": { "at": ":scope > div.item > p.name", "edit": "text", "min": 3, "max": 4 },
+  "value": { "at": ":scope > div.item > p.value", "edit": "text", "min": 3, "max": 4 },
+  "change": { "at": ":scope > div.item > p.change", "edit": "text", "min": 3, "max": 4 }
+}
+```
+
+Each part is counted across the instance on its own: the check does not hold the parts of one item to each other, so four items, one of them without its `change`, pass, three changes being enough. Say in writing.md that every item holds all three.
+
+`edit` says whose a part is:
+
+| `edit` | What it means now |
+| --- | --- |
+| `text` | words the user types in, in the browser. It holds words and marks alone (`strong`, `em`, `b`, `i`, `u`, `s`, `code`, `a`, `sub`, `sup`, `br`): a heading, a paragraph, a label. With anything else in it, a block, a field, a picture, a comment, an element it does not close, the editor leaves it read-only, and the check fails it |
+| `none` | the component's: read it, draw from it. The user changes it through the source alone |
+| `data` | what a script reads its data from and writes back to (a table, a `<script type="application/json">`): the component's alone, written by `context.edit` and by nothing else, told to it when it changes |
+| `flow` | a slot: blocks of the document's own in the instance, a `<div data-doc-slot="<name>">` of its markup and no `at` (Slots, below) |
+
+What stands in an instance belongs by region:
+
+| Where | Whose events and contents |
+| --- | --- |
+| a `text` part | the editor's: Enter, Backspace, undo and the selection work as in any text |
+| a `data` part | the component's, and only `context.edit` changes its content. A `text` part in one, or around one, is no text part: the file holds one or the other there |
+| what the manifest's `runtime` names, and all else in the instance | the component's: the editor leaves its clicks and keys alone |
+| a slot, a `flow` part, and what it holds | the editor's: any block, as in the page; the component reads it and never writes in it |
+| the instance as a whole, its handle | Gallery's: moving, copying and deleting it |
+
+In the page the user types words in the text parts, edits the blocks of a slot as any, and moves, copies or deletes the instance whole; a component changes its data parts by `context.edit` on a gesture of the reader's, a drag or a press, and nothing else of it changes there. No item of a repeated group of text parts is added or taken out on the page, its text parts being the file's words: an item more or fewer is a change of the source, so say so in writing.md. A component whose items come and go keeps them in a data part, where a control of its own adds, renames or removes one by `context.edit`, as a move is written.
+
+A component reads a text part and never writes one: what a user types there is the file's, and a script that writes it on the `source` signal hears itself without end. It draws in what is its own, and writes a data part by `context.edit` alone: a change made straight to the part stands on that page and may end up anywhere, or nowhere.
+
+## Slots
+
+A slot is where an instance holds blocks of the document's own under its own markup: a card with a title over any content, a frame around a few paragraphs and a table. Its part is edited as `flow`, with no `at`, `min` or `max`, a name of lowercase letters, digits and hyphens, and `"optional": true` when an instance may have none:
+
+```json
+"parts": {
+  "title": { "at": ":scope > h3", "edit": "text" },
+  "body": { "edit": "flow" }
+}
+```
+
+In the markup it is a `<div>` or `<section>` of the instance's own, marked with that name, once in an instance, never the instance itself and with no `data-block-id`:
+
+<!-- the file holds -->
+```html
+<div class="brief" data-doc-component="local/brief">
+  <h3>本周要点</h3>
+  <div class="brief-body" data-doc-slot="body">
+    <p>上线了新的导出流程。</p>
+    <ul>
+      <li>导出更快</li>
+      <li>离线文件更小</li>
+    </ul>
+  </div>
+</div>
+```
+
+`gallery component new <id> --flow` writes one, `body`, in place of the text paragraph. What a slot holds is written as anywhere in the document ([writing-html.md](writing-html.md)): paragraphs, headings, lists, tables, formulas, code, a chart card, pictures, a disclosure, columns, another instance; no section and no tab area. Gallery converts, spaces and draws it as it does the page's. `template.html` gives it what a new instance starts with, an empty paragraph (`<p></p>`) where the reader starts typing; `example.html` some blocks a writer would put there.
+
+On the page the reader edits a slot's blocks as any of the page's: types in them, splits and turns them, moves them in and out by their handles, adds blocks there with "/", undoes. Where the package is missing, turned off or fails, the slot is still the document's and still editable; the rest of the instance shows as it stands.
+
+The slot is the reader's, not the component's:
+
+- `context.part("body")` gives the slot element, to read: its height, its words, its headings. A change of what it holds comes as `source`, whoever made it.
+- A component never writes in it, moves it or takes it off: what it holds is the reader's words, and a page would take a change there for the reader's, and save it. It draws outside the slot, in what its manifest's `runtime` names, as `local/brief` draws its count of words under it. `gallery component check` fails a script that changes what a slot holds or where it stands, as it mounts, as it is put back and as its example makes its edit. `context.edit` on a slot throws.
+- Its style reaches no block in the slot: a selector that goes down from the instance by a blank (`[data-doc-component="local/brief"] p`) styles the slot's paragraphs too, which read as the page's. Write each step with `>` (`[data-doc-component="local/brief"] > h3`), or wrap the rules in `@scope ([data-doc-component="local/brief"]) to ([data-doc-slot]) { … }`; the check gives a note on each that goes down.
+- With `"markdown": "parts"` a slot is written as its blocks, in its place among the parts; with `"text"`, its words.
+
+## Writing an instance
+
+<!-- the file holds -->
+```html
+<div class="metrics" data-doc-component="local/metrics">
+  <h3>本周指标</h3>
+  <dl>
+    <dt>收入</dt><dd>12 万</dd>
+    <dt>新客</dt><dd>3–5 位</dd>
+  </dl>
+</div>
+```
+
+An instance is a `<div>` or `<section>` naming its package, straight in the page or in anything that holds blocks. Classes and attributes of your own are free in it; `doc-*` and `data-doc-*` are the kit's. Nothing of Gallery's goes into an instance: no conversion, no spacing, no formula, no other component's script, but in its slots, which are the document's. Write no `data-block-id` in `template.html`: every block gets its own.
+
+`template.html` is one instance and nothing around it, closed by its own end tag, with as many of each part as the manifest says. Write what shows well when nothing is filled in yet: the user's first look at the block is this. Nothing in it runs or leaves its block: no script but data (`<script type="application/json">`), no `on…` attribute or address of code, no `<style>`, `<link>` or `<iframe>`, no `style` that positions it `fixed`, `absolute` or `sticky`, nothing of the editor's (`data-ge-*`). No menu offers a template that breaks this, and the check fails it at its line. `example.html` may hold several, and blocks around them.
+
+Put what the block says in the instance itself: an element a reader can read without its script, so that a reader of a file the package is not in, or a Markdown export, still has it. Where the package is missing or turned off, or its script fails or starts nothing, Gallery shows the instance as it stands and draws a script of data in it as it draws any, read-only: an array of objects as a table, an object as its keys and values, any other array as a list, cut short and saying so past twenty entries, three levels down or a few hundred values. A package with no script draws nothing of its scripts of data: what such a block says is in elements. A component that cannot fully read what it finds leaves it as it stands. A table part it leaves showing, drawing and hiding nothing. A script of data it hands to Gallery with `context.fail(error)` (or by throwing): Gallery then shows the instance as it stands, its script of data drawn read-only as above, its text parts read-only too until the page is loaded again. It never rebuilds what it found and writes that over it, and what it leaves alone nothing writes. Write no snapshot of what the block draws beside its data unless writing.md says how the snapshot is made again from that one source: otherwise it goes stale, unseen.
+
+A picture in an instance is the document's, a file of the document's `assets/` folder. `example.html` and `template.html` stand in no document, so a picture there is a `data:` address, or stands in the style, a file its `assets` name.
+
+## Style
+
+Every selector stands in the instance, whatever it is:
+
+```css
+[data-doc-component="local/metrics"] dl { display: grid; grid-auto-flow: column; }
+[data-doc-component="local/metrics"] dt { color: var(--doc-muted); }
+@media (max-width: 480px) {
+  [data-doc-component="local/metrics"] dl { grid-auto-flow: row; }
+}
+```
+
+An instance stands `--doc-block-gap` from what is around it, in whatever state it is: the kit gives it that margin, and a `margin` on the instance itself changes it.
+
+Start each one at `[data-doc-component="<id>"]`, the instance's own attribute, not a class of yours: a class is anybody's. A selector may have something before that, which only says when it applies, and nothing reaches outside it or beside it (`+`, `~`; in nesting, `& + p` is beside the instance when `&` is the instance, and fine when `&` is something in it): the check names each that does, with its line. Colors come from the kit's variables, which follow the dark theme: `--doc-text`, `--doc-muted`, `--doc-border`, `--doc-grid`, `--doc-surface`, `--doc-bg`, `--doc-accent`, `--doc-accent-soft`, `--doc-series-1` … `-6` ([writing-html.md](writing-html.md#the-page)). Text on a `--doc-accent` fill is `--doc-bg`, never `#fff`: the dark theme's accent is light. Text on `--doc-accent-soft` is `--doc-text`. A picture or a font a style names is a file of the package, listed in `assets`; an export embeds it. No `@import` and no address elsewhere.
+
+## Script
+
+`kit.js` is one classic script, no module and no `import`. It runs in a function of its own, on the page and in an offline file, and the types are in `sdk/doc-kit.d.ts`:
+
+```js
+DocKit.component({
+  id: "local/metrics",
+  on: ["source"],
+  mount(host, context) {
+    const drawn = document.createElement("div");
+    drawn.className = "metrics-drawn";
+    host.append(drawn);
+    const draw = () => { drawn.textContent = context.part("title")?.textContent ?? ""; };
+    draw();
+    return { update: draw };
+  },
+});
+```
+
+Its manifest says what that draws: `"runtime": { "generated": [".metrics-drawn"] }`.
+
+- `mount(host, context)` starts one instance from what the file says. It runs again on a node an undo puts back, and in an exported file: before each mount the kit takes off what `runtime` names and calls `dehydrate`, so that mount, dehydrate, mount gives the same DOM. `gallery component check` tests it, and names what piles up.
+- Whatever it adds to an instance is named in the manifest's `runtime`, `generated` for the nodes it makes and `attrs` for the marks it sets, or taken off in `dehydrate(host)`. A selector there goes down from the instance, and `:scope` is the instance itself (`"attrs": { ":scope": ["aria-busy"] }`). `dehydrate` may be given a host with nothing on it.
+- A component draws in its instance, with ordinary elements. Nothing goes on `document.body` or in the head, and no attribute on what stands around the instance: what must stand elsewhere for a while (a tooltip, a popover) `destroy` takes away, and a listener outside the instance ends with `context.signal`. `gallery component check` names what piles up outside. A shadow root is not forbidden, but `gallery qa` and `gallery component check` do not look into one and the kit's theme stops at it, so what stands there goes unchecked.
+- No `alert`, `confirm`, `prompt` or `window.open`: a dialog stops a reader's page until it is answered, and the check fails it.
+- `on` lists the signals `update(reason)` hears: `source` (a text or data part changed, or what a slot holds, whoever changed it: an undo too), `editable` (`context.canEdit()` has just become true), `resize`, `theme`, `viewport`, `fonts`, `reveal`, `layout` (a card's size changed where widths do not tell: a resize in the editor), `content` (a change inside the instance, heard only with `owns: false`, for a component that leaves what it draws to the kit to watch). `owns` (default true): the kit watches nothing the component draws, only its parts.
+- `context.part(name)` is a part of this instance (of a slot, its element, to read), `context.state({ version, defaults })` its reading state, of no other instance, `context.frame(draw)` draws in the kit's frame, `context.signal` ends with the instance (give it to `addEventListener`), `context.fail(error)` says it failed, `context.canEdit()` and `context.edit(name, change)` write back: below.
+- A component that throws fails that instance alone: it shows what it holds, read-only, its text parts too, until the page is loaded again.
+- `kit.js` is type-checked against `sdk/` as strict TypeScript would: a syntax error, a name nothing defines and what the SDK does not say fail the check, and any other word of the types is a note. A part and a draft are typed `HTMLElement`, and `querySelector` gives an `Element`: name what it is, `/** @type {HTMLTableElement} */ (table)`, or test it (`node instanceof HTMLElement`), and guard what can be null (`event.dataTransfer`, `context.part(…)`).
+- An export blocks the network: no `fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource`, `sendBeacon` or `import()`, and no `eval`. `gallery component check` refuses them, and `localStorage`: what a reader chooses goes in `context.state`.
+
+The SDK's types are named as they stand, with no `import`: `sdk/doc-kit.d.ts` declares them for every script. `DocComponentContext` is what `mount` is given, `DocComponentHandle` what it returns, `DocComponentSignal` what `update` hears and `DocComponent` what `DocKit.component` registers. A function the mount hands its context to names it so:
+
+```js
+/** @param {DocComponentContext} context */
+function titleOf(context) {
+  return context.part("title")?.textContent?.trim() ?? "";
+}
+```
+
+A component runs with the rights of a document's own script: on the page, with its origin, able to do what any script of the document can. Say so in writing.md when the block has a script, and put in the workspace only what the user or you wrote.
+
+## Writing back
+
+What a reader does in the block goes to the file through a part edited as `data`:
+
+```js
+// The row numbered `from` put before the row numbered `before`, or last, with the blank before it, so
+// that a table written a row a line stays so: what a drop calls, and the example too.
+/** @param {DocComponentContext} context @param {number} from @param {number | null} before */
+function move(context, from, before) {
+  return context.edit("tasks", (table) => {
+    const body = /** @type {HTMLTableElement} */ (table).tBodies[0];
+    const blankBefore = (node) => (node?.previousSibling?.nodeType === Node.TEXT_NODE && !node.previousSibling.textContent.trim() ? node.previousSibling : null);
+    const row = body.rows[from];
+    const next = before === null ? null : body.rows[before];
+    const at = next ? blankBefore(next) ?? next : body.lastChild?.nodeType === Node.TEXT_NODE ? body.lastChild : null;
+    for (const node of [blankBefore(row), row]) if (node) body.insertBefore(node, at);
+  });
+}
+
+DocKit.component({
+  id: "local/board",
+  on: ["source", "editable"],
+  mount(host, context) {
+    const draw = () => { /* draw the board from context.part("tasks"), handles only if context.canEdit(); a drop calls move(context, from, before) */ };
+    draw();
+    return { update: draw };
+  },
+  example(host, context) {
+    move(context, 0, null);
+  },
+});
+```
+
+`example(host, context)` calls the change a gesture calls (`move` here), on a small edit of its own: `gallery component check` runs it on its way back to the file, so that what it tries is the code a reader's drag or press runs, and an example that writes the part some other way tries nothing a reader does.
+
+- `context.edit(name, change)` hands `change` a draft of the part, off the page, and what it does to what the draft holds goes onto the page when it returns: draw from the part afterwards, as for any change, on `source`, which comes once `edit` has returned (a moment later, before the next frame; never inside it). There is nothing to wait for and no save to ask for. Saving, undo, a redo and a conflict with an Agent's write are Gallery's, as for words typed: each `edit` is one undo step, so call it once for a gesture, at its end, and not at every step of a drag. A gesture that writes two parts (a card moved and the move counted) names both in one edit, `context.edit(["tasks", "log"], ({ tasks, log }) => { … })`, and is one step; two edits are two steps.
+- Write on a reader's gesture alone, a press, a drop or a key, never as the block mounts or hears a signal: a mount runs each time a page opens it, an undo puts it back or a reader inserts it, and what it writes there a page would write each time, with nothing done. Draw what the parts hold as they are. `gallery component check` fails a component that writes as it mounts, or as it hears `editable` or `source`, once `context.canEdit()` is true.
+- It answers at once whether it was taken. `false` means nothing happened. That is so while `context.canEdit()` is false (always in an exported file and its PDF and in 演示视图, and until the page has come to edit: ask for `editable` to hear when; the editing page printed is still the editing page), when `change` throws, when it changed the part on the page rather than the draft it is handed (the draft is what goes in: what the page shows of the part is set back), and when what it made cannot go in the file: a script, an `on…` attribute, an address of code, `data-block-id`, `data-ge-*`, an element that would not read back as itself (a `<tr>` straight in a `<table>` with a `<tbody>`), the part's own tag or attributes changed, or more than 1 MB in one part. The console says which. What goes in is a copy of the draft, so a draft kept after the change returns writes nothing. `change` runs at once: it cannot wait for anything.
+- Only what changed is written, only inside that part, and every other byte of the file stays. A `data` part is written whole, so what a change leaves alone in it may come back spelled as a browser spells it: `&#20013;` as `中`.
+- A part that nothing edits is never written. So a component that cannot fully read what a part holds (a version it does not know, markup it did not write) leaves it alone and shows it read-only: it never rebuilds it and writes that over it. An edit that changes nothing writes nothing.
+- A `<script type="application/json">` part is the same: read `JSON.parse(part.textContent)`, and in `change` set `script.textContent` to the JSON (the scorecard's, below, keeps the layout it was written in). Write `</` as `<\/` and `<!--` as `\u003c!--`, which could end the script, or the edit is refused.
+- Keep what a reader only chooses (a filter, what is open) in `context.state`, and write to a part what the document says: what another reader should find there.
+- An instance a component wrote can come back through undo: mount and draw from what the parts hold, whatever they hold.
+- Someone else may write the file while the page is open (an Agent, another tab, the CLI). An edit of a part they left alone goes in beside what they changed; one of a part they changed waits on a card for the reader, who keeps theirs or writes the page's over it, and nothing of that is the component's to decide. The parts one `context.edit` writes go or wait together, so write in one edit what only makes sense together (a card moved and the count of moves), and in edits of their own what does not. Either way it next finds the part as the file then holds it: by a mount, as the page is shown again once nothing waits, or by `source`, when the reader undoes the choice. Draw from the part each time, never from what an edit last wrote.
+
+### Two examples: a table and a script of data
+
+Two packages written as this page says show the two kinds of data part. Each writes its part once for a gesture and draws from it on every `source`.
+
+| | Its data part | What a reader does | Where its script does not run |
+| --- | --- | --- | --- |
+| 任务看板, a task board | `"tasks": { "at": ":scope > table", "edit": "data" }`: a row a task, its first cell the card's title, its second its status; an attribute of the package's own on the instance lists the columns, empty ones too | drags a card to another column or place: its row moves and its status cell takes the column's (adding a task is an edit like a move, when the board offers it) | the table |
+| 评分表, a scorecard | `"scores": { "at": ":scope > script", "edit": "data" }`: `{ "scale": 5, "criteria": [{ "name": "价格", "weight": 3 }], "options": [{ "name": "供应商甲", "scores": [4] }] }` | presses a dot: that score | what the JSON holds, drawn by Gallery where the kit runs and the package does not: an array of objects as a table, an object as keys and values |
+
+Use a table when what the block says reads as a table by itself, rows of words that a reader with no script, a Markdown export or another program should find as written, and that the script arranges and moves. Use a script of data when the block holds values it works from rather than words to read: numbers and true or false, keyed or nested, that a table would hold as words to parse back (a weight, a score for each criterion). Either way, what the block works out (a total, a ranking, a count by column) is drawn, never written beside the data.
+
+A write keeps the part as it is laid out, so that a reader's change is a change of a line or two in the file. Move a row with the blank before it (`blankBefore` below), and write JSON back with `jsonIn` below. jsonIn keeps JSON on one line where it was on one. Otherwise it gives each entry of an object or a list a line of its own, but keeps on one line an object or list whose entries are all values or lists of values (`{ "name": "供应商甲", "scores": [4, 3] }`, `[[1, 2], [3, 4]]`): a list of objects, and an object that holds one, is spread over lines. So lay out the JSON in `template.html` and `example.html` the way jsonIn writes it:
+
+```json
+{
+  "scale": 5,
+  "criteria": [
+    { "name": "价格", "weight": 3 },
+    { "name": "质量", "weight": 2 }
+  ],
+  "options": [
+    { "name": "供应商甲", "scores": [4, 3] }
+  ]
+}
+```
+
+The board's drop and the scorecard's press:
+
+```js
+// The board: the row numbered `from` to the column `status`, before the row numbered `before`, or last.
+const blankBefore = (node) => (node?.previousSibling?.nodeType === Node.TEXT_NODE && !node.previousSibling.textContent.trim() ? node.previousSibling : null);
+context.edit("tasks", (table) => {
+  const body = /** @type {HTMLTableElement} */ (table).tBodies[0];
+  const row = body.rows[from];
+  const next = before === null ? null : body.rows[before];
+  const at = next ? blankBefore(next) ?? next : body.lastChild?.nodeType === Node.TEXT_NODE ? body.lastChild : null;
+  row.cells[1].textContent = status;
+  for (const node of [blankBefore(row), row]) if (node) body.insertBefore(node, at);
+});
+
+// The scorecard: the option numbered `option` given `score` on the criterion numbered `criterion`.
+const isValue = (value) => value === null || typeof value !== "object";
+const isFlat = (value) => Object.values(value).every((each) => isValue(each) || (Array.isArray(each) && each.every(isValue)));
+function laidOut(value, indent) {
+  if (isValue(value)) return JSON.stringify(value);
+  const list = Array.isArray(value);
+  const items = Object.entries(value).map(([key, each]) => `${list ? "" : `${JSON.stringify(key)}: `}${laidOut(each, `${indent}  `)}`);
+  if (items.length === 0) return list ? "[]" : "{}";
+  if (isFlat(value)) return list ? `[${items.join(", ")}]` : `{ ${items.join(", ")} }`;
+  return `${list ? "[" : "{"}\n${items.map((item) => `${indent}  ${item}`).join(",\n")}\n${indent}${list ? "]" : "}"}`;
+}
+function jsonIn(text, value) {
+  const start = text.length - text.trimStart().length;
+  const end = text.trimEnd().length;
+  const indent = text.slice(text.lastIndexOf("\n", start) + 1, start);
+  const json = text.slice(start, end).includes("\n") ? laidOut(value, indent) : JSON.stringify(value);
+  return text.slice(0, start) + json.replaceAll("</", "<\\/").replaceAll("<!--", "\\u003c!--") + text.slice(end);
+}
+context.edit("scores", (script) => {
+  const data = JSON.parse(script.textContent);
+  data.options[option].scores[criterion] = score;
+  script.textContent = jsonIn(script.textContent, data);
+});
+```
+
+While it draws the board, the board hides the table, `table.hidden = true`, a mark its manifest's `runtime` names (`"attrs": { ":scope > table": ["hidden"] }`), so that no file or copy holds it and the table shows wherever the script does not draw. A drag is best made with pointer events (`pointerdown`, `pointermove`, `pointerup`, `setPointerCapture`), which work with touch too. With HTML5 drag and drop, a list a card can be dropped on cancels `dragenter` as well as `dragover`, or a release just as the pointer enters it is refused.
+
+### When the content's shape changes
+
+An instance may say in which shape it holds its content, `data-doc-schema="2"`, a whole number you choose and write in the package's template and examples, and the manifest's `schema` says the newest the component reads. An instance past that, or one whose `data-doc-schema` is no number, was written by a newer version of the package: it is read-only whole, its text parts too, `context.canEdit()` is false for it, the component shows it read-only, and `gallery check` says so in a note. A package upgrade never touches a document: to move content to a new shape, change it as a task of its own.
+
+## What it says
+
+`gallery component check <id>` prints five sections, each `FAIL <file>:<line>: …` for what to fix and `note …` for what is advice:
+
+1. the manifest: as Gallery reads it, `template.html` there, no text part that holds more than words and marks, a note on a Chinese name no word of `words` spells whole in pinyin, by the count of its syllables;
+2. `kit.js`: what a browser refuses, what an export refuses, what it registers, a type check against `sdk/`, what the types alone say of code a browser runs being a note;
+3. `style.css`: each selector, what an export cannot hold;
+4. `template.html` and `example.html`: as the page of a document, by what `gallery check` runs, and `template.html` as what a menu can put in;
+5. both in a temporary document, exported, in Chrome or Edge under the export's policy: the console, a dialog or a window it opens, a page that loads itself again or stops answering, mount and dehydrate, what piles up in the instance or outside it, a text part the component redraws, a data part a mount changes, a write with no gesture once the page takes edits, the way back to the file, a page wider than the window, and the pictures. The way back runs the component's `example` (above), a small edit made by the change a reader's gesture calls: it must change a data part and nothing else, the server must take what it wrote, and with the part put back, as an undo does, the block must show what it showed. Its `way back` line says what the example wrote, each part and how many of its lines changed, and that the server took it; a note says a write that lays a part out anew (lines a change did not mean, a line left blank), and a list a card is dropped on that listens for `dragover` and not for `dragenter`, at the line of `kit.js` that listens. A package with a data part and no `example` gets a note: nothing has tried its way back. Exit 3 and `UNVERIFIED` when no browser ran it, or the browser went while it ran: run it again, or export a document that holds it and look yourself.
+
+Exit 0 is all five, exit 1 a failure. A failure with no line is of that file as a whole, or, as `the page`, of what ran. A package the user turned off in 设置 is checked as any, with a note saying so: passing the check does not turn it on, and that stays theirs to do.
+
+## States
+
+| State | In the menus | Instances there already |
+| --- | --- | --- |
+| available | shown | run and export |
+| hidden, in 设置 | not shown | run and export |
+| disabled, in 设置, or an `apiVersion` this Gallery does not run | not shown | show what they hold, read-only, with no script and no style, a script of data drawn by Gallery |
+| missing, or a package that does not load | not shown | show what they hold, read-only, a script of data drawn by Gallery; `gallery check` says why in a note |
+
+In an export the package's script runs with `context.canEdit()` false: the block is drawn as on the page, read-only, every edit answering false, so draw nothing to drag or press there. What the instance holds shows by itself only where its script does not draw:
+
+- a table part, with JavaScript off, in a Markdown export, and where the package is missing, turned off or failed;
+- a script of data, drawn read-only by Gallery where the package is missing, turned off or failed (`context.fail`); nothing of it shows with JavaScript off.
+
+A package whose template a menu cannot take is in no menu in any state; its instances are written by hand as `gallery component show` prints. The user chooses hidden and disabled, and can hide a block of Gallery's own too: `gallery component list` names those last, and you leave them out of what you write unless the user asks for one. Write an instance only of what `gallery component list` gives as a component to write with. A document never loses what an instance holds: moved, copied or sent to someone with no such package, it stays in the file.