@heycys/gallery 0.0.0-stage → 0.1.0

package/browser/shared/preview-server.mjs

@@ -0,0 +1,247 @@
+import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import fs from "node:fs/promises";
+import net from "node:net";
+import path from "node:path";
+import { packageRoot } from "./paths.mjs";
+import { layoutOf } from "./workspace.mjs";
+
+// Where a workspace's Gallery server listens (one a gallery command started, kind "cli", or npm run
+// dev's, kind "dev"): the one way the commands tell this workspace's server from any other. gallery
+// export hands a document in through the server's edit service (POST /__gallery/edit/hand-in), in the
+// queue its pages' commits run in, instead of writing the file beside them; gallery open, new and
+// import give a document's address on it, or start one when none runs (src/cli/server-process.mjs).
+// The server keeps a small file in its workspace while it listens, .gallery/server.json (one server
+// a workspace), with its port, its process, the token its requests need, its kind and Gallery's
+// version; a command finds it there, or does without it when there is none, or its process is gone.
+// A port is never asked whose it is: 4317 may be another workspace's server, whose pages would write
+// that workspace's files.
+
+// A directory as one name, however it was reached: on Windows a drive letter and the folders' names
+// may be typed in either case (`cd /d d:\…` in cmd gives d:\), and they name the same directory.
+const canonical = (directory) => {
+  const resolved = path.resolve(directory);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+};
+/** Whether two paths name the same directory (a server's workspace and a command's). */
+export const sameDirectory = (a, b) => canonical(a) === canonical(b);
+
+const fileOf = (reportsDirectory) => layoutOf(reportsDirectory).serverFile;
+/** Gallery's version, as its package says it (a server of another version is another Gallery's). */
+export const galleryVersion = (() => {
+  try {
+    return JSON.parse(readFileSync(path.join(packageRoot, "package.json"), "utf8")).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+// Whether a process runs (only asked: nothing is sent to it).
+const runs = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+};
+
+/**
+ * Keep where the server listens: { port, pid, workspace, token, nonce, kind, version, started }, for
+ * as long as it does (the owner's alone on POSIX: the token authorizes writes), so
+ * that a server that runs is one the commands find, never one a command starts a second server
+ * beside (which would take the announcement: the pages' commits in one queue, an export's hand-in in
+ * another). Every `every` ms (0: never) it is written again when its file is gone (taken away by
+ * hand, or by a server of these reports that closed as this one wrote it) or names a process that is
+ * gone (left behind). One that names another process that runs is left: a server of these reports
+ * started later (the last to start is the one the commands use), or the one Vite started again in
+ * this process. The .gallery/ folder is made again, never the workspace (a workspace deleted stays
+ * deleted). Resolves to a function that stops that and, only while the announcement is this one's
+ * (`nonce`), gives the file back to the server it was written over when that one's process runs (in
+ * another process: in this one it is Vite's earlier server), or else takes it away: for when the
+ * server closes. A server stopped without closing leaves it behind, which the commands find out (its
+ * process gone, its port answering no more).
+ */
+export async function announcePreviewServer({ reportsDirectory, port, token, kind = "dev", version = galleryVersion, every = 1000 }) {
+  const file = fileOf(reportsDirectory);
+  const nonce = randomBytes(8).toString("hex");
+  const text = `${JSON.stringify({ port, pid: process.pid, workspace: path.resolve(reportsDirectory), token, nonce, kind, version, started: new Date().toISOString() })}\n`;
+  const save = (content) => fs.writeFile(file, content, { mode: 0o600 });
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const before = await fs.readFile(file, "utf8").catch(() => null);
+  await save(text);
+  let closed = false;
+  const look = async () => {
+    let there = null;
+    try {
+      there = JSON.parse(await fs.readFile(file, "utf8"));
+    } catch (error) {
+      if (error.code !== "ENOENT") return; // being written (by another server), or not an announcement: left
+    }
+    if (there && (there.nonce === nonce || !Number.isInteger(there.pid) || runs(there.pid))) return;
+    if (closed) return;
+    await fs.mkdir(path.dirname(file)).catch(() => {});
+    await save(text).catch(() => {});
+  };
+  let looking = Promise.resolve();
+  const keeping = every > 0 ? setInterval(() => (looking = looking.then(look).catch(() => {})), every) : null;
+  keeping?.unref();
+  return async () => {
+    closed = true;
+    clearInterval(keeping);
+    await looking;
+    try {
+      if (JSON.parse(await fs.readFile(file, "utf8")).nonce !== nonce) return;
+    } catch {
+      return;
+    }
+    let earlier = null;
+    try {
+      earlier = JSON.parse(before);
+    } catch {}
+    const back = Number.isInteger(earlier?.pid) && earlier.pid !== process.pid && runs(earlier.pid);
+    await (back ? save(before) : fs.rm(file, { force: true })).catch(() => {});
+  };
+}
+
+// The announcement of this workspace's server, while its process runs: { port, pid, workspace, token, nonce, kind, version, started }.
+export async function readAnnouncement({ reportsDirectory }) {
+  let found;
+  try {
+    found = JSON.parse(await fs.readFile(fileOf(reportsDirectory), "utf8"));
+  } catch {
+    return null;
+  }
+  if (!Number.isInteger(found?.port) || !Number.isInteger(found.pid) || typeof found.token !== "string" || typeof found.workspace !== "string" || !sameDirectory(found.workspace, reportsDirectory)) return null;
+  return runs(found.pid) ? found : null;
+}
+
+/** Whether process `pid` runs (only asked: nothing is sent to it). */
+export const processRuns = runs;
+
+/**
+ * How the server an announcement names answers on its port, within `timeout` ms: "yes", as that
+ * server (GET /__gallery/workspace/info there names the announcement's token, its process and this
+ * workspace, docs/workbench.md; there itself, not where it sends the request on to); "no", as none (a
+ * server stopped without closing leaves its announcement behind, and by now its process's number may
+ * be another program's, its port another server's); or "busy": the port took the request and gave no
+ * answer in time.
+ */
+export async function answerOf(found, reportsDirectory, timeout) {
+  try {
+    const response = await fetch(`http://127.0.0.1:${found.port}/__gallery/workspace/info`, { redirect: "error", signal: AbortSignal.timeout(timeout) });
+    const info = response.ok ? await response.json() : null;
+    const same = info?.token === found.token && info.server?.pid === found.pid && typeof info.server.workspace === "string" && sameDirectory(info.server.workspace, reportsDirectory);
+    return same ? "yes" : "no";
+  } catch (error) {
+    return error?.name === "TimeoutError" ? "busy" : "no";
+  }
+}
+
+/**
+ * The running server of this workspace: { port, token, pid }, or null when none says it runs. With
+ * `answering`, only one that answers on its port as the server its announcement names, within
+ * `timeout` ms (gallery open, which gives its address to the user); gallery export asks without it,
+ * its hand-in's own request telling whether the server takes it (a server slow to answer may still
+ * write the file).
+ */
+export async function findPreviewServer({ reportsDirectory, answering = false, timeout = 10_000 }) {
+  const found = await readAnnouncement({ reportsDirectory });
+  if (!found || (answering && (await answerOf(found, reportsDirectory, timeout)) !== "yes")) return null;
+  return { port: found.port, token: found.token, pid: found.pid };
+}
+
+/**
+ * Whether `port` of 127.0.0.1 is free: nothing holds it (held for a moment), and nothing answers on
+ * it (a server listening on every address may leave 127.0.0.1 alone to be held).
+ */
+export const portIsFree = (port) => new Promise((resolve) => {
+  const holder = net.createServer();
+  holder.once("error", () => resolve(false));
+  holder.listen(port, "127.0.0.1", () => holder.close(() => {
+    const socket = net.connect(port, "127.0.0.1");
+    socket.once("connect", () => {
+      socket.destroy();
+      resolve(false);
+    });
+    socket.once("error", (error) => resolve(error.code === "ECONNREFUSED"));
+  }));
+});
+
+/** -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;
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// Whether process `pid` is gone within `ms` (asked every 100 ms).
+async function goneWithin(pid, ms) {
+  for (const until = Date.now() + ms; Date.now() < until; await sleep(100)) if (!runs(pid)) return true;
+  return !runs(pid);
+}
+
+/**
+ * Stop the server announcement `found` names, which answered as that server during this call
+ * (answerOf "yes": its process is this server's, never a number used again): POST
+ * /__gallery/workspace/stop (its token; the server finishes the saves in its queue, closes and exits), then,
+ * when its process still runs after `wait` ms, that process killed. Resolves to { ok: true, killed }
+ * or { ok: false, reason: "dev" (npm run dev's: stopped where it runs) | "running" (it would not stop), message }.
+ */
+export async function stopServer(found, { wait = 10_000 } = {}) {
+  const host = `127.0.0.1:${found.port}`;
+  let status = 0;
+  try {
+    const response = await fetch(`http://${host}/__gallery/workspace/stop`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Origin: `http://${host}`, "X-Gallery-Token": found.token },
+      body: "{}",
+      signal: AbortSignal.timeout(wait),
+    });
+    status = response.status;
+    await response.text().catch(() => "");
+  } catch {} // it closed as it answered, or did not answer: its process says
+  if (status === 409) return { ok: false, reason: "dev", message: `This workspace's server is npm run dev's (port ${found.port}, pid ${found.pid}): stop it where it runs.` };
+  if (await goneWithin(found.pid, wait)) return { ok: true, killed: false };
+  try {
+    process.kill(found.pid);
+  } catch {}
+  if (await goneWithin(found.pid, 3000)) return { ok: true, killed: true };
+  return { ok: false, reason: "running", message: `The server on port ${found.port} (pid ${found.pid}) did not stop: end that process yourself.` };
+}
+
+/**
+ * This workspace's server, for a command that needs one (src/cli/server-process.mjs serverFor): the
+ * one its announcement names when it answers there within `timeout` ms (as findPreviewServer with
+ * `answering`), or else one `start(port)` starts on the first free port of `ports`. A server of
+ * Gallery's of an older `version` (a command's, kind "cli": never npm run dev's) is stopped first
+ * (`stop(found)`, stopServer) and replaced; a newer one, or npm run dev's of any version, is used.
+ * Resolves to { port, started: what `start` gave, or null for a server that ran already, running: {
+ * pid, kind, version } of that one, replaced: { pid, version } of the one stopped, or null, passed:
+ * the ports passed over, as "4317 (in use)" }; `port` is null when none of `ports` is free; when the
+ * announced server's port took the request and gave no answer in time, with `busy: { port, pid,
+ * version, newer }`: this workspace's server, busy or stuck, and none is started beside it; and when
+ * an older one would not stop, with `stuck: { port, pid, message }`.
+ */
+export async function previewServerFor({ reportsDirectory, ports, start, stop = stopServer, timeout = 10_000, version = galleryVersion }) {
+  const found = await readAnnouncement({ reportsDirectory });
+  const answer = found ? await answerOf(found, reportsDirectory, timeout) : "no";
+  const kind = found?.kind === "dev" ? "dev" : "cli";
+  const order = found ? compareVersions(found.version, version) : 0;
+  if (answer === "busy") return { port: null, started: null, passed: [], replaced: null, busy: { port: found.port, pid: found.pid, version: found.version ?? null, newer: kind === "cli" && order > 0 } };
+  let replaced = null;
+  if (answer === "yes") {
+    if (kind === "dev" || order >= 0) return { port: found.port, started: null, passed: [], replaced: null, running: { pid: found.pid, kind, version: found.version ?? null } };
+    const stopped = await stop(found);
+    if (!stopped.ok) return { port: null, started: null, passed: [], replaced: null, stuck: { port: found.port, pid: found.pid, message: stopped.message } };
+    replaced = { pid: found.pid, version: found.version ?? null };
+  }
+  const passed = [];
+  for (const port of ports) {
+    if (await portIsFree(port)) return { port, started: await start(port), passed, replaced };
+    passed.push(`${port} (in use)`);
+  }
+  return { port: null, started: null, passed, replaced };
+}

package/browser/shared/qa-levels.mjs

@@ -0,0 +1,93 @@
+// The levels of what gallery qa finds (src/cli/qa.mjs, docs/render.md "Quality check"), and
+// of the kit's layout notes (data-doc-layout), which the preview's note reads with the same
+// function (render/preview-checks.mjs puts layoutNotesScript() in the page): a note that fails qa is
+// among the preview's failures, the others its 排版提示. levelOf and layoutNotesOf read nothing but
+// WIDE, KINDS and NARROW_INFO, so they can be written into a page as their text. And the windows
+// gallery qa looks in, whose widths the preview's note names.
+
+// Three widths in a window 900px tall, and the widest again in a laptop's window (768px tall), where
+// a frame of the kit's height (72vh) shows fewer rows: that look says only what the first did not.
+export const LOOKS = [
+  { width: 1024, height: 900, label: "1024" },
+  { width: 1024, height: 768, label: "1024×768", laptop: true },
+  { width: 736, height: 900, label: "736" },
+  { width: 360, height: 900, label: "360" },
+];
+// The widths blocks are pictured at (the laptop's window adds no pictures of blocks).
+export const WIDTHS = LOOKS.filter((look) => !look.laptop).map((look) => look.width);
+
+// A table's columns or rows out of sight, and a code block or a formula whose content scrolls inside
+// its frame, are a warning only where a reader has room for them (WIDE and wider), and info below,
+// where a frame that scrolls is what it does (NARROW_INFO).
+export const WIDE = 736;
+export const LEVELS = ["fail", "warn", "unverified", "info"];
+export const KINDS = {
+  error: "fail", // the page's error, uncaught or on the console
+  request: "fail", // a request that failed
+  blocked: "fail", // what the export's policy blocked: a file not embedded
+  image: "fail", // a picture that did not load
+  "chart-empty": "fail", // a chart that drew nothing (the kit's data-missing too)
+  "chart-text-clipped": "fail", // a chart's text cut by a clip
+  "chart-text-outside": "fail", // a chart's text outside its card
+  "raw-formula": "fail", // TeX shown as written
+  "formula-error": "fail", // a formula KaTeX refused
+  overflow: "fail", // the page wider than the window
+  "overflow-in-block": "warn", // words past the side of their box in a whole block or a figure's drawing, over what is beside it
+  "cut-in-block": "warn", // words or marks of a whole block or a figure's drawing cut at the bottom of a box that clips them
+  "table-columns": "warn", // a table's columns out of sight or cut (below WIDE: info)
+  "table-rows": "warn", // a table's rows below a frame of the kit's height (below WIDE: info)
+  "code-scrolls": "warn", // a code block's code scrolling inside its frame (below WIDE: info)
+  "formula-scrolls": "warn", // a formula block scrolling inside its frame (below WIDE: info)
+  "chart-text-overlap": "warn", // two texts of a drawing over each other
+  "svg-text-small": "warn", // a drawing's text its viewBox scales below a readable size
+  ticks: "warn", // a value axis's tick labels closer than a digit's width and a hair (0.6em)
+  "layout-note": "info", // the kit's other notes on its layout
+  "table-scrolls": "info", // a table that scrolls in its frame
+  "code-title-cut": "info", // a code block's title cut to fit its header
+  unverified: "unverified", // a wait that ran out, a state not reached, a picture not taken
+};
+
+// The kinds that warn at WIDE and wider and are info below.
+export const NARROW_INFO = ["table-columns", "table-rows", "code-scrolls", "formula-scrolls"];
+
+/** The level of a finding of `kind` at a window `width` px wide. */
+export function levelOf(kind, width) {
+  if (NARROW_INFO.includes(kind)) return width >= WIDE ? "warn" : "info";
+  return KINDS[kind] ?? "warn";
+}
+
+/**
+ * The notes the kit wrote on an element (data-doc-layout: one a line, each "<name>: <message>",
+ * such as "data-missing: its table has merged cells: …"), each with the kind of finding it makes and
+ * its level at a window `width` px wide: data-missing fails (a chart drawn from a table with nothing
+ * to draw, its card saying why: chart-empty); columns-hidden is a table's columns out of sight and
+ * rows-hidden its rows below its frame (warnings where a reader has room for them, info below); any
+ * other note is info. [{ note, name, kind, level }]
+ */
+export function layoutNotesOf(value, width = Infinity) {
+  const kinds = { "columns-hidden": "table-columns", "rows-hidden": "table-rows", "data-missing": "chart-empty" };
+  return String(value ?? "").split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((note) => {
+    const name = note.split(":")[0].trim().toLowerCase();
+    const kind = kinds[name] ?? "layout-note";
+    return { note, name, kind, level: levelOf(kind, width) };
+  });
+}
+
+/**
+ * A layout note of the kit's that fails (layoutNotesOf's `note`, "<name>: <message>"), in the words of
+ * the person reading the preview's note, in Chinese unless { english } (the UI's language): a chart
+ * that drew nothing (the preview says its card's own line of why when it has one), in a sentence. The
+ * note itself, in English, is gallery qa's and an Agent's, and stays as it is on the page; a note it
+ * does not know is said as it is. Written with no outside name, so the preview's page can carry it
+ * (layoutNotesScript).
+ */
+export function noteInWords(note, { english = false } = {}) {
+  const text = String(note ?? "").trim();
+  const colon = text.indexOf(":");
+  const name = colon < 0 ? "" : text.slice(0, colon).trim().toLowerCase();
+  if (name === "data-missing") return english ? "The chart was not drawn: its table gave it nothing to draw" : "图表没有画出来：从表格里没读到能画的数据";
+  return text;
+}
+
+/** levelOf, layoutNotesOf and noteInWords as a script's text, for a page (the preview's note) to read notes as qa does and say them. */
+export const layoutNotesScript = () => `const WIDE = ${WIDE}; const KINDS = ${JSON.stringify(KINDS)}; const NARROW_INFO = ${JSON.stringify(NARROW_INFO)}; ${levelOf}; ${layoutNotesOf}; ${noteInWords};`;

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]);
+  });
+}