@heycys/gallery 0.1.0 → 0.1.2

package/packs/gallery-soft/pack.json

@@ -0,0 +1,8 @@
+{
+  "id": "gallery-soft",
+  "name": { "zh": "柔光风格", "en": "Soft style" },
+  "description": { "zh": "柔和的配色、圆润的卡片：首页卡片的另一种样子。", "en": "Soft colors and rounded cards: another look for the home page's cards." },
+  "version": "1.0.0",
+  "author": "Gallery",
+  "icon": "🌷"
+}

package/release.json

@@ -1,25 +1,27 @@
 {
   "name": "@heycys/gallery",
-  "version": "0.1.0",
-  "built": "2026-11-06T10:00:52.739Z",
+  "version": "0.1.2",
+  "built": "2026-11-09T12:40:13.596Z",
   "stamps": {
-    "editor": "295752d9b9a9fa1b",
+    "editor": "3e8a535e1b3305fd",
     "kit": {
-      "styles": "564765b3cbdaa4a4",
+      "styles": "b4df48c5b58e5996",
       "katex-styles": "81d0a0b4dcb41846",
-      "runtime": "7962ca56c811916f",
-      "code": "0a5cdb6e4d87b122",
-      "state": "48e779637984ca20",
+      "runtime": "2e70af13bb7f6272",
+      "code": "ac7030c365b49692",
+      "state": "d4a528bd33704119",
       "sheets": "fda7b7b754e01019",
       "tokens": "a218d5d5f9008530",
-      "ui": "2dd7ea87c2703215",
+      "ui": "9d426d38850cc54f",
       "dialogs": "42866e832540bf9f",
       "katex": "1b0a973a02ab84f0",
       "katex-auto-render": "63e7162ddec186d6",
-      "math": "623acde1bb2dba91",
+      "math": "af1582414dca108c",
       "d3": "9f5a21b6070f8353",
-      "charts": "ae38e5e52ab30cef",
-      "tables": "7154e8327052d2b8"
+      "charts": "22bde4e5900579fe",
+      "tables": "7ab99911557a2efe",
+      "board-styles": "021119be212eaf56",
+      "board": "15007a0cd8566621"
     }
   }
 }

package/sdk/doc-kit.d.ts

@@ -3,15 +3,22 @@ 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.
+ * 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,
+ * 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. */
@@ -27,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. */
@@ -41,7 +299,12 @@ export interface DocComponentContext {
   frame(draw: () => void): void;
   /** Say this instance failed: it ends there, even as `mount` runs, and shows what it holds, read-only. */
   fail(error: unknown): void;
-  /** The first element of a part of the manifest, or null. A name the manifest does not have throws. */
+  /**
+   * The first element of a part of the manifest in this instance's own markup, or null. A part edited as
+   * flow gives its slot (data-doc-slot), whose blocks are the document's, the reader's: read it (its
+   * height, its words, its headings), and never write in it, move it or take it off. A name the manifest
+   * does not have throws.
+   */
   part(name: string): HTMLElement | null;
   /** This instance's reading state, of no other instance of the package: the same object at every mount. */
   state<T extends Record<string, unknown>>(options: DocComponentStateOptions<T>): DocState<T>;
@@ -59,11 +322,97 @@ export interface DocComponentContext {
    * draft, or leaves what a file cannot hold (a script, a handler, an element that does not read back as
    * itself, its own tag changed): nothing has happened then, and the console says why. Undo puts the
    * part back and `source` tells you, like any change of it. A name the manifest does not have, or a
-   * part not edited as data, throws. A list of names changes those parts in one write, one undo step (a
+   * part not edited as data (a text part, a slot), throws. A list of names changes those parts in one write, one undo step (a
    * gesture that moves a card and counts the move): `change` is handed a draft of each, by its name, and
    * 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. */
@@ -86,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;
@@ -101,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. */
@@ -129,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>;
 }