@heycys/gallery 0.0.0-stage → 0.1.1

package/browser/shared/number-reading.mjs

@@ -0,0 +1,92 @@
+// How a table's cells are read as numbers: the one reading of the kit (src/render/kit/tables/
+// cells.js: its numeric columns, centered and sorted by number, and the values a sort compares) and
+// the page editor (src/editor/components/table/index.mjs: 一键优化's header column is a column of
+// names, so none of its cells is a number; page/table/index.mjs sortRows sorts by parsedValue).
+// A column is a number column only when every cell holds one, so what counts as a number is decided here and nowhere else.
+
+/** What a cell holds in the way of a value: its sort value when it has one, else its words. */
+export function rawCellValue(cell) {
+  return (cell?.dataset.sortValue ?? cell?.textContent ?? "").trim();
+}
+
+// A cell that holds no value: it does not disqualify a column of numbers (a dash is also what a
+// minus sign alone reads as, below).
+const missingValues = new Set(["", "-", "—", "–", "−", "n/a", "na", "null"]);
+
+export function isMissingValue(raw) {
+  return missingValues.has(raw.toLowerCase());
+}
+
+// A number as tables write it: a qualifier before it (约, ≈, ~, <, ≥ …), a sign, a currency, digits
+// grouped by commas (in thousands or ten-thousands) or spaces, a decimal part (a point with no digit
+// after it too: "1." is 1, as a number being typed reads), an exponent, then a percent, a multiplier
+// or a unit (12.5%, 3.4亿, 120 ms, 50 元/月); a range (3–5, 3~5 天) reads as its first number, an
+// accountant's negative ((12)) as -12; 千, 万 and 亿 scale it (1.2万 is 12000). Full-width
+// characters (１２，３４５％) read as their ASCII, a Unicode minus or dash as a minus.
+const QUALIFIER = String.raw`(?:约|大约|近|超过|不足|≈|~|<=?|>=?|≤|≥|±)?`;
+const AMOUNT = String.raw`[$¥€£₩₹]?\s*((?:\d{1,3}(?:[,\s\u00a0\u2009]\d{3})+|\d{1,4}(?:,\d{4})+|\d+)(?:\.\d*)?(?:e[+-]?\d+)?|\.\d+)`;
+const UNIT = String.raw`((?:[%‰x×]|[A-Za-zµμ\u4e00-\u9fff°℃]+(?:\/[A-Za-zµμ\u4e00-\u9fff°℃·]+)?)?)`;
+/** What a unit's first character scales its number by (1.2万 is 12000): such a unit is its base unit (3.6亿元: 元) in that scale. */
+export const UNIT_SCALES = { 千: 1e3, 万: 1e4, 亿: 1e8 };
+const SCALE = UNIT_SCALES;
+const SINGLE = new RegExp(`^${QUALIFIER}\\s*([+-]?)\\s*${AMOUNT}\\s*${UNIT}$`, "i");
+const RANGE = new RegExp(`^([+-]?)\\s*${AMOUNT}\\s*${UNIT}\\s*(?:-|~|至|到)\\s*[+-]?\\s*${AMOUNT}\\s*${UNIT}$`, "i");
+
+/**
+ * How a cell's words write a number (read as above): { value, written, unit }, `value` the number
+ * they hold (3.6亿 is 360000000), `written` the number before its unit scales it (3.6), `unit` what
+ * follows it as written ("亿", "%", "ms"; "" for none; a range's first), and `range: true` for a range
+ * (its first number: a sort's value, which a chart, drawing one number a cell, does not take). Null
+ * when they hold none.
+ */
+export function numberReading(raw) {
+  let text = raw.normalize("NFKC").trim().replace(/[−–—]/g, "-");
+  const accounting = /^\((.+)\)$/.exec(text);
+  if (accounting) text = accounting[1].trim();
+  const single = SINGLE.exec(text);
+  const match = single ?? RANGE.exec(text);
+  if (!match) return null;
+  const value = Number(`${match[1]}${match[2].replace(/[,\s\u00a0\u2009]/g, "")}`);
+  const written = accounting ? -value : value;
+  const unit = match[3] ?? "";
+  const scaled = written * (SCALE[unit[0]] ?? 1);
+  if (!Number.isFinite(scaled)) return null;
+  return single ? { value: scaled, written, unit } : { value: scaled, written, unit, range: true };
+}
+
+/** The number a cell's words hold (read as above), or null. */
+export function numberValue(raw) {
+  return numberReading(raw)?.value ?? null;
+}
+
+/** The numbers a cell holds: one (12.5%), or several told apart by a slash (3 / 4), or null when it is none. */
+export function numericParts(cell) {
+  const raw = rawCellValue(cell);
+  if (isMissingValue(raw)) return null;
+
+  const scalar = numberValue(raw);
+  if (scalar !== null) return [scalar];
+
+  const tokens = raw.split(/\s*\/\s*/);
+  if (tokens.length < 2) return null;
+  const values = tokens.map(numberValue);
+  return values.every((value) => value !== null) ? values : null;
+}
+
+/** The value a sort reads from a cell: a number ("number"), a date ("date") or its words; null when it is missing (or no number, no date). */
+export function parsedValue(cell, type) {
+  const raw = rawCellValue(cell);
+  if (isMissingValue(raw)) return null;
+
+  if (type === "number") {
+    const values = numericParts(cell);
+    return values?.length === 1 ? values[0] : null;
+  }
+
+  if (type === "date") {
+    const value = Date.parse(raw);
+    return Number.isFinite(value) ? value : null;
+  }
+
+  return raw;
+}

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/outline.mjs

@@ -0,0 +1,194 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeAtomic } from "./files.mjs";
+import { layoutOf, listDocumentSlugs, pageSlug, slugPattern } from "./workspace.mjs";
+
+// The workspace's outline: which document sits under which, in what order (the sidebar's tree,
+// <workspace>/.gallery/outline.json, docs/workbench.md "Workspace commands"):
+//   { version: 1, children: { "": [top-level slugs], "<slug>": [slugs under it] } }
+// Hierarchy and order only: a document's folder never moves with it, and no file of a document
+// names where it is (links between documents are relative links between their files). Read, it
+// lists every document of the workspace once but the 写作偏好 page (listed apart, in .gallery/pages/):
+// slugs that are gone drop out, documents it does not know yet come last at the top.
+// Written by the workspace's server (src/workbench/service.mjs: the workbench's moves, a new, copied,
+// restored or imported document, gallery new --under and gallery move while it runs, in the queue its
+// saves go through), and by a gallery command when no server runs (src/cli/tree.mjs), with the same
+// functions, each change read, made and written under the outline's lock (withOutlineLock: a file
+// that two processes cannot both make), so that two writers never lose each other's change.
+
+/** The outline file's lock (.gallery/outline.lock): who holds it, until when it counts. */
+const LOCK_STALE = 10_000; // a lock older than this was left by a process that ended: taken over
+const LOCK_WAIT = 15_000;
+
+/**
+ * Run `task` holding the outline's lock of workspace `root`: a file made with "wx", which one
+ * process alone can make, removed after; one older than 10 s is a crashed writer's and is taken over.
+ * Waits for it 15 s at most, then takes it all the same (a writer that holds it that long holds
+ * nothing any more).
+ */
+export async function withOutlineLock(root, task) {
+  const { gallery } = layoutOf(root);
+  const lock = path.join(gallery, "outline.lock");
+  const mine = `${process.pid} ${randomBytes(4).toString("hex")}`;
+  await fs.mkdir(gallery, { recursive: true });
+  for (const until = Date.now() + LOCK_WAIT; ;) {
+    try {
+      await fs.writeFile(lock, mine, { flag: "wx" });
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const age = await fs.stat(lock).then(({ mtimeMs }) => Date.now() - mtimeMs, () => 0);
+      if (age > LOCK_STALE || Date.now() > until) await fs.rm(lock, { force: true });
+      else await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+  }
+  try {
+    return await task();
+  } finally {
+    // Removed only while it is still this writer's (one taken over meanwhile is the next writer's).
+    if ((await fs.readFile(lock, "utf8").catch(() => null)) === mine) await fs.rm(lock, { force: true });
+  }
+}
+
+const readJson = (file) => fs.readFile(file, "utf8").then(JSON.parse).catch(() => null);
+
+/** The outline of workspace `root` as it is read: every document but the 写作偏好 page once (above). */
+export async function readOutline(root) {
+  return (await outlineAndFile(root)).outline;
+}
+
+/**
+ * The outline as it is read and what its file holds: { outline, stored: the file's children, or null }.
+ * A change is written when what it makes is not what the file holds (writtenAs), a document the file
+ * does not hold yet too (one made since, listed last at the top only as it is read), so that the file
+ * keeps every place a command or the workbench gave.
+ */
+export async function outlineAndFile(root) {
+  const instructions = await pageSlug(root);
+  const slugs = (await listDocumentSlugs(root)).filter((slug) => slug !== instructions);
+  const stored = await readJson(layoutOf(root).outline);
+  const outline = { version: 1, children: ordered(stored, slugs) };
+  return { outline, stored: stored?.children ?? null };
+}
+
+/**
+ * Whether `children` is what the outline's file holds (`stored`, outlineAndFile's): the same lists
+ * (an empty one as none), in whatever order the file has its keys. Also whether an outline a
+ * workbench changed (POST outline's `base`) is the one read now.
+ */
+export function writtenAs(children, stored) {
+  if (!stored || typeof stored !== "object") return false;
+  const lists = (value) => Object.keys(value).filter((key) => Array.isArray(value[key]) && value[key].length > 0);
+  const [ours, theirs] = [lists(children), lists(stored)];
+  return ours.length === theirs.length && ours.every((key) => JSON.stringify(children[key]) === JSON.stringify(stored[key]));
+}
+
+// The outline's children of the documents `slugs`, in the order `stored` (the file's value) gives.
+function ordered(stored, slugs) {
+  const children = { "": [] };
+  const seen = new Set();
+  const place = (parent) => {
+    for (const slug of stored?.children?.[parent] ?? []) {
+      if (!slugs.includes(slug) || seen.has(slug)) continue;
+      seen.add(slug);
+      (children[parent] ??= []).push(slug);
+      place(slug);
+    }
+  };
+  place("");
+  for (const slug of slugs) if (!seen.has(slug)) children[""].push(slug);
+  return children;
+}
+
+/** Whether `value` is an outline to store: each document at most once, never under itself. */
+export function validOutline(value) {
+  const children = value?.children;
+  if (!children || typeof children !== "object" || Array.isArray(children)) return false;
+  const listed = new Set();
+  for (const [parent, list] of Object.entries(children)) {
+    if (parent !== "" && !slugPattern.test(parent)) return false;
+    if (!Array.isArray(list)) return false;
+    for (const slug of list) {
+      if (typeof slug !== "string" || !slugPattern.test(slug) || listed.has(slug) || slug === parent) return false;
+      listed.add(slug);
+    }
+  }
+  return true;
+}
+
+/** Write outline `value` ({ children }) of workspace `root` (.gallery/ made when there is none yet). */
+export async function writeOutline(root, value) {
+  const file = layoutOf(root).outline;
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  return writeAtomic(file, `${JSON.stringify({ version: 1, children: value.children }, null, 2)}\n`);
+}
+
+/** The document `slug` sits under in `children` ("" at the top), or null when the outline holds it not. */
+export function parentIn(children, slug) {
+  for (const [parent, list] of Object.entries(children)) if (list.includes(slug)) return parent;
+  return null;
+}
+
+/** The documents above `slug` in `children`, from the top down (itself not among them). */
+export function ancestorsIn(children, slug) {
+  const above = [];
+  for (let parent = parentIn(children, slug); parent; parent = parentIn(children, parent)) above.unshift(parent);
+  return above;
+}
+
+/** Every document under `slug` in `children` ("": all), depth first, in the sidebar's order. */
+export function descendantsIn(children, slug) {
+  const found = [];
+  const walk = (parent) => (children[parent] ?? []).forEach((child) => { found.push(child); walk(child); });
+  walk(slug);
+  return found;
+}
+
+/**
+ * Document `slug` moved in `children` (an outline as read: changed in place) with the documents under
+ * it, to where `where` says: `parent` ("" the top; undefined: where it is now, or `after`'s parent),
+ * right after `after` (one of that parent's), first (`first`), else last. Resolves to { ok: true,
+ * moved: whether its place changed, parent, index, from: { parent, index } } or { ok: false, reason }:
+ * "missing" (no such document in the outline), "parent" (no such parent), "after" (no such document
+ * to go after), "level" (`after` is not under `parent`), "itself" (after itself), "inside" (under
+ * itself or one of the documents under it).
+ */
+export function moveIn(children, slug, { parent = undefined, after = null, first = false } = {}) {
+  const from = parentIn(children, slug);
+  if (from === null) return { ok: false, reason: "missing" };
+  let to = parent;
+  if (after !== null) {
+    if (after === slug) return { ok: false, reason: "itself" };
+    const its = parentIn(children, after);
+    if (its === null) return { ok: false, reason: "after" };
+    if (to !== undefined && to !== its) return { ok: false, reason: "level" };
+    to = its;
+  }
+  to ??= from;
+  if (to !== "" && parentIn(children, to) === null) return { ok: false, reason: "parent" };
+  if (to === slug || ancestorsIn(children, to).includes(slug)) return { ok: false, reason: "inside" };
+  const index = children[from].indexOf(slug);
+  children[from].splice(index, 1);
+  const list = (children[to] ??= []);
+  const at = after !== null ? list.indexOf(after) + 1 : first ? 0 : list.length;
+  list.splice(at, 0, slug);
+  for (const key of Object.keys(children)) if (key !== "" && children[key].length === 0) delete children[key];
+  return { ok: true, moved: to !== from || at !== index, parent: to, index: at, from: { parent: from, index } };
+}
+
+/**
+ * Move document `slug` of workspace `root` where `where` says (moveIn), under the outline's lock: the
+ * outline read, changed and written when that is not what its file holds (writtenAs: a move, or a
+ * document the file does not hold yet placed where it is read). Resolves to moveIn's answer, with
+ * `written`: whether the file was written.
+ */
+export function moveDocument(root, slug, where) {
+  return withOutlineLock(root, async () => {
+    const { outline, stored } = await outlineAndFile(root);
+    const result = moveIn(outline.children, slug, where);
+    const written = result.ok && !writtenAs(outline.children, stored);
+    if (written) await writeOutline(root, outline);
+    return { ...result, ...(result.ok ? { written } : {}) };
+  });
+}

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}` : ""}`;