@heycys/gallery 0.0.0-stage → 0.1.0

package/browser/shared/old-names.mjs

@@ -0,0 +1,143 @@
+// The format's old names, made new (2026-10-26). Until then the HTML a report is written in named
+// its kit with "report": classes report-*, attributes data-report-*, custom properties --report-*,
+// globals and SDK types Report*, events report-*-change. They are doc-*, data-doc-*, --doc-* and
+// Doc* now (docs/render.md, "Names"). A file written before, an Agent that still writes the old
+// names (the user's own 写作偏好 may teach them for good) and an export made before all keep
+// working: the tools read a report's text through newNames (new-names.mjs) where they already make
+// its natural HTML the kit's (source/natural.mjs naturalize: the preview before showing it, the
+// first edit, gallery check, build, export and ids, gallery import) and where they read a page of
+// Gallery's own made elsewhere (an import of an export, a paste: newDomNames below), so every reader past those reads the new names
+// only, and a file takes them the next time a tool writes it. The kit's runtime answers to the old
+// globals too (window.ReportCharts is DocCharts), for a script of the report's folder that no
+// tool rewrites.
+//
+// The old names are a closed set: those the kit had on 2026-10-26 (the rename's table), never one
+// added since. A class written report-<name> of none of them (a typo) is left as written, for the
+// checks to say as the file writes it (component-checks.mjs). An id the report spelled as an old
+// name (id="report-summary") is renamed with everything of the file that names it (its selectors and
+// script strings, href="#…", for, aria-*), so they still meet; inside the report's own <style> and
+// <script> a whole old name is renamed wherever it stands, their comments too. Nothing else of the
+// file changes: its text and comments, other ids, slugs (report-2) and paths (assets/report-chart.png)
+// stay as written; what the product is named after (gallery, html-report-studio, /__gallery/edit/) is no name
+// of the format.
+
+/** The kit's old class, keyframe, event and meta names: report-<name> for each, now doc-<name>. */
+export const OLD_NAMES = new Set([
+  "accent", "align-", "align-center", "align-left", "align-right", "annotations-changed", "assets-changed", "bar", "bar-series", "bar-shares",
+  "bold", "bookmark", "bookmark-card", "bookmark-cover", "bookmark-description", "bookmark-href", "bookmark-icon", "bookmark-text",
+  "bookmark-title", "bookmark-url", "button", "callout", "card", "chart", "chart-message", "charts", "checks", "checks-layout", "checks-live",
+  "code", "code--folded", "code--nowrap", "code--wrap", "code-block", "code-card", "code-content", "code-copy", "code-fold", "code-header",
+  "code-language", "code-line", "code-line--", "code-line--added", "code-line--folded", "code-line--hidden", "code-line--removed",
+  "code-line-fold", "code-line-more", "code-lines", "code-range", "code-run", "code-separator", "code-title", "code-toolbar", "code-tools",
+  "code-wrap", "column", "columns", "details", "details-content", "details-summary-label", "dialog", "dialog-close", "dialog-content",
+  "dialog-fade", "dialog-header", "dialog-in", "dialog-open", "dialog-panel", "dialog-title", "dialog-trigger", "dialogs", "diff", "diff-",
+  "diff-added", "diff-body", "diff-removed", "diff-stats", "display", "display-button", "display-check", "display-header", "display-icon",
+  "display-item", "display-label", "display-menu", "display-section", "display-switch", "edit-map", "embed", "embed--file", "embed-frame",
+  "export-copy-done", "export-id", "export-source", "figure", "figure--compact", "figure-caption", "file", "file-link", "file-name",
+  "file-size", "filter", "filter-button", "filter-row", "flow", "flow-right", "grid", "grid-3", "header", "hero", "highlight", "highlight-",
+  "highlight-blue", "highlight-brown", "highlight-gray", "highlight-green", "highlight-orange", "highlight-pink", "highlight-purple",
+  "highlight-red", "highlight-yellow", "icon", "image", "image--center", "image--left", "image--right", "image--wide", "image-like", "kicker",
+  "kit-error", "layout-change", "lead", "lede", "legend", "link-mention", "link-mention-icon", "link-mention-title", "math", "math-",
+  "math-block", "math-break", "math-inline", "math-joiner", "math-tie", "note", "page", "panel", "pie-", "pie-center", "pie-labels",
+  "pie-slice", "pie-slices", "plot-clip", "plot-clip-", "prose", "prose-h1", "prose-h2", "prose-h3", "prose-h4", "range", "reference-legend",
+  "reveal", "scrollbar", "scrollbar--x", "scrollbar--y", "scrollbar-thumb", "scrollbars", "scrollbars-frame", "section",
+  "section--no-divider", "section-header", "sheet-dock", "sheet-shell", "sheet-shell--plain", "sheet-tab", "sheet-tabs", "sheets", "sheets-",
+  "source", "source-changed", "state", "state-actions", "state-field", "state-fields", "state-grid", "state-group", "state-list",
+  "state-status", "summary", "swatch", "tab", "table", "table--auto", "table--full", "table--sticky-first", "table-meta", "table-sort",
+  "table-sort-button", "table-wrap", "tables", "text-", "text-blue", "text-brown", "text-cyan", "text-gray", "text-green", "text-orange",
+  "text-pink", "text-purple", "text-red", "text-teal", "text-yellow", "theme-change", "theme-request", "title", "todo", "tokens", "tooltip",
+  "tooltip-row", "underline-", "underline-blue", "underline-orange", "underline-plain", "underline-purple", "underline-thick",
+  "underline-thin", "valign-", "valign-bottom", "valign-middle", "valign-top", "zoom", "zoom-", "zoom-caption", "zoom-close", "zoom-fade",
+  "zoom-grow", "zoom-gutter", "zoom-hover", "zoom-open", "zoom-picture",
+]);
+
+/** The kit's old globals and SDK types: Report<name> for each, now Doc<name>. */
+export const OLD_GLOBALS = [
+  "ChartBaseOptions", "ChartDrawContext", "ChartHandle", "ChartPart", "ChartPartContext", "Charts", "ChartsApi", "ChartState", "Code",
+  "Dialogs", "DialogsApi", "DotDatum", "DrawnChartHandle", "Kit", "Math", "MathApi", "PieDatum", "SharedChartOptions", "SharedChartType",
+  "Sheets", "SheetsApi", "SheetsHandle", "SortDirection", "SortType", "State", "StateChange", "StateFactory", "StateOptions",
+  "TableChartChoices", "TableChartOptions", "TableChoices", "Tables", "TablesApi", "TableSeriesChoices", "TableSortDetail", "TableState",
+  "Tokens", "TokensApi", "TokenSnapshot", "ValueFormat",
+];
+
+// A name of the old set where it stands as a whole (a class, a selector's, a keyframe's, an event's,
+// an id's, a string's), never inside another word (html-report-studio, x-report-studio-*, x-gallery-*) and never
+// a file's name (assets/report-chart.png, report-chart.png: a path stays as the folder has it).
+const FILE_TYPE = "png|jpe?g|gif|svg|webp|avif|bmp|ico|css|js|mjs|cjs|ts|json|html?|xml|pdf|csv|tsv|txt|md|woff2?|ttf|otf|mp4|webm|mov|mp3|wav|ogg|zip";
+const NAME = new RegExp(String.raw`(?<![\w$/-])report-([a-z0-9]+(?:-{1,2}[a-z0-9]+)*-{0,2})(?![\w-])(?!\.(?:${FILE_TYPE})(?![\w-]))`, "g");
+// The SDK's files were report-*.d.ts (sdk/report-charts.d.ts): a script's type import names them by path.
+const SDK_FILE = /(\bsdk\/)report-(?=[a-z])/g;
+// An id named where an attribute points to one (href="#report-summary", data-doc-dialog-open="#…",
+// fill="url(#report-grad)"): its old name new, as the id's own is (ID_LISTS).
+const ID_REFERENCE = /(?<=^|[\s(,'"=])#report-([a-z0-9]+(?:-{1,2}[a-z0-9]+)*)(?![\w-])/g;
+// The attributes whose value is ids (an element's own, or those it points to).
+const ID_LISTS = /^(?:id|for|headers|list|form|aria-(?:labelledby|describedby|controls|owns|activedescendant|details|errormessage|flowto))$/i;
+const ATTRIBUTE = /(?<![\w-])data-report-(?=[\w$])/gi;
+const PROPERTY = /(?<![\w-])--report-(?=[\w$])/gi;
+const DATASET = /\b(dataset\??\.)report(?=[A-Z])/g;
+const GLOBAL = new RegExp(`\\bReport(?=(?:${[...OLD_GLOBALS].sort((a, b) => b.length - a.length).join("|")})\\b)`, "g");
+const FONT = /\bReport Segoe\b/g; // the kit's alias of Segoe UI (styles/tokens.css)
+// What a text needs to hold for any of these to be in it: most files hold none, and are not parsed.
+const ANY = /report-|Report(?:[A-Z]| Segoe)|\.report[A-Z]/;
+
+/**
+ * Whether a class is in the kit's namespace: doc-*, or report-* left as written (none of the old set:
+ * a typo of an old name), which the checks say as the kit's (no class of its, did you mean …), never
+ * taking it for a class of the report's own.
+ */
+export const kitNamespace = (name) => /^(?:doc|report)-/.test(name);
+
+/** A name in the kit's namespace as the kit's new names spell it (report-calout: doc-calout), to compare. */
+export const asDocName = (name) => name.replace(/^report-/, "doc-");
+
+/** Whether a text may hold an old name: most hold none, and need not be read again. */
+export const mayHoldOldNames = (text) => ANY.test(text);
+
+/** A class attribute's value (or a list of classes, a meta's name) with its old names new: those of the old set alone. */
+export const newClassNames = (text) => text.replace(NAME, (whole, name) => (OLD_NAMES.has(name) ? `doc-${name}` : whole));
+
+/** An attribute's name with its old prefix new (data-report-id: data-doc-id). */
+export const newAttributeName = (name) => name.replace(ATTRIBUTE, "data-doc-");
+
+/** A text's custom properties new (--report-ink: --doc-ink), as any attribute's value may name them (an SVG's fill). */
+export const newProperties = (text) => text.replace(PROPERTY, "--doc-");
+
+/**
+ * An attribute's value with the old names new, by what the attribute holds: a class list (a meta's
+ * name too), ids (id, for, aria-labelledby …: an id spelled as an old name is renamed with the
+ * selectors and script strings that name it, so they still meet), a style, or anything else (custom
+ * properties, and an id it points to: href="#report-summary"). Code (on*, javascript:) is the caller's.
+ */
+export const newAttributeValue = (name, value, tag) => (name === "class" || (name === "name" && tag === "meta") || ID_LISTS.test(name)
+  ? newClassNames(value)
+  : name === "style" ? newStyleNames(value)
+    : newProperties(value).replace(ID_REFERENCE, (whole, old) => (OLD_NAMES.has(old) ? `#doc-${old}` : whole)));
+
+const names = newClassNames;
+const properties = newProperties;
+
+/** A stylesheet's text (a <style>'s, a style attribute's) with the old names new. */
+export const newStyleNames = (text) => properties(names(text.replace(ATTRIBUTE, "data-doc-").replace(FONT, "Doc Segoe")));
+
+/** A script's text (a <script>'s, an on* attribute's, a javascript: address) with the old names new. */
+export const newScriptNames = (text) => newStyleNames(text).replace(DATASET, "$1doc").replace(GLOBAL, "Doc").replace(SDK_FILE, "$1doc-");
+
+
+/**
+ * The old names in a DOM made new where they stand (what another program pasted: a page or an export
+ * of Gallery (HTML Report Studio then) made before 2026-10-26, its classes and attributes as its page had them): every
+ * element under `root`, its data-report-* attributes and their values (classes, ids and what points
+ * to one, style, custom properties: newAttributeValue). Text is left as it is.
+ */
+export function newDomNames(root) {
+  for (const element of root.querySelectorAll("*")) {
+    for (const { name, value } of [...element.attributes]) {
+      const renamed = newAttributeName(name);
+      const next = newAttributeValue(name, value, element.localName);
+      if (renamed === name && next === value) continue;
+      if (renamed !== name) element.removeAttribute(name);
+      element.setAttribute(renamed, next);
+    }
+  }
+  return root;
+}

package/browser/shared/page-address.mjs

@@ -0,0 +1,140 @@
+import { pageLink, pageOfLink } from "./page-links.mjs";
+
+// A document's address, as a link, a paste or the address bar may write it (docs/workbench.md, "A
+// document's addresses"), read in one place: { slug, block }, block null for the page itself. Pure: the
+// link card, a paste, a click, the workbench's address and the checks all come here, and a click
+// stays synchronous, for only one form asks for a list.
+//
+// In a file there is one form, an ordinary link between two ordinary files: ../<slug>/doc.html (an old
+// document's ../<slug>/report.html), with #<block id> for a block; #<block id> within a page, which
+// names no page and is no business of this module's. It holds no port and no title, and a slug in a
+// file is no address a reader sees. On this computer's own host (127.0.0.1 or localhost) or as a path
+// alone, a document is also /generated/<slug>.html (its page, with any query) and /<slug>/doc.html,
+// each with #<block id>, and in a workbench's address /#<link>/<block id> and /#<link> (shared/page-links.mjs:
+// its title's words and its page id), the one form a whole address is written in (fullAddress), the
+// words as they are; a page id alone or a slug in its place reads as well. A workbench's address is the
+// one form that needs `links` (pageLinks: a Map of slug to link), for only the list can say which
+// document an id is or whether a name is a slug at all; given, `links` also turns away every slug it
+// does not hold. Without it such an address is none here, and workbenchHash hands it to the workbench,
+// which has the list. pageAddress reads no port, as a link outlives a server; but this computer runs
+// other programs too, and other workspaces, whose folder of one name has one page id, so an address
+// on another port (elsewhere) is a document's only if the list holds it, by its folder name or its
+// link of now (addressOn).
+
+const SLUG = "[a-z0-9]+(?:-[a-z0-9]+)*"; // shared/workspace.mjs slugPattern, which needs Node
+const FILE = "(?:doc|report)\\.html";
+const IN_FILE = new RegExp(`^\\.\\./(${SLUG})/${FILE}(?:#(.*))?$`);
+const PAGE = new RegExp(`^/generated/(${SLUG})\\.html$`);
+const OWN_FILE = new RegExp(`^/(${SLUG})/${FILE}$`);
+const LOOPBACK = new Set(["127.0.0.1", "localhost"]);
+const HOSTED = /^(?:https?:)?\/\//i;
+
+/** A hash or a part of an address as words: as it is written where it is no good encoding. */
+export const decoded = (text) => {
+  try {
+    return decodeURIComponent(text);
+  } catch {
+    return text;
+  }
+};
+
+// `text` as an address of this computer's own host, read as the page reads a path: a URL, or null.
+function ownAddress(text) {
+  try {
+    const url = new URL(text, "http://127.0.0.1");
+    return /^https?:$/.test(url.protocol) && LOOPBACK.has(url.hostname) && /^(?:https?:|\/)/i.test(text) ? url : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What a workbench's hash says, decoded, of the documents of `links`: a link or a slug, with a block
+ * or without (neither ever holds "/"). Else null, as with no `links` to read it by.
+ * @param {string} hash
+ * @param {Map<string, string> | null} [links]
+ */
+export function hashAddress(hash, links = null) {
+  const at = hash.indexOf("/");
+  const name = at < 0 ? hash : hash.slice(0, at);
+  const block = at < 0 ? null : hash.slice(at + 1) || null;
+  const slug = links && pageOfLink(links, name);
+  return slug ? { slug, block } : null;
+}
+
+/** The document and block `text` is the address of ({ slug, block }), or null: a web address, another host, a slug `links` does not hold, a workbench's address with no `links`. */
+export function pageAddress(text, links = null) {
+  const address = String(text ?? "").trim();
+  const known = (slug, block) => (!links || links.has(slug) ? { slug, block: block || null } : null);
+  const inFile = IN_FILE.exec(address);
+  if (inFile) return known(inFile[1], decoded(inFile[2] ?? ""));
+  const url = ownAddress(address);
+  if (!url) return null;
+  const path = PAGE.exec(url.pathname) ?? OWN_FILE.exec(url.pathname);
+  if (path) return known(path[1], decoded(url.hash.slice(1)));
+  return url.pathname === "/" && url.hash.length > 1 ? hashAddress(decoded(url.hash.slice(1)), links) : null;
+}
+
+/** The document and block `text` names of those in `links`: an address, as pageAddress reads one, or what stands after the # of a workbench's, the # with it or not, or after the Windows path Git Bash puts in place of a word's first / (/#<link>), as a person may hand a command one. Else null. */
+export const namedPlace = (text, links) => pageAddress(text, links) ?? hashAddress(decoded(text.replace(/^(?:[a-z]:\/(?:.*\/)?)?#/i, "")), links);
+
+/** The hash of an address of a workbench (/#<anything>, on this computer's own host), decoded, or null: what a click hands the workbench to read. */
+export function workbenchHash(text) {
+  const url = ownAddress(String(text ?? "").trim());
+  return url?.pathname === "/" && url.hash.length > 1 ? decoded(url.hash.slice(1)) : null;
+}
+
+/**
+ * The document and block `text` names of those in `links` (a Map, or null with no list) as read on the
+ * server of `origin`, as pageAddress reads it; but a workbench's address on another port says what it
+ * is by its words, the folder name or the link the document has now, for the same id there may be
+ * another workspace's page. With no `origin`, as a file is read, every port is another.
+ * @param {string} text
+ * @param {Map<string, string> | null} links
+ * @param {string} [origin]
+ */
+export function addressOn(text, links, origin = "http://127.0.0.1") {
+  const place = pageAddress(text, links);
+  const name = place && elsewhere(text, origin) ? workbenchHash(text)?.split("/")[0] : undefined;
+  return name === undefined || links.has(name) || links.get(place.slug) === name ? place : null;
+}
+
+/** Whether `text` is an address of a document of this workspace, as far as can be told with no list. */
+export const isPageAddress = (text) => pageAddress(text) !== null || workbenchHash(text) !== null;
+
+/** Whether `text` may be one, once the list is read (a paste reads it): an address of this computer's own host. */
+export const mayBePage = (text) => ownAddress(String(text ?? "").trim()) !== null;
+
+/** Whether `href` is written as a file writes a link to a document or a block: all a page block's address may be. */
+export const isFileLink = (href) => IN_FILE.test(href) || /^#[^\s"<>]+$/.test(href);
+
+/** The link a file writes to a document or block, from document `own`: within it a block is #<block id>. */
+export const fileLink = ({ slug, block = null }, own = null) => (slug === own && block ? `#${block}` : `../${slug}/doc.html${block ? `#${block}` : ""}`);
+
+/** Whether `text` names a host of its own, where a path or a relative link is read on the server that shows it. */
+export const hosted = (text) => HOSTED.test(String(text ?? "").trim());
+
+/** Whether `text` is an address of this computer on another server than `origin`'s, which may be another program's. */
+export function elsewhere(text, origin) {
+  const url = hosted(text) ? ownAddress(text.trim()) : null;
+  return url !== null && url.port !== new URL(origin).port;
+}
+
+/** Where `href`, a link in the file of document `own`, leads, read beside that file as the disk reads it: an address on `origin`, or null for none. */
+export function fromFile(href, own, origin = "http://127.0.0.1") {
+  try {
+    return new URL(String(href ?? "").trim(), `${origin}/${own}/doc.html`).href;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The full address of a document or block, which a browser opens in a workbench from anywhere
+ * (`origin`: its server's): /#<link>/<block id>, or /#<link> for a page, in the words as they are. A
+ * document `links` does not hold goes by its page id, which opens it all the same.
+ * @param {string} origin
+ * @param {{ slug: string, block?: string | null }} place
+ * @param {Map<string, string> | null} [links]
+ */
+export const fullAddress = (origin, { slug, block = null }, links = null) => `${origin}/#${links?.get(slug) ?? pageLink({ slug })}${block ? `/${block}` : ""}`;

package/browser/shared/page-links.mjs

@@ -0,0 +1,86 @@
+// A document's link in the workbench's address (#项目周报-Q3-k3xv9q2a): its title in the words a link can
+// hold, the rest of it dashes, then the document's page id; a title that leaves no words is the id
+// alone. The words are a label and nothing more: a link is read by what stands after its last dash,
+// so that an address written down before a rename opens its document for ever, and two documents of
+// one title need nothing to tell them apart.
+//
+// A page id has the look of a block id (shared/ids.mjs) and is worked out from the folder name, the
+// document's identity, which a title never changes. So nothing is kept anywhere: no file, no list to
+// keep in step, and a page alone in a tab or with no list read yet can always say its own address.
+// The folder name opens its document too, for what was written by it. A document in the trash has its
+// id, and has its address back when it is restored; one restored under another folder name goes by
+// that name's id, as the links of files to it change too.
+//
+// Pure, and the same on the server, in the workbench and on a page, so that a title typed shows in the
+// address at once. Only the documents of the sidebar and of the trash go by a link: 写作偏好 stands
+// outside the tree of pages.
+
+// What is no word of a title, a mark going with what it sits on (an emoji's variation selector).
+const NOT_WORDS = /(?:[^\p{L}\p{M}\p{N}_]\p{M}*)+/gu;
+
+/**
+ * A document's page id: eight letters and digits, a letter first, from a 53-bit hash of its folder
+ * name (cyrb53).
+ * @param {string} slug
+ */
+export function pageId(slug) {
+  let one = 0xdeadbeef;
+  let two = 0x41c6ce57;
+  for (let at = 0; at < slug.length; at++) {
+    one = Math.imul(one ^ slug.charCodeAt(at), 2654435761);
+    two = Math.imul(two ^ slug.charCodeAt(at), 1597334677);
+  }
+  one = Math.imul(one ^ (one >>> 16), 2246822507) ^ Math.imul(two ^ (two >>> 13), 3266489909);
+  two = Math.imul(two ^ (two >>> 16), 2246822507) ^ Math.imul(one ^ (one >>> 13), 3266489909);
+  const hash = (two >>> 0) % 2 ** 21 * 2 ** 32 + (one >>> 0);
+  return String.fromCharCode(97 + hash % 26) + Math.floor(hash / 26).toString(36).padStart(7, "0").slice(-7);
+}
+
+/**
+ * A document's link, what stands after # in its address: its title's words and its page id, the id
+ * alone for a title that leaves no words or one not known here.
+ * @param {{ slug: string, title?: string }} page
+ */
+export function pageLink({ slug, title }) {
+  const words = String(title ?? "").replace(NOT_WORDS, "-").replace(/^[-\p{M}]+|-+$/gu, "");
+  return words ? `${words}-${pageId(slug)}` : pageId(slug);
+}
+
+/**
+ * Each document's link: a Map of slug to link, which is also the list of documents an address is read
+ * against (pageOfLink).
+ * @param {{ slug: string, title?: string }[]} pages
+ * @returns {Map<string, string>}
+ */
+export const pageLinks = (pages) => new Map(pages.map((page) => [page.slug, pageLink(page)]));
+
+/**
+ * The document `value` names of those in `links`: by its folder name, else by the page id after the
+ * last dash of a link, or that id alone, whatever words stand before it. Its slug, or null.
+ * @param {Map<string, string>} links
+ * @param {string} value
+ */
+export function pageOfLink(links, value) {
+  if (links.has(value)) return value;
+  const id = value.slice(value.lastIndexOf("-") + 1);
+  for (const slug of links.keys()) if (pageId(slug) === id) return slug;
+  return null;
+}
+
+/**
+ * Whether `name` (a slug or a link, what stands before any "/" of an address) names a document of the trash ({ slug, title } each).
+ * @param {{ slug: string, title?: string }[]} trash
+ * @param {string} name
+ */
+export const inTrash = (trash, name) => pageOfLink(pageLinks(trash), name.split("/")[0]) !== null;
+
+/**
+ * What an address written for anyone goes by: `links` and the links of the trash (`trash`: { slug,
+ * title } each).
+ * @param {Map<string, string>} links
+ * @param {{ slug: string, title?: string }[]} trash
+ */
+export const namedLinks = (links, trash) => new Map([...pageLinks(trash), ...links]);
+
+/** The pages of a list of reports (`reports` of the outline's answer) that hold a link: all but 写作偏好. */
+export const linkedPages = (reports) => Object.values(reports).filter(({ instructions }) => !instructions);

package/browser/shared/paths.mjs

@@ -0,0 +1,73 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { findWorkspace, layoutOf } from "./workspace.mjs";
+
+// Where everything is on disk, for every system, in two kinds: the workspace's (the user's documents
+// and what Gallery keeps of them: ./workspace.mjs) and the package's (Gallery's own files). Only paths
+// are computed here, at import, and nothing is made: the gallery command sets GALLERY_WORKSPACE (from
+// --workspace, or the workspace it found) before it imports anything that imports this; npm run dev
+// sets it to the repository's reports/ (vite.config.ts), the tests to folders of their own.
+
+// The package: the folder up from this file whose package.json is @heycys/gallery's (src/shared/ here,
+// a dist/ chunk in the release).
+function findPackageRoot() {
+  for (let directory = path.dirname(fileURLToPath(import.meta.url)); ; directory = path.dirname(directory)) {
+    try {
+      if (JSON.parse(readFileSync(path.join(directory, "package.json"), "utf8")).name === "@heycys/gallery") return directory;
+    } catch {}
+    if (path.dirname(directory) === directory) return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+  }
+}
+export const packageRoot = findPackageRoot();
+/** The package's folder (its old name, which the tests and the maintainers' scripts use). */
+export const projectRoot = packageRoot;
+/**
+ * Whether this is the release build (npm run release:build, src/cli/release-build.mjs): release.json in
+ * the package, which says its version and the stamps of its files (src/server/stamps.mjs). Gallery's
+ * own files are then the package's folders (dist/, web/, browser/, kit/, vendor/…), else the source
+ * checkout's (src/, public/, node_modules/).
+ */
+export const releaseFile = path.join(packageRoot, "release.json");
+export const release = existsSync(releaseFile);
+
+// The workspace: the user's documents (<workspace>/<slug>/) and what is made of them.
+export const workspaceRoot = path.resolve(process.env.GALLERY_WORKSPACE || findWorkspace().root);
+const workspace = layoutOf(workspaceRoot);
+/** The documents' folder: the workspace's root (its old name, which 60 modules import). */
+export const reportsDirectory = workspaceRoot;
+export const generatedDirectory = workspace.built; // built previews (nothing serves them: the export builds through them)
+export const exportsDirectory = workspace.exports; // the offline deliverables, the user's
+export const qaDirectory = workspace.qa; // gallery qa's pictures of what it flagged in an export
+export const backupsDirectory = workspace.backups; // documents as they were before a migration (add-block-ids.mjs)
+export const editStateDirectory = workspace.state; // the editor's token, snapshots, recent versions…
+// What a server a command started says while it runs (it runs on after that command).
+export const previewLogFile = workspace.serverLog;
+
+// Gallery's own files, which a command never writes (a global install may be read-only): the shared
+// kit and the starter, what the preview serves, what the checks and the import read. In the release
+// each is a folder of the package (docs/internals.md, "Packaging"); in the source checkout, where it is
+// kept or built (npm run dev's predev writes public/kit and public/vendor: src/cli/build-kit.mjs).
+const inPackage = (built, ...source) => path.join(packageRoot, ...(release ? built : source));
+export const kitSourceDirectory = path.join(packageRoot, "src", "render", "kit"); // the source checkout's only
+export const starterDirectory = inPackage(["starter"], "src", "render", "starter");
+export const vendorDirectory = inPackage(["vendor"], "public", "vendor");
+export const kitPublicDirectory = inPackage(["kit"], "public", "kit");
+/** The editor's browser modules, at their path under src/ (the preview serves them so: src/server/routes.mjs). */
+export const browserDirectory = inPackage(["browser"], "src");
+/** The emoji and icon data (the editor fetches it; the render reads it for a page's icon). */
+export const emojiDataDirectory = path.join(browserDirectory, "shared", "emoji", "data");
+/** The workbench as built (index.html and assets/): the release's; the source checkout's is Vite's (src/workbench/app/). */
+export const workbenchDirectory = release ? path.join(packageRoot, "web") : null;
+/** The SDK's types (the type check's roots, and what a script's JSDoc imports of ../../sdk reach). */
+export const sdkDirectory = path.join(packageRoot, "sdk");
+/** Gallery's default 写作偏好 (shared/writing-preferences.mjs). */
+export const defaultPreferencesFile = inPackage(["assets", "writing-preferences.md"], "src", "shared", "writing-preferences.md");
+/** TypeScript (src/render/typescript.mjs): the release's own minified copy, beside the libs it reads; null: the typescript package. */
+export const typescriptFile = release ? path.join(packageRoot, "vendor", "typescript", "typescript.js") : null;
+/** Where the type check finds d3's types (the type library d3, and the d3-* it names). */
+export const typeRoots = [inPackage(["vendor", "types", "@types"], "node_modules", "@types")];
+/** pdf.js (a PDF's import: src/transfer/import.mjs): the release's subset; null: the pdfjs-dist package. */
+export const pdfjsDirectory = release ? path.join(packageRoot, "vendor", "pdfjs") : null;
+/** The thin skill gallery skill install writes: the release's (the source checkout makes it: src/cli/package-skill.mjs). */
+export const skillDirectory = release ? path.join(packageRoot, "skill") : null;

package/browser/shared/preferences.mjs

@@ -0,0 +1,110 @@
+// The reader's preferences of Gallery's UI (the workbench's 设置): switches (and a width) kept in localStorage,
+// which the workbench and every report page share (one origin), so the page editor follows a change
+// at once (the storage event reaches every other page of the origin). Each is off (or its default) until changed.
+//   editFrame     显示编辑框: the dashed frame around the text being edited (editor/page/frame.mjs)
+//   quietNotices  减少通知: the notices of everyday operations (what was just done, how to go on) are not
+//                 shown, only what the reader must act on or would not know otherwise (editor/page/quiet.mjs)
+//   outlineWidth  the outline's width in full, as the reader dragged it (px; 0: its default), for every report
+//
+// Whether the outline (目录, the top bar's 更多; editor/page/outline/) shows is no preference of the UI
+// but the report's, as what is folded in it is: switched on for one report, the others keep
+// theirs, and every report has it off until it is switched on there. It is kept apart, under its own
+// key (OUTLINE_OPEN_KEY): the slugs of the reports that have it on, the one switched on last at the end,
+// at most OPEN_KEEP of them (switched on for one more, the one switched on longest ago lets it go), so
+// what is kept stays small with no list of the reports to check it against. Off, a report is taken out
+// of it. The page's head reads it before the page shows (editor/page/margin.mjs), and a page follows a
+// switch made in another (the workbench's top bar, another tab) by the storage event, as the switches above.
+// Both keys are named in renamed-storage.mjs, which carries what the old names hold (before 2026-10-26).
+
+import { KEYS, OLD_KEYS } from "./renamed-storage.mjs";
+
+const KEY = KEYS.preferences;
+/** The preferences, each with its default (a switch's false, a width's 0). */
+export const PREFERENCES = { editFrame: false, quietNotices: false, outlineWidth: 0 };
+
+/** The key they are kept under (the page's head reads the outline's width before it shows: editor/page/margin.mjs). */
+export const PREFERENCES_KEY = KEY;
+
+function stored() {
+  try {
+    const value = JSON.parse(globalThis.localStorage?.getItem(KEY) ?? "{}");
+    return value && typeof value === "object" ? value : {};
+  } catch {
+    return {};
+  }
+}
+
+/** The value of preference `name` (one of the other kind than its default's: the default). */
+export function preference(name) {
+  const value = stored()[name];
+  return typeof value === typeof PREFERENCES[name] && (typeof value !== "number" || Number.isFinite(value)) ? value : PREFERENCES[name];
+}
+
+/**
+ * Keep preference `name` as `value`. What is no preference any more is let go as one is kept (the
+ * outline's switch, once one for every report, is now each report's own: outlineOpen).
+ */
+export function setPreference(name, value) {
+  if (!Object.hasOwn(PREFERENCES, name)) return;
+  try {
+    const kept = typeof PREFERENCES[name] === "number" ? (Number.isFinite(Number(value)) ? Number(value) : PREFERENCES[name]) : Boolean(value);
+    const known = Object.fromEntries(Object.entries(stored()).filter(([key]) => Object.hasOwn(PREFERENCES, key)));
+    globalThis.localStorage?.setItem(KEY, JSON.stringify({ ...known, [name]: kept }));
+  } catch {}
+}
+
+/** Call `listener` when another page of the origin changes the preferences (the workbench, for a report page). */
+export function onPreferences(listener) {
+  globalThis.addEventListener?.("storage", (event) => {
+    if (event.key === KEY || event.key === null) listener();
+  });
+}
+
+// ---------- the outline, each report's ----------
+
+const OPEN_KEY = KEYS.outlineOpen;
+const OPEN_KEEP = 100; // reports with the outline on
+
+/** The key the reports with the outline on are kept under (a JSON list of their slugs; the page's head reads it: editor/page/margin.mjs). */
+export const OUTLINE_OPEN_KEY = OPEN_KEY;
+/** The two keys under their names before 2026-10-26, for the page's head, which runs before renamed-storage.mjs has carried them. */
+export const OLD_PREFERENCES_KEY = OLD_KEYS.preferences;
+export const OLD_OUTLINE_OPEN_KEY = OLD_KEYS.outlineOpen;
+
+function openSlugs() {
+  try {
+    const value = JSON.parse(globalThis.localStorage?.getItem(OPEN_KEY) ?? "[]");
+    return Array.isArray(value) ? value.filter((slug) => typeof slug === "string" && slug !== "") : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Whether report `slug` has its outline on (off until it is switched on there). */
+export function outlineOpen(slug) {
+  return typeof slug === "string" && slug !== "" && openSlugs().includes(slug);
+}
+
+/**
+ * Report `slug`'s outline switched on or off: on, it is the one switched on last (at most OPEN_KEEP
+ * reports, the one switched on longest ago let go); off, it is taken out.
+ */
+export function setOutlineOpen(slug, on) {
+  if (typeof slug !== "string" || slug === "") return;
+  try {
+    const slugs = openSlugs().filter((one) => one !== slug);
+    if (on) slugs.push(slug);
+    globalThis.localStorage?.setItem(OPEN_KEY, JSON.stringify(slugs.slice(-OPEN_KEEP)));
+  } catch {}
+}
+
+/**
+ * Call `listener` when another page of the origin switches a report's outline (the workbench's 更多 ›
+ * 目录, the same report in another tab): it reads outlineOpen() for its own report, which may not have
+ * changed (another report switched).
+ */
+export function onOutlineOpen(listener) {
+  globalThis.addEventListener?.("storage", (event) => {
+    if (event.key === OPEN_KEY || event.key === null) listener();
+  });
+}