@heycys/gallery 0.1.1 → 0.2.0

package/browser/shared/session.mjs

@@ -1,7 +1,9 @@
 // The session between a report page and a workbench that shows it in an iframe of the same origin
 // (docs/workbench.md): the page's side is src/editor/page/session.mjs, the workbench's
 // src/workbench/app/session/. Every message is { protocol: PROTOCOL, v: VERSION, type, slug, ... },
-// posted to the other window for this origin only.
+// posted to the other window for this origin only; or, for a draft of another workspace, between the
+// page and a workbench of another origin each side's server vouched for (the page's ?shell=<origin>,
+// GET /__gallery/workspace/shell; the workbench's POST elsewhere: src/workbench/elsewhere.mjs).
 //
 //   report -> workbench   ready    once the editor started: { commands, title, icon, look, state, annotations, card }
 //                         state    when the state, the title, the page's icon, the look it shows, how many 批注 it
@@ -31,9 +33,14 @@
 //                         workspace a page was made under this one (a page block's box, the page itself
 //                                  staying as it is): the workbench reads the list of pages again and
 //                                  shows this page's row open
+//                         consent  a block's card asks to be let online (its 允许访问: the kit's net.js):
+//                                  { block (its id), hosts (those of its needs waiting) }: the workbench
+//                                  opens its consent dialog, which writes what the reader says
 //                         annotations-removed
 //                                  a 批注 deleted from its card: { items }: the workbench says so, as
 //                                  it does for 全部删除, and its 撤销 puts them back
+//                         bye      the page goes (pagehide), to a workbench of another origin alone, which
+//                                  cannot see it go: its session ends there
 //   workbench -> report   command  { id, name, ... }
 
 export const PROTOCOL = "gallery/session";

package/browser/shared/shipped-blocks.mjs

@@ -0,0 +1,299 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { beforeCatalogRead } from "./component-catalog.mjs";
+import { packsDirectory } from "./paths.mjs";
+import { PACKAGE_MANIFEST, layoutOf } from "./workspace.mjs";
+
+// Gallery's own custom blocks (自带块): the blocks of Gallery's own block packs (./block-packs.mjs), a
+// folder each in the package (src/packs/<pack>/<name>/ in the source checkout, packs/<pack>/<name>/ in
+// the release), each a block of the scope <pack> as any workspace's is, its manifest's id <pack>/<name>:
+// the pack gallery's (Gallery 风格) and gallery-soft's (柔光风格). A workspace's first start installs each
+// pack as any shared pack is installed (./block-packs.mjs installOfficialPacks); gallery block add <name>
+// (gallery's, or <pack>/<name>) copies one unchanged into a workspace, components/<pack>/<name>/, and records its
+// version and a fingerprint of what it copied in .gallery/blocks.json; adding it again updates a copy
+// that is as it was put there, and never one whose fingerprint has changed since, which is someone's
+// work (gallery block new <id> --recipe <name> starts a block of one's own from a shipped one instead).
+// The scopes of Gallery's packs are kept for these: gallery block new refuses them. A custom page's
+// service (phase 2) adds one the same way when a card asks for it.
+//
+// A workspace's copies follow Gallery (the user, 2026-11-09: a home page made with 1.0.0's cards kept
+// their plain look after 1.1.0 brought the cards' design): a copy that is as it was added and behind
+// Gallery's is updated in place, as gallery block add would update it, without the command
+// (followShipped): as a server starts (src/server/index.mjs, production.mjs), whenever its catalog
+// reads the workspace's blocks (readCatalog, by followOnRead's hook) and when the page service reads
+// them (its library, an add), once a process for each block and version, told once in the server's
+// log. A copy changed since it was added is someone's work and stays as it is: the log says so once,
+// and 设置 › 组件列表 and gallery block list say that Gallery has a newer one and how to take it.
+
+/** The scope of Gallery's own blocks that a bare name names (gallery block add card): the pack gallery's. */
+export const SHIPPED_SCOPE = "gallery";
+
+// What a system writes into a folder it shows, which nobody wrote: macOS's Finder (.DS_Store, and ._
+// files beside each on a disk of another format), Windows' Explorer (Thumbs.db, desktop.ini). No
+// fingerprint counts them, no add takes them out, and a recipe copies none.
+const SYSTEM_FILE = /^(?:\.DS_Store|\._.*|Thumbs\.db|ehthumbs\.db|desktop\.ini)$/i;
+
+/** Whether a file called `name` (its last part) is one a system wrote into a folder it showed. */
+export const isSystemFile = (name) => SYSTEM_FILE.test(name);
+
+/** The files of a folder, by their paths in it with "/", sorted, what a system wrote there left out. */
+export function filesIn(folder) {
+  return fs.readdirSync(folder, { recursive: true, withFileTypes: true }).filter((entry) => entry.isFile() && !SYSTEM_FILE.test(entry.name))
+    .map((entry) => path.relative(folder, path.join(entry.parentPath, entry.name)).split(path.sep).join("/")).sort();
+}
+
+/**
+ * The names of a block's files in the order they are written: its manifest last, what makes a folder a
+ * block to whoever watches (a running server's watcher, the catalog), so that a block that appears is
+ * whole, and one a write stopped partway through is a folder with no manifest, which loads as nothing.
+ */
+export const writingOrder = (names) => [...names.filter((name) => name !== PACKAGE_MANIFEST), ...(names.includes(PACKAGE_MANIFEST) ? [PACKAGE_MANIFEST] : [])];
+
+/** What a folder holds, as a hash of each file's path and bytes (what a system wrote there aside), or null when there is no such folder. */
+export function fingerprintOf(folder) {
+  if (!fs.existsSync(folder)) return null;
+  return fingerprintOfFiles(filesIn(folder).map((name) => ({ name, data: fs.readFileSync(path.join(folder, name)) })));
+}
+
+/** What fingerprintOf says of a folder that holds `files` alone ([{ name, data }], each by its path in it with "/"). */
+export function fingerprintOfFiles(files) {
+  const hash = createHash("sha256");
+  const named = files.filter(({ name }) => !SYSTEM_FILE.test(name.split("/").at(-1))).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  for (const { name, data } of named) hash.update(`${name}\u0000`).update(data).update("\n");
+  return hash.digest("hex").slice(0, 16);
+}
+
+// The folders right in `directory`, by name, or none where it is not there.
+const foldersOf = (directory) => {
+  try {
+    return fs.readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+  } catch {
+    return [];
+  }
+};
+
+/** The ids of Gallery's own packs in `directory` (the package's): each folder of it, by name. */
+export const shippedPackIds = (directory = packsDirectory) => foldersOf(directory);
+
+/**
+ * Gallery's own blocks in `directory` (the package's packs): [{ name, id, pack, folder, version, title:
+ * { zh, en }, description: { zh, en }, places }], by pack and name; a folder whose manifest does not read
+ * as its pack's block of its name is none.
+ */
+export function shippedBlocks(directory = packsDirectory) {
+  return foldersOf(directory).flatMap((pack) => foldersOf(path.join(directory, pack)).flatMap((name) => {
+    const folder = path.join(directory, pack, name);
+    try {
+      const manifest = JSON.parse(fs.readFileSync(path.join(folder, PACKAGE_MANIFEST), "utf8"));
+      if (manifest.id !== `${pack}/${name}`) return [];
+      return [{ name, id: manifest.id, pack, folder, version: manifest.version, title: manifest.name, description: manifest.description, places: manifest.places ?? ["document"] }];
+    } catch {
+      return [];
+    }
+  }));
+}
+
+/** The shipped block `written` names (card, gallery/card, gallery-soft/todos: a bare name is the pack gallery's), or null. */
+export function shippedBlock(written, directory = packsDirectory) {
+  const id = written.includes("/") ? written : `${SHIPPED_SCOPE}/${written}`;
+  return shippedBlocks(directory).find((block) => block.id === id) ?? null;
+}
+
+/** Whether `id` is of a scope of Gallery's own packs (gallery/…, gallery-soft/…). */
+export const isShippedId = (id, directory = packsDirectory) => shippedPackIds(directory).includes(String(id).split("/")[0]);
+
+/**
+ * .gallery/blocks.json: { "<id>": { version, fingerprint } } of each block added or installed (one of
+ * Gallery's own, or of a pack), and `packs`, { "<pack id>": { version, fingerprint, blocks, official? } } of
+ * each pack installed (./block-packs.mjs); {} for none or a file that does not read.
+ */
+export function recordOf(root) {
+  try {
+    const record = JSON.parse(fs.readFileSync(layoutOf(root).blocks, "utf8"));
+    return record && typeof record === "object" && !Array.isArray(record) ? record : {};
+  } catch {
+    return {};
+  }
+}
+
+/** .gallery/blocks.json as `record` says. */
+export function writeRecord(root, record) {
+  const file = layoutOf(root).blocks;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`);
+}
+
+/** Where a block of the workspace at `root` is. */
+const folderIn = (root, id) => path.join(layoutOf(root).components, ...id.split("/"));
+
+/**
+ * What the workspace at `root` holds of the shipped `block`: { added (a folder of its id is there),
+ * version (what its manifest says, or null), changed (its files are not what was added: changed since,
+ * or put there by some other hand), behind (it is as added, and Gallery's is another now) }.
+ */
+export function shippedState(root, block) {
+  const folder = folderIn(root, block.id);
+  const now = fingerprintOf(folder);
+  if (now === null) return { added: false, version: null, changed: false, behind: false };
+  let version = null;
+  try {
+    version = JSON.parse(fs.readFileSync(path.join(folder, PACKAGE_MANIFEST), "utf8")).version ?? null;
+  } catch {}
+  const kept = recordOf(root)[block.id];
+  const shipped = fingerprintOf(block.folder);
+  const changed = now !== shipped && now !== kept?.fingerprint;
+  return { added: true, version, changed, behind: !changed && now !== shipped };
+}
+
+/**
+ * Copies the shipped `block` into the workspace at `root`, unchanged: { did: "added", "updated" (from a
+ * copy as it was added, `from` its version) or "same" (nothing to do), folder }. A copy whose files
+ * changed since it was added (or that no add put there) is left as it is: an error with code "changed".
+ * The manifest is written last, what makes a folder a block to a running server's watcher, so that a
+ * block that appears is whole; files of the old copy that the new one has not go first.
+ */
+export function addShipped(root, block) {
+  const folder = folderIn(root, block.id);
+  const state = shippedState(root, block);
+  if (state.changed) throw Object.assign(new Error(`${block.id} was changed after it was added`), { code: "changed", folder });
+  const shipped = fingerprintOf(block.folder);
+  const record = recordOf(root);
+  if (state.added && !state.behind) {
+    if (record[block.id]?.fingerprint !== shipped) writeRecord(root, { ...record, [block.id]: { version: block.version, fingerprint: shipped } });
+    return { did: "same", folder };
+  }
+  const files = filesIn(block.folder);
+  if (state.added) for (const old of filesIn(folder)) if (!files.includes(old)) fs.rmSync(path.join(folder, old));
+  for (const file of writingOrder(files)) {
+    fs.mkdirSync(path.dirname(path.join(folder, file)), { recursive: true });
+    fs.copyFileSync(path.join(block.folder, file), path.join(folder, file));
+  }
+  writeRecord(root, { ...record, [block.id]: { version: block.version, fingerprint: shipped } });
+  return { did: state.added ? "updated" : "added", from: state.version, folder };
+}
+
+// A version's numbers (1.10.0: [1, 10, 0]), or null for one that is not three of them.
+const numbersOf = (version) => (/^\d+\.\d+\.\d+$/.test(String(version ?? "")) ? version.split(".").map(Number) : null);
+
+/** Whether version `a` comes after `b` (both x.y.z); `b` none or not of that form: whether they differ. */
+export function versionAfter(a, b) {
+  const [x, y] = [numbersOf(a), numbersOf(b)];
+  if (!x || !y) return a !== b;
+  const at = x.findIndex((number, index) => number !== y[index]);
+  return at !== -1 && x[at] > y[at];
+}
+
+/**
+ * The version of the shipped `block` that the workspace at `root` does not take because its copy was
+ * changed since it was added (or no add put it there), when Gallery's comes after the copy's; else null.
+ */
+export function shippedNewer(root, block) {
+  const state = shippedState(root, block);
+  return state.changed && versionAfter(block.version, state.version) ? block.version : null;
+}
+
+const looked = new Map(); // a workspace's root and a shipped block's folder -> the version of it looked at
+let told = () => {}; // where followShipped tells what it did when it is not given a log: the server's (followOnRead)
+
+// What followShipped did, as lines of the log.
+function followedLines(root, { updated, kept, failed }) {
+  const lines = [];
+  if (updated.length) lines.push(`Gallery's own blocks in ${root}, as they were added, updated to this Gallery's: ${updated.map(({ id, from, to }) => `${id} ${from ?? "?"} -> ${to}`).join(", ")}`);
+  for (const { id, version, shipped } of kept) lines.push(`${id} in ${root} was changed after it was added, so it stays at ${version ?? "its version"}: Gallery's is ${shipped} (设置 › 组件列表 says how to take it)`);
+  for (const { id, to, why } of failed) lines.push(`${id} in ${root} could not be updated to Gallery's ${to}: ${why}`);
+  return lines;
+}
+
+/**
+ * Bring the workspace at `root`'s copies of Gallery's own blocks (of `ids`, by default each one) up to
+ * Gallery's (in `directory`): one that is as it was added and behind is updated as addShipped updates
+ * it (the manifest written last); one changed since it was added is kept as it is. Each block and
+ * version is looked at once a process, a later call for it doing nothing, so that what reads the blocks
+ * again and again (a server's catalog, its page service) pays once. `log`: told once of what was done,
+ * a line each (by default the one followOnRead set: none in a command). Never throws: { updated: [{ id,
+ * from, to }], kept: [{ id, version, shipped }] (changed, Gallery's newer), failed: [{ id, to, why }] }.
+ */
+export function followShipped(root, { ids = null, directory = packsDirectory, log = null } = {}) {
+  const done = { updated: [], kept: [], failed: [] };
+  const key = path.resolve(root);
+  for (const block of shippedBlocks(directory)) {
+    if (ids && !ids.includes(block.id)) continue;
+    const at = `${key}\u0000${path.resolve(block.folder)}`;
+    if (looked.get(at) === block.version) continue;
+    looked.set(at, block.version);
+    try {
+      const state = shippedState(root, block);
+      if (state.changed && versionAfter(block.version, state.version)) done.kept.push({ id: block.id, version: state.version, shipped: block.version });
+      if (!state.behind) continue;
+      if (addShipped(root, block).did === "updated") done.updated.push({ id: block.id, from: state.version, to: block.version });
+    } catch (error) {
+      done.failed.push({ id: block.id, to: block.version, why: error?.message ?? String(error) });
+    }
+  }
+  for (const line of followedLines(key, done)) (log ?? told)(line);
+  return done;
+}
+
+const following = new Set(); // the workspaces whose server runs in this process (followOnRead), by their resolved root
+const keyOf = (root) => (process.platform === "win32" ? path.resolve(root).toLowerCase() : path.resolve(root));
+
+/**
+ * From now on in this process, the catalog brings the copies of Gallery's own blocks of the workspace at
+ * `root` up to Gallery's before it reads them (followShipped, its ids those of the scopes of Gallery's
+ * packs it finds), and what is done of it is told to `log` (a line): a server's, set as it starts for
+ * its own workspace (another's blocks are its own server's to follow, and a test's process reads the
+ * repository's reports/ too, which nothing of it is to write).
+ */
+export function followOnRead(root, log) {
+  following.add(keyOf(root));
+  told = log;
+  beforeCatalogRead((read, ids) => {
+    if (following.has(keyOf(read))) followShipped(read, { ids });
+  }, shippedPackIds());
+}
+
+// The words of a shipped block's files that name it, and what a recipe's copy names instead: its id,
+// and the id with "-" for "/" (a class, a chart type).
+const namesOf = (id) => [id, id.replace("/", "-")];
+const escaped = (words) => words.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * The shipped block whose preview.svg the file `bytes` is, byte for byte, as Gallery ships it or as a
+ * recipe of it for the block `id` has it (every word that named it naming `id`), or null: a block made
+ * by --recipe keeps its recipe's picture until someone draws its own, which gallery block check notes.
+ */
+export function shippedPreviewOf(bytes, id, directory = packsDirectory) {
+  for (const block of shippedBlocks(directory)) {
+    if (block.id === id) continue; // a shipped block's own picture is its own
+    let shipped;
+    try {
+      shipped = fs.readFileSync(path.join(block.folder, "preview.svg"));
+    } catch {
+      continue;
+    }
+    if (shipped.equals(bytes) || Buffer.from(recipeFiles(block, id)["preview.svg"] ?? "").equals(bytes)) return block;
+  }
+  return null;
+}
+
+/**
+ * The files of a new block `id` made from the shipped `block` (gallery block new <id> --recipe <name>),
+ * by name, the manifest last: each as Gallery ships it, every word that names the shipped block naming
+ * the new one, all in one pass, so that a new name holding an old one (local/gallery-card, made of
+ * gallery/card) is not renamed again; its version 0.1.0.
+ */
+export function recipeFiles(block, id) {
+  const [from, to] = [namesOf(block.id), namesOf(id)];
+  const names = new RegExp(from.map(escaped).join("|"), "g");
+  const files = {};
+  for (const file of filesIn(block.folder)) {
+    const bytes = fs.readFileSync(path.join(block.folder, file));
+    if (/\.(?:json|html|md|css|js|svg)$/.test(file)) {
+      let text = bytes.toString("utf8").replace(names, (name) => to[from.indexOf(name)]);
+      if (file === PACKAGE_MANIFEST) text = text.replace(/"version":\s*"[^"]*"/, '"version": "0.1.0"');
+      files[file] = text;
+    } else files[file] = bytes;
+  }
+  return Object.fromEntries(writingOrder(Object.keys(files)).map((name) => [name, files[name]]));
+}

package/browser/shared/sidebar-head.mjs

@@ -0,0 +1,70 @@
+// The sidebar's head rows (docs/workbench.md "The sidebar", **Head**; the user's word of 2026-11-09):
+// 新建, 搜索 and each custom page, one list the reader orders by dragging its rows (no row goes into
+// another, none into the tree, no document among them), kept for the workspace in the outline file
+// (.gallery/outline.json's `head`, which ./outline.mjs keeps as it writes the tree, so that every browser
+// shows the order the reader gave). A row's key: "new" (新建), "search" (搜索), or "@<slug>" for a custom
+// page (its address in the workbench, which no slug holds). Pure: the server's (shared/pages.mjs listPages,
+// the workbench service's head) and the workbench's (its sidebar) alike.
+
+/** The key of the head's 新建 row. */
+export const HEAD_NEW = "new";
+/** The key of the head's 搜索 row. */
+export const HEAD_SEARCH = "search";
+/** The key of custom page `slug`'s row: @<slug>. */
+export const pageHeadKey = (slug) => `@${slug}`;
+/** The custom page a head key names, or null (new, search). */
+export const headPage = (key) => (typeof key === "string" && key.startsWith("@") ? key.slice(1) : null);
+/** How many keys a stored head keeps at most (those of pages gone stay, so that one restored goes back to its place). */
+export const MOST_HEAD = 200;
+
+const KEY = /^(?:new|search|@[a-z0-9]+(?:-[a-z0-9]+)*)$/;
+
+/**
+ * `value` as a head to store: an array of keys (new, search, @<slug>), each once, MOST_HEAD at most; null
+ * for anything else (not an array, a key that is none, one twice, too many).
+ */
+export function storedHead(value) {
+  if (!Array.isArray(value) || value.length > MOST_HEAD) return null;
+  if (!value.every((key) => typeof key === "string" && KEY.test(key))) return null;
+  return new Set(value).size === value.length ? [...value] : null;
+}
+
+/**
+ * The head's rows in their order: the keys `stored` (a head as the outline file keeps it, or null) gives,
+ * those of pages that are not there passed over, then what it does not name: 新建 first and 搜索 after it
+ * where it names neither (as before any drag), and each page of `pages` (their slugs, in the order a page
+ * goes by when the reader gave it none: shared/pages.mjs inPageOrder) after the last row it names, in that
+ * order. Always holds new and search once each, and each page of `pages` once.
+ */
+export function headOrder(stored, pages = []) {
+  const there = new Set(pages);
+  const named = (storedHead(stored) ?? []).filter((key) => key === HEAD_NEW || key === HEAD_SEARCH || there.has(headPage(key)));
+  if (!named.includes(HEAD_SEARCH)) named.unshift(HEAD_SEARCH);
+  if (!named.includes(HEAD_NEW)) named.splice(named.indexOf(HEAD_SEARCH), 0, HEAD_NEW);
+  for (const slug of pages) if (!named.includes(pageHeadKey(slug))) named.push(pageHeadKey(slug));
+  return named;
+}
+
+/**
+ * The head with the row `key` moved before the row `before` (null: last), the others as they were: what a
+ * drop on the head makes. Unchanged where `key` is not in it or is `before`.
+ */
+export function movedInHead(head, key, before) {
+  if (!head.includes(key) || key === before) return [...head];
+  const rest = head.filter((one) => one !== key);
+  const at = before === null ? rest.length : rest.indexOf(before);
+  rest.splice(at < 0 ? rest.length : at, 0, key);
+  return rest;
+}
+
+/**
+ * The stored head `stored` (or null, when none is kept yet: `shown`, the head as the sidebar shows it now,
+ * stands for it) with page `slug`'s row put right after the row of `after` (a page's slug), else last: a
+ * new page's place. Keys of pages gone are kept where they stand.
+ */
+export function headWithPage(stored, shown, slug, after = null) {
+  const head = (storedHead(stored) ?? storedHead(shown) ?? [HEAD_NEW, HEAD_SEARCH]).filter((key) => key !== pageHeadKey(slug));
+  const at = after ? head.indexOf(pageHeadKey(after)) : -1;
+  head.splice(at < 0 ? head.length : at + 1, 0, pageHeadKey(slug));
+  return head.slice(-MOST_HEAD);
+}

package/browser/shared/table-chart.mjs

@@ -13,11 +13,21 @@ import { isMissingValue, numberReading } from "./number-reading.mjs";
 // copy or delete either block (a copied pair takes a key of its own:
 // src/editor/page/clipboard/own/chart-keys.mjs, and the commit makes sure of it against the file:
 // src/editor/source/chart-keys.mjs).
+//
+// A view of a table (plan 阶段 4: a task board, a count, a chart card of a custom block's) is the same
+// link: an instance of a custom block whose manifest's needs hold "tables" names the table by that key
+// (VIEW_FROM), reads its rows as a chart does (the kit's runtime/table-reading.js, context.table()) and
+// changes them only by asking the page editor (an intent: docs/editor.md, "Table views"). A key is one
+// table's, which any number of charts and views read: TABLE_READERS are the attributes that read one.
 
 /** On a chart's host: the key of the table it draws. */
 export const CHART_DATA = "data-doc-chart-data";
 /** On a table's frame (.doc-table-wrap): the key a chart reads it by. */
 export const CHART_SOURCE = "data-doc-chart-source";
+/** On an instance of a custom block whose needs hold "tables": the key of the table it is a view of (context.table()). */
+export const VIEW_FROM = "data-doc-from";
+/** The attributes that name a table by its key, a chart's host's and a view's. */
+export const TABLE_READERS = [CHART_DATA, VIEW_FROM];
 /** A key: a letter, then letters, digits, "_" or "-", 32 at most. */
 export const CHART_KEY = /^[A-Za-z][\w-]{0,31}$/;
 
@@ -38,6 +48,28 @@ const FORMULA = /\\\(([\s\S]*?)\\\)|\\\[([\s\S]*?)\\\]|\$\$([\s\S]*?)\$\$/g;
  */
 export const cellWords = (text) => text.replace(FORMULA, (_, inline, display, dollars) => inline ?? display ?? dollars).replaceAll(ZWSP, "").replace(/\s+/g, " ").trim();
 
+// A formula KaTeX drew on a page: its TeX is its annotation (its drawing's text is its glyphs, twice over).
+const TEX = 'annotation[encoding="application/x-tex"]';
+
+/**
+ * A cell's text on a page as the file writes it, as near as the page tells: a formula KaTeX drew as its
+ * TeX, the editor's chip of an empty one as nothing (the file's \(\)). Its words are then cellWords'.
+ * For the kit, which reads a table on a page (runtime/table-reading.js: a chart's, a view's and a package's rows).
+ * @param {Node} node
+ * @returns {string}
+ */
+export function cellText(node) {
+  if (node.nodeType === 3) return /** @type {Text} */ (node).data;
+  if (node.nodeType !== 1) return "";
+  const element = /** @type {Element} */ (node);
+  if (element.hasAttribute("data-ge-empty")) return "";
+  const tex = element.classList.contains("katex") ? element.querySelector(TEX) : null;
+  if (tex) return tex.textContent ?? "";
+  let text = "";
+  for (const child of element.childNodes) text += cellText(child);
+  return text;
+}
+
 // A header's data-sort-type that says its column holds no numbers: its values are its words.
 const WORD_TYPES = new Set(["text", "date"]);
 
@@ -66,7 +98,7 @@ export function cellValue(cell, type = null) {
  * row of header cells alone; null when it has neither), its header cells' data-sort-type (null where
  * none), its rows of data in the file's order (never a <tfoot>'s), each cell { words, sort } (its
  * words, cellWords', and its data-sort-value, or null), and whether a cell of the header or the rows
- * spans rows or columns (charts/from-table.js tableCells reads it from the page,
+ * spans rows or columns (runtime/table-reading.js readTable reads it from the page,
  * chart-declarations.mjs tableCells from the file).
  *
  * `data` is what d3.csvParse gives: an object for each row of data, in their order, its values by

package/browser/shared/todos.mjs

@@ -0,0 +1,83 @@
+import { parse } from "parse5";
+import { TODO } from "./components/list.mjs";
+import { sha256 } from "./files.mjs";
+import { attr, BLOCK_LEVEL, elementsOf, hasClass } from "./html-tree.mjs";
+
+// A document's to-dos as its pages show them (the items of its to-do lists, ul.doc-todo): what the
+// workspace's facts list (src/workbench/index.mjs, workspace.query("todos")) and what a check of one
+// from another page finds it by (src/editor/todos.mjs, workspace.setTodo: the plan's 5.1), the one
+// reading for both, so that a ref the facts gave names the item the write looks for. Pure but for the
+// parser and the hash: no DOM.
+
+const SKIPPED = new Set(["script", "style", "template", "noscript", "svg", "math"]);
+const HEADING = /^h([1-6])$/;
+const tidy = (text) => text.replace(/[\s​]+/g, " ").trim();
+
+// The words an element holds, as a reader reads them: its text, a line break a space, nothing of a script,
+// a style or a drawing; `stop(child)`: a child left out with what it holds.
+function wordsOf(node, stop = () => false) {
+  let text = "";
+  const visit = (current) => {
+    for (const child of current.childNodes ?? []) {
+      if (child.nodeName === "#text") text += child.value;
+      else if (child.tagName === "br") text += " ";
+      else if (child.tagName && !SKIPPED.has(child.tagName) && !stop(child)) visit(child);
+    }
+  };
+  visit(node);
+  return tidy(text);
+}
+
+// A to-do's own words: what the item holds before its lists and the blocks it holds (a paragraph, a
+// picture), or, where it holds no words of its own (an item written <li><p>…</p></li>), its first block's.
+function itemWords(item) {
+  const own = wordsOf(item, (child) => BLOCK_LEVEL.has(child.tagName));
+  if (own) return own;
+  const first = elementsOf(item).find((child) => BLOCK_LEVEL.has(child.tagName) && child.tagName !== "ul" && child.tagName !== "ol");
+  return first ? wordsOf(first, (child) => child.tagName === "ul" || child.tagName === "ol") : "";
+}
+
+/**
+ * The to-dos of a document's `text` (its page's HTML, as its pages see it), in their order: [{ text,
+ * done, block, path, nth }], `path` the headings above it (their words, the outermost first: an h2 under
+ * an h1 of the body, the document's title never one), `nth` which of the to-dos of the same words under
+ * the same path it is (0 the first). With `at`, each says where its <li> starts in `text` too (`at`, the
+ * offset of its start tag), which the editor's units name it by (source/units.mjs elStart).
+ */
+export function todosOf(text, { at = false } = {}) {
+  const root = parse(String(text), { sourceCodeLocationInfo: at });
+  const headings = []; // [{ level, words }]
+  const todos = [];
+  const seen = new Map();
+  const visit = (node) => {
+    for (const child of elementsOf(node)) {
+      if (SKIPPED.has(child.tagName)) continue;
+      const heading = HEADING.exec(child.tagName);
+      if (heading && !hasClass(child, "doc-title")) {
+        const level = Number(heading[1]);
+        while (headings.length && headings.at(-1).level >= level) headings.pop();
+        const words = wordsOf(child);
+        if (words) headings.push({ level, words });
+        continue;
+      }
+      if (child.tagName === "li" && child.parentNode?.tagName === "ul" && hasClass(child.parentNode, TODO)) {
+        const path = headings.map(({ words }) => words);
+        const words = itemWords(child);
+        const key = JSON.stringify([words, path]);
+        const nth = seen.get(key) ?? 0;
+        seen.set(key, nth + 1);
+        todos.push({ text: words, done: attr(child, "data-checked") !== undefined, block: attr(child, "data-block-id") ?? null, path, nth, ...(at ? { at: child.sourceCodeLocation?.startOffset ?? -1 } : {}) });
+      }
+      visit(child);
+    }
+  };
+  visit(root);
+  return todos;
+}
+
+/**
+ * The version of a document's file the facts read its to-dos from (the hash of its text, as a to-do's
+ * ref carries it: workspace.query("todos")), which a check of one finds it by its place in (`nth`) while
+ * the file is still that one.
+ */
+export const fileVersion = (source) => sha256(source).slice(0, 16);

package/browser/shared/user-directory.mjs

@@ -0,0 +1,24 @@
+import os from "node:os";
+import path from "node:path";
+
+// The user's own folders for Gallery, outside every workspace: "cache", what may be thrown away (the
+// update check's answer, src/cli/updates.mjs), and "data", what Gallery keeps of the machine (the
+// registry of the workspaces used on it, ./workspace-registry.mjs). One function, so that every system
+// finds them alike. Node's built-ins only: gallery --version reads it, and stays as fast as Node's start.
+
+/**
+ * The folder of `kind` ("cache" or "data"): GALLERY_CACHE_DIR or GALLERY_DATA_DIR when set (the tests
+ * name folders of their own); else on Windows %LOCALAPPDATA%\gallery for both; on macOS
+ * ~/Library/Caches/gallery and ~/Library/Application Support/gallery; elsewhere $XDG_CACHE_HOME/gallery
+ * (~/.cache/gallery) and $XDG_STATE_HOME/gallery (~/.local/state/gallery). Only a path: nothing is made.
+ */
+export function userDirectory(kind, { env = process.env, platform = process.platform, home = os.homedir() } = {}) {
+  const cache = kind === "cache";
+  const own = cache ? env.GALLERY_CACHE_DIR : env.GALLERY_DATA_DIR;
+  if (own) return path.resolve(own);
+  if (platform === "win32") return path.join(env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "gallery");
+  if (platform === "darwin") return path.join(home, "Library", cache ? "Caches" : "Application Support", "gallery");
+  return cache
+    ? path.join(env.XDG_CACHE_HOME || path.join(home, ".cache"), "gallery")
+    : path.join(env.XDG_STATE_HOME || path.join(home, ".local", "state"), "gallery");
+}

package/browser/shared/versions.mjs

@@ -0,0 +1,14 @@
+// Gallery's versions compared, with nothing imported: the preview server's choice of a server to use
+// or replace (./preview-server.mjs) and gallery --version's notes (src/cli/updates.mjs, which loads
+// nothing it can do without) read it.
+
+/** -1, 0 or 1 as version `a` is older than, the same as or newer than `b` (numbers by dots: 0.1.0 < 0.1.10 < 0.2.0). */
+export function compareVersions(a, b) {
+  const parts = (version) => String(version ?? "0").split(/[.+-]/).slice(0, 3).map((part) => Number.parseInt(part, 10) || 0);
+  const [x, y] = [parts(a), parts(b)];
+  for (let index = 0; index < 3; index++) if ((x[index] ?? 0) !== (y[index] ?? 0)) return (x[index] ?? 0) < (y[index] ?? 0) ? -1 : 1;
+  return 0;
+}
+
+/** A released version as npm writes one, numbers alone (0.1.2): what a registry's answer must be to be believed. */
+export const RELEASED = /^\d{1,6}\.\d{1,6}\.\d{1,6}$/;