@heycys/gallery 0.1.0 → 0.1.2

package/browser/shared/component-source.mjs

@@ -0,0 +1,37 @@
+// What a component that hears `source` hears of attributes (src/render/kit/runtime/kernel.js;
+// docs/render.md "A custom block on a page"): a change of an attribute in a part or a slot that says
+// something of the file, and of a class only where a look class changes, so that what the kit and the
+// editor toggle as they lay the page out is no change of the file's.
+
+import { COLOR_NAMES } from "./colors.mjs";
+
+/**
+ * The attributes that say something of the file in a part or a slot, which a component hearing
+ * `source` hears change (runtime/kernel.js): a to-do item checked, a cell's spans, what a table's
+ * header and cells say of its sort (the table description's data-sort-*, listed one by one, as an
+ * observer takes them). A class is one only where a look class changes (lookChanged); `hidden` and
+ * `open` are the reader's, which `reveal` tells.
+ */
+export const SOURCE_ATTRIBUTES = ["data-checked", "rowspan", "colspan", "data-sort-status", "data-sort-type", "data-sort-key", "data-sort-default", "data-sort-ignore", "data-sort-value", "data-sort-rank"];
+
+/**
+ * The classes that are a block's or a cell's look, which a reader sets and the file keeps: a text color
+ * or a fill (doc-text-<color>, doc-highlight-<color>), a cell's alignments and its bold (table.mjs's
+ * CELL_ALIGN_CLASSES, CELL_VALIGN_CLASSES, CELL_BOLD_CLASS, the editor's CELL_LOOKS). What the kit and
+ * the editor toggle as they lay a page out (a table's number and doc-table--auto, a code block's
+ * folds) is none, so that no component hears its own layout as a change of the file, and draws again
+ * for ever.
+ */
+export const LOOK_CLASSES = new Set([
+  ...COLOR_NAMES.flatMap((name) => [`doc-text-${name}`, `doc-highlight-${name}`]),
+  // table.mjs's CELL_ALIGN_CLASSES, CELL_VALIGN_CLASSES and CELL_BOLD_CLASS, written out: an import of that
+  // file would bring its description, prose and all, into the kit's runtime (tests/unit/installed.mjs
+  // holds the two lists together).
+  "doc-align-left", "doc-align-center", "doc-align-right", "doc-valign-top", "doc-valign-middle", "doc-valign-bottom", "doc-bold",
+]);
+
+/** Whether a class attribute's look classes (LOOK_CLASSES) differ from `before` to `after`, either null for none. */
+export function lookChanged(before, after) {
+  const looks = (value) => [...new Set(String(value ?? "").split(/\s+/).filter((name) => LOOK_CLASSES.has(name)))].sort().join(" ");
+  return looks(before) !== looks(after);
+}

package/browser/shared/components/callout.mjs

@@ -1,7 +1,9 @@
-// A callout (提示块): a basic block.
+// A callout (提示块), a container of blocks set apart on a fill, a line at its left; one written the
+// old way, words straight in it, holds them as one paragraph (the editor's natural HTML).
 export default {
   id: "callout",
-  category: "block",
+  category: "container",
   match: ".doc-callout",
+  flow: ".doc-callout",
   classes: ["doc-callout"],
 };

package/browser/shared/components/index.mjs

@@ -28,7 +28,7 @@ import table from "./table.mjs";
 import text from "./text.mjs";
 import widget from "./widget.mjs";
 import { attr, elementsOf, walk } from "../html-tree.mjs";
-import { ATTRIBUTE, INSTANCE } from "./installed.mjs";
+import { ATTRIBUTE, INSTANCE, SLOT, SLOT_PART } from "./installed.mjs";
 
 // The kit's components as every system sees them (docs/internals.md, "Components"): what each is
 // in a report's markup, one plain-data description each, shared by the kit (how it runs), the
@@ -95,8 +95,8 @@ import { ATTRIBUTE, INSTANCE } from "./installed.mjs";
 
 export const COMPONENTS = [
   page, text, mention, // the page; inline marks, links shown with their icon
-  paragraph, heading, list, quote, callout, code, divider, math, // basic blocks
-  section, highlight, details, dialog, sheets, table, columns, // containers
+  paragraph, heading, list, quote, code, divider, math, // basic blocks
+  section, highlight, callout, details, dialog, sheets, table, columns, // containers
   figure, chart, image, file, bookmark, embed, // cards (a figure: a chart or a drawing of the report's own; an image, a file, a bookmark, an embed)
   widget, diff, icon, installed, // whole blocks (the page's icon one, in the header; an instance of a component package)
   state, // reading state, bound to blocks of any kind
@@ -135,9 +135,18 @@ export const CATEGORIES = {
 export const EVENTS = {
   "doc-theme-change": "the theme shown changed (ui.js): the reader chose one, the workbench asked for one, or the system's changed while none is chosen",
   "doc-theme-request": "a workbench asks for a theme (ui.js listens)",
-  "doc-layout-change": "a card's size changed where widths do not tell (the editor)",
+  "doc-look-request": "the document's look is asked of the page (字体与布局: the page's session for the workbench, the preview's live reload for doc.json written again; ui.js puts it on <html>, src/shared/document-look.mjs)",
+  "doc-look-change": "the look the page shows changed (ui.js): the page editor's session tells the workbench",
+  "doc-layout-change": "a card's size changed where widths do not tell (the editor, a custom page's canvas), or the document's look changed (ui.js)",
+  "doc-workspace-change": "what the workspace holds changed, the kind its detail (the page's live script, as the server's \"data <kind>\" says it): the kit tells the instances that hear data and read that kind",
+  "doc-todo-set": "a block's context.workspace.setTodo asks whoever shows the page to check a to-do of a document (cancelable: a custom page's board or a document's editor cancels it and answers from the workspace's service)",
+  "doc-open-request": "a block's context.workspace.open asks to open a document or a custom page (cancelable: the page's session for the workbench answers it, else the kit goes there)",
   "doc-editable": "the page takes what a component writes from now on (the editor)",
   "doc-component-edit": "a component's context.edit asks to write a part: the editor cancels it to say it took the edit, the kit writing no file (on the instance)",
+  "doc-table-intent": "a view's context.table() asks to change the table it reads (set a cell, move, add or take out a row), or whether it would take such a change now (canEdit, op check): the editor cancels it to say it made the change (or would), one undo step, the kit writing nothing (on the instance)",
+  "doc-settings-changed": "what gallery.json says of the components changed (the page's event stream, its settings line: hidden, disabled, shown, the consents to the net, unlisted and the packs off): the editor's menus follow it, and the kit starts again an instance whose block's consent changed (runtime/net.js)",
+  "doc-net-fetch": "a block's context.fetch asks whoever serves the page to fetch for it (runtime/net.js sends it; the server's live script cancels it and answers from its net route)",
+  "doc-net-consent": "a block's 允许访问 asks the reader to let it online (runtime/net.js sends it; the page's session cancels it and the workbench opens its consent dialog)",
   "doc-export-copy-done": "导出当前视图副本 finished (ui.js)",
   "doc-table-sort": "a table's sort changed (tables/, on the table)",
   "doc-jump-request": "演示视图 asks the kit to go to a block of its own page, a step of the history (runtime/reveal.js listens, editor/page/present-links.mjs sends)",
@@ -169,9 +178,11 @@ export const FLOW_BLOCKS = `${FLOWS.join(", ")}, :is(${GROUPING_FLOWS.join(", ")
  * What the kit's runtime reads of the descriptions (runtime/kernel.js): where each component's
  * instances are (`match`) and what it leaves on the page (`runtime`), of the components that say
  * either. /kit/runtime.js carries these alone (assets.mjs, `define`), so an export holds no prose.
- * A field the kernel starts reading is added to RUNTIME_FIELDS (tests/unit/runtime.mjs checks it).
+ * A field the kernel starts reading is added to RUNTIME_FIELDS (tests/unit/runtime.mjs checks it):
+ * `needs`, what a custom block uses (its context.workspace), which only a package describes (no
+ * component of the kit has it, so the runtime carries none).
  */
-export const RUNTIME_FIELDS = ["match", "runtime", "schema"];
+export const RUNTIME_FIELDS = ["match", "runtime", "schema", "needs"];
 export const runtimeDescriptions = (components = COMPONENTS) => components
   .filter((component) => RUNTIME_FIELDS.some((field) => component[field] !== undefined))
   .map((component) => Object.fromEntries([["id", component.id], ...RUNTIME_FIELDS.filter((field) => component[field] !== undefined).map((field) => [field, component[field]])]));
@@ -239,6 +250,58 @@ export function matchesNode(node, selector) {
 /** Whether a parsed node is an instance of a component package (installed.mjs): asked of every element by every walk, so by its attribute first, which few have. */
 export const isInstance = (node) => attr(node, ATTRIBUTE) !== undefined && matchesNode(node, INSTANCE);
 
+/** Whether a parsed node is a slot of an instance (installed.mjs SLOT): a block-level div or section marked so, wherever it stands. */
+export const isSlot = (node) => attr(node, SLOT) !== undefined && matchesNode(node, SLOT_PART);
+
+// The nearest edge of a region around a parsed node (an instance or a slot, itself left out), or null.
+const edgeAround = (node) => {
+  let around = node.parentNode;
+  while (around && !(isInstance(around) || isSlot(around))) around = around.parentNode;
+  return around ?? null;
+};
+
+/**
+ * The instance whose own region a parsed node stands in, or null where it is the document's: the rule
+ * of installed.mjs heldBy, on parse5's tree (the edges folded from the outermost in: an instance's own
+ * slot opens the document's again, what stands in a component's region stays its).
+ */
+export function heldByNode(node) {
+  const edge = edgeAround(node);
+  if (!edge) return null;
+  const owner = heldByNode(edge);
+  if (isInstance(edge)) return owner ?? edge;
+  return owner !== null && edgeAround(edge) === owner ? null : owner;
+}
+
+/**
+ * Every slot of an instance's own markup, in document order (none of an instance in it, none in
+ * another slot), whatever its name: what the checks hold to its manifest.
+ */
+export function ownSlots(instance) {
+  const found = [];
+  const look = (node) => {
+    for (const child of elementsOf(node)) {
+      if (isSlot(child)) found.push(child);
+      else if (!isInstance(child)) look(child);
+    }
+  };
+  look(instance);
+  return found;
+}
+
+/** The slots of an instance, the first of each name: where what it holds is the document's (a second of a name is a failure of the checks). */
+export function instanceSlots(instance) {
+  const named = new Set();
+  return ownSlots(instance).filter((slot) => !named.has(attr(slot, SLOT)) && named.add(attr(slot, SLOT)));
+}
+
+/**
+ * How a walk (html-tree.mjs) goes through what is the document's own: it stops at an instance of a
+ * component package and goes on in its slots, never handing a slot itself to the visit (its tag is
+ * the component's, what it holds the document's).
+ */
+export const BODY = Object.freeze({ stop: isInstance, through: instanceSlots });
+
 /** A part's elements in a parsed host, each once, in document order. */
 export function partOf(host, at) {
   const pieces = piecesOf(at);
@@ -254,12 +317,12 @@ export function partOf(host, at) {
 
 /**
  * Each instance of a component in a parsed tree, in document order. What stands in an instance of a
- * component package is its component's and no other's, and such an element is of its own package
- * alone, whatever class it carries.
+ * component package is its component's and no other's, but for what its slots hold, which is the
+ * document's (BODY), and such an element is of its own package alone, whatever class it carries.
  */
 export function instancesOf(root, component) {
   const found = [];
-  if (component.match) walk(root, (element) => { if (matchesNode(element, component.match) && (!isInstance(element) || attr(element, ATTRIBUTE) === component.id)) found.push(element); }, { stop: isInstance });
+  if (component.match) walk(root, (element) => { if (matchesNode(element, component.match) && (!isInstance(element) || attr(element, ATTRIBUTE) === component.id)) found.push(element); }, BODY);
   return found;
 }
 

package/browser/shared/components/installed.mjs

@@ -2,11 +2,16 @@
 // src/shared/component-catalog.mjs): a block-level div or section naming its package, which is all a
 // system needs to tell where the instance stands. The boundary depends on no catalog, so it holds in
 // a file sent to someone who has no such package, or that has lost it: nothing of Gallery's goes into
-// an instance, whatever it holds (the scan and naturalize, the kit's other components, formulas,
-// spacing and a picture's viewer), but the parts its manifest gives the editor. The rest of it is
-// the component's, its events too. One of no package is shown as it stands, read-only, and the kit marks
-// it so (FALLBACK), a note beside what it holds in a preview, and what a script of data in it holds,
-// which no reader would see, drawn as the kit draws any (DATA_SHOWN).
+// an instance's own region, whatever it holds (the scan and naturalize, the kit's other components,
+// formulas, spacing and a picture's viewer), but the parts its manifest gives the editor. The rest of
+// it is the component's, its events too, but for its slots (SLOT: a div or section of its own markup
+// marked data-doc-slot, its manifest's part edited as "flow"), whose insides are the document's again:
+// its blocks, read, edited, checked and drawn as anywhere in a flow, by the same mark and no catalog
+// either. One rule tells whose an element is (heldBy), the same on the server (components/index.mjs
+// heldByNode), in the kit and on the page. One of no package is shown as it stands, read-only, and the
+// kit marks it so (FALLBACK), a note beside what it holds in a preview, and what a script of data in
+// it holds, which no reader would see, drawn as the kit draws any (DATA_SHOWN); its slots stay the
+// document's, and editable.
 
 /** The attribute that makes an element an instance, its value the package's id: <scope>/<name>. */
 export const ATTRIBUTE = "data-doc-component";
@@ -17,6 +22,79 @@ export const PACKAGE_ID = /^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/;
 /** Where a document's instances are: what stops every system at the edge of one. */
 export const INSTANCE = `div[${ATTRIBUTE}], section[${ATTRIBUTE}]`;
 
+/** The attribute that makes an element of an instance's own markup a slot, its value the name of the part its manifest edits as "flow". */
+export const SLOT = "data-doc-slot";
+
+/** Where slots are: a block-level div or section so marked. */
+export const SLOT_PART = `div[${SLOT}], section[${SLOT}]`;
+
+// The edges of a region: an instance, where the component's begins, and a slot, where the document's may again.
+const REGION = `${INSTANCE}, ${SLOT_PART}`;
+
+// The nearest edge of a region around a node (itself left out), or null.
+const edgeAround = (node) => node?.parentElement?.closest(REGION) ?? null;
+
+/**
+ * The instance whose own region a node of a page stands in, or null where it is the document's: the
+ * edges around it folded from the outermost in. An instance met in the document's region opens its
+ * component's; its own slot (one whose nearest edge is that instance) opens the document's again; an
+ * instance or a slot met in a component's region stays that component's. A slot itself is its
+ * instance's (the component places it), and an instance itself stands in the region around it (its
+ * frame and its handle are Gallery's). For a page's DOM; the server's is heldByNode.
+ */
+export function heldBy(node) {
+  const edge = edgeAround(node);
+  if (!edge) return null;
+  const owner = heldBy(edge);
+  if (edge.matches(INSTANCE)) return owner ?? edge;
+  return owner !== null && edgeAround(edge) === owner ? null : owner;
+}
+
+/**
+ * The region what an element holds stands in (its children, its words): the instance itself for an
+ * instance, the document's (null) inside a slot that opens it again, and otherwise the region the
+ * element stands in, as heldBy says it. heldBy for a child the element does not have yet, or has lost:
+ * where a change of what it holds happened.
+ */
+export function heldWithin(element) {
+  if (!element.matches(REGION)) return heldBy(element);
+  const owner = heldBy(element);
+  if (element.matches(INSTANCE)) return owner ?? element;
+  return owner !== null && edgeAround(element) === owner ? null : owner;
+}
+
+/** Whether an element is a slot that opens the document's region again: one of an instance that stands in the document's. */
+const opensDocument = (node) => node.matches(SLOT_PART) && heldBy(node) !== null && edgeAround(node) === heldBy(node);
+
+/**
+ * Whether what happens on an element (a press, a key, a change of what it holds) is a component's: it
+ * stands in an instance's own region. Not a slot that opens the document's (its blank is the page's
+ * box), nor an instance itself (its frame is Gallery's).
+ */
+export const componentAt = (node) => node?.nodeType === 1 && heldBy(node) !== null && !opensDocument(node);
+
+/**
+ * The slot whose inside is the document's region a node stands in (one of an instance that stands in
+ * the document's, opening it again), the nearest, or null for the page around it: where what is one
+ * block of the page's is looked for (the editor's registry.mjs ownerOf).
+ */
+export function slotAround(node) {
+  for (let at = node; at;) {
+    const owner = heldBy(at);
+    if (owner) {
+      at = owner;
+      continue;
+    }
+    const edge = edgeAround(at); // a slot, or none: no instance holds it
+    if (!edge || opensDocument(edge)) return edge;
+    at = edge; // a slot of no instance's: the region around it
+  }
+  return null;
+}
+
+/** The slots of an instance: those of its own markup (no other instance's, nor one in another slot), in document order. */
+export const slotsIn = (instance) => [...instance.querySelectorAll(SLOT_PART)].filter((slot) => edgeAround(slot) === instance);
+
 /** The kit's mark on an instance of no package, for its look (styles/installed.css). */
 export const FALLBACK = "data-doc-fallback";
 
@@ -45,8 +123,24 @@ export const PACKAGE_MARK = "data-doc-package";
  */
 export const ARRIVING = "data-ge-arriving";
 
-/** What gallery.json's lists make of a package that loads: "disabled", "hidden" or "normal". */
-export const settingState = (id, { hidden, disabled }) => (disabled.includes(id) ? "disabled" : hidden.includes(id) ? "hidden" : "normal");
+/**
+ * Whether the document's insert entries ("/", 在下方新建, the handle's grid, a table's 视图 ›) offer the
+ * block `id` whose manifest's `places` are those (left out: ["document"]), by gallery.json's lists
+ * (`settings`: hidden, shown, disabled, unlisted, packsOff, each left out for none): one that says it stands in a
+ * document is offered unless hidden; one that does not, only where shown; one disabled never, as it does
+ * not load, nor one unlisted (设置 › 组件列表's master switch off: no menu and no library offers it, what
+ * is written of it shows as ever), nor one of a pack switched off (packsOff, the ids of the packs off: the
+ * scope of its id; the same as unlisted, for a whole pack). The one rule, which the server and the page
+ * both run (notes/plans/custom-blocks-spec-2026-11-07.md section 2, block-packs-plan-2026-11-09.md §1).
+ */
+export function inDocumentMenus(places, settings, id) {
+  const { hidden = [], shown = [], disabled = [], unlisted = [], packsOff = [] } = settings ?? {};
+  if (disabled.includes(id) || unlisted.includes(id) || packsOff.includes(String(id).split("/")[0])) return false;
+  return (places ?? ["document"]).includes("document") ? !hidden.includes(id) : shown.includes(id);
+}
+
+/** What gallery.json's lists make of a package that loads, its manifest's `places` with them: "disabled", "hidden" (no document's menu offers it: inDocumentMenus, which a block unlisted is too) or "normal". */
+export const settingState = (id, settings, places) => (settings.disabled.includes(id) ? "disabled" : inDocumentMenus(places, settings, id) ? "normal" : "hidden");
 
 /** The class of the kit's note in such an instance, in a preview alone. */
 export const NOTE = "doc-component-note";
@@ -150,13 +244,21 @@ export default {
   id: "installed",
   category: "whole",
   match: INSTANCE,
+  // An instance's slots are flows: what they hold is the document's blocks (FLOWS, styles/flow.css). A
+  // plain string, [SLOT]: an expression here would keep this description in every bundle that imports a
+  // constant of this file (the runtime takes none of its prose).
+  flow: "[data-doc-slot]",
   attrs: {
     "data-doc-component": "the package an instance is of: <scope>/<name>, on a block-level div or section",
     "data-doc-schema": "the shape an instance holds its content in: a whole number its component chooses, read-only past its manifest's schema",
+    "data-doc-slot": "a slot of an instance: the part of its manifest edited as flow, by name, on a block-level div or section in the instance's own region; what it holds is the document's blocks",
+    "data-doc-from": "on an instance of a custom block whose needs hold tables: the key of the table it is a view of, which the table's frame carries as data-doc-chart-source",
   },
   runtime: {
     generated: [".doc-component-note", ".doc-component-data"],
     attrs: { "[data-doc-fallback]": ["data-doc-fallback"], "[data-doc-fallback-control]": ["data-doc-fallback-control", "inert"] },
-    internal: [PACKAGE_MARK, "doc-component-more", DATA_ONE, DATA_LINE, DATA_SHORT], // of what the kit drew of a script of data: a line saying what it left out, and its marks
+    // Of what the kit drew of a script of data: a line saying what it left out, and its marks; and the mark
+    // DocKit.drag (runtime/gestures.js) puts on what a component draws while it is dragged, a class.
+    internal: [PACKAGE_MARK, "doc-component-more", DATA_ONE, DATA_LINE, DATA_SHORT, "doc-dragging"],
   },
 };

package/browser/shared/components/page.mjs

@@ -13,6 +13,15 @@ export function pageLanguage(html) {
   return /\slang\s*=\s*["']?en(?:-[^"'\s>]*)?(?=["'\s>]|$)/i.test(tag) ? "en" : "zh";
 }
 
+/**
+ * A document's look on its <html> (字体与布局: its doc.json's look, which the render puts on and the kit's
+ * tokens read; src/shared/document-look.mjs), the attribute of each choice. The 正文宽度's is
+ * data-doc-measure (a column's measure, its line length); 全宽 (the top bar's 更多, under 目录) is
+ * data-doc-width="full", the one attribute the kit's page, the editor's room and the display menu's
+ * 全宽显示 (the reader's own switch in an export) all read: one way to be wide, not two.
+ */
+export const LOOK_ATTRIBUTES = Object.freeze({ font: "data-doc-font", size: "data-doc-size", spacing: "data-doc-spacing", width: "data-doc-measure", full: "data-doc-width" });
+
 export default {
   id: "page",
   match: "main.doc-page",
@@ -30,8 +39,18 @@ export default {
   classes: ["doc-page", "doc-header", "doc-kicker", "doc-title", "doc-button"],
   runtime: {
     generated: [".doc-display", "script[data-doc-state]"],
-    root: { attrs: ["data-doc-ready", "data-doc-drawn", "data-doc-controls"] },
-    state: { html: ["data-doc-theme", "data-doc-width"] },
-    internal: ["doc-display*", "data-doc-export-copy", "data-theme", "doc-export-id", "doc-reveal", "doc-kit-error"],
+    // data-doc-effective-theme: the theme the page shows now (ui.js), "light" or "dark", which a custom page's own colors go by.
+    // data-doc-platform: "mac" on an Apple platform (runtime/index.js sets it as the page opens), the text's color and smoothing go by it; a copy of the view lets it go, its reader's machine judges anew.
+    root: { attrs: ["data-doc-ready", "data-doc-drawn", "data-doc-controls", "data-doc-effective-theme", "data-doc-platform"] },
+    // The reader's theme (ui.js) and the document's look (字体与布局 and 全宽: its doc.json's, put on by
+    // the render, src/shared/document-look.mjs; the reader's own 全宽显示 is the same data-doc-width), which
+    // a copy of the view keeps; never written in doc.html.
+    state: { html: ["data-doc-theme", ...Object.values(LOOK_ATTRIBUTES)] },
+    internal: ["doc-display*", "data-doc-export-copy", "data-theme", "doc-export-id", "doc-reveal", "doc-kit-error", "doc-net-consent*", "data-doc-snapshot",
+      // The time an export's snapshot was made (its data-doc-snapshot tag's: render/net-snapshot.mjs), which context.workspace.query answers as `at`.
+      "data-at",
+      // A custom page's (no document's: src/render/page-html.mjs, the kit's board/): its cards' cells, the Agent's
+      // (data-x, data-y, data-w, data-h), and its boards' columns now (data-columns, board.js's).
+      "data-x", "data-y", "data-w", "data-h", "data-columns"],
   },
 };

package/browser/shared/components/state.mjs

@@ -2,7 +2,9 @@
 // a key (data-doc-bind), elements shown for a key's value (data-doc-show),
 // keys forgotten when the page is left (data-doc-transient); and the kit's styles of such
 // controls (styles/state.css). A filter (.doc-filter) is one block: its row of buttons and what
-// they filter below it (a list, say), together.
+// they filter below it (a list, say), together. A <select> of any control or block, bound or not, opens
+// the kit's menu of choices (runtime/choice.js, styles/choice.css), never the browser's popup: a card at
+// the end of <body> while it is open, nothing an author writes, which an export of the view leaves out.
 export default {
   id: "state",
   match: "[data-doc-bind], [data-doc-show]",
@@ -14,7 +16,9 @@ export default {
   classes: ["doc-state-fields", "doc-state-field", "doc-state-actions", "doc-filter", "doc-filter-row", "doc-filter-button", "doc-state-list"],
   wholes: ["doc-filter", "doc-filter-row", "doc-state-fields", "doc-state-list"], // the classes above that are a whole block of their own (the others are parts inside one)
   runtime: {
+    generated: [".doc-choice"],
     attrs: { "[data-doc-show]": ["hidden"] },
     state: { "button[data-doc-bind]": ["aria-pressed"] },
+    internal: ["doc-choice-*"], // the menu's rows, their words, the check and the group headings
   },
 };

package/browser/shared/components/table.mjs

@@ -31,7 +31,7 @@ export default {
     "data-doc-chart-source": "on its frame: the key a chart drawn from it reads it by (data-doc-chart-data on the chart's host)",
   },
   // A cell may also be given a text color or a fill (doc-text-*, doc-highlight-*: text.mjs), an alignment, a vertical one and bold
-  // (doc-bold); a header cell's look is doc-bold doc-highlight-gray, as the page editor gives it.
+  // (doc-bold); a header row's cell's look is doc-bold doc-highlight-gray, as the page editor gives it (a header column's th scope="row" none).
   classes: ["doc-table", "doc-table-wrap", "doc-table-meta", "doc-table--sticky-first", ...CELL_ALIGN_CLASSES, ...CELL_VALIGN_CLASSES, CELL_BOLD_CLASS],
   fills: { "th": ["data-sort-type"] },
   runtime: {

package/browser/shared/components/text.mjs

@@ -9,6 +9,6 @@ export default {
     ...COLORS.map((color) => `doc-highlight-${color}`),
     ...["orange", "blue", "purple", "plain", "thin", "thick"].map((kind) => `doc-underline-${kind}`),
   ],
-  // A number range in the text (3–13, 1–3B), held on one line (runtime/spacing.js).
-  runtime: { classes: { ".doc-range": ["doc-range"] } },
+  // A number range in the text (3–13, 1–3B), held on one line, and a long run (a path, a URL: src/shared/long-runs.mjs) held in a span that breaks anywhere (runtime/spacing.js).
+  runtime: { classes: { ".doc-range": ["doc-range"], ".doc-long-run": ["doc-long-run"] } },
 };

package/browser/shared/document-look.mjs

@@ -0,0 +1,183 @@
+// A document's look (字体与布局 and 全宽, under the workbench's 更多: Notion's page format, notion-lite's
+// view/frame/page-format.js, whose page_full_width is a field of the page as ours is of the document):
+// its font, the size of its text, the spacing of its lines and blocks, the width of its reading column
+// and whether it is shown at the full width of the page whatever that is (全宽). The document's own, as
+// Notion keeps it on the page: `look` in its
+// doc.json (report.json in a document made before Gallery 0.1), over the workspace's default look,
+// `look` in its gallery.json (which the card's 应用到全部文档 writes, every document's own taken away:
+// ./workspace-look.mjs), choice by choice (effectiveLook). The workspace's keeps each choice that is
+// not the default, the field gone when none is; a doc.json each choice that is not the workspace's,
+// the field gone when none is:
+//
+//   "look": { "font": "serif" | "mixed", "size": "small" | "large", "spacing": "compact" | "loose", "width": "narrow" | "wide", "full": "full" }
+//
+// A doc.json may say a default too ("font": "sans", "size": "default"…): 默认 chosen on a page while
+// the workspace's default says otherwise. The look a document shows is never written in doc.html: the
+// render puts it on the page's <html> as data attributes
+// (withLook, render/report-html.mjs: the preview, 演示视图, a build, an export, its PDF), which the
+// kit's tokens read (styles/tokens.css, @kit-look, written by render/look-css.mjs); a page takes a
+// change at once (`doc-look-request`, the kit's ui.js: the workbench's choice, sent by the page's
+// session, and doc.json changed, said by the preview's live reload). A value it does not know is the
+// default. docs/render.md "A document's look" says what each choice does.
+
+import { LOOK_ATTRIBUTES } from "./components/page.mjs";
+
+/** Each choice and its values, the default first. */
+export const LOOK = Object.freeze({
+  font: Object.freeze(["sans", "serif", "mixed"]), // 等线体, 衬线体, 混合体 (the title and headings serif)
+  size: Object.freeze(["default", "small", "large"]), // 字体大小: 小号, 默认, 大号
+  spacing: Object.freeze(["default", "compact", "loose"]), // 正文间距: 紧凑, 默认, 宽松
+  width: Object.freeze(["default", "narrow", "wide"]), // 正文宽度: 偏窄, 默认, 偏宽
+  // 全宽 (the 更多 menu's switch under 目录): the page at the full width of its area, whatever its 正文宽度 is; its attribute is
+  // the kit's own data-doc-width="full", the reader's display menu's 全宽显示 too (components/page.mjs LOOK_ATTRIBUTES)
+  full: Object.freeze(["default", "full"]),
+});
+
+/** The attribute each choice is on <html> by: the page's description says them (components/page.mjs). */
+export { LOOK_ATTRIBUTES };
+
+/**
+ * 字体大小: the factor every size of the text takes, and its line height with it (body text 15px, 16px,
+ * 18px): the type alone, not the gaps between blocks (正文间距's) nor the column's width (正文宽度's).
+ * 14px (Notion's small text) set small text and captions at 11px, too small for Chinese; 17px was hard
+ * to tell from 16px.
+ */
+export const SIZE_FACTOR = Object.freeze({ default: 1, small: 15 / 16, large: 18 / 16 });
+
+/**
+ * 正文间距: what a line's leading (its line height less its font size) and the gaps between blocks
+ * are taken at (body text's line 24px, 26px, 28px at 16px; a paragraph's gap 9px, 12px, 15px at any
+ * 字体大小).
+ */
+export const SPACING = Object.freeze({
+  default: Object.freeze({ leading: 1, gaps: 1 }),
+  compact: Object.freeze({ leading: 0.8, gaps: 0.75 }),
+  loose: Object.freeze({ leading: 1.2, gaps: 1.25 }),
+});
+
+/**
+ * 正文宽度: the reading column in px, whatever the 字体大小 (which changes the type alone): 默认 the
+ * kit's 712px (tokens.css --doc-content-max-width), 44 characters of Chinese body text to a line at the
+ * default 16px; 偏窄 and 偏宽 the widths of 40 and 48 of them (40.5 and 48.5 times 16px, as 712 is 44.5
+ * times it). The user counted a line in characters only to fix these widths (2026-11-07: until then
+ * they were counted at the size chosen, so 大号 widened the column too). A narrow window narrows it as
+ * ever.
+ */
+export const WIDTH = Object.freeze({ default: 712, narrow: 648, wide: 776 });
+
+/**
+ * The serif (衬线体, and 混合体's title and headings): the system's own book serifs, nothing to download
+ * (the sidebar's Gallery wordmark is set in the first of them), then the Chinese serifs: Songti SC
+ * (macOS), Noto or Source Han Serif where installed, SimSun (Windows).
+ */
+export const SERIF_FONT = '"Iowan Old Style", "Palatino Linotype", Palatino, "Book Antiqua", Georgia, "Songti SC", "Noto Serif SC", "Noto Serif CJK SC", "Source Han Serif SC", SimSun, serif';
+
+const isPlain = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+/** A look as kept: the choices `value` makes that are known and not the default, {} for none. */
+export function lookOf(value) {
+  const look = {};
+  if (!isPlain(value)) return look;
+  for (const [key, choices] of Object.entries(LOOK)) {
+    const chosen = value[key];
+    if (typeof chosen === "string" && choices.includes(chosen) && chosen !== choices[0]) look[key] = chosen;
+  }
+  return look;
+}
+
+/** Each choice of a look, the default where it makes none: { font, size, spacing, width, full }. */
+export const fullLook = (value) => ({ ...Object.fromEntries(Object.entries(LOOK).map(([key, [first]]) => [key, first])), ...lookOf(value) });
+
+/** Whether two looks are the same. */
+export const sameLook = (a, b) => JSON.stringify(lookOf(a)) === JSON.stringify(lookOf(b));
+
+/**
+ * A document's own look as its doc.json keeps it: each known choice `value` makes, the default too
+ * ("sans", "default": 默认 chosen on a page while the workspace's default look says otherwise), {} for
+ * none. lookOf is what it shows of that alone.
+ */
+export function ownLookOf(value) {
+  const look = {};
+  if (!isPlain(value)) return look;
+  for (const [key, choices] of Object.entries(LOOK)) {
+    const chosen = value[key];
+    if (typeof chosen === "string" && choices.includes(chosen)) look[key] = chosen;
+  }
+  return look;
+}
+
+/**
+ * The look a document shows (lookOf's form: the defaults left out), choice by choice: its own (doc.json's
+ * `look`, ownLookOf), else the workspace's default look (gallery.json's `look`, 应用到全部文档), else the
+ * default.
+ */
+export const effectiveLook = (own, workspace) => lookOf({ ...lookOf(workspace), ...ownLookOf(own) });
+
+/**
+ * What a document's doc.json keeps for it to show `look` under the workspace's default look
+ * `workspace`: each choice that is not the workspace's, a default too (ownLookOf), {} when it shows
+ * the workspace's own.
+ */
+export function ownLookFor(look, workspace) {
+  const [shown, base] = [fullLook(look), fullLook(workspace)];
+  return Object.fromEntries(Object.keys(LOOK).filter((key) => shown[key] !== base[key]).map((key) => [key, shown[key]]));
+}
+
+/**
+ * A document's doc.json (its parsed object) with its own look as given (ownLookOf: an explicit default
+ * kept): in the field's place when it had one, else last; the field gone when it makes no choice.
+ * Every other field stays as it is.
+ */
+export function withLookField(metadata, look) {
+  const next = ownLookOf(look);
+  const keep = Object.keys(next).length > 0;
+  const base = isPlain(metadata) ? metadata : {};
+  if (!Object.hasOwn(base, "look")) return keep ? { ...base, look: next } : { ...base };
+  return Object.fromEntries(Object.entries(base).flatMap(([key, value]) => (key !== "look" ? [[key, value]] : keep ? [[key, next]] : [])));
+}
+
+/** The look's attributes on <html>: [name, value] for each choice that is not the default. */
+export const lookAttributes = (look) => Object.entries(lookOf(look)).map(([key, value]) => [LOOK_ATTRIBUTES[key], value]);
+
+const ATTRIBUTE_VALUE = String.raw`(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'>]+))?`;
+
+/**
+ * A page's text with the look on its <html> start tag (the first one), as the render serves and
+ * exports it: whatever look attributes the file writes there taken off (doc.json is their one home),
+ * the look's put on. A page without an <html> tag is returned as it is.
+ */
+export function withLook(html, look) {
+  const text = String(html ?? "");
+  const found = /<html\b[^>]*>/i.exec(text);
+  if (!found) return text;
+  let tag = found[0];
+  for (const name of Object.values(LOOK_ATTRIBUTES)) tag = tag.replace(new RegExp(String.raw`\s${name}${ATTRIBUTE_VALUE}(?=[\s/>])`, "gi"), "");
+  const added = lookAttributes(look).map(([name, value]) => ` ${name}="${value}"`).join("");
+  if (added) tag = tag.replace(/\s*>$/, (end) => `${added}${end.trimStart()}`);
+  return text.slice(0, found.index) + tag + text.slice(found.index + found[0].length);
+}
+
+/** The look an element (the page's <html>) carries by its attributes. */
+export function lookOfElement(element) {
+  return lookOf(Object.fromEntries(Object.entries(LOOK_ATTRIBUTES).map(([key, name]) => [key, element?.getAttribute?.(name) ?? undefined])));
+}
+
+/** Put a look on an element (the page's <html>) by its attributes; whether anything changed. */
+export function setLookOn(element, look) {
+  const next = lookOf(look);
+  let changed = false;
+  for (const [key, name] of Object.entries(LOOK_ATTRIBUTES)) {
+    const value = next[key] ?? null;
+    if (element.getAttribute(name) === value) continue;
+    if (value === null) element.removeAttribute(name);
+    else element.setAttribute(name, value);
+    changed = true;
+  }
+  return changed;
+}
+
+/** A look as a line's word (the preview's live reload says "look <word>"): "font=serif&size=small", "" for the default. */
+export const lookWord = (look) => Object.entries(lookOf(look)).map(([key, value]) => `${key}=${value}`).join("&");
+
+/** The look a word says (lookWord's inverse; anything else the default). */
+export const lookOfWord = (word) => lookOf(Object.fromEntries(new URLSearchParams(String(word ?? ""))));