@heycys/gallery 0.0.0-stage → 0.1.0

package/browser/shared/workspace.mjs

@@ -0,0 +1,535 @@
+import { execFile, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+// A workspace: the folder of the user's documents (docs/internals.md, "Where things live"). Found in
+// this order: --workspace <dir> (the gallery command sets GALLERY_WORKSPACE from it before it loads
+// anything else), the GALLERY_WORKSPACE environment variable, the nearest folder up from the current
+// one holding a gallery.json that says it is ours ({ "gallery": "workspace", "version": 1 }: another
+// program's gallery.json is not), else Gallery in the user's Documents folder (~/Documents/Gallery:
+// documentsFolder() says which folder that is on each system). Its root shows the user's documents,
+// gallery.json, preferences.md (写作偏好), exports/ and components/ only:
+//
+//   <workspace>/gallery.json, preferences.md, exports/<slug>.html (the offline deliverables)
+//   <workspace>/components/<scope>/<name>/  a component package (./component-catalog.mjs), no document
+//   <workspace>/<slug>/doc.html, doc.json (report.html, report.json in a document made before
+//     Gallery 0.1: read and written under those names, never renamed), assets/, materials/, annotations.json
+//   <workspace>/.gallery/  everything else Gallery keeps: the sidebar's outline, the trash, the emoji
+//     library, the 写作偏好 page (pages/<slug>/), the edit state (state/), qa's pictures, backups, built
+//     previews, the server's announcement, port and log, and what was adopted of an old layout.
+//
+// A document is a folder at the root holding doc.html or report.html, its name a slug that is not
+// reserved (exports, generated, which the preview's addresses keep, the names Windows keeps for
+// devices: a workspace moves between systems) and not a dot name. components/ holds no document, but
+// one of that name made before the packages came stays one, and no new one takes it (COMPONENTS_FOLDER).
+// Nothing here writes outside the workspace, and nothing writes an old folder it copies from.
+// Node's built-ins only: every system reads its layout from here.
+
+export const WORKSPACE_FILE = "gallery.json";
+/**
+ * What tells a workspace's gallery.json from another program's file of that name, which is all a
+ * reader of it looks at: what else it holds is whose it is (`components`, ./component-catalog.mjs).
+ */
+export const WORKSPACE_MARK = { gallery: "workspace", version: 1 };
+/** A document's slug: lowercase kebab-case. */
+export const slugPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** The names Windows keeps for devices, which no folder of a workspace takes: a workspace moves between systems. */
+export const DEVICE_NAMES = new Set(["con", "prn", "aux", "nul", ...[1, 2, 3, 4, 5, 6, 7, 8, 9].flatMap((n) => [`com${n}`, `lpt${n}`])]);
+/**
+ * Names at the root that are never a document's: exports/; generated, for ../generated/doc.html would
+ * be the page of the document called doc (the preview's /generated/<slug>.html, src/server/routes.mjs);
+ * and the names Windows keeps for devices.
+ */
+export const RESERVED = new Set(["exports", "generated", ...DEVICE_NAMES]);
+/**
+ * The folder of a workspace's component packages. Unlike RESERVED it hides nothing: a document called
+ * so, made before the packages came, keeps its folder and stays a document beside them. It is only a
+ * name no new document takes (slugTaken, keptName), the next free one coming instead.
+ */
+export const COMPONENTS_FOLDER = "components";
+/** A component package's manifest, which is what makes a folder of components/ a package. */
+export const PACKAGE_MANIFEST = "component.json";
+/** The folders a document keeps beside its files: what is its own of a folder it shares with the packages. */
+export const DOCUMENT_FOLDERS = ["assets", "materials"];
+/** Whether a new document may not be called `name`, whatever the workspace holds. */
+export const keptName = (name) => RESERVED.has(name) || name === COMPONENTS_FOLDER;
+/** Whether `name` may be a document's slug. */
+export const isSlugName = (name) => typeof name === "string" && slugPattern.test(name) && !RESERVED.has(name);
+/** The slug of the 写作偏好 page made new (one copied from an old layout keeps its own). */
+export const PAGE_SLUG = "writing-preferences";
+
+/**
+ * Where a checkout of Gallery, or an old full skill, kept its edit state before the workspace (before
+ * Gallery 0.1, under the editor's old name): <folder>/node_modules/.cache/report-edit. Read only by the
+ * migrations (copyOldDocuments, adoptOldLayout, gallery skill install, the dev server).
+ */
+export const oldStateOf = (folder) => path.join(folder, "node_modules", ".cache", "report-edit");
+
+// The file names of a document: the new ones, and those of a document made before Gallery 0.1.
+const NEW = { html: "doc.html", json: "doc.json" };
+const OLD = { html: "report.html", json: "report.json" };
+/** Whether `name` is the source file of a document (doc.html, or report.html in an old one). */
+export const isDocumentSource = (name) => name === NEW.html || name === OLD.html;
+/** Whether `name` is a file of a document's own (its source, its metadata or its 批注). */
+export const isDocumentFile = (name) => [NEW.html, NEW.json, OLD.html, OLD.json, "annotations.json"].includes(name);
+
+/**
+ * What the text of a gallery.json is, a byte-order mark passed over, which an editor on Windows may
+ * write: { value, ours, reads }, `reads` whether it is JSON at all, `ours` whether it says it is
+ * Gallery's. One that does not read says neither: it may be anyone's, a workspace's with a slip in it.
+ */
+export function markerOf(text) {
+  try {
+    const value = JSON.parse(text.replace(/^\uFEFF/, ""));
+    return { value, ours: value?.gallery === WORKSPACE_MARK.gallery, reads: true };
+  } catch {
+    return { value: null, ours: false, reads: false };
+  }
+}
+
+const markerAt = (file) => {
+  try {
+    return markerOf(readFileSync(file, "utf8"));
+  } catch {
+    return { value: null, ours: false, reads: false };
+  }
+};
+
+/**
+ * Where the workspace is: { root, how } (how: "flag", "env", "found" or "default"). Reads gallery.json
+ * files on the way up, writes nothing (ensureWorkspace makes it).
+ */
+export function findWorkspace({ flag = null, env = process.env, cwd = process.cwd(), home = os.homedir() } = {}) {
+  if (typeof flag === "string" && flag) return { root: path.resolve(cwd, flag), how: "flag" };
+  if (env.GALLERY_WORKSPACE) return { root: path.resolve(cwd, env.GALLERY_WORKSPACE), how: "env" };
+  for (let directory = path.resolve(cwd); ; directory = path.dirname(directory)) {
+    if (markerAt(path.join(directory, WORKSPACE_FILE)).ours) return { root: directory, how: "found" };
+    if (path.dirname(directory) === directory) break;
+  }
+  return { root: path.join(documentsFolder({ home, env }), "Gallery"), how: "default" };
+}
+
+// Where Windows keeps the Documents folder Explorer shows as 文档: the Personal shell folder, as the
+// user's own registry holds it (%USERPROFILE%\Documents as Windows sets it up; OneDrive's Documents
+// when OneDrive backs the folder up, another drive's when the user moved it there).
+const SHELL_FOLDERS = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\User Shell Folders";
+
+/**
+ * The Personal shell folder's value as reg.exe prints it (%USERPROFILE%\Documents, or a path), else
+ * null. reg.exe writes in the console's code page (GBK on a Chinese Windows): a value with any other
+ * byte than ASCII is read again with the code page set to UTF-8, so that a folder named in Chinese
+ * (OneDrive - 公司) comes out whole; an ASCII one costs one reg.exe (about 30 ms).
+ */
+function registryDocuments() {
+  const system = process.env.SystemRoot ?? process.env.windir ?? "C:\\Windows";
+  const valueOf = (output) => /^\s*Personal\s+REG_(?:EXPAND_)?SZ\s+(.+?)\s*$/m.exec(output)?.[1] ?? null;
+  const query = (bytes) => bytes.status === 0 && Buffer.isBuffer(bytes.stdout) ? bytes.stdout : null;
+  const ascii = query(spawnSync(path.join(system, "System32", "reg.exe"), ["query", SHELL_FOLDERS, "/v", "Personal"], { windowsHide: true, timeout: 5000 }));
+  if (!ascii) return null;
+  if (ascii.every((byte) => byte < 0x80)) return valueOf(ascii.toString("utf8"));
+  const command = `"chcp 65001 >nul & "${path.join(system, "System32", "reg.exe")}" query "${SHELL_FOLDERS}" /v Personal"`;
+  const utf8 = query(spawnSync(process.env.ComSpec ?? path.join(system, "System32", "cmd.exe"), ["/d", "/s", "/c", command], { windowsHide: true, windowsVerbatimArguments: true, timeout: 5000 }));
+  return utf8 ? valueOf(utf8.toString("utf8")) : null;
+}
+
+const sameFolder = (a, b, platform) => {
+  const [one, two] = [path.resolve(a), path.resolve(b)];
+  return platform === "win32" ? one.toLowerCase() === two.toLowerCase() : one === two;
+};
+
+/**
+ * The user's Documents folder, the default workspace's parent: on Windows the one Explorer shows as
+ * 文档 (SHELL_FOLDERS' Personal, its %VARIABLES% expanded), read for the user's own home alone (a test
+ * or a sandbox naming another HOME/USERPROFILE gets <that home>/Documents, never the user's folder);
+ * on Linux the XDG documents folder (~/.config/user-dirs.dirs' XDG_DOCUMENTS_DIR: ~/文档 on a Chinese
+ * desktop); a folder either names that is not there, or not absolute, is passed over; else, and on
+ * macOS, <home>/Documents. `realHome`, `readRegistry`, `readText` and `exists` are the tests'.
+ */
+export function documentsFolder({
+  home = os.homedir(), env = process.env, platform = process.platform,
+  realHome = (() => { try { return os.userInfo().homedir; } catch { return null; } })(),
+  readRegistry = registryDocuments, readText = (file) => readFileSync(file, "utf8"), exists = existsSync,
+} = {}) {
+  const fallback = path.join(home, "Documents");
+  const usable = (folder) => folder && path.isAbsolute(folder) && exists(folder) ? path.normalize(folder) : null;
+  if (platform === "win32") {
+    if (!realHome || !sameFolder(home, realHome, platform)) return fallback;
+    let value = null;
+    try {
+      value = readRegistry();
+    } catch {}
+    if (!value) return fallback;
+    const variables = Object.fromEntries(Object.entries(env).map(([name, setting]) => [name.toUpperCase(), setting]));
+    variables.USERPROFILE ??= home;
+    let unknown = false;
+    const expanded = value.replace(/%([^%]+)%/g, (whole, name) => variables[name.toUpperCase()] ?? ((unknown = true), whole));
+    return (!unknown && usable(expanded)) || fallback;
+  }
+  if (platform === "linux") {
+    let text = "";
+    try {
+      text = readText(path.join(env.XDG_CONFIG_HOME || path.join(home, ".config"), "user-dirs.dirs"));
+    } catch {}
+    const value = /^\s*XDG_DOCUMENTS_DIR\s*=\s*"([^"]*)"/m.exec(text)?.[1];
+    if (!value) return fallback;
+    const folder = value.replace(/^\$HOME(?=\/|$)/, home);
+    // XDG says $HOME itself when the user turned the folder off: the home is no documents folder.
+    return sameFolder(folder, home, platform) ? fallback : usable(folder) ?? fallback;
+  }
+  return fallback;
+}
+
+/** Every place of a workspace, by what it holds. Only paths: nothing is read or made. */
+export function layoutOf(root) {
+  const resolved = path.resolve(root);
+  const gallery = path.join(resolved, ".gallery");
+  const state = path.join(gallery, "state");
+  return {
+    root: resolved,
+    marker: path.join(resolved, WORKSPACE_FILE),
+    preferences: path.join(resolved, "preferences.md"),
+    exports: path.join(resolved, "exports"),
+    components: path.join(resolved, COMPONENTS_FOLDER),
+    gallery,
+    outline: path.join(gallery, "outline.json"),
+    trash: path.join(gallery, "trash"),
+    emojiLibrary: path.join(gallery, "emoji-library"),
+    pages: path.join(gallery, "pages"),
+    state,
+    history: path.join(state, "history"),
+    qa: path.join(gallery, "qa"),
+    backups: path.join(gallery, "backups"),
+    built: path.join(gallery, "built"),
+    logs: path.join(gallery, "logs"),
+    serverLog: path.join(gallery, "logs", "server.log"),
+    serverFile: path.join(gallery, "server.json"),
+    lastPortFile: path.join(gallery, "last-port"),
+    migrated: path.join(gallery, "migrated.json"),
+  };
+}
+
+/**
+ * Make the workspace when it is not there: the folder, its gallery.json (never over one that is
+ * there) and .gallery/ (hidden on Windows; dot folders are already on macOS and Linux), its state
+ * folder only its owner's on POSIX (the token there authorizes writes). Resolves to { made: whether
+ * gallery.json was written now, ours: whether the gallery.json there is ours, reads: whether it reads
+ * at all (markerOf) }.
+ */
+export async function ensureWorkspace(root) {
+  const layout = layoutOf(root);
+  await fs.mkdir(layout.root, { recursive: true });
+  let made = true;
+  try {
+    await fs.writeFile(layout.marker, `${JSON.stringify(WORKSPACE_MARK, null, 2)}\n`, { flag: "wx" });
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    made = false;
+  }
+  const hidden = !existsSync(layout.gallery);
+  await fs.mkdir(layout.state, { recursive: true, mode: 0o700 });
+  if (hidden && process.platform === "win32") execFile("attrib", ["+h", layout.gallery], { windowsHide: true }, () => {}); // once; a failure leaves it shown
+  const { ours, reads } = markerAt(layout.marker);
+  return { made, ours, reads };
+}
+
+/**
+ * A document folder's two files: { html, json, old: whether they are the old names, both: whether
+ * the folder holds both doc.html and report.html }. doc.html there: the new names; else report.html
+ * there: the old ones (read and written so, never renamed); neither: the new ones (a document to be made).
+ */
+export function documentFiles(directory) {
+  const hasNew = existsSync(path.join(directory, NEW.html));
+  const old = !hasNew && existsSync(path.join(directory, OLD.html));
+  const names = old ? OLD : NEW;
+  return {
+    html: path.join(directory, names.html),
+    json: path.join(directory, names.json),
+    old,
+    both: hasNew && existsSync(path.join(directory, OLD.html)),
+  };
+}
+
+/** Where document `slug` is: the 写作偏好 page's folder under .gallery/pages/ when it is one, else <root>/<slug>. */
+export function documentDirectory(slug, root) {
+  const page = path.join(layoutOf(root).pages, slug);
+  return existsSync(page) ? page : path.join(path.resolve(root), slug);
+}
+
+/** Whether `slug` can name no new document: a name kept, or held by a folder at the root or a page. */
+export function slugTaken(slug, root) {
+  return keptName(slug) || existsSync(path.join(path.resolve(root), slug)) || existsSync(path.join(layoutOf(root).pages, slug));
+}
+
+// The folders right in `directory`, by name, sorted: no dot name, and no link, which leads out of it.
+const foldersIn = (directory) => {
+  try {
+    return readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => entry.name).sort();
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * The component packages of a workspace, sorted: [{ id: "<scope>/<name>", folder }], each a folder
+ * two down in components/ holding component.json, whatever it says. Any other folder there is no
+ * package and is passed over: one being written, or what a document called components keeps.
+ */
+export function packageFolders(root) {
+  const { components } = layoutOf(root);
+  return foldersIn(components).flatMap((scope) => foldersIn(path.join(components, scope))
+    .map((name) => ({ id: `${scope}/${name}`, folder: path.join(components, scope, name) }))
+    .filter(({ folder }) => existsSync(path.join(folder, PACKAGE_MANIFEST))));
+}
+
+/**
+ * The manifests one level too shallow: [{ name, file }], each a component.json right in a folder of
+ * components/, which no catalog reads: a package is <scope>/<name>, and `name` is what the folder would
+ * be called under a scope. What tells a package's writer why theirs is not there.
+ */
+export function shallowPackages(root) {
+  const { components } = layoutOf(root);
+  return foldersIn(components).map((name) => ({ name, file: path.join(components, name, PACKAGE_MANIFEST) })).filter(({ file }) => existsSync(file));
+}
+
+const readJson = (file) => fs.readFile(file, "utf8").then(JSON.parse).catch(() => null); // not there, or half written: null
+const isFolder = (target) => fs.stat(target).then((stat) => stat.isDirectory(), () => false);
+const exists = (target) => fs.access(target).then(() => true, () => false);
+
+// The folders of `directory` that are documents (D2): a name that is no dot name and not reserved,
+// holding doc.html or report.html; with their metadata's `instructions` mark.
+async function documentsIn(directory) {
+  const entries = await fs.readdir(directory, { withFileTypes: true }).catch((error) => {
+    if (error.code === "ENOENT" || error.code === "ENOTDIR") return [];
+    throw error;
+  });
+  const found = await Promise.all(entries
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && !RESERVED.has(entry.name))
+    .map(async ({ name }) => {
+      const folder = path.join(directory, name);
+      const files = documentFiles(folder);
+      if (!(await exists(files.html))) return null;
+      return { slug: name, folder, instructions: (await readJson(files.json))?.instructions === true };
+    }));
+  return found.filter(Boolean).sort((a, b) => (a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0));
+}
+
+/**
+ * The documents of a workspace, by slug, sorted: the folders at its root holding doc.html or
+ * report.html, but exports/, dot names and an old layout's 写作偏好 page (marked "instructions": true:
+ * the page lives in .gallery/pages/ now). A folder holding neither (a user's own materials/) is left alone.
+ */
+export async function listDocumentSlugs(root) {
+  return (await documentsIn(path.resolve(root))).filter((entry) => !entry.instructions).map((entry) => entry.slug);
+}
+
+/** The 写作偏好 page's slug (the first document under .gallery/pages/), or null when there is none yet. */
+export async function pageSlug(root) {
+  return (await documentsIn(layoutOf(root).pages))[0]?.slug ?? null;
+}
+
+/** The id of an entry of the trash, a folder of .gallery/trash/. */
+export const trashIdPattern = /^[a-z0-9]+-[a-z0-9]+$/;
+
+/** What the trash holds, the latest first: each folder's entry.json ({ id, slug, title, at, parent, index }). */
+export async function listTrash(root) {
+  const { trash } = layoutOf(root);
+  const names = await fs.readdir(trash).catch(() => []);
+  const entries = await Promise.all(names.filter((name) => trashIdPattern.test(name)).map((id) => readJson(path.join(trash, id, "entry.json"))));
+  return entries.filter(Boolean).sort((a, b) => b.at - a.at);
+}
+
+// ---------- copying an old layout ----------
+
+const copyTree = (from, to) => fs.cp(from, to, { recursive: true, errorOnExist: true, force: false, preserveTimestamps: true });
+
+// The files of `from` copied into `to` that `to` does not hold (by name, one level): the names copied.
+async function copyMissing(from, to, { filter = () => true } = {}) {
+  const names = (await fs.readdir(from).catch(() => [])).filter(filter);
+  const copied = [];
+  for (const name of names) {
+    const target = path.join(to, name);
+    if (await exists(target)) continue;
+    await fs.mkdir(to, { recursive: true });
+    await copyTree(path.join(from, name), target);
+    copied.push(name);
+  }
+  return copied;
+}
+
+// The emoji library of `from` (library.json and its images) brought into `to`'s: the images it lacks
+// by name, library.json's entries it lacks by id. The number of entries added.
+async function mergeEmojiLibrary(from, to) {
+  if (!(await isFolder(from))) return 0;
+  await copyMissing(from, to, { filter: (name) => name !== "library.json" && !name.startsWith(".") });
+  const old = await readJson(path.join(from, "library.json"));
+  if (!Array.isArray(old)) return 0;
+  const stored = await readJson(path.join(to, "library.json"));
+  const current = Array.isArray(stored) ? stored : [];
+  const known = new Set(current.map((entry) => entry?.id));
+  const added = old.filter((entry) => entry && typeof entry.id === "string" && !known.has(entry.id));
+  if (added.length || !Array.isArray(stored)) {
+    await fs.mkdir(to, { recursive: true });
+    await fs.writeFile(path.join(to, "library.json"), `${JSON.stringify([...current, ...added], null, 2)}\n`);
+  }
+  return added.length;
+}
+
+// An old outline's nesting of `slugs` only: each under its nearest ancestor among them, else at the top.
+function outlineOf(stored, slugs) {
+  const children = { "": [] };
+  const keep = new Set(slugs);
+  const seen = new Set();
+  const walk = (parent, under) => {
+    for (const slug of stored?.children?.[parent] ?? []) {
+      if (typeof slug !== "string" || seen.has(slug)) continue;
+      seen.add(slug);
+      if (keep.has(slug)) (children[under] ??= []).push(slug);
+      walk(slug, keep.has(slug) ? slug : under);
+    }
+  };
+  walk("", "");
+  for (const slug of slugs) if (!seen.has(slug)) children[""].push(slug);
+  return children;
+}
+
+/**
+ * Copy an old layout's documents into workspace `to` (gallery init --from, gallery skill install over
+ * an old skill): `from` a folder of document folders (an old Gallery's reports/), `state` its edit
+ * state (oldStateOf the folder beside it, when there). Copied: every document whose name is a slug
+ * free in `to` (the others left, listed: `skipped`, a slug taken or a name that is no slug, and `kept`,
+ * a name no new document takes, which is free of no workspace); preferences.md when `to` has none; the sidebar's order
+ * (.workspace.json), as `to`'s when it has none, else the copied documents added at its top in their
+ * old nesting; the 写作偏好 page (a folder marked "instructions": true) into .gallery/pages/ when `to`
+ * has none; the custom emoji library (images by name, entries by id); the recent versions of the
+ * documents copied; the component packages `from` holds, each one `to` does not. Never the trash,
+ * exports, qa pictures or backups. `from` is only read. Resolves to { copied, skipped, kept, preferences:
+ * "copied"|"kept"|null, outline: "copied"|"appended"|null, page: "copied"|"kept"|null, emoji: entries
+ * added, history: documents whose versions were copied, packages: the ids of those copied }.
+ */
+export async function copyOldDocuments({ from, to, state = undefined }) {
+  const source = path.resolve(from);
+  const layout = layoutOf(to);
+  await ensureWorkspace(layout.root);
+  const oldState = state === undefined ? oldStateOf(path.dirname(source)) : state;
+  const found = await documentsIn(source);
+  const copied = [];
+  const skipped = [];
+  const kept = [];
+  let page = null;
+  for (const { slug, folder, instructions } of found) {
+    if (instructions) {
+      if (await pageSlug(layout.root)) page = "kept";
+      else {
+        await fs.mkdir(layout.pages, { recursive: true });
+        await copyTree(folder, path.join(layout.pages, slug));
+        page = "copied";
+      }
+      continue;
+    }
+    if (!isSlugName(slug) || slugTaken(slug, layout.root)) {
+      (keptName(slug) ? kept : skipped).push(slug);
+      continue;
+    }
+    await copyTree(folder, path.join(layout.root, slug));
+    copied.push(slug);
+  }
+
+  let preferences = null;
+  if (await exists(path.join(source, "preferences.md"))) {
+    preferences = (await exists(layout.preferences)) ? "kept" : "copied";
+    if (preferences === "copied") await fs.copyFile(path.join(source, "preferences.md"), layout.preferences);
+  }
+
+  let outline = null;
+  const stored = await readJson(path.join(source, ".workspace.json"));
+  if (stored && copied.length) {
+    const nested = outlineOf(stored, copied);
+    const current = await readJson(layout.outline);
+    if (!current?.children) {
+      await fs.writeFile(layout.outline, `${JSON.stringify({ version: 1, children: nested }, null, 2)}\n`);
+      outline = "copied";
+    } else {
+      const children = { ...current.children };
+      for (const [parent, list] of Object.entries(nested)) children[parent] = [...(children[parent] ?? []), ...list];
+      await fs.writeFile(layout.outline, `${JSON.stringify({ version: 1, children }, null, 2)}\n`);
+      outline = "appended";
+    }
+  }
+
+  const emoji = await mergeEmojiLibrary(path.join(source, ".emoji-library"), layout.emojiLibrary);
+
+  let history = 0;
+  if (oldState) {
+    for (const slug of copied) {
+      const versions = path.join(oldState, "history", slug);
+      const target = path.join(layout.history, slug);
+      if (!(await isFolder(versions)) || (await exists(target))) continue;
+      await fs.mkdir(layout.history, { recursive: true });
+      await copyTree(versions, target);
+      history++;
+    }
+  }
+
+  const packages = [];
+  for (const { id, folder } of packageFolders(source)) {
+    const target = path.join(layout.components, ...id.split("/"));
+    if (await exists(target)) continue;
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await copyTree(folder, target);
+    packages.push(id);
+  }
+  return { copied, skipped, kept, preferences, outline, page, emoji, history, packages };
+}
+
+// A directory as a key of the old edit state (the old preview-server's directoryKey: one folder for
+// each directory of reports there, for checkouts that shared it).
+const canonical = (directory) => (process.platform === "win32" ? path.resolve(directory).toLowerCase() : path.resolve(directory));
+const oldKey = (directory) => createHash("sha256").update(canonical(directory)).digest("hex").slice(0, 16);
+
+/**
+ * Bring a workspace's own old layout into .gallery/, once (the dev checkout's reports/, a folder of
+ * documents made before Gallery 0.1): reports' .workspace.json → .gallery/outline.json, .trash/ →
+ * .gallery/trash/, .emoji-library/ → .gallery/emoji-library/, a root page marked "instructions": true
+ * → .gallery/pages/ (when there is none); and with `devState` (the old edit state, oldStateOf the
+ * checkout whose reports/ this is) its token, source snapshots, and the recent
+ * versions, commit answers, rewrites and dropped 批注 of this workspace's documents → .gallery/state/.
+ * Everything is copied, never over what is there; the old copies are left. .gallery/migrated.json
+ * says it was done: a second call does nothing. Resolves to { adopted: whether it ran, copied: what was }.
+ */
+export async function adoptOldLayout(root, { devState = null } = {}) {
+  const layout = layoutOf(root);
+  if (await exists(layout.migrated)) return { adopted: false, copied: [] };
+  await ensureWorkspace(layout.root);
+  const copied = [];
+  const once = async (what, from, to) => {
+    if (!(await exists(from)) || (await exists(to))) return;
+    await fs.mkdir(path.dirname(to), { recursive: true });
+    await copyTree(from, to);
+    copied.push(what);
+  };
+  await once("outline", path.join(layout.root, ".workspace.json"), layout.outline);
+  if ((await copyMissing(path.join(layout.root, ".trash"), layout.trash)).length) copied.push("trash");
+  if ((await mergeEmojiLibrary(path.join(layout.root, ".emoji-library"), layout.emojiLibrary)) > 0) copied.push("emoji-library");
+  const oldPage = (await documentsIn(layout.root)).find((entry) => entry.instructions);
+  if (oldPage && !(await pageSlug(layout.root))) await once("page", oldPage.folder, path.join(layout.pages, oldPage.slug));
+
+  if (devState && (await isFolder(devState))) {
+    const slugs = [...(await listDocumentSlugs(layout.root)), ...(oldPage ? [oldPage.slug] : [])];
+    await once("token", path.join(devState, "token"), path.join(layout.state, "token"));
+    if ((await copyMissing(path.join(devState, "snapshots"), path.join(layout.state, "snapshots"))).length) copied.push("snapshots");
+    const key = oldKey(layout.root);
+    for (const slug of slugs) {
+      for (const [kind, from] of [
+        ["history", path.join(devState, "history", slug)],
+        ["receipts", path.join(devState, "receipts", slug)],
+        ["rewrites", path.join(devState, "rewrites", key, slug)],
+        ["dropped-annotations", path.join(devState, "dropped-annotations", key, slug)],
+      ]) await once(`${kind}/${slug}`, from, path.join(layout.state, kind, slug));
+    }
+  }
+  await fs.writeFile(layout.migrated, `${JSON.stringify({ version: 1, at: new Date().toISOString(), copied }, null, 2)}\n`);
+  return { adopted: true, copied };
+}

package/browser/shared/writing-preferences.mjs

@@ -0,0 +1,68 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { defaultPreferencesFile, reportsDirectory as defaultReportsDirectory } from "./paths.mjs";
+
+// 写作偏好: the user's rules for writing a report, which an Agent reads before it writes (SKILL.md),
+// at <workspace>/preferences.md (shared/workspace.mjs). Gallery ships its default (writing-preferences.md,
+// beside this module; the release's assets/writing-preferences.md: paths.mjs defaultPreferencesFile): what
+// to write, in what order, the opening summary, titles, fidelity to the materials, evidence). The first
+// time the preferences are read and there is no preferences.md in the workspace (by gallery new, gallery
+// import, gallery list, or the workbench's 写作偏好 in 设置), it is made from that default; from then on it is the user's, edited in the workbench (its page, src/shared/reports.mjs
+// isInstructions, written as this file when the user saves it: src/transfer/service.mjs), and
+// never written over by the default again: a file that exists stays as it is, an empty one too.
+
+/** Gallery's default writing preferences (Markdown). */
+export { defaultPreferencesFile };
+
+/** Where the user's writing preferences are, for the documents of workspace `reportsDirectory`. */
+export const preferencesFileOf = (reportsDirectory = defaultReportsDirectory) => path.join(reportsDirectory, "preferences.md");
+
+/**
+ * The user's writing preferences: { file, text, made }, the file made from Gallery's default
+ * first when there is none (`made`), never over one that exists (another reader making it at the
+ * same moment: its file is read).
+ */
+export async function readWritingPreferences(reportsDirectory = defaultReportsDirectory) {
+  const file = preferencesFileOf(reportsDirectory);
+  const existing = await fs.readFile(file, "utf8").catch((error) => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
+  if (existing !== null) return { file, text: existing, made: false };
+  const text = await fs.readFile(defaultPreferencesFile, "utf8");
+  await fs.mkdir(reportsDirectory, { recursive: true });
+  try {
+    await fs.writeFile(file, text, { flag: "wx" });
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    return { file, text: await fs.readFile(file, "utf8"), made: false };
+  }
+  return { file, text, made: true };
+}
+
+/** Whether preferences (their Markdown) say anything: a letter or a digit under the title (its first line, a # heading). */
+export const saysAnything = (text) => /[\p{L}\p{N}]/u.test(text.replace(/^\s*# [^\n]*/, ""));
+
+// Markdown's words as their letters alone, under its title: a comment's words are words; every other
+// tag, a picture's address (the page keeps its pictures under names of its own), the marks, spaces
+// and numbers are not.
+const lettersOf = (text) => text
+  .replace(/<!--|-->/g, " ")
+  .replace(/!\[((?:\\.|[^\]\\])*)\]\([^)]*\)/g, "$1")
+  .replace(/<\/?[A-Za-z][^>]*>/g, " ")
+  .replace(/[^\p{L}]/gu, "");
+const underTitle = (text) => text.replace(/^\s*# [^\n]*/, "");
+
+/**
+ * The lines of preferences `file` (Markdown) whose words the page made of it does not hold, as its
+ * Markdown `page` writes them (what writing the page back over the file would take out: a comment, a
+ * link's address on this computer), trimmed, in order: each a line whose letters are not, in a row,
+ * among the page's. Words joined or split again, spaced, numbered or marked otherwise are the same.
+ */
+export function unshownLines(file, page) {
+  const shown = lettersOf(underTitle(page));
+  return underTitle(file).split("\n").map((line) => line.trim()).filter((line) => {
+    const letters = lettersOf(line);
+    return letters !== "" && !shown.includes(letters);
+  });
+}

package/browser/shared/zoom.mjs

@@ -0,0 +1,57 @@
+import { INSTANCE } from "./components/installed.mjs";
+
+// 图片放大: which pictures of a report open large when clicked (docs/render.md, "Opening a picture
+// large"). One rule for both ways in: the kit's viewer for a reader (src/render/kit/runtime/zoom.js:
+// a click, in an export, a build, the preview's 演示视图), and the page editor's while editing
+// (editor/components/image/viewer.mjs: a double-click, notion-lite's rule, 展开 and 全屏查看 on an
+// image block). Nothing is written for it: a picture is one by where it stands and how large it is
+// shown, so an Agent's report gets it without a word in its markup.
+//
+// A picture is an <img> of the page (main.doc-page), whatever holds it: an image block, a table's
+// cell, a card (one of the kit's or a drawing of the report's own), a column, a flowchart's node, a
+// list item, a detail card. Not one that is a control's or a link's (a click there is theirs: it
+// follows the link, opens the disclosure, chooses the tab), nor one in an instance of a component
+// package (its component's), nor an icon: the page's icon and a panel's or a node's (.doc-icon, emoji
+// pictures among them), a link's icon, a bookmark's pictures, a file's; nor a picture shown smaller
+// than ZOOM_LEAST each way (an icon's or an emoji's size in a line of text), nor one that did not load.
+
+/** What a picture inside of opens nothing: a control or a link, an icon, the kit's and the preview's own. */
+export const ZOOM_SKIP = [
+  "a[href]", "button", "summary", "label", "select", "[role=button]", "[role=link]", "[role=tab]", "[data-doc-dialog-open]",
+  ".doc-icon", ".doc-link-mention", ".doc-bookmark", ".doc-file",
+  ".doc-zoom", "[data-doc-dev]", INSTANCE,
+].join(", ");
+
+/** The pictures the reader's runtime watches to offer to the keyboard (runtime/zoom.js), those of the rule among them. */
+export const ZOOM_PICTURES = ".doc-page img";
+
+/**
+ * The runtime's mark on a picture that opens, offered to the keyboard while the page is read (not
+ * edited): with it a tab stop, a button's role and a name saying what it does, which the picture
+ * itself is no control of its own for the rule (its role is the runtime's). An export of the view
+ * takes them off (the image description's runtime).
+ */
+export const ZOOM_MARK = "data-doc-zoom";
+
+/** The least a picture is shown, in CSS pixels, across or down, to open large. */
+export const ZOOM_LEAST = 48;
+
+// A picture loaded: one of pixels has a size of its own; an SVG may have none (no width, height or
+// viewBox) and still draw.
+const loaded = (img) => img.complete && (img.naturalWidth > 0 || /^data:image\/svg|\.svg(?:[?#]|$)/i.test(img.currentSrc || img.src));
+
+/** Whether `img` opens large when clicked (or double-clicked in the page editor). */
+export function zoomable(img) {
+  const holder = img?.hasAttribute?.(ZOOM_MARK) ? img.parentElement : img; // the runtime's own role is no control's
+  if (img?.localName !== "img" || !img.closest(".doc-page") || holder?.closest(ZOOM_SKIP) || !loaded(img)) return false;
+  const box = img.getBoundingClientRect();
+  return box.width >= ZOOM_LEAST || box.height >= ZOOM_LEAST;
+}
+
+/** The words shown under a picture opened large: the caption of the image block or card it is the one picture of, else none. */
+export function zoomCaption(img) {
+  const figure = img.closest("figure");
+  if (!figure || [...figure.querySelectorAll("img")].filter((each) => each.closest("figure") === figure).length !== 1) return null;
+  const caption = figure.querySelector(":scope > figcaption, :scope > .doc-figure-caption");
+  return caption && caption.textContent.trim() ? caption : null;
+}