@heycys/gallery 0.1.1 → 0.2.0

package/packs/gallery-soft/weather/writing.md

@@ -0,0 +1,28 @@
+# 天气 (gallery-soft/weather)
+
+A card for a custom page (its places are `page`): a city's weather now (the sky's picture and words, the temperature, today's highest and lowest, how it feels, the humidity and the wind) and, on a tall card, the next five days. The data comes from Open-Meteo (open-meteo.com), which needs no key. Use it when the user asks for the weather on a page, its home page among them.
+
+It is 柔光风格's (the pack `gallery-soft`, off until the user turns it on in 设置 › 组件列表): the same card as Gallery 风格's `gallery/weather`, its settings, its data and what the user does on it the same, in the soft look of design A (a faint wash of blue from the card's top, rounded chips, big numbers). Write it only where the user asked for 柔光风格 or the page already holds its cards.
+
+## Settings
+
+Its two settings are the card's form, which the user opens from the grip at the card's top right › 设置…:
+
+| Key | Label | Type | What it is |
+| --- | --- | --- | --- |
+| `city` | 城市 | text | the city, as the user names it: 上海, 杭州, Berlin; looked up by that name, its first match taken |
+| `unit` | 单位 | select | `℃` (the default) or `℉` |
+
+They are kept in its data part `settings`, a `<script type="application/json">`, as example.html does: `{"city":"上海","unit":"℃"}` (on one line and compact, as the card's 设置… writes it back). The city is the one setting it cannot show anything without (`required` in its manifest): when the user did not say which, ask them, or take it from what the workspace says of where they live (写作偏好, the documents; a trip is not a home: ask when that is a guess), and tell them in the handoff which you did; never hand over a card with no city unsaid. `gallery page add <slug> gallery-soft/weather --set city=上海` writes it with the add (`--set unit=℉` the unit); for a card already there, write the city in its settings part. `{}` (template.html, what a menu adds) is a card with no city yet, which asks for one (右上角手柄 › 设置…), and `gallery page check` notes it. The block reads them and writes nothing.
+
+## Going online
+
+Its needs name the two hosts it reaches, `net:api.open-meteo.com` (the weather) and `net:geocoding-api.open-meteo.com` (a city's name to its coordinates). Gallery fetches nothing for it until the user allows those: the card then shows 允许访问 api.open-meteo.com 等 2 个网站, a press of which opens Gallery's consent dialog, and the card fetches once the user says yes. Tell the user so when you put the card on a page ("点卡片上的「允许访问」"). They can take it back in 设置 › 组件列表 (允许联网). Never write the consent into gallery.json yourself: it is the user's to give.
+
+## How to write it
+
+Put it on a custom page as a card of its board, `<section class="gallery-card" data-card-id="…" data-x data-y data-w data-h>`, holding one instance, after `gallery block add gallery-soft/weather`, the instance as template.html has it, then its settings as above (`gallery page add <slug> gallery-soft/weather` does the card for you). Sizes: 4 × 2 (the default: now, the range and how it feels, the humidity and the wind), 2 × 2 (the temperature and the sky alone) and 4 × 4 (and the next five days).
+
+## How it looks
+
+The city beside a pin's chip and when the weather was fetched (更新于 14:05) at the top, the sky's picture in its own colors (the sun, a cloud and its shade, rain) and the temperature large beside it, the sky's words and the range beside them, the humidity and the wind under them after small pictures (on a 4 × 4 card how it feels too, and the next five days under a hairline, each its sky and its lowest and highest at the ends of a bar drawn against the whole five, warm toward the top, now ringed on today's); a 2 × 2 card the temperature beside the picture, the sky's words and the range under them; in 柔光风格's soft look (as every card of it: a faint wash of blue from the card's top, a head of a rounded tinted chip and a title, its end clear of the card's grip), light and dark. It is fetched again when its settings change and every 30 minutes. While there is nothing to show it says why on a soft disc: 写上一个城市 (no city), 找不到「…」 (a name Open-Meteo does not know), 允许联网之后显示天气 (waiting for the user's consent, the kit's button over it), 现在连不上网，取不到天气 (no network, and nothing fetched before), 网络设置把天气服务指向了本地地址 (this computer's network setup gives Open-Meteo's names an address of this computer or of a private network, which Gallery refuses). The script runs with the rights of the page's own scripts, as any block's does.

package/release.json

@@ -1,25 +1,27 @@
 {
   "name": "@heycys/gallery",
-  "version": "0.1.1",
-  "built": "2026-11-07T19:54:21.173Z",
+  "version": "0.2.0",
+  "built": "2026-11-10T06:00:12.267Z",
   "stamps": {
-    "editor": "7973798600a49543",
+    "editor": "730eb4fe396a3d82",
     "kit": {
-      "styles": "352e294997d57222",
+      "styles": "90714ca047271da8",
       "katex-styles": "81d0a0b4dcb41846",
-      "runtime": "5f0ec1aab5218879",
-      "code": "0a5cdb6e4d87b122",
-      "state": "48e779637984ca20",
+      "runtime": "ccf037942f0fee28",
+      "code": "f893c8b464096161",
+      "state": "d4a528bd33704119",
       "sheets": "fda7b7b754e01019",
       "tokens": "a218d5d5f9008530",
-      "ui": "c2df5a6e42253acc",
+      "ui": "6ab6d809a853b59a",
       "dialogs": "42866e832540bf9f",
       "katex": "1b0a973a02ab84f0",
       "katex-auto-render": "63e7162ddec186d6",
       "math": "af1582414dca108c",
       "d3": "9f5a21b6070f8353",
-      "charts": "ae38e5e52ab30cef",
-      "tables": "5138346c9a693efb"
+      "charts": "22bde4e5900579fe",
+      "tables": "f776dc063389a916",
+      "board-styles": "338f6b6b6145b4dc",
+      "board": "15007a0cd8566621"
     }
   }
 }

package/sdk/doc-kit.d.ts

@@ -4,15 +4,21 @@ import type { DocState } from "./doc-state.js";
  * What an instance can hear (`on`). `editable`: `context.canEdit()` has just become true, for one mounted before the page came to edit.
  * `content`: a change inside the instance, heard only with `owns: false`, as what a component owns the
  * kit does not watch; a change of what the file says of it is `source`, whatever it owns: of a part edited
- * as text or data, or of the blocks a slot holds (a part edited as flow), typed, moved in or out, undone.
+ * as text or data, or of the blocks a slot holds (a part edited as flow), typed, moved in or out, undone,
+ * an attribute that says something of the file among them (a to-do item checked, a cell's spans, a look
+ * class), none an instance among those blocks draws; told in the next frame, a frame's changes in one.
+ * `clock`: each whole minute of the reader's clock, its detail "minute", or "day" for the first of a day.
+ * `data`: what the workspace holds changed, its detail the kind (`"todos"`, `"recent"`, `"stats"`, `"activity"`):
+ * heard for the kinds this instance read with `context.workspace.query`; read it again then. For a view of a
+ * table (the manifest's needs hold `"tables"`) the detail is `"table"`: the rows of the table it reads changed.
  */
-export type DocComponentSignal = "source" | "resize" | "theme" | "layout" | "viewport" | "fonts" | "content" | "reveal" | "editable";
+export type DocComponentSignal = "source" | "resize" | "theme" | "layout" | "viewport" | "fonts" | "content" | "reveal" | "editable" | "clock" | "data";
 
 /** What a component's `mount` returns, all of it optional. */
 export interface DocComponentHandle {
   /**
    * A signal it asked for (`on`). `detail`: the mutation records of `source` and `content`; the faces of a
-   * later `fonts`. `options.quiet`: on `content`, a change that leaves the page looking as it was.
+   * later `fonts`; of `data`, the kind that changed ("table": the rows of the table a view reads). `options.quiet`: on `content`, a change that leaves the page looking as it was.
    */
   update?(reason: DocComponentSignal, detail?: unknown, options?: { quiet?: boolean }): void;
   /** The host left the page. What listens on `context.signal` goes by itself. */
@@ -28,6 +34,257 @@ export interface DocComponentStateOptions<T extends Record<string, unknown>> {
   transientKeys?: Array<keyof T & string>;
 }
 
+/** A link a row's cells hold to a document of the workspace, or to a block of one. */
+export interface DocRowLink {
+  /** The document's folder name: of this document for a link within it. */
+  slug: string;
+  /** The link's words. */
+  title: string;
+  /** The block's id, or null for the document. */
+  block: string | null;
+}
+
+/** A row of a table a part holds (`context.rows`), or of the table a view reads (`context.table()`), as it reads it when it is asked. */
+export interface DocRow {
+  /** The row on the page: read it, never write it (a write is `add`, `move`, `remove`, and a view's `set`). */
+  readonly el: HTMLTableRowElement;
+  /** Its values by the header's words: a number where a cell writes one, its words, or null for none (as a chart drawn from a table reads them). */
+  readonly values: Readonly<Record<string, string | number | null>>;
+  /** The links its cells hold to documents. */
+  readonly links: readonly DocRowLink[];
+}
+
+/**
+ * The rows of the table a part is or holds, read when `context.rows` is called: its header's words and
+ * the rows of its body. Each write is one `context.edit` of the part, one undo step, false where it
+ * was not taken, as `edit`'s; a row added, moved or removed takes the blank before it along, so a table
+ * written a row a line stays so. Read the rows again after a write: on `source`.
+ */
+export interface DocRowSet {
+  /** The header's words, in order. */
+  readonly columns: readonly string[];
+  readonly rows: readonly DocRow[];
+  /** A row of these values (by the header's words; a name the header does not have throws), after `at.after`, or last. */
+  add(values: Record<string, string>, at?: { after?: DocRow }): boolean;
+  /** `row` put before `to.before`, or after `to.after`, its cells of `to.values` set in the same write (a card dropped in another column: its status and its place); neither leaves it where it is. */
+  move(row: DocRow, to: { before?: DocRow; after?: DocRow; values?: Record<string, string> }): boolean;
+  /** `row` taken out. */
+  remove(row: DocRow): boolean;
+}
+
+/**
+ * The table of the document a view reads (`context.table()`, for a block whose manifest's needs hold
+ * "tables", bound to the table by the key on its instance, data-doc-from, which the table's frame carries
+ * as data-doc-chart-source), read when it is called, in the file's order (a reader's sort of the table
+ * leaves it): its header's words and its rows of data, as a chart drawn from the table reads them. A row
+ * is the same object until it, or the header, changes, so that a view keeps what it drew of a row while
+ * that row is the same. No write is a write of the view's: `set`, `add`, `move` and `remove` each ask
+ * the page editor, which changes the table as its own tools do (one undo step; a cell's words merged word
+ * by word with someone else's, a row moved, put in or taken out held back as a conflict where the table
+ * changed meanwhile), and answer whether it did: false in an export, in 演示视图, before the page edits,
+ * for a table the editor's tools do not manage (one with merged cells, or not written as the kit writes
+ * one), and for a row no longer in the table; a name the header does not have throws. Its own sort and
+ * filter a view keeps in `context.state`, never in the table.
+ */
+export interface DocTableView extends DocRowSet {
+  /** Whether the page editor would take a change of this table now, asked with no change: false where every change answers false whatever it is (an export, 演示视图, before the page edits, a table the editor's tools do not manage: a `<tfoot>`, rows of other lengths), so that a view shows it read-only. */
+  canEdit(): boolean;
+  /** One cell's words: the cell of `column` (a name of the header) in `row`. */
+  set(row: DocRow, column: string, text: string): boolean;
+  /** `listener` called once a change of the page leaves the table's rows other than they were (a cell typed in, a row added, moved or taken out, the table or the view's key changed); the function returned takes it off, as the instance's end does. A view that hears `data` (detail "table") needs none. */
+  subscribe(listener: () => void): () => void;
+}
+
+/** A card's size on a custom page: in the grid's cells as the board draws it (1 to 12 wide, no more than the board's columns, 4 on a narrow window; 1 to 24 high), and in pixels, what the card holds inside its padding. */
+export interface DocComponentSize {
+  w: number;
+  h: number;
+  width: number;
+  height: number;
+}
+
+/** Where a to-do stands, what names it to its document whether or not its item has a block id. */
+export interface DocTodoRef {
+  /** Its document's folder name. */
+  slug: string;
+  /** Its item's block id (data-block-id), or null for one written with none yet. */
+  block: string | null;
+  /** Its words. */
+  text: string;
+  /** The headings it stands under, the outermost first. */
+  path: string[];
+  /** Which of the to-dos of the same words under the same path it is, 0 the first. */
+  nth: number;
+  /** The version of its document's file it was read from (a hash), by which a check finds it by its place while the file is still that one; null where none is known. */
+  version?: string | null;
+}
+
+/** A to-do of a document of the workspace (`workspace.query("todos")`): an item of a to-do list. */
+export interface DocTodo {
+  ref: DocTodoRef;
+  /** Its words. */
+  text: string;
+  /** Checked. */
+  done: boolean;
+  /** Its document's folder name and title. */
+  slug: string;
+  title: string;
+  /** The headings it stands under, the outermost first. */
+  path: string[];
+}
+
+/** A document of the workspace as `workspace.query("recent")` lists it, the one edited last first. */
+export interface DocRecentDocument {
+  slug: string;
+  title: string;
+  /** Its page icon as its doc.json writes it (an emoji, or an icon's or a picture's value), or null. */
+  icon: string | null;
+  /** When its file was last written, an ISO time. */
+  edited: string;
+}
+
+/** The workspace's counts (`workspace.query("stats")`). */
+export interface DocWorkspaceStats {
+  /** Its documents (not the 写作偏好 page, nor a custom page). */
+  documents: number;
+  /** Its to-dos, checked and all. */
+  todos: { done: number; total: number };
+  /** The words of all its documents. */
+  words: number;
+  /** How many documents were written since this week's Monday, 0:00. */
+  editedThisWeek: number;
+}
+
+/** A day of the workspace's record of edits (`workspace.query("activity")`), of every document. */
+export interface DocActivityDay {
+  /** YYYY-MM-DD, the server's local day. */
+  date: string;
+  /** The writes that changed a document that day. */
+  edits: number;
+  /** The net change of words that day (below 0 where more went than came). */
+  words: number;
+  /** Of those, the reader's own (their commits on the page) and the Agent's (any other write). */
+  reader: { edits: number; words: number };
+  agent: { edits: number; words: number };
+}
+
+/** A row of a table of a document as `workspace.query("table")` gives it: its values by the header's words, the links its cells hold to documents. */
+export interface DocWorkspaceRow {
+  values: Record<string, string | number | null>;
+  links: { slug: string; title: string; block: string | null }[];
+}
+
+/** What `workspace.query("table")` gives: the header's words, the rows asked for (the first `limit`), and how many rows matched in all. */
+export interface DocWorkspaceTable {
+  columns: string[];
+  rows: DocWorkspaceRow[];
+  total: number;
+}
+
+/** What `workspace.query` resolves to: its data, and when it was read (an ISO time; in an exported file, when the export was made). */
+export interface DocWorkspaceAnswer<T> {
+  data: T;
+  at: string;
+}
+
+/**
+ * What a block reads of the workspace, where its manifest's `needs` hold `"workspace"` (no consent asked:
+ * it is the user's own). A query that cannot be answered rejects with an Error whose `code` says why, one
+ * of these and never another: "offline" (an exported file whose export kept none of it, or a server that does
+ * not answer: show that the data is Gallery's), "failed" (the server answered and could not read it: show
+ * that it could not be read), "missing" (`table`: no such document, no table of that key in it, or one with
+ * merged cells), "kind", "options", "unsupported" (which no server of this version says). In an exported
+ * file each kind is answered from what the export embedded (to-dos 200 at most, documents 50, the tables
+ * the document's blocks asked for), `at` the export's time: say "截至 …" with it.
+ */
+export interface DocWorkspace {
+  /** The to-dos of the documents, of those edited last first, each in its document's order (`limit` default 200, at most 1000). */
+  query(kind: "todos", options?: { done?: boolean; slugs?: string[]; limit?: number }): Promise<DocWorkspaceAnswer<DocTodo[]>>;
+  /** The documents edited last (`limit` default 10, at most 50). */
+  query(kind: "recent", options?: { limit?: number }): Promise<DocWorkspaceAnswer<DocRecentDocument[]>>;
+  query(kind: "stats", options?: Record<string, never>): Promise<DocWorkspaceAnswer<DocWorkspaceStats>>;
+  /** The last `days` days to today (default 365, at most 371: 53 weeks, as long as the record is kept), a day of none 0, from the day the record started at the earliest. */
+  query(kind: "activity", options?: { days?: number }): Promise<DocWorkspaceAnswer<DocActivityDay[]>>;
+  /** A keyed table of a document (its frame's data-doc-chart-source), read-only: its rows whose cells hold the words `where` names (`limit` default 200, at most 1000). A column the table does not have rejects with "options". */
+  query(kind: "table", options: { slug: string; key: string; where?: Record<string, string>; limit?: number }): Promise<DocWorkspaceAnswer<DocWorkspaceTable>>;
+  /** Open a document (at a block of it) or a custom page where the page is shown: the workbench, else the page itself goes there; nothing in an exported file. */
+  open(target: { slug: string; block?: string | null } | { page: string }): void;
+  /**
+   * Check (`done` true) or clear a to-do of a document, by the ref `query("todos")` gave: the server writes that
+   * document as the reader's edit (an open page of it merges it; on a custom page, its undo checks it back).
+   * Resolves to whether it changed the document (false: it said so already). Rejects with `code`: "changed"
+   * (the item is not as read: its words changed, or it is gone; read again), "ambiguous" (several items alike
+   * and the file changed since), "locked" (the item is there, where the document's own page cannot check it: in a table cell, in a block of the document's own), "missing", "busy", "offline" (nothing on the page writes the workspace),
+   * "ref", "failed". Not there in an exported file: test `if (workspace.setTodo)` and draw the boxes read-only.
+   */
+  setTodo?(ref: DocTodoRef, done: boolean): Promise<boolean>;
+}
+
+/** Where a drag would drop: the element the marker goes in, and the child of it the marker goes before (null: its end). */
+export interface DocDropSpot {
+  into: Element;
+  before: Node | null;
+}
+
+/** What `DocKit.input` takes. */
+export interface DocInputOptions {
+  /** Hears each value the reader is done with, once: Enter, the field left, a select changed; never while an input method composes. */
+  commit(value: string): void;
+  /** Ends what it listens to (`context.signal`). */
+  signal?: AbortSignal;
+}
+
+/** What `DocKit.input` returns. */
+export interface DocInputHandle {
+  /** The value the file holds now, drawn from a part: shown unless the reader is typing another there. */
+  set(value: string): void;
+  /** The value committed last, or set. */
+  readonly value: string;
+}
+
+/** What `DocKit.drag` takes. */
+export interface DocDragOptions<S extends DocDropSpot> {
+  /** What a press starts a drag on, a selector inside the area. */
+  items: string;
+  /** Where in an item a press starts one, a selector (default: anywhere in it). */
+  handle?: string;
+  /** How far, in pixels, a press moves before it is a drag (default 4). */
+  threshold?: number;
+  /** Whether a drag may start now (default: always): `() => context.canEdit()`. */
+  enabled?: () => boolean;
+  /** An element of the component's that stands where a drop would go, while one would. */
+  marker?: Element | null;
+  /** Where a drop at (x, y), the pointer's place in the window, goes, or null for nowhere. */
+  over(x: number, y: number, item: HTMLElement): S | null;
+  /** The item released over a spot: the write, one `context.edit`. */
+  drop(item: HTMLElement, spot: S): void;
+  /** Ends what it listens to (`context.signal`). */
+  signal?: AbortSignal;
+}
+
+/** What `DocKit.drag` returns. */
+export interface DocDragHandle {
+  /** Give up a drag going on, as Escape does: nothing dropped. */
+  cancel(): void;
+  /** Whether an item is being dragged. */
+  readonly dragging: boolean;
+}
+
+/** A row of `DocKit.choose`'s menu: `[value, words]`, `{ value, label?, disabled? }`, a bare string (its own value and words), or `{ group }`, a heading that is no row. */
+export type DocChoice = [value: string, label: string] | { value: string; label?: string; disabled?: boolean } | { group: string } | string;
+
+/** What `DocKit.choose` takes. */
+export interface DocChooseOptions {
+  /** The rows of the menu, in order. */
+  options: DocChoice[];
+  /** The value checked (and lit first), if any. */
+  value?: string | null;
+  /** The menu's name for a screen reader. */
+  label?: string;
+  /** Closes the menu without a choice when it aborts (`context.signal`). */
+  signal?: AbortSignal;
+}
+
 /** What `mount` is given for a package's instance. */
 export interface DocComponentContext {
   /** The instance's element. */
@@ -70,6 +327,92 @@ export interface DocComponentContext {
    * two that are one element, or one in the other, throw.
    */
   edit<P extends string | string[]>(part: P, change: (draft: P extends string[] ? Record<string, HTMLElement> : HTMLElement) => void): boolean;
+  /**
+   * What a part holds, parsed as JSON (a script of data's), JSON's null too; undefined where there is
+   * nothing to read: an optional part the instance does not hold, and one that holds no JSON, which
+   * fails the instance, as `fail` does.
+   */
+  readJSON(part: string): any;
+  /**
+   * `edit` of a part of JSON: `change` is handed what it holds, parsed, and changes it, or returns what is
+   * to stand there instead. Written back as it was laid out (on one line where it was on one, else a line
+   * an entry, but for an object or a list of values alone), so that a change of one value changes its
+   * line; a change that leaves the value as it was writes nothing. Returns what `edit` returns.
+   */
+  editJSON(part: string, change: (draft: any) => any): boolean;
+  /** The rows of the table a part is or holds, or null for none, or one with a cell spanning others. */
+  rows(part: string): DocRowSet | null;
+  /**
+   * The table of the document this instance is a view of (its data-doc-from), for a block whose
+   * manifest's needs hold "tables": null with none (no key, no table carries it, a cell spanning others),
+   * on a custom page, and for a block whose needs do not hold "tables" (the console says so once).
+   */
+  table(): DocTableView | null;
+  /** `setInterval`, cleared as the instance ends; what it runs is the instance's (its failure the instance's). */
+  interval(run: () => void, ms: number): number;
+  /** `setTimeout`, cleared as the instance ends; what it runs is the instance's. */
+  timeout(run: () => void, ms: number): number;
+  /** `addEventListener`, removed as the instance ends (or as `options.signal` aborts). */
+  listen<K extends keyof WindowEventMap>(target: Window, type: K, listener: (event: WindowEventMap[K]) => void, options?: AddEventListenerOptions | boolean): void;
+  listen<K extends keyof DocumentEventMap>(target: Document, type: K, listener: (event: DocumentEventMap[K]) => void, options?: AddEventListenerOptions | boolean): void;
+  listen<K extends keyof HTMLElementEventMap>(target: HTMLElement, type: K, listener: (event: HTMLElementEventMap[K]) => void, options?: AddEventListenerOptions | boolean): void;
+  listen(target: EventTarget, type: string, listener: (event: Event) => void, options?: AddEventListenerOptions | boolean): void;
+  /** Where the instance is: a document as Gallery shows it, a custom page, or an exported file (where nothing writes). */
+  readonly place: "document" | "page" | "export";
+  /** Its card's size on a custom page, read when asked (`layout` says it changed); null anywhere else. */
+  readonly size: DocComponentSize | null;
+  /** What it reads of the workspace: there where its manifest's `needs` hold `"workspace"`, else undefined. `data` says what it read changed. */
+  readonly workspace?: DocWorkspace;
+  /**
+   * The web, for a block whose manifest's needs name the host ("net:<host>", "net:*.<host>" for the names
+   * under it): an absolute http or https address on it, asked of Gallery's server, which fetches it (a GET,
+   * no cookie, the answer JSON or text, 512 KB at most), keeps it a minute and keeps what it got for when
+   * the network is not there. `as`: "json" (the default: `data` is its JSON) or "text". `{key}` in the
+   * address is where the server writes the workspace's key for that host (gallery block key), which no
+   * page ever holds. Resolves with the answer and when it was fetched (`cached`: given from what was kept,
+   * which may be old where the network is not there). Rejects with a DocFetchError: "consent" until the
+   * reader allows it, on the card the kit then shows 允许访问 <host> on (draw your own state too, and the
+   * instance starts again once the reader says yes or takes it back). In an exported file nothing is
+   * fetched: what the export embedded of the address, or "offline", for the block to show a placeholder.
+   * Not there for a block whose needs name no host of the net (declared here as always there, so that a
+   * block that names one need not ask).
+   */
+  fetch(url: string, options?: { as?: "json" | "text" }): Promise<DocFetchAnswer>;
+}
+
+/** What `context.fetch` resolves with. */
+export interface DocFetchAnswer {
+  /** The answer's JSON (as "json") or its text (as "text"). */
+  data: any;
+  /** When it was fetched, an ISO time. */
+  at: string;
+  /** Whether it was given from what was kept, not fetched now. */
+  cached: boolean;
+}
+
+/** Why `context.fetch` was refused: its `code`. */
+export type DocFetchCode = "consent" | "host" | "url" | "private" | "key" | "rate" | "status" | "type" | "too-large" | "offline" | "missing";
+
+/** What `context.fetch` rejects with. */
+export interface DocFetchError extends Error {
+  /**
+   * consent: the reader has not allowed it yet; host: its needs do not name the address's host (or a
+   * redirect's); url: no address it may ask for (not http(s), another port, a user in it), its own or a
+   * redirect's (or a redirect to an address that does not parse); private: the host is this computer or
+   * a private network as this computer's resolver answered it, with no proxy of this computer to take
+   * its name (usually the reader's network setup, not the block: the message names the address); key:
+   * the address names `{key}` and the workspace has none for that host; rate: too many fetches a
+   * minute; status: the site answered an error (`status`);
+   * type: no JSON or text (or no JSON asked as JSON); too-large: more than 512 KB; offline: the network
+   * or the site not reached, and nothing kept (in an exported file: nothing embedded); missing: the block does not load.
+   */
+  code: DocFetchCode;
+  /** The hosts of its needs the reader has not allowed yet (consent). */
+  hosts?: string[];
+  /** The host refused (host, private, key). */
+  host?: string;
+  /** The site's status (status). */
+  status?: number;
 }
 
 /** What a package's kit.js registers. */
@@ -92,7 +435,7 @@ export interface DocComponent {
    */
   dehydrate?(host: HTMLElement): void;
   /**
-   * A small edit, as a reader's gesture would make it, by `context.edit`: what `gallery component check`
+   * A small edit, as a reader's gesture would make it, by `context.edit`: what `gallery block check`
    * calls to try the way back to the file. Nothing else calls it.
    */
   example?(host: HTMLElement, context: DocComponentContext): void;
@@ -107,6 +450,30 @@ declare global {
   type DocComponentSignal = import("./doc-kit.js").DocComponentSignal;
   /** What kit.js registers. */
   type DocComponent = import("./doc-kit.js").DocComponent;
+  /** A row of a table a part holds (`context.rows`). */
+  type DocRow = import("./doc-kit.js").DocRow;
+  /** The rows of a table a part holds (`context.rows`). */
+  type DocRowSet = import("./doc-kit.js").DocRowSet;
+  /** The table of the document a view reads (`context.table()`). */
+  type DocTableView = import("./doc-kit.js").DocTableView;
+  /** A card's size on a custom page (`context.size`). */
+  type DocComponentSize = import("./doc-kit.js").DocComponentSize;
+  /** Where a drag would drop (`DocKit.drag`'s `over`). */
+  type DocDropSpot = import("./doc-kit.js").DocDropSpot;
+  /** What `context.fetch` resolves with. */
+  type DocFetchAnswer = import("./doc-kit.js").DocFetchAnswer;
+  /** What `context.fetch` rejects with: its `code` says why. */
+  type DocFetchError = import("./doc-kit.js").DocFetchError;
+  /** What a block reads of the workspace (`context.workspace`), and what it gives. */
+  type DocWorkspace = import("./doc-kit.js").DocWorkspace;
+  type DocTodo = import("./doc-kit.js").DocTodo;
+  type DocTodoRef = import("./doc-kit.js").DocTodoRef;
+  type DocWorkspaceRow = import("./doc-kit.js").DocWorkspaceRow;
+  type DocWorkspaceTable = import("./doc-kit.js").DocWorkspaceTable;
+  type DocRecentDocument = import("./doc-kit.js").DocRecentDocument;
+  type DocWorkspaceStats = import("./doc-kit.js").DocWorkspaceStats;
+  type DocActivityDay = import("./doc-kit.js").DocActivityDay;
+  type DocWorkspaceAnswer<T> = import("./doc-kit.js").DocWorkspaceAnswer<T>;
 }
 
 /** How much the kit runs now. */
@@ -135,13 +502,37 @@ export interface DocKitApi {
   quietly<T>(change: () => T): T;
   /** Take what the kit and its components left off `root`, a copy of the page. */
   dehydrate<T extends Element>(root: T): T;
-  /** The component on `host` makes its `example` of an edit, as `gallery component check` asks it. Whether it has one. */
+  /** The component on `host` makes its `example` of an edit, as `gallery block check` asks it. Whether it has one. */
   example(host: Element): boolean;
   /** Open what hides an element, and bring it into view. */
   reveal(element: Element): void;
+  /**
+   * A field whose value goes to the file when the reader is done with it: `commit` hears it on Enter (in
+   * a textarea Ctrl+Enter), as the field is left or a select changes, never while an input method
+   * composes and never twice; Escape puts back the value committed last.
+   */
+  input(field: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement, options: DocInputOptions): DocInputHandle;
+  /**
+   * A drag of what `items` finds in `area`, by pointer events: past a threshold, a `marker` where a drop
+   * would go (`over`), `drop` on a release over a spot, nothing on Escape or a release elsewhere; the
+   * item carries the class `doc-dragging` while it moves.
+   */
+  drag<S extends DocDropSpot>(area: HTMLElement, options: DocDragOptions<S>): DocDragHandle;
+  /**
+   * The kit's menu of choices under `anchor`, a button of the block's own: the card every `<select>` of the
+   * page opens (flat, rounded, the chosen row checked, light and dark as the page is; ↑ ↓ Enter, a letter, Esc).
+   * Resolves with the value chosen, or null when it is dismissed (Esc, a press outside, `signal`, the anchor
+   * leaving the page); called again on the anchor of a menu that is open, it closes it. Never the browser's
+   * popup: a `<select>` needs no call (the kit opens this menu for it), and a menu a block draws itself is not
+   * to look like the browser's.
+   */
+  choose(anchor: Element, options: DocChooseOptions): Promise<string | null>;
+
   stats(): DocKitStats;
   /** The keys of the page's bound controls. */
   readonly bindings: unknown;
   /** The selectors of the elements blocks stand in. */
   readonly flows: readonly string[];
+  /** The tables of the page a key names, as the kit's charts drawn from a table and the views of one read them: the kit's own (a view reads its table by `context.table()`). */
+  readonly tables: unknown;
 }

package/sdk/doc-state.d.ts

@@ -27,6 +27,8 @@ export interface DocStateOptions<T extends Record<string, unknown>> {
   defaults: T;
   /** Overrides the browser storage key; normally left out. */
   storageKey?: string;
+  /** A name the state was kept under before (a component's instance before it had a block id): read when nothing is kept under `id`, and carried to it. */
+  formerId?: string;
   /** Default: []; excluded from browser restoration and exported snapshots. */
   transientKeys?: Array<keyof T & string>;
 }