@heycys/gallery 0.1.1 → 0.2.0

package/skill/SKILL.md

@@ -9,17 +9,21 @@ Create a self-contained HTML document whose claims, numbers, and visual encoding
 
 ## 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.
+This skill holds the instructions; the tools are the npm package `@heycys/gallery`, the `gallery` command. This skill is Gallery 0.2.0's and needs `@heycys/gallery` ^0.2.0: a version npm's range `^0.2.0` takes, 0.2.0 or a later 0.2.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.
+1. Run `gallery --version`. Its first line is the version: when it is such a version, go on to step 3. A line after it may say that something is newer; that never stops the task: say it once (the handoff will do) and go on, and update nothing without the user's yes, unless they already said in this conversation to update.
+   - `技能：<folder> …`: the Gallery skill there (this one, maybe) is older than the gallery. Tell the user so and offer to run the command the line gives (`gallery skill install`, with `--project` for a project's skill; run by `npx`, the line gives `npx -y @heycys/gallery@^<version> skill install`); after their yes, run it and tell them a new Agent session reads the new skill. Finish this task with the skill as it is.
+   - `新版本：…`: npm has a newer Gallery. Tell the user once in the conversation and offer to update; after their yes, run the line's `npm i -g …`, then `gallery skill install`, and tell them a new Agent session reads the new skill. Where you run Gallery by `npx` (no global install), the line gives `npx -y @heycys/gallery@^<its version> skill install` instead: run that after their yes, and tell them the next commands can take the newer range: `npx -y @heycys/gallery@^<its version> …`.
+2. When `gallery` is not found, or prints a version older than `^0.2.0` takes, install it with `npm i -g @heycys/gallery@^0.2.0`, 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.2.0` takes, install nothing (that would take Gallery back to an older version): this skill is older than their Gallery. Tell the user and offer to run `gallery skill install` (with `--project` when the skill is the project's, in its `.claude/skills/`; a `技能：` line gives it); after their yes, run it and ask them 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.
+   - 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.2.0 <command> …` instead of `gallery <command> …`.
+   - Use `npx -y @heycys/gallery@^0.2.0 <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.
+   - Gallery remembers every workspace used on this machine: `gallery workspaces` lists them, and `gallery list <words> --all` searches the documents of them all. When a document the user names is not in the current workspace, search with `--all` first, then pass the `工作区：` line printed before it as `--workspace`.
+   - Do not make a workspace of your own for a task unless the user asks for one; when you make one, give it the project's name: `gallery init <dir> --name "<project name>"`.
 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`.
 
@@ -31,9 +35,9 @@ A document is the folder `<workspace>/<slug>/`: `doc.html`, the page you write,
 
 ## 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.
+1. Read 写作偏好 before anything else (for a document: a custom page has none, [Custom pages](#custom-pages-自定义页)). 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.
+   - Its place in the sidebar's tree: [Organizing documents](#organizing-documents) (`--under` or `--after` where the user says).
    - 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)).
@@ -45,11 +49,12 @@ A document is the folder `<workspace>/<slug>/`: `doc.html`, the page you write,
    - 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.
+   - A task board, a number or a chart over a table of the user's (a board of tasks by status, a data dashboard) is Gallery's own views of a table, never a block of your own: an ordinary table carrying `data-doc-chart-source="<key>"`, then an instance of `gallery/kanban`, `gallery/metric` or `gallery/chart-view` with the same `data-doc-from="<key>"`, its settings one line of JSON. `gallery block add <name>` puts the block in, and `gallery block show gallery/<name>` (or `show kanban`) prints how to write it ([references/pages-and-data.md](references/pages-and-data.md#a-view-of-a-table)). Run `gallery block add <name>` before you write the instance, not after: an instance of a block that is not in the workspace stays read-only (`gallery export` notes it). Write the table first and the views below it, as each block's writing.md does (above it works, and `gallery check` notes it). These views read a table of their own document; a custom page's card that reads another document's table (`workspace.query("table")`) is a block of your own ([Custom pages](#custom-pages-自定义页), step 4).
    - 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.
+   - `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 custom blocks 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. Its `Not opened yet: …` line, right before the verdict, lists every picture of the run in one place, none opened for you: count by it. 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.
@@ -63,12 +68,18 @@ 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) |
+| `技能：<folder> 是 Gallery <version> 的，比这个 gallery … 旧；…` | `gallery --version`'s, after the version: that Gallery skill (this one, maybe) is older than the gallery: offer the user the command it gives (the first section) |
+| `新版本：npm 上有 Gallery <version>…` | `gallery --version`'s: npm has a newer Gallery: offer the update, once in the conversation (the first section) |
+| `工作区：<path>` | the workspace the command worked in (`gallery new`, `gallery import`, `gallery list`, `gallery open`, `gallery init`); `gallery list --all` prints it before each document it finds in another workspace: pass it as `--workspace` to work on that document |
+| `工作区名字：没有（…）；…gallery workspaces --name "<项目名>"…` | `gallery new` and `gallery init` in a workspace with no name of its own: when you made it for a project, name it after the project with that command; a workspace that is the user's own, leave as it is |
+| `gallery workspaces`: `路径：`, `文档：`, `服务：`, `不在了` | the workspaces this machine has used, each with its path, its document count and last edit, and its server's address while one runs; `不在了` a folder that is gone (it stays registered; nothing to do) |
+| `写作偏好：…（<path>）`, `Made now: …` | where 写作偏好 is (`gallery new`, `gallery import`, `gallery list`): read it before you write (`空`: the user emptied it); `gallery list` makes the file when there is none, and says so on a `Made now:` line of its own: it is the user's, never yours to change |
 | `交给用户（…）：<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 |
+| `Agent 自用（…）：<address>` | the document's page alone, editable, with no frame: yours (to try a custom block in), not for the user |
+| `Wrote: …`, `Undone: …`, `Kept (--keep): …`, `Read back: …`, `Not opened yet: …` | `gallery block try`'s, made on a scratch copy of the document (`doc.html` not written; `--keep` makes it on `doc.html` and leaves the write): what each gesture or step wrote, each part of the instance with the lines it took out and put in, those lines under it (`-`, `+`: read them), that a Ctrl+Z for each write gave the copy back, and that a fresh page of what it wrote shows what it wrote as the page did (what the page showed and never wrote, a filter or an editor left open, is a `note`: not to be written); `Picture of the instance after …` names a picture to open, which no one has looked at for you, and the `Not opened yet: …` line after it lists it (`gallery block check` ends with one too, for its pictures); a `note` line asks what the check's do. In the handoff name each gesture tried and what it wrote |
+| `gallery page try`'s lines and exit code | as `gallery block try`'s, of one card of the page (`page.html` not written; `--keep` writes it): `Wrote:` names that card's data parts, and `nothing else in page.html changed`; a write anywhere else (another card, the card's place) is a `FAIL`. The exit codes are `gallery block try`'s (below) |
+| `gallery page check`: `FAIL page.html:<line>: …`, `note page.html:<line>: card <id> (<block>): the workspace had not answered its read of …`, `Changes since …`, `Not opened yet: …` | each problem at its line (exit 1: fix each, then check again); what changed since the last check that found nothing (cards added, removed, moved, resized, their data with the lines): only the cards you meant; the pictures to open. A `note` (no failure) says a card was pictured before the workspace answered its read, and the `OK` line then ends `; but N cards were pictured before the workspace answered it (see "note" above), so their pictures do not show what they read`: such a picture says nothing of what the card shows, so open the page in Gallery or run the check again (your own card that reads `context.workspace` is covered too). Another `note` says a card holds no value for a setting its block cannot show anything without (`weather`'s city, `countdown`'s date: `note page.html:<line>: card <id> (<block>) holds no city …`), and the `OK` line ends `; and one card asks for a setting no one gave (see "note" above): c8 (city)`: its picture is the card's ask for it, so ask the user or take it from the workspace and write it ([Custom pages](#custom-pages-自定义页), step 4). A `FAIL` that says the browser did not answer within N s is a look that stopped (the looks after it were not made): a script of the page that never ends does this; run the check once more, and when it stops at the same place, the page holds it up. `OK <slug>` exit 0; `UNVERIFIED` exit 3, the page not looked at in a browser (its structure checked): run it once more |
+| `gallery block try`'s exit code | 0 it wrote, the Ctrl+Z took it back and a fresh page read it back · 1 a problem of the block's (gestures that wrote nothing, said with what came of the last; an undo that left part of a write; a fresh page that shows the block otherwise in what was written, or writes as it opens): fix it, check it, try again · 2 a mistake in the command (a selector that finds nothing: the line lists the classes the instance shows; an option a `<select>` has not; a steps file that does not read; one at a later step is said after what the steps before it wrote, which `--keep` leaves in `doc.html`) · 3 `UNVERIFIED`, the trial not seen through (no browser or server, a page that loaded itself again), its line saying why, `doc.html` holding nothing of it: 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 |
@@ -84,7 +95,7 @@ Paths are absolute, as this system writes them: use them as they are.
 | `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 |
+| `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 line goes on to say what each became (a table's `<caption>` a note line above it, its header cells highlighted) and that the words and numbers are unchanged. 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 |
@@ -95,7 +106,7 @@ Paths are absolute, as this system writes them: use them as they are.
 
 ## 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).
+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.
 
@@ -104,10 +115,11 @@ A long `doc.html` may not fit one read: map it first with a search of its headin
 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.
+- 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 block (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.
+- 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. In a document that was the user's, the export's `natural …` lines say which of their elements became the kit's markup (a table's `<caption>` a note line above it, its header cells highlighted): the words and numbers stay, the markup is not what they wrote, so tell them in the handoff what changed, by what it was and is, and never that nothing of theirs was touched.
+- Write a block's files, or any file you make, with the file tool, one file each; never several heredocs in one shell command (Git Bash on Windows fails 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.
@@ -119,19 +131,37 @@ The workbench's sidebar shows the documents as a tree: a document may sit under
 
 - 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.
+- The sidebar lists custom pages (自定义页) too, among 新建 and 搜索 in the order the user drags them to: pages, not documents ([Custom pages](#custom-pages-自定义页)). A page's slug and a document's are one set: `gallery new` refuses a page's, `gallery page new` a document's.
+- The sidebar is in columns, one for each workspace of this machine (the default one's is 默认文档), and holds web links beside the documents. A document made or opened by `gallery new` or `gallery open` in another workspace joins the default workspace's sidebar too, as its line `默认工作区（…）的侧边栏：已加进…` says (display only: edit it in its own workspace). To put a web page in the sidebar, use `gallery link add <url> "<name>"` (`--column "<column>"`, `--under`, `--after` or `--first` for its place; `gallery link set` and `gallery link remove` change and take it out): a link is no document, so nothing checks, exports or searches it, and an address of this Gallery's own server is refused (link the document). `gallery list` and `gallery list --tree` show links and columns as the sidebar does. Say in the handoff where a link went (`位置：`).
 - 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.
 
+## Custom pages (自定义页)
+
+A page has no 写作偏好: do not read it for rules, and Workflow step 1 is for documents (a `gallery list` that made it in passing changes nothing of that). A card made for "me" (my tasks) needs who that is: a setting of the card, never written into a block's code, asked or taken as step 4 says (写作偏好 may name them: read it for that alone, none of its rules is a page's).
+
+A custom page is the user's own page in the workbench's sidebar, yours to design: the folder `pages/<slug>/` of the workspace, `page.html` (any HTML, CSS and script of yours, [pages-and-data.md](references/pages-and-data.md#a-page-is-yours-to-design); a board of cards is one way, `<div class="gallery-board" data-board-id="main">`, each card a `<section class="gallery-card" data-card-id="…" data-x data-y data-w data-h>` around one custom block's instance, in square cells, twelve to a row) and `page.json` (its title and icon), opened at `/#@<slug>`. On a board the user moves, resizes, adds and deletes its cards there (the grip at a card's top-right corner: a drag moves it, a click opens its menu, 大小, 设置… and 删除; 添加自定义块 is the first row of the ··· menu at the right of the workbench's top bar, and puts a card on the page's first board), and types in them. The page draws no big title: its name is the sidebar's, the tab's and the top bar's, so write no `<h1>` of the page's name (one in `header.gallery-page-head` is not drawn). Keep a card's top-right corner clear (28 × 28 px, 6px in): the grip stands over it while the pointer is on the card; you write it when they ask for a page or a card ("首页加一张卡片…", "给我做一个读书页").
+
+1. Run `gallery page list` and `gallery block list` first: the pages there are, and the blocks a card can be (自定义页可用, and Gallery's own not yet added). "首页" is `pages/home` (a page as any: the user may rename or trash it). Gallery makes it once, when its server first starts in a workspace (`gallery init` does too), with its own cards, which the user may have moved, filled in or taken off; until then `gallery page list` and the commands of `home` say it is not made yet, and `gallery open --no-browser` makes it: run that once, then again. Extend it with `gallery page add home <block>`, never write its `page.html` over whole; one the user trashed stays away. A new page only when the user asks: `gallery page new <slug> "<title>"`. A blank page they made in the sidebar (新建页面, `page-…`, an empty main) is one to write whole.
+2. Send the address first, before you write any card: on the `交给用户` line of `gallery page new <slug> "<title>"` (a server running prints it; without one, `gallery page open <slug> --no-browser` does), or of `gallery page open home --no-browser` for the home page, in a message of its own: the user watches the cards arrive.
+3. On a page that is there, change only the cards the request needs. Every other card keeps its `data-card-id`, its place and its data parts as they are: the user placed them, and a note's words are theirs. Put a card on with `gallery page add <slug> <block>` (the first free spot by the block's default size, or `--x --y --w --h`; it gives the card its id and pushes down what it meets); re-read `page.html` right before each change you make in it by hand, and replace that card alone.
+4. Use one of Gallery's own blocks when it fits the request exactly (two packs: Gallery 风格's by a bare name, and 柔光风格's, off till the user turns it on, as `gallery-soft/<name>`; `gallery block add <name>` puts one in, and comes before `gallery page add`: `today`, `note`, `countdown`, `habit`, `weather` (a city's weather, from Open-Meteo: it goes online), and `todos`, `recent`, `stats`, `heatmap`, which read the workspace: its to-dos, the documents edited last, its counts, its edits by day; the user ticks a to-do on `todos`, and the tick is written into the document it is in as the user's own edit, which the page's Ctrl+Z takes back), and `gallery/static` for a card that only shows what you write (a heading, links, a short list, a picture: its file in `pages/<slug>/assets/`, written `assets/<file>`; it is for a custom page alone, a document's HTML is written as it is; it takes any size of cells, 4 × 4 at first, and does not grow with its words, so write the `data-w` and `data-h` it needs). When one is close but not exact (other fields, another look, another rule), do not settle for it, and do not write a block from nothing either: copy it with `gallery block new <id> --recipe <name>` and change the copy (a count by day, glasses of water or times, starts from `habit`: `gallery block new <id> --recipe habit`; a recipe, a block already made, takes no `--script`, `--flow`, `--data` or `--page`): its name, words, description, `preview.svg`, writing.md and example.html, which the command lists; Gallery's own stays as it ships. Make a block of your own from nothing ([references/building-blocks.md](references/building-blocks.md), and [references/pages-and-data.md](references/pages-and-data.md) for a card's size and settings and for what it reads: `gallery block new <id> --page --data` for a card that keeps what the user enters, `places` holding `page`) for a card that does something or keeps data the user changes that none of Gallery's is near, and for a read-only card over the workspace's data or the web's that none of Gallery's shows (a count by day, a rate, a feed, the rows of another document's table: `kanban`, `metric` and `chart-view` are views inside a document and read no table from a page): it is a block too (`needs` `workspace` or `net:<host>`; start from `heatmap` or `weather` with `--recipe`), never the page's own script or HTML. What a card holds stays in its card (a data part, its settings), never in the page's own HTML. A card that shows nothing without a setting the user did not give (`weather`'s city, `countdown`'s date, a block of your own with its owner) is asked about: ask the user, or take it from what the workspace says (写作偏好, the documents; ask when that is a guess), and tell them in the handoff what it holds and where you took it from, or that the card still asks for it. Give it with the add, `gallery page add home weather --set city=上海` (each `--set <key>=<value>`, no JSON to quote, held to the setting's type: a date is `YYYY-MM-DD`); for a card already there, write it in the card's settings part (its `<script type="application/json">`, as the block's writing.md shows), re-reading `page.html` right before and changing that part alone. `gallery page check` notes a card whose required setting is empty.
+5. Try each gesture of a new block on its card: `gallery page try <slug> <card id> --press <selector>` (the gestures and `--steps` of `gallery block try`, on a scratch copy of the page): its `Wrote:` lines name that card's data parts alone, then the page's own Ctrl+Z gives the copy back and a fresh page reads it back. Then `gallery page check <slug>` until it prints `OK`: each `FAIL page.html:<line>` (an id missing or twice, cards sharing cells or past the row, a block a page does not run, a file of `assets/` not there or a frame of one, a card whose content does not fit it; the page's own scripts and stylesheets pass); open the pictures its `Not opened yet` line lists (1280, 1920 and 600px wide, light and dark) and read its `Changes since …` lines: they name the cards you meant to change and no other, but those that end `(the user's, on the page)`, the user's own gestures on the page since the last check (a card moved, words typed in it): leave those as they are, never put one back. A line that ends `(put there by Gallery)` is the home page's own today or note, there before you came (a new workspace's first check of `home` lists them): leave those too.
+6. At the end tell the user what you changed (each card, by what it shows) and where: the page's title in the sidebar (with 新建 and 搜索), and the address again. A card that goes online (`weather`, or a block whose needs name `net:<host>`) shows nothing until the user allows it: tell them to press 允许访问 on the card, and never write that consent yourself.
+- A page is no document: no opening summary, no source line, no export; 写作偏好 is for documents.
+- Its look is yours to choose (a header of your own that is no title, colors of its own in its `<style>`), written for both themes: the dark ones under `:root[data-doc-effective-theme="dark"]`.
+- Its own scripts are yours too, a board or none; what a card does is its block's, which the server puts in.
+
 ## 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.
+- `<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 custom blocks (自定义块: their files keep the word component, `component.json` and `data-doc-component`), no document, and is no slug a new document can take; `<workspace>/pages/` holds the custom pages ([Custom pages](#custom-pages-自定义页)), each with its own files in its `assets/`; `<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 custom blocks are. A document uses the kit's blocks and whole blocks. A document's own script cannot write the file: a control that must keep what a reader enters (a ledger, a checklist, a form) is a custom block's data part (`gallery block new <id> --data`), though the user does not say to use it again. Otherwise make a custom block only when the user clearly wants a block to use again, never one per document: run `gallery block list` first (Gallery's own blocks among what it lists, each added as it ships by `gallery block add <name>`), then read [references/building-blocks.md](references/building-blocks.md) (a block with a script: [references/block-script.md](references/block-script.md); one that reads the workspace, a table or the web: [references/pages-and-data.md](references/pages-and-data.md)). `gallery component …` is another name for `gallery block …`. 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 block, and write the instance into its section last. An instance of a block `gallery block list` gives under 文档里可用 is written as `gallery block 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;
+- 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: count by the `Not opened yet: …` line that `gallery qa`, `gallery page check`, `gallery block check` and `gallery block try` end with); 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).
@@ -145,6 +175,9 @@ Before you hand over, do the review 写作偏好 asks for before handing in (a r
 | 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) |
+| A custom block (a block to use again), when the user asks for one: the block, its flow, files, manifest and instance; sharing a block pack | [references/building-blocks.md](references/building-blocks.md) |
+| A block's script (`kit.js`) and how it writes back to the file | [references/block-script.md](references/block-script.md) |
+| A card of a custom page (size, settings), and a block that reads the workspace's data, a table of its document or the web | [references/pages-and-data.md](references/pages-and-data.md) |
+| A sidebar column of links an extension provides (`extensions/<id>/sidebar.json`), when the user asks for one | [references/extensions.md](references/extensions.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/references/block-script.md

@@ -0,0 +1,140 @@
+# The script of a block
+
+A block that does something when a reader uses it, or draws from what changes, has a `kit.js`. This page is its interface (what `mount` is given, the signals it hears, what the kit gives so that no block writes it again) and the one way a block changes its file, `context.edit`, with the two example blocks that show it. A block with no script needs none of it: [building-blocks.md](building-blocks.md) is the block itself. What a script reads beyond its own parts (the workspace, a table of its document, the web) is in [pages-and-data.md](pages-and-data.md).
+
+## 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 block 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 block 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 block check` names what piles up outside. A shadow root is not forbidden, but `gallery qa` and `gallery block 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, detail)` hears: `source` (a text or data part changed, or what a slot holds, an attribute there that says something of the file among them, a to-do item checked, a cell's span, a color; whoever changed it, an undo too; heard in the next frame, all that changed since in one, `detail` the records; what another instance among a slot's blocks draws is none of it, what its words say is), `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, a card of a custom page), `clock` (each whole minute of the reader's clock, `detail` `"minute"`, or `"day"` for the first minute of a day: one timer for every block on the page, so a clock or a date asks for it rather than setting its own), `data` (what the workspace holds changed, `detail` its kind, for what reads it), `content` (a change inside the instance, heard only with `owns: false`, for a block that leaves what it draws to the kit to watch). `owns` (default true): the kit watches nothing the block 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 (kept by its `data-block-id`, else by its markup, what its parts hold left out, and its place among the instances of that markup, so that an edit of its words keeps it), `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.
+- What the kit gives so that no block writes it again: `context.readJSON(name)` (a script of data's JSON, parsed, `null` when that is what it says; `undefined` for an optional part it does not hold and for one that holds no JSON, which fails the instance: stop there, and let your own check of what it read fail the rest, `null` included) and `context.editJSON(name, change)` (Writing back); `context.rows(name)` (the rows of the table a part is or holds: `columns`, the header's words; `rows`, each `{ el, values, links }`, its element, its values by the header's words as a chart reads them, a number, its words or null, and the links its cells hold to documents, `{ slug, title, block }`; and `add`, `move`, `remove`, each one write: Writing back); `context.interval(run, ms)`, `context.timeout(run, ms)` and `context.listen(target, type, listener, options)` (cleared and removed as the instance ends; what a timer runs is the instance's, a throw failing it); `context.place` (`"document"`, `"export"`, an exported file, where nothing writes, or `"page"`, a card of a custom page) and `context.size` (on a custom page its card's `{ w, h, width, height }`, cells and pixels, read again on `layout`; null in a document).
+- Data beyond its own parts is the kit's too, each for a block whose manifest's `needs` name it ([pages-and-data.md](pages-and-data.md)): `context.workspace` (the workspace's to-dos, documents, counts and edits by day, a table of another document, and checking a to-do: [The workspace's data](pages-and-data.md#the-workspaces-data); `needs` `"workspace"`), `context.table()` (the table of its document a view reads: [A view of a table](pages-and-data.md#a-view-of-a-table); `needs` `"tables"`) and `context.fetch` (the web: [Going online](pages-and-data.md#going-online); `needs` `"net:<host>"`).
+- Two gestures are the kit's: `DocKit.input(field, { commit, signal: context.signal })` hands `commit(value)` what the reader typed in an `input` or a `textarea`, or chose in a `select`, once they are done (Enter, in a textarea Ctrl+Enter; the field left), never while an input method composes (a Chinese IME's Enter only takes its letters), never twice; Escape puts the value back, and the handle's `set(value)` shows what the file holds now unless the reader is typing there. `DocKit.drag(area, { items, over, drop, marker, enabled, signal })` drags what `items` finds in `area` by pointer events, from a few pixels' move on: `over(x, y, item)` says where a drop there goes, `{ into, before, … }` (the `marker` is put in `into` before `before`) or null, `drop(item, spot)` writes on a release over one, Escape or a release elsewhere drops nothing, the item carries the class `doc-dragging` while it moves, for its style, and `enabled: () => context.canEdit()` keeps an export still. Give what a finger drags `touch-action: none`.
+- A choice is the kit's too, never a native select's popup (a square white box that follows no theme). A `<select>` in your block opens the kit's flat menu by itself and keeps its `value`, `input` and `change`, so draw one and read it as any select. For a choice from a button of your own, `DocKit.choose(button, { options: [["a", "Alpha"], ["b", "Beta"]], value, signal: context.signal })` opens the same menu under it and answers with the value chosen, or `null` when it was dismissed (Esc, a press outside); an option may be `{ value, label, disabled }`, and `{ group }` a heading. Don't draw a dropdown of your own, and don't call `select.showPicker()`.
+- A block whose script 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 block check` refuses them, and `localStorage`: what a reader chooses goes in `context.state`. A block that reads the web uses `context.fetch` ([Going online](pages-and-data.md#going-online)), which the check lets through.
+
+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 block's script 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: one write of the table's rows,
+// which takes the blank before the row along, 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) {
+  const rows = context.rows("tasks");
+  if (!rows || !rows.rows[from]) return false;
+  return rows.move(rows.rows[from], before === null ? { after: rows.rows.at(-1) } : { before: rows.rows[before] });
+}
+
+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 block 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. It runs on every instance of `example.html` and of `template.html`, and the template's is empty: `example()` must change a data part there too (add an entry, set a field; a change of `books[0]` that an empty instance does not hold changes nothing, and fails as `its example(host, context) changes nothing a part holds`, said at `kit.js`), by the function the reader's own control calls, not a copy of it written for the check.
+
+- `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 (in the next frame, before it is painted, with whatever else changed since; 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 block check` fails a block that writes as it mounts, or as it hears `editable` or `source`, once `context.canEdit()` is true.
+- Draw a control that writes only while `context.canEdit()`: hide it with `hidden = !context.canEdit()` or disable it (`box.disabled = !context.canEdit()`), so that an export, where nothing is written, shows no button or field that does nothing. The kit holds the `hidden` attribute over any `display` the block's style gives the control (`display: flex` on its class does not show it again), and `gallery block check` notes a control of an instance with a data part that its export still shows enabled.
+- 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 block 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 read with `context.readJSON(name)` and written with `context.editJSON(name, change)`: `change` is handed what the part holds, parsed, and changes it, or returns what is to stand there instead, and the kit writes it back as it was laid out (below), `</` and `<!--`, which could end the script, escaped; a change that leaves the value as it was writes nothing. It is one `context.edit`, and answers as one.
+- A table part is read and written with `context.rows(name)`: `add(values, { after })`, `move(row, { before | after, values })` and `remove(row)` are each one write, one undo step, the blank before a row going with it; `move` sets the cells `values` names as it moves the row, so that a card dropped in another column is one step. Each answers as `context.edit` does, and a set is read once: after a write, read the rows again on `source`.
+- 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 block 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 block'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 blocks 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`. Both are blocks a reader changes, so both have a script: make each with `gallery block new <id> --script`, which starts `kit.js` with its registration (with no `--script` the block has none to start from).
+
+| Made with | Its data part | What a reader does | Where its script does not run |
+| --- | --- | --- | --- |
+| 任务看板, a task board: `gallery block new local/board --script` | `"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 block'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: `gallery block new local/scorecard --script` | `"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 block 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 `context.rows(name)`, which takes the blank before it along, and write JSON back with `context.editJSON`, which writes a part that was on one line back on one line, compact (`JSON.stringify`, no blanks inside: `{"items":[{"text":"a"}]}`, whatever blanks the file had), so write a one-line part that way in `template.html` and `example.html`. Otherwise (a part that spreads over lines) 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 editJSON 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 rows = context.rows("tasks");
+if (rows && rows.rows[from]) {
+  const values = { [rows.columns[1]]: status };
+  rows.move(rows.rows[from], before === null ? { after: rows.rows.at(-1), values } : { before: rows.rows[before], values });
+}
+
+// The scorecard: the option numbered `option` given `score` on the criterion numbered `criterion`.
+context.editJSON("scores", (data) => {
+  data.options[option].scores[criterion] = score;
+});
+```
+
+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 `DocKit.drag` (Script, above), the board's: pointer events, which work with touch too, a threshold, Escape and a marker, written once. 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 block's template and examples, and the manifest's `schema` says the newest its script reads. An instance past that, or one whose `data-doc-schema` is no number, was written by a newer version of the block: it is read-only whole, its text parts too, `context.canEdit()` is false for it, the block shows it read-only, and `gallery check` says so in a note. A block upgrade never touches a document: to move content to a new shape, change it as a task of its own.