@heycys/gallery 0.0.0-stage → 0.1.1

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,116 @@
+// 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 has its default (off, but for
+// showChanges) 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)
+//   showChanges   显示变更: what an Agent wrote marked on the page, with the bar to keep or revert it
+//                 (editor/page/changes/); on until switched off, and off, what comes under review is kept as it comes
+//   outlineWidth  the outline's width in full, as the reader dragged it (px; 0: its default), for every report
+//   outlineCollapsed  the outline as its strip where the room would give it the list in full: a click on its
+//                 guide (editor/page/outline/), and again on the guide in the strip's card to have the list back;
+//                 for every report, as its width
+//
+// 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 but 显示变更's, a width's 0). */
+export const PREFERENCES = { editFrame: false, quietNotices: false, showChanges: true, outlineWidth: 0, outlineCollapsed: false };
+
+/** The key they are kept under (the page's head reads the outline's width and whether it is collapsed 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();
+  });
+}

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