@heycys/gallery 0.0.0-stage → 0.1.1

package/browser/shared/reading-place.mjs

@@ -0,0 +1,91 @@
+// Where a reader is in a page, for the way back from a link to a block of it (docs/render.md, "Links
+// to blocks"; the page editor's and the workbench's too): the scroll position and the element that
+// stands at the top of the window, with how far down the window its top is. A jump opens what hides
+// its block (a disclosure, a tab, a detail card), and what opens above the place moves the rest, so
+// the way back goes by that element where it can, by the scroll position where it cannot. The element
+// is named by where it stands in the page's main (the child indices down to it: an Agent's blocks
+// carry no id until a commit or an export gives them one), checked by the id of the block it is in.
+
+const rootOf = (doc) => doc.querySelector("main") ?? doc.body;
+
+/** `value` for a quoted CSS string: the window's CSS.escape, where there is one (a DOM of a test may have none). */
+export const cssString = (win, value) => (win?.CSS?.escape ? win.CSS.escape(value) : String(value).replace(/["\\]/g, "\\$&").replace(/\n/g, "\\a "));
+
+const blockOf = (element) => element.closest("[data-block-id]")?.getAttribute("data-block-id") ?? null;
+
+// The tab each Sheet area of `win`'s page shows, by the area's name (sheets.js keeps one state per name).
+const tabsIn = (win) => {
+  const tabs = {};
+  for (const area of win.document.querySelectorAll("[data-doc-sheets]")) {
+    const key = win.DocSheets?.get(area)?.get();
+    if (typeof key === "string") tabs[area.getAttribute("data-doc-sheets")] = key;
+  }
+  return tabs;
+};
+
+/**
+ * `win`'s place: { x, y, top, tabs }, `top` { path, id, at } the first element of the page's main, in
+ * its order, whose top is in the window or below it (none in a detail card, none that sticks or is
+ * fixed, none that takes no room), or null where none is; `tabs` the tab each Sheet area shows.
+ */
+export function placeIn(win) {
+  const doc = win.document;
+  const root = rootOf(doc);
+  let top = null;
+  if (root) {
+    const walker = doc.createTreeWalker(root, 1, (element) => {
+      if (element.localName === "dialog") return 2; // a card's blocks stand over the page, not in it
+      const box = element.getBoundingClientRect();
+      if (box.bottom <= 0 && box.height > 0) return 2; // what ends above the window holds nothing in it
+      const { position } = win.getComputedStyle(element);
+      return position === "fixed" || position === "sticky" ? 2 : 1; // what stands still as the page scrolls (a heading that sticks, a bar of the document's own), and what is in it, names no place in it
+    });
+    for (let element = walker.nextNode(); element; element = walker.nextNode()) {
+      const box = element.getBoundingClientRect();
+      if (box.height === 0 || box.top < 0) continue;
+      const path = [];
+      for (let node = element; node !== root; node = node.parentElement) path.unshift([...node.parentElement.children].indexOf(node));
+      top = { path, id: blockOf(element), at: Math.round(box.top) };
+      break;
+    }
+  }
+  return { x: Math.round(win.scrollX), y: Math.round(win.scrollY), top, tabs: tabsIn(win) };
+}
+
+// The element `top` names: at its path when that is still in the block it was in, else that block.
+function elementOf(doc, top) {
+  const root = rootOf(doc);
+  if (!root || !top) return null;
+  let element = root;
+  for (const index of Array.isArray(top.path) ? top.path : [null]) element = Number.isInteger(index) ? element?.children[index] ?? null : null;
+  const id = typeof top.id === "string" ? top.id : null;
+  if (element && (id === null || blockOf(element) === id)) return element;
+  return id ? doc.querySelector(`[data-block-id="${cssString(doc.defaultView, id)}"]`) : null;
+}
+
+/**
+ * `win` back at `place` (placeIn's): the tabs it names shown again (a jump to a block in another tab of
+ * an area showed that one), then its top element where it stood in the window, else its scroll position.
+ */
+export function goBackTo(win, place) {
+  const tabs = place?.tabs && typeof place.tabs === "object" ? place.tabs : {};
+  for (const area of win.document.querySelectorAll("[data-doc-sheets]")) {
+    const key = tabs[area.getAttribute("data-doc-sheets")];
+    if (typeof key === "string" && win.DocSheets?.get(area)?.get() !== key) win.DocSheets?.get(area)?.set(key);
+  }
+  const element = elementOf(win.document, place?.top);
+  const box = element && !element.closest("dialog") ? element.getBoundingClientRect() : null;
+  const x = Number(place?.x) || 0;
+  if (box && box.height > 0 && Number.isFinite(place.top.at)) win.scrollTo(x, win.scrollY + box.top - place.top.at);
+  else win.scrollTo(x, Number(place?.y) || 0);
+}
+
+/**
+ * Whether `win` stands where goBackTo put it (`put`: [x, y] then) or where the browser puts an entry's
+ * scroll position back on the way back (`place`'s own x and y, Chrome's after popstate), so that a
+ * second goBackTo, once what lays itself out later has, is no reader's scroll taken back.
+ */
+export function unmoved(win, place, put) {
+  const at = (x, y) => Math.abs(win.scrollX - x) < 1 && Math.abs(win.scrollY - y) < 1;
+  return at(put[0], put[1]) || at(Number(place?.x) || 0, Number(place?.y) || 0);
+}

package/browser/shared/renamed-storage.mjs

@@ -0,0 +1,220 @@
+// What a browser keeps of the UI (the workbench and the report pages, one origin) under the product's
+// name, Gallery, and under its old one, HTML Report Studio (before 2026-10-26): the keys of
+// localStorage and sessionStorage and the workbench's IndexedDB. Every module that reads or writes
+// one of these keys takes its name from here (KEYS, DATABASES), so this module has
+// run, and carried what the old keys hold, before any of them reads: one table, whichever page of
+// the origin loads first (docs/workbench.md, "Kept in the browser").
+//
+// Carrying never removes an old key or the old database: a page or workbench of the old version
+// still open (a tab left from before the update) goes on reading and writing them. An old key is
+// carried to its new one
+//   - the first time it is looked at, when the new key is empty (a new key already written wins);
+//   - again whenever it changed since it was last looked at: only a page of the old version writes
+//     it, and what it wrote is the reader's latest (a favorite set, a theme picked in the old tab);
+//     removed there (the theme, the icon set or color back to their default), the new key goes too.
+// What each old key held when it was last looked at is kept (as a short digest) under RECORD, so a
+// carry is done once: run again, nothing changes, and a new key the new version removed (its
+// default) stays removed. Each runs as this module loads, and again when another tab changes an old
+// key (the storage event). A failure (full or blocked storage) leaves that key to the next time.
+// The kit's reading state (DocState, src/render/kit/state.js, a classic script) carries its own
+// keys, html-report-studio:<report>:<id> to gallery:<report>:<id>, the same way, as it reads them.
+//
+// The editor's keys, made per document and per tab (the crash buffer, what a page keeps over a
+// reload, the lost list, the recent choices of its menus: gallery-edit:<slug>:<kind>[:<tab>],
+// gallery-edit:<name>), were report-edit:… before 2026-10-28 (decision E). They are carried by their
+// prefix (PREFIXES) under the same rules, every old key under it that is there or was looked at
+// before; what they hold is carried as it is (a crash buffer then sent by the page as any, the
+// server reading it as the page of this version sends it).
+
+/** localStorage, new names. */
+export const KEYS = {
+  language: "gallery:language", // shared/i18n
+  preferences: "gallery:preferences", // shared/preferences.mjs
+  outlineOpen: "gallery:outline-open", // shared/preferences.mjs
+  outlineFolds: "gallery:outline", // editor/page/outline/folds.mjs
+  emojiSkinTone: "gallery:emoji-skin-tone", // shared/emoji/data.mjs
+  emojiFrecency: "gallery:emoji-frecency",
+  iconColor: "gallery:icon-picker-color", // shared/emoji/glyphs.mjs
+  recentGlyphs: "gallery:recent-glyphs",
+  glyphSet: "gallery:glyph-set",
+  sidebar: "gallery/workbench:sidebar", // the workbench's state/
+  theme: "gallery/workbench:theme",
+  tree: "gallery/workbench:tree",
+  favorites: "gallery/workbench:favorites", // workbench/app/workspace/store.ts
+  presentZoom: "gallery/workbench:present-zoom", // features/present/
+};
+/** localStorage, the names before 2026-10-26, each of the key of KEYS by the same name. */
+export const OLD_KEYS = {
+  language: "html-report-studio:language",
+  preferences: "html-report-studio:preferences",
+  outlineOpen: "html-report-studio:outline-open",
+  outlineFolds: "html-report-studio:outline",
+  emojiSkinTone: "report-studio:emoji-skin-tone",
+  emojiFrecency: "report-studio:emoji-frecency",
+  iconColor: "report-studio:icon-picker-color",
+  recentGlyphs: "report-studio:recent-glyphs",
+  glyphSet: "report-studio:glyph-set",
+  sidebar: "html-report-studio/workbench:sidebar",
+  theme: "html-report-studio/workbench:theme",
+  tree: "html-report-studio/workbench:tree",
+  favorites: "html-report-studio/workbench:favorites",
+  presentZoom: "html-report-studio/workbench:present-zoom",
+};
+/** IndexedDB, new and old names (the workbench's chosen export folder: workspace/exportFolder.ts). */
+export const DATABASES = { workbench: "gallery-workbench" };
+export const OLD_DATABASES = { workbench: "html-report-studio-workbench" };
+
+/** Where what each old key held when last looked at is kept (in each storage, for its own keys). */
+export const RECORD = "gallery:renamed";
+
+/** Prefixes of keys named per document or tab, the old with its new one (the editor's, before 2026-10-28). */
+export const PREFIXES = [["report-edit:", "gallery-edit:"]];
+
+const pairsOf = (old, now) => Object.keys(now).map((name) => [old[name], now[name]]);
+export const LOCAL_PAIRS = pairsOf(OLD_KEYS, KEYS);
+
+/**
+ * The [old, new] pairs of the keys under `prefixes` in `area` (a Storage): each old key there now,
+ * and each looked at before (in `record`), so that one removed since takes its new key with it.
+ */
+export function prefixPairs(area, prefixes = PREFIXES, record = RECORD) {
+  if (!area) return [];
+  const names = new Set();
+  try {
+    for (let index = 0; index < area.length; index++) names.add(area.key(index));
+  } catch {} // blocked: none
+  try {
+    const kept = JSON.parse(area.getItem(record) ?? "{}");
+    if (kept && typeof kept === "object" && !Array.isArray(kept)) for (const name of Object.keys(kept)) names.add(name);
+  } catch {}
+  return [...names].map((name) => prefixPair(name, prefixes)).filter(Boolean);
+}
+
+/** [name, its new name] when `name` is a key under one of the old prefixes of `prefixes`, else null. */
+export function prefixPair(name, prefixes = PREFIXES) {
+  const pair = typeof name === "string" ? prefixes.find(([old]) => name.startsWith(old)) : null;
+  return pair ? [name, pair[1] + name.slice(pair[0].length)] : null;
+}
+
+/** A short digest of a stored value (null: none), enough to tell that it changed. */
+export function digest(value) {
+  if (value === null || value === undefined) return null;
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < value.length; index++) hash = Math.imul(hash ^ value.charCodeAt(index), 0x01000193);
+  return `${value.length}:${(hash >>> 0).toString(36)}`;
+}
+
+/**
+ * Carry the old keys of `pairs` ([old, new]) to the new ones in `area` (a Storage), as said above,
+ * keeping what was looked at under `record`. Returns the new keys written or removed.
+ */
+export function carryKeys(area, pairs, record = RECORD) {
+  const carried = [];
+  if (!area) return carried;
+  let seen = {};
+  try {
+    const kept = JSON.parse(area.getItem(record) ?? "{}");
+    if (kept && typeof kept === "object" && !Array.isArray(kept)) seen = kept;
+  } catch {} // unreadable: as if nothing was looked at (a new key written still wins)
+  let changed = false;
+  for (const [old, now] of pairs) {
+    try {
+      const value = area.getItem(old);
+      const mark = digest(value);
+      const first = !Object.hasOwn(seen, old);
+      if (!first && seen[old] === mark) continue;
+      if (first ? value !== null && area.getItem(now) === null : true) {
+        if (value === null) area.removeItem(now);
+        else area.setItem(now, value);
+        carried.push(now);
+      }
+      seen[old] = mark;
+      changed = true;
+    } catch {} // full or blocked: this key is looked at again next time
+  }
+  if (changed) {
+    try {
+      area.setItem(record, JSON.stringify(seen));
+    } catch {}
+  }
+  return carried;
+}
+
+/**
+ * Copy what IndexedDB database `from` holds in object store `store` into the one `open()` opens (a
+ * connection of its own to the new database, made with that store as its owner makes it; closed
+ * here once done): each key the new one does not hold
+ * yet, so it runs any number of times with the same result and never takes a choice made since.
+ * The old database is never made (looked for, not opened, when it is not there), changed or
+ * deleted. Resolves to the number of entries copied; a failure rejects and leaves both as they were
+ * but for what was copied whole, to be tried again next time.
+ */
+export async function carryDatabase(factory, { from, store, open }) {
+  const done = (request) => new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+  if (typeof factory.databases === "function" && !(await factory.databases()).some((database) => database.name === from)) return 0;
+  const old = await new Promise((resolve, reject) => {
+    const request = factory.open(from);
+    let absent = false;
+    request.onupgradeneeded = () => { // it was not there: make nothing
+      absent = true;
+      request.transaction.abort();
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = (event) => {
+      if (!absent) return reject(request.error);
+      event.preventDefault();
+      resolve(null);
+    };
+  });
+  if (!old) return 0;
+  let entries;
+  try {
+    if (!old.objectStoreNames.contains(store)) return 0;
+    const reading = old.transaction(store, "readonly").objectStore(store);
+    const [keys, values] = await Promise.all([done(reading.getAllKeys()), done(reading.getAll())]);
+    entries = keys.map((key, index) => [key, values[index]]);
+  } finally {
+    old.close();
+  }
+  if (entries.length === 0) return 0;
+  const database = await open();
+  try {
+    const writing = database.transaction(store, "readwrite");
+    const target = writing.objectStore(store);
+    let copied = 0;
+    for (const [key, value] of entries) {
+      const held = target.get(key);
+      held.onsuccess = () => {
+        if (held.result !== undefined) return;
+        target.put(value, key);
+        copied++;
+      };
+    }
+    await new Promise((resolve, reject) => {
+      writing.oncomplete = resolve;
+      writing.onerror = () => reject(writing.error);
+      writing.onabort = () => reject(writing.error ?? new Error("aborted"));
+    });
+    return copied;
+  } finally {
+    database.close();
+  }
+}
+
+// As this module loads, in a page (never in Node, which imports it with the modules that name a key).
+if (typeof document !== "undefined") {
+  const local = (() => { try { return globalThis.localStorage ?? null; } catch { return null; } })();
+  const session = (() => { try { return globalThis.sessionStorage ?? null; } catch { return null; } })();
+  carryKeys(local, [...LOCAL_PAIRS, ...prefixPairs(local)]);
+  carryKeys(session, prefixPairs(session));
+  // A tab of the old version, still open, changed an old key: carried now, so that what this page
+  // writes after it (which it can only do later) stays the latest.
+  globalThis.addEventListener?.("storage", (event) => {
+    if (!local || event.storageArea !== local) return;
+    const pair = LOCAL_PAIRS.find(([old]) => old === event.key) ?? prefixPair(event.key);
+    if (pair) carryKeys(local, [pair]);
+  });
+}

package/browser/shared/reports.mjs

@@ -0,0 +1,46 @@
+import fs from "node:fs/promises";
+import { namedLinks, pageLinks } from "./page-links.mjs";
+import { reportsDirectory } from "./paths.mjs";
+import { documentDirectory, documentFiles, listDocumentSlugs, listTrash, slugPattern } from "./workspace.mjs";
+
+// The documents' layout, as every system reads it (./workspace.mjs): one folder a document,
+// <workspace>/<slug>/ with doc.html and doc.json (report.html and report.json in one made before
+// Gallery 0.1), its slug lowercase kebab-case. Dot names (.gallery/) and exports/ are never documents.
+
+export { slugPattern };
+
+// A workspace with no documents yet has none: gallery new makes the folder with its first one.
+export async function listReportSlugs(directory = reportsDirectory) {
+  return listDocumentSlugs(directory);
+}
+
+/**
+ * The links of the documents of the workspace at `directory`, by their titles as they are now
+ * (./page-links.mjs): { links: a Map of slug to link of those of the sidebar, named: those and the
+ * trash's, what an address written for anyone goes by }. A doc.json that cannot be read now (an Agent
+ * writing it) names no title, and its document goes by its page id alone.
+ */
+export async function documentLinks(directory = reportsDirectory) {
+  const page = async (slug) => ({ slug, title: await fs.readFile(documentFiles(documentDirectory(slug, directory)).json, "utf8").then((text) => JSON.parse(text).title).catch(() => null) });
+  const links = pageLinks(await Promise.all((await listDocumentSlugs(directory)).map(page)));
+  return { links, named: namedLinks(links, await listTrash(directory)) };
+}
+
+// The page of the user's writing preferences (写作偏好: `"instructions": true` in its doc.json, one at
+// most, in <workspace>/.gallery/pages/<slug>/): a page like any other to edit, which the workbench
+// opens from 设置 and lists apart from the documents, and writes as <workspace>/preferences.md for
+// Agents to read before they write (src/shared/writing-preferences.mjs). Any other doc.json field names
+// no role: an old one's "template" is read as nothing, the document an ordinary one.
+export async function isInstructions(directory) {
+  return (await roleOf(directory)) === "instructions";
+}
+
+/** What a document is besides a document: "instructions", or null (an ordinary one). */
+export async function roleOf(directory) {
+  try {
+    const metadata = JSON.parse(await fs.readFile(documentFiles(directory).json, "utf8"));
+    return metadata?.instructions === true ? "instructions" : null;
+  } catch {
+    return null;
+  }
+}

package/browser/shared/search.mjs

@@ -0,0 +1,85 @@
+import { unescapeText } from "./escape.mjs";
+
+// 搜索文档 in a report's text (the workbench's search: GET /__gallery/workspace/search). A report's text is
+// read as its blocks' lines: the text of its main below the header (the title is matched apart), a
+// line a block, no script, style or drawing, a formula its TeX. The words are found in a line as they
+// are typed (one phrase, upper and lower case alike, runs of spaces as one), each hit shown as a
+// snippet of its line around it; `before` (the text just before it in its line) and `index` (which
+// time the words occur in the report) let the page find it again (editor/page/find/).
+
+const SKIPPED = /<(script|style|template|noscript|svg)\b[\s\S]*?<\/\1>/gi;
+const FORMULA = /\\\(([\s\S]*?)\\\)|\\\[([\s\S]*?)\\\]/g;
+const BLOCK = /<\/?(p|li|ul|ol|h[1-6]|table|tr|td|th|caption|summary|details|figure|figcaption|pre|blockquote|div|section|article|aside|dl|dt|dd|hr|br)\b[^>]*>/gi;
+
+/** Runs of spaces as one, the ends trimmed: a query as it is matched. */
+export const tidyQuery = (text) => String(text).replace(/\s+/g, " ").trim().slice(0, 100);
+
+/** The lines of report `html` (a whole report.html, or the inside of its main): its blocks' text. */
+export function reportLines(html) {
+  let body = String(html);
+  const main = /<main\b[^>]*>([\s\S]*)<\/main>/i.exec(body);
+  if (main) body = main[1];
+  body = body.replace(/^\s*<header\b[^>]*>[\s\S]*?<\/header>/i, " "); // the page's header: its title and icon
+  const text = body
+    .replace(SKIPPED, " ")
+    .replace(FORMULA, (_, inline, display) => ` ${inline ?? display} `)
+    .replace(BLOCK, "\n")
+    .replace(/<[^>]*>/g, "")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)))
+    .replace(/&#x([0-9a-f]+);/gi, (_, code) => String.fromCodePoint(parseInt(code, 16)));
+  return unescapeText(text).replace(/\u200b/g, "").split("\n").map(tidyQuery).filter(Boolean);
+}
+
+/**
+ * Where `query` occurs in `lines`: { count, hits }, hits the first `most` lines it is in (once a
+ * line), each { text (the snippet), start, end (the words in it), before, index }.
+ */
+export function findIn(lines, query, { most = 3, ahead = 16, length = 90 } = {}) {
+  const words = tidyQuery(query).toLowerCase();
+  const hits = [];
+  let count = 0;
+  if (!words) return { count, hits };
+  for (const line of lines) {
+    const lower = line.toLowerCase();
+    let shown = false;
+    for (let at = lower.indexOf(words); at >= 0; at = lower.indexOf(words, at + words.length)) {
+      if (!shown && hits.length < most) {
+        shown = true;
+        const from = at <= ahead ? 0 : at - ahead;
+        const to = Math.min(line.length, Math.max(from + length, at + words.length));
+        const head = from > 0 ? "…" : "";
+        hits.push({
+          text: `${head}${line.slice(from, to)}${to < line.length ? "…" : ""}`,
+          start: head.length + at - from,
+          end: head.length + at - from + words.length,
+          before: line.slice(Math.max(0, at - 16), at),
+          index: count,
+        });
+      }
+      count += 1;
+    }
+  }
+  return { count, hits };
+}
+
+/**
+ * gallery list's choice of the reports `words` name (src/cli/list.mjs): of `reports`
+ * ([{ slug, title, description, edited }]), those whose title, description or slug holds at least
+ * one of the words (upper and lower case alike; a word anywhere in them, as Chinese is written
+ * without spaces between words), the best first: those holding more of the words, then more of them
+ * in the title, then in the slug, then the one edited last. `words`: what was typed, split at spaces.
+ */
+export function rankReports(reports, words) {
+  const wanted = [...new Set(tidyQuery(words).toLowerCase().split(" ").filter(Boolean))];
+  if (!wanted.length) return [...reports].sort((a, b) => b.edited - a.edited);
+  const scored = reports.map((report) => {
+    const [title, slug, description] = [report.title, report.slug, report.description].map((value) => String(value ?? "").toLowerCase());
+    const found = wanted.filter((word) => title.includes(word) || slug.includes(word) || description.includes(word));
+    return { report, found: found.length, title: wanted.filter((word) => title.includes(word)).length, slug: wanted.filter((word) => slug.includes(word)).length };
+  });
+  return scored
+    .filter(({ found }) => found > 0)
+    .sort((a, b) => b.found - a.found || b.title - a.title || b.slug - a.slug || b.report.edited - a.report.edited)
+    .map(({ report }) => report);
+}

package/browser/shared/session.mjs

@@ -0,0 +1,77 @@
+// 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.
+//
+//   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
+//                                  has or whether a detail card is open changed: { title, icon, look, state,
+//                                  annotations, card } (icon: the page's icon, an emoji, or null; look: the
+//                                  document's look on its <html>, shared/document-look.mjs; card: a detail card is open)
+//                         reply    to a command, once it is done: { id, ok, ... }
+//                         key      a key combination the workbench registered, pressed in the page: { key }
+//                         notice   something to tell the reader, as the workbench's toast: { text, tone, hold,
+//                                  room }
+//                         noticeRoom
+//                                  the room the page's bottom panels take changed: { room }, px above the
+//                                  frame's bottom (0: none), which the workbench's toasts stand above
+//                         reload   show the report again (the file changed): the workbench loads it in a
+//                                  hidden frame (data-pending) and swaps it in once that page is ready,
+//                                  so the reader never sees a page being reloaded; this page has
+//                                  stopped (it commits and stores nothing more)
+//                         open     go to another document (a link in the page): { target, block }
+//                                  (`target` its slug, as `slug` stays the sender's; `block` a block's id
+//                                  or null), or { hash } (a workbench's address, which the page cannot
+//                                  read without the titles); unsaved text is as for a click in the sidebar
+//                         jump     a link goes to a block of this page, sent before the page goes there:
+//                                  { block, place } (`place` where the reader is: x, y, top and tabs as
+//                                  reading-place.mjs's placeIn gives them, the caret's unit, self and
+//                                  offset, the detail cards open as modals): the workbench adds a history
+//                                  entry, the way back to it being the command show-place
+//                         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
+//                         annotations-removed
+//                                  a 批注 deleted from its card: { items }: the workbench says so, as
+//                                  it does for 全部删除, and its 撤销 puts them back
+//   workbench -> report   command  { id, name, ... }
+
+export const PROTOCOL = "gallery/session";
+// The protocol's id before the product's rename (2026-10-26). A workbench and a page of different
+// versions meet when one was open before the server was updated and the other loaded after: each
+// side takes either id. The page, until the workbench has spoken to it (its first command), sends
+// every message under both ids, PROTOCOL first; once it has, only under the id the workbench used,
+// and it answers a command under the id the command came in. The workbench sends a frame its
+// commands under the id the frame last spoke, and takes an OLD_PROTOCOL message from a page that has
+// spoken PROTOCOL as the copy it is (ignored). So an old workbench still hears a new page's reload
+// and notices, and a new workbench drives an old page; nothing the page says is lost on either.
+export const OLD_PROTOCOL = "html-report-studio/session";
+/** The ids a message may carry: the new one first. */
+export const PROTOCOLS = [PROTOCOL, OLD_PROTOCOL];
+export const VERSION = 2;
+
+/**
+ * Where a page finds, as it starts, where its reader was ({ x, y, top, unit, self, offset, modals,
+ * notice }, once: autosave.mjs takeView; `top` as reading-place.mjs's placeIn gives it, which the way
+ * back from another document keeps): sessionStorage, which a workbench and its frames share. A page
+ * puts it there before it is shown again; the workbench before the way back comes to it.
+ */
+export const viewKey = (slug) => `gallery-edit:${slug}:view`;
+
+/**
+ * What `state` reports, in this order: editing (the editor runs: the page edits from the start),
+ * pending (changes wait to be saved, or are on their way), saving (a commit is on its way), offline
+ * (commits do not get through; the changes wait in the browser), conflicts (how many the reader has
+ * to decide, a number), changed (someone else wrote the file; the page shows it once nothing waits).
+ */
+export const STATE_FLAGS = ["editing", "pending", "saving", "offline", "conflicts", "changed"];
+
+/**
+ * A key combination as the protocol names it: "Mod" (Ctrl, or ⌘ on a Mac), "Alt", "Shift", then
+ * the key (a letter upper-cased), joined by "+": "Mod+K", "Mod+\\", "Mod+Shift+P".
+ */
+export function keyCombo(event, mac = /Mac|iPhone|iPad/.test(globalThis.navigator?.platform ?? "")) {
+  const mod = mac ? event.metaKey : event.ctrlKey;
+  const key = event.key.length === 1 ? event.key.toUpperCase() : event.key;
+  return [mod && "Mod", event.altKey && "Alt", event.shiftKey && "Shift", key].filter(Boolean).join("+");
+}

package/browser/shared/table-chart.mjs

@@ -0,0 +1,113 @@
+import { ZWSP } from "./inline-spacing.mjs";
+import { isMissingValue, numberReading } from "./number-reading.mjs";
+
+// A chart drawn from a table (docs/render.md, "Charts from a table"). An Agent writes an ordinary
+// table with data-doc-chart="<type>", a type its report's script defines (DocCharts.define); the
+// intake (src/editor/source/natural.mjs) makes it two blocks, the table's frame, which carries a key
+// (CHART_SOURCE), and right after it a chart card whose host names the table by that key
+// (CHART_DATA). The kit (src/render/kit/charts/from-table.js) reads the table as the page shows it and
+// draws the chart again when the table changes; the checks (src/render/chart-declarations.mjs) read it
+// from the file. Both take the rows a table gives a chart from here (tableRows): plain, predictable,
+// d3.csvParse's shape, each value read as the table's own sort reads it (number-reading.mjs). The
+// link is that pair of attributes alone, never an id or the blocks' order, so the reader may move,
+// 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).
+
+/** 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";
+/** A key: a letter, then letters, digits, "_" or "-", 32 at most. */
+export const CHART_KEY = /^[A-Za-z][\w-]{0,31}$/;
+
+/** The first key of t1, t2 … that `taken` (a Set) does not hold. */
+export function nextChartKey(taken) {
+  for (let index = 1; ; index++) if (!taken.has(`t${index}`)) return `t${index}`;
+}
+
+// A formula in a cell's text as the file writes it (and the page, before KaTeX draws it): its TeX
+// between \( \), \[ \] or $$ $$.
+const FORMULA = /\\\(([\s\S]*?)\\\)|\\\[([\s\S]*?)\\\]|\$\$([\s\S]*?)\$\$/g;
+
+/**
+ * A cell's words as a chart reads them, from the file (the checks) and from the page (the kit) alike:
+ * `text` its text, where a formula is its TeX (written between its delimiters in the file; the kit
+ * reads one KaTeX drew by its TeX: charts/from-table.js), the editor's zero-width pads none, blanks
+ * one space, none at either end.
+ */
+export const cellWords = (text) => text.replace(FORMULA, (_, inline, display, dollars) => inline ?? display ?? dollars).replaceAll(ZWSP, "").replace(/\s+/g, " ").trim();
+
+// 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"]);
+
+/**
+ * A cell's value for a chart (`cell`: { words, sort }, undefined where its row has none; `type`: its
+ * header's data-sort-type), as the table's sort reads it (number-reading.mjs, rawCellValue): its sort
+ * value when it has one, else its words; null for none (no cell, an empty one, a dash, n/a); its words
+ * in a column its header says holds words or dates; the number they write when they write one (12.5%
+ * 12.5, 3.6亿 360000000, 1,234 1234, (12) -12, 约 20 20, 120 ms 120); else its words (a range, 3–5 天,
+ * which a sort reads by its first number, is no one number: its words; so is 3 / 4).
+ */
+export function cellValue(cell, type = null) {
+  if (!cell) return null;
+  const raw = cell.sort ?? cell.words;
+  if (isMissingValue(raw)) return null;
+  if (WORD_TYPES.has(type)) return cell.words;
+  const reading = numberReading(raw);
+  return reading && !reading.range ? reading.value : cell.words;
+}
+
+/**
+ * The rows a table gives a chart drawn from it: { data } or, when it gives none, { error, message }
+ * (`error` for a check and the host's layout note, `message` the card's line for its reader, as the
+ * kit's words name it: [key, ...values], said in the page's language by src/render/kit/words.js).
+ * `table`: { names, types, rows, merged }: its header row's words (its head's first row, else a first
+ * 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,
+ * 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
+ * the header's words (cellValue: a number, its words, or null; a row shorter than the header null
+ * where it has no cell, the cells past the header not read), and `data.columns` the header's words in
+ * order. With no header row the first row is the header, as csvParse takes it; a header cell with no
+ * words is the key "", and of two alike the later column's value is the one kept (the checks note
+ * both: rowsReading). Merged cells give nothing: a value has one cell.
+ */
+export function tableRows(table) {
+  const fail = (error, ...message) => ({ error, message });
+  if (table.merged) return fail("has merged cells: write each value in its own cell, the category on every row", "merged-cells");
+  let { names, types, rows } = table;
+  if (!names) [names, types, rows] = rows.length > 0 ? [rows[0].map((cell) => cell?.words ?? ""), null, rows.slice(1)] : [[], null, []];
+  const data = rows.map((row) => {
+    const values = {};
+    names.forEach((name, column) => {
+      values[name] = cellValue(row[column], types?.[column] ?? null);
+    });
+    return values;
+  });
+  data.columns = [...names];
+  return { data };
+}
+
+/**
+ * What a table gave a chart (`table` as tableRows takes it, plus `foot`, its <tfoot>'s rows, which no
+ * chart reads; `data`: tableRows' rows), for the checks to say (chart-declarations.mjs
+ * tableChartReadings, chartDeclarationNotes): { rows: how many, columns: [{ name, numbers, words,
+ * empty }] how many of its values are numbers, words and null, column by column in the header's
+ * order (a name the header gives twice once: its later column's), blank: whether a header cell has no
+ * words, twice: the names the header gives twice, foot: how many <tfoot> rows were left out, extra:
+ * how many rows have cells past the header (not read) }.
+ */
+export function rowsReading(table, data) {
+  const names = data.columns;
+  const twice = [...new Set(names.filter((name, at) => names.indexOf(name) !== at))];
+  const columns = [...new Set(names)].map((name) => {
+    const values = data.map((row) => row[name]);
+    return { name, numbers: values.filter((value) => typeof value === "number").length, words: values.filter((value) => typeof value === "string").length, empty: values.filter((value) => value === null).length };
+  });
+  const rows = table.names ? table.rows : table.rows.slice(1);
+  return { rows: data.length, columns, blank: names.includes(""), twice, foot: table.foot?.length ?? 0, extra: rows.filter((row) => row.length > names.length).length };
+}