@heycys/gallery 0.1.1 → 0.2.0

package/browser/shared/drafts.mjs

@@ -0,0 +1,432 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { descendantsIn, outlineAndFile, parentIn, placeIn, readOutline, withOutlineLock, writeOutline, writtenAs } from "./outline.mjs";
+import { DOCS, GROUP_LIMITS, isForeign, isTop, newGroupId, topIn, topOf } from "./outline-shape.mjs";
+import { findPreviewServer } from "./preview-server.mjs";
+import { idsOf, shownIcon } from "./workspace-columns.mjs";
+import { nameStops, workspaceLabels, workspaceName } from "./workspace-name.mjs";
+import { isWorkspace, readRegistry, workspaceId, workspaceKey } from "./workspace-registry.mjs";
+import { defaultWorkspace, documentFiles, isSlugName, listDocumentSlugs } from "./workspace.mjs";
+
+// The drafts of other workspaces in a workspace's sidebar (notes/plans/workspaces-links-plan-2026-11-08.md
+// §2.2, §2.5, §7.2; docs/workbench.md "Drafts of other workspaces"): an entry of the outline written
+// "~<ws id>/<slug>" (./outline-shape.mjs), the workspace's id its path's hash on the machine's registry
+// (./workspace-registry.mjs), the draft its document <root>/<slug>/doc.html there. Only where the sidebar
+// shows it is this workspace's to keep: the draft's folder never moves, and its own workspace's tree is
+// never written (its server shows it as it was). Every registered workspace has a column of its own
+// (./workspace-columns.mjs, ./outline.mjs), "whole" (all its documents) unless the user picked a document
+// of it in 添加其他 Gallery 项目… (POST draft-add) while it had none shown: then it is `picked`, holding that
+// document and those under it alone, and what an Agent makes or opens there later (gallery new, gallery
+// open in another workspace than the default one: joinDefaultTree). The column the user removed is
+// `hidden`; an Agent's gallery new or open there, or the user's pick, shows it again. A draft the user took
+// out of a whole column (从文档树移除) is in its `left`, not filled in again until it is put back here.
+// A draft whose workspace is not on the registry, two registered folders sharing its id (six hex digits
+// of a hash: a clash is refused, never guessed), or whose folder is gone stays in the tree, shown grey
+// (找不到底稿) until the user removes it. Reads other workspaces' files only; writes this one's outline.
+
+/** A draft's entry in the outline. */
+export const DRAFT_ENTRY = /^~(ws-[0-9a-f]{6})\/([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+export const draftEntry = (id, slug) => `~${id}/${slug}`;
+/** The workspace's id and the slug a draft's entry names, or null for an entry that names none. */
+export function draftOf(entry) {
+  const match = DRAFT_ENTRY.exec(String(entry ?? ""));
+  return match ? { ws: match[1], slug: match[2] } : null;
+}
+
+const oneLine = (value) => (typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "");
+const exists = (target) => fs.access(target).then(() => true, () => false);
+
+/**
+ * The registered workspaces by their ids: a Map of id to the roots registered under it (two for one id:
+ * a clash of the hash's six digits, which names neither: workspaceOf). `registry`: readRegistry()'s.
+ */
+export const registeredIds = (registry = readRegistry()) => idsOf(registry);
+
+/**
+ * The workspace `id` names on the registry: { root }, or { refused: "unknown" (no registered workspace
+ * of that id: forgotten, or never registered) | "ambiguous" (two registered folders share it), roots }.
+ */
+export function workspaceOf(id, ids = registeredIds()) {
+  const roots = ids.get(id) ?? [];
+  if (roots.length === 1) return { root: roots[0] };
+  return { refused: roots.length ? "ambiguous" : "unknown", roots };
+}
+
+/** The ids two or more registered folders share: [{ id, roots }] (gallery workspaces and the sidebar say so). */
+export const clashingIds = (ids = registeredIds()) => [...ids].filter(([, roots]) => roots.length > 1).map(([id, roots]) => ({ id, roots }));
+
+/** Whether a draft's doc.json says it is a document (not the 写作偏好 page of an old layout), and what it says. */
+async function metadataAt(folder) {
+  const files = documentFiles(folder);
+  const [html, metadata] = await Promise.all([exists(files.html), fs.readFile(files.json, "utf8").then((text) => JSON.parse(text.replace(/^/, "")), () => null)]);
+  return { files, html, metadata: metadata && typeof metadata === "object" && !Array.isArray(metadata) ? metadata : null };
+}
+
+/**
+ * What the sidebar shows of draft `entry`: { entry, ws, slug, root (null: no workspace of that id),
+ * folder, path (its doc.html, or an old one's report.html), title, description, icon, missing: null, or
+ * why it is shown grey: "workspace" (none of that id on the registry, or its folder gone), "ambiguous"
+ * (two of that id), "draft" (its document is gone) }.
+ */
+export async function draftFacts(entry, ids = registeredIds()) {
+  const { ws, slug } = draftOf(entry) ?? { ws: "", slug: entry };
+  const found = workspaceOf(ws, ids);
+  const none = { entry, ws, slug, root: null, folder: null, path: null, title: slug, description: "", icon: null };
+  if (!found.root) return { ...none, missing: found.refused === "ambiguous" ? "ambiguous" : "workspace" };
+  const folder = path.join(found.root, slug);
+  const { files, html, metadata } = await metadataAt(folder);
+  const missing = !isWorkspace(found.root) ? "workspace" : !html || metadata?.instructions === true ? "draft" : null;
+  // An untitled document says so (its title empty: the workbench names it 未命名文档); one with no doc.json to read, its slug.
+  return { entry, ws, slug, root: found.root, folder, path: files.html, title: typeof metadata?.title === "string" ? oneLine(metadata.title) : slug, description: oneLine(metadata?.description), icon: shownIcon(metadata?.icon), missing };
+}
+
+/**
+ * The names the sidebar calls the registered workspaces by: a Map of id to { name, above, upper, root,
+ * there }, for the ids `wanted`. `above` is what tells it apart from another of `among` (ids: those shown
+ * side by side, the sidebar's columns or the list of 添加其他 Gallery 项目…; `wanted` when none is given) that has
+ * its name (./workspace-name.mjs workspaceLabels), else null: never a workspace of the machine that is not
+ * shown. `upper`: the name of the folder above the one named (null at a drive's root), which the sidebar
+ * shows when a column of another kind has the name. `stops`: nameStops()'s (asked once by a server: it
+ * reads Windows' registry).
+ */
+export function workspaceNames(wanted, { ids = registeredIds(), stops = nameStops(), among = wanted } = {}) {
+  const named = [...ids].filter(([id, roots]) => roots.length === 1 && (wanted.has(id) || among.has(id))).map(([id, [root]]) => ({ id, root, ...workspaceName(root, { stops }) }));
+  const compared = named.filter((entry) => among.has(entry.id));
+  const labels = new Map(workspaceLabels(compared).map((label, index) => [compared[index].id, label]));
+  const names = new Map();
+  for (const entry of named) {
+    if (wanted.has(entry.id)) names.set(entry.id, { name: entry.name, above: labels.get(entry.id)?.above ?? null, upper: entry.above, root: entry.root, there: isWorkspace(entry.root) });
+  }
+  return names;
+}
+
+/**
+ * What a path the user pasted or picked (添加其他 Gallery 项目…) names: a workspace's folder, a document's
+ * doc.html (an old one's report.html) or its folder; a file:// address of one too, and quotes around it are
+ * taken away. One of: { kind: "workspace", root } (a folder holding Gallery's gallery.json);
+ * { kind: "draft", folder, slug, root (the workspace it is in: the nearest folder up holding Gallery's
+ * gallery.json; null for none, `parent` then the folder that would become one) }; { kind: "folder", folder }
+ * (a folder that is no workspace yet but holds Gallery documents: the one that would become a workspace);
+ * { kind: "missing" } (nothing there, or not an absolute path); { kind: "plain" } (an HTML file, or a folder
+ * that is no Gallery draft, workspace or folder of documents); { kind: "nested", root } (a draft that is not
+ * right in its workspace: the trash's, the 写作偏好 page's); { kind: "name" } (a folder whose name is no slug).
+ */
+export async function findDraft(written) {
+  let target = String(written ?? "").trim().replace(/^["']+|["']+$/g, "");
+  if (/^file:\/\//i.test(target)) {
+    try {
+      target = fileURLToPath(target);
+    } catch {
+      return { kind: "missing", path: target };
+    }
+  }
+  if (!target || !path.isAbsolute(target)) return { kind: "missing", path: target };
+  target = path.resolve(target);
+  const stat = await fs.stat(target).catch(() => null);
+  if (!stat) return { kind: "missing", path: target };
+  let folder;
+  if (stat.isDirectory()) folder = target;
+  else if (/^(doc|report)\.html$/i.test(path.basename(target))) folder = path.dirname(target);
+  else return { kind: "plain", path: target };
+  if (stat.isDirectory() && isWorkspace(folder)) return { kind: "workspace", path: target, root: folder };
+  const { files, html, metadata } = await metadataAt(folder);
+  if (stat.isDirectory() && !html && (await listDocumentSlugs(folder).catch(() => [])).some(isSlugName)) return { kind: "folder", path: target, folder };
+  if (!html || (!files.old && !metadata) || metadata?.instructions === true) return { kind: "plain", path: target };
+  let root = null;
+  for (let directory = path.dirname(folder); ; directory = path.dirname(directory)) {
+    if (isWorkspace(directory)) {
+      root = directory;
+      break;
+    }
+    if (path.dirname(directory) === directory) break;
+  }
+  const slug = path.basename(folder);
+  if (root && workspaceKey(path.dirname(folder)) !== workspaceKey(root)) return { kind: "nested", path: target, root };
+  if (!isSlugName(slug)) return { kind: "name", path: target };
+  return { kind: "draft", path: files.html, folder, slug, root, parent: path.dirname(folder) };
+}
+
+/**
+ * The column of workspace `id` in `outline` (changed in place): the one that has `workspace: id`; with none
+ * (a workspace the sidebar does not show as it was read: the outline of a workspace's own tree, or past 50
+ * columns), one made right after the column `after` (an id; none: last), picked (`picked`) or whole, or null
+ * where no column can be made (50 already: the entry goes to the own column's top).
+ */
+function columnFor(outline, id, { after = null, picked = false } = {}) {
+  let group = outline.groups.find((each) => each.workspace === id);
+  if (group) return group;
+  if (outline.groups.length >= GROUP_LIMITS.groups) return null;
+  group = { id: outline.groups.some((each) => each.id === id) ? newGroupId(outline.groups) : id, workspace: id, ...(picked ? { picked: true } : {}) };
+  const at = outline.groups.findIndex((each) => each.id === after);
+  outline.groups = at < 0 ? [...outline.groups, group] : [...outline.groups.slice(0, at + 1), group, ...outline.groups.slice(at + 1)];
+  outline.children[topOf(group.id)] ??= [];
+  return group;
+}
+
+/** `outline`'s column `id` (changed in place: its object replaced) as `change(column)` gives it, at index `to` when given. */
+function changeColumn(outline, id, change, to = null) {
+  const groups = outline.groups.filter((each) => each.id !== id);
+  const at = outline.groups.findIndex((each) => each.id === id);
+  const next = change(outline.groups[at]);
+  groups.splice(to === null ? at : Math.min(to, groups.length), 0, next);
+  outline.groups = groups;
+  return next;
+}
+
+/** `outline`'s column `id` moved right after column `after` (one of it; none, or itself: where it is). */
+function moveAfter(outline, id, after) {
+  if (!after || after === id || !outline.groups.some((each) => each.id === after)) return;
+  const groups = outline.groups.filter((each) => each.id !== id);
+  groups.splice(groups.findIndex((each) => each.id === after) + 1, 0, outline.groups.find((each) => each.id === id));
+  outline.groups = groups;
+}
+
+const shownColumn = ({ hidden, ...column }) => column;
+
+/**
+ * Draft `slug` of workspace `draftRoot` put in the sidebar of workspace `treeRoot` (its outline, under the
+ * outline's lock; `changed()` once it is written), with the drafts under it in its own workspace's tree
+ * (documents: a web link of that workspace is none, nor a draft of a third its tree shows, the drafts under
+ * one going under the draft above it), those the tree does not hold yet. Its workspace's column is shown
+ * again when the user had removed it (hidden). How, `pick` says:
+ * - false (an Agent's gallery new or open there: joinDefaultTree, POST draft-join): one the outline holds
+ *   (the file, or a whole column as it is read) stays where it is; else (a picked column) under its own
+ *   parent's entry when the tree holds that, else last in its workspace's column;
+ * - true (the user's pick in 添加其他 Gallery 项目…, `after`: the column whose menu it came from): one shown
+ *   in the sidebar already stays where it is (revealed, `existing`); its workspace's column hidden, or one the
+ *   sidebar showed not before (`fresh`: its workspace registered just now, its column made only as the outline
+ *   is read, filled whole), it is made a picked one holding it and those under it alone, right after `after`;
+ *   one shown picked or whole takes it (under its own parent's entry, else last: one the user had taken out of
+ *   a whole one); with none, a picked column is made right after `after`.
+ * Either way, what is put in a whole column is in its `left` no more.
+ * Resolves to { entry, existing: whether the file held it, so that nothing was put in, parent, added: the
+ * entries put in, column: the id of the column it is in, under: the entry it is under, or null, shown: whether
+ * the column was shown again }.
+ */
+export async function addDraft(treeRoot, draftRoot, slug, { changed = () => {}, pick = false, after = null, fresh = false } = {}) {
+  const id = workspaceId(draftRoot);
+  const entry = draftEntry(id, slug);
+  const own = await readOutline(draftRoot, { others: false }).catch(() => ({ children: {}, links: [] })); // its own tree, read alone
+  // No document of that workspace: its web links, and the drafts of others its tree shows (~<ws id>/<slug>).
+  const none = (key) => own.links.includes(key) || isForeign(key);
+  const ownParent = (child) => {
+    let up = parentIn(own.children, child);
+    while (up !== null && !isTop(up) && none(up)) up = parentIn(own.children, up);
+    return up === null || isTop(up) ? null : up;
+  };
+  return withOutlineLock(treeRoot, async () => {
+    const { outline, stored } = await outlineAndFile(treeRoot);
+    const holds = (key) => Object.values(outline.children).some((list) => list.includes(key));
+    const storedHolds = Object.values(stored?.children ?? {}).some((list) => list.includes(entry));
+    const where = () => {
+      const parent = parentIn(outline.children, entry);
+      const top = topIn(outline.children, entry);
+      return { parent, column: top === null || top === "" ? DOCS : top.slice(1), under: parent !== null && !isTop(parent) ? parent : null };
+    };
+    const columnOf = (key) => outline.groups.find((each) => topOf(each.id) === topIn(outline.children, key)) ?? null;
+    let shown = false;
+    let column = outline.groups.find((each) => each.workspace === id) ?? null;
+    const put = () => {
+      const added = [];
+      const top = column ? topOf(column.id) : topOf(DOCS);
+      const above = ownParent(slug);
+      placeIn(outline, entry, above !== null && holds(draftEntry(id, above)) ? draftEntry(id, above) : top);
+      added.push(entry);
+      for (const child of descendantsIn(own.children, slug)) {
+        const childEntry = draftEntry(id, child);
+        if (none(child) || holds(childEntry)) continue;
+        placeIn(outline, childEntry, draftEntry(id, ownParent(child) ?? slug));
+        added.push(childEntry);
+      }
+      // Put in again: taken out of a whole column no more.
+      if (column?.left) {
+        const back = new Set(added.map((each) => draftOf(each).slug));
+        column = changeColumn(outline, column.id, ({ left, ...rest }) => {
+          const still = left.filter((taken) => !back.has(taken));
+          return still.length ? { ...rest, left: still } : rest;
+        });
+      }
+      return added;
+    };
+    let added = [];
+    let existing = false;
+    if (!pick) {
+      if (column?.hidden) {
+        column = changeColumn(outline, column.id, shownColumn);
+        shown = true;
+      }
+      existing = storedHolds;
+      if (!holds(entry)) {
+        column ??= columnFor(outline, id);
+        added = put();
+      } else if (!storedHolds) added = [entry];
+    } else {
+      // A column the file holds not, of a workspace the sidebar showed not before: made as it was read, whole.
+      const madeNow = Boolean(column) && fresh && !(stored?.groups ?? []).some((each) => each.workspace === id);
+      const at = columnOf(entry);
+      const there = holds(entry) && !at?.hidden && !(madeNow && at?.id === column.id);
+      if (there) existing = true;
+      else if (column?.hidden || madeNow) {
+        // Made a picked column holding it and those under it alone, shown, right after `after`.
+        const top = topOf(column.id);
+        for (const key of descendantsIn(outline.children, top)) delete outline.children[key];
+        outline.children[top] = [];
+        shown = Boolean(column.hidden);
+        column = changeColumn(outline, column.id, ({ left: _left, ...each }) => ({ ...shownColumn(each), picked: true }));
+        moveAfter(outline, column.id, after);
+        added = put();
+      } else {
+        column ??= columnFor(outline, id, { after, picked: true });
+        added = put();
+      }
+    }
+    if (!writtenAs(outline, stored)) {
+      await writeOutline(treeRoot, outline);
+      changed();
+    }
+    return { entry, existing, added, shown, ...where() };
+  });
+}
+
+/**
+ * Workspace `otherRoot` shown whole in the sidebar of workspace `treeRoot` (添加其他 Gallery 项目… with a
+ * workspace: its outline, under the outline's lock; `changed()` once it is written): its column (made when
+ * there is none) shown, whole (all its documents, those the user had taken out of it too: those no column
+ * holds come as the outline is read), right after the column `after` (an id). Resolves to { column: its id,
+ * moved, shown, whole: whether each changed }.
+ */
+export async function addWorkspace(treeRoot, otherRoot, { changed = () => {}, after = null } = {}) {
+  const id = workspaceId(otherRoot);
+  return withOutlineLock(treeRoot, async () => {
+    const { outline, stored } = await outlineAndFile(treeRoot);
+    let column = columnFor(outline, id, { after });
+    if (!column) return { column: null, moved: false, shown: false, whole: false };
+    const shown = Boolean(column.hidden);
+    const whole = Boolean(column.picked || column.left);
+    // Whole: all its documents, those the user took out of it before too (its `left` gone).
+    column = changeColumn(outline, column.id, ({ picked: _picked, left: _left, ...each }) => shownColumn(each));
+    const before = outline.groups.findIndex((each) => each.id === column.id);
+    moveAfter(outline, column.id, after);
+    const moved = outline.groups.findIndex((each) => each.id === column.id) !== before;
+    if (!writtenAs(outline, stored)) {
+      await writeOutline(treeRoot, outline);
+      changed();
+    }
+    return { column: column.id, moved, shown, whole };
+  });
+}
+
+/**
+ * The other registered workspaces (but `treeRoot`'s own), for 添加其他 Gallery 项目…'s list: [{ ws, root, name,
+ * above, documents: [{ entry, slug, title, icon, path, depth }] }], each workspace's documents in the order
+ * its own sidebar has them (depth: how deep under others there), those whose folder is no workspace now left
+ * out, a clash of ids too (refused, never guessed), the one used last first. Reads files only: nothing of
+ * another workspace is written (its 写作偏好 page is no draft).
+ */
+export async function projectChoices(treeRoot, { ids = registeredIds(), stops = nameStops(), registry = readRegistry() } = {}) {
+  const seen = new Map(registry.workspaces.map(({ root, seen: at }) => [workspaceKey(root), Date.parse(at)]));
+  const wanted = new Set([...ids].filter(([, roots]) => roots.length === 1 && workspaceKey(roots[0]) !== workspaceKey(treeRoot)).map(([id]) => id));
+  const names = workspaceNames(wanted, { ids, stops });
+  const found = await Promise.all([...names].filter(([, { there }]) => there).map(async ([id, { name, above, root }]) => {
+    const tree = await readOutline(root, { others: false }).catch(() => null);
+    const documents = [];
+    const isDocument = (slug) => !(tree?.links ?? []).includes(slug) && !isForeign(slug) && isSlugName(slug);
+    const walk = (key, depth) => (tree?.children[key] ?? []).forEach((slug) => {
+      const document = isDocument(slug);
+      if (document) documents.push({ slug, depth });
+      walk(slug, document ? depth + 1 : depth);
+    });
+    for (const { id: column } of tree?.groups ?? []) walk(topOf(column), 0);
+    const listed = await Promise.all(documents.map(async ({ slug, depth }) => {
+      const { files, metadata } = await metadataAt(path.join(root, slug));
+      return { entry: draftEntry(id, slug), slug, title: oneLine(metadata?.title) || slug, icon: shownIcon(metadata?.icon), path: files.html, depth };
+    }));
+    return { ws: id, root, name, above, seen: seen.get(workspaceKey(root)) ?? 0, documents: listed };
+  }));
+  return found.sort((a, b) => b.seen - a.seen).map(({ seen: _seen, ...rest }) => rest);
+}
+
+
+/** The environment variable that keeps gallery new and gallery open from putting their draft in the default workspace's sidebar (the tests set it). */
+export const NO_DEFAULT_TREE = "GALLERY_NO_DEFAULT_TREE";
+const set = (value) => !["", "0", undefined].includes(value);
+
+/**
+ * gallery new and gallery open in a workspace other than the default one (src/shared/workspace.mjs
+ * defaultWorkspace): draft `slug` of workspace `root` put in the default workspace's sidebar (addDraft,
+ * with the drafts under it), through the default workspace's server when one runs (POST
+ * /__gallery/workspace/draft-join: in its queue, its workbench told at once), else here under the
+ * outline's lock. Null where it is not done: NO_DEFAULT_TREE set, `root` the default workspace, no
+ * default workspace there yet (nothing is made for it), or `root` not on the registry under its id (a
+ * workspace in the system's temporary folder, or a clash of ids: an entry would name none). Else
+ * addDraft's answer with `home` (the default workspace) and `names`: { column: the name of the column
+ * it is in, under: the title of the draft it is under, or null }; or { failed: why } (nothing written).
+ */
+export async function joinDefaultTree(root, slug, { env = process.env } = {}) {
+  if (set(env[NO_DEFAULT_TREE])) return null;
+  const home = defaultWorkspace({ env });
+  if (workspaceKey(home) === workspaceKey(root) || !isWorkspace(home)) return null;
+  const ids = registeredIds();
+  const found = workspaceOf(workspaceId(root), ids);
+  if (!found.root || workspaceKey(found.root) !== workspaceKey(root)) return null;
+  let done = null;
+  try {
+    const server = await findPreviewServer({ reportsDirectory: home });
+    if (server) done = await joinThrough(server, root, slug);
+    done ??= await addDraft(home, root, slug);
+  } catch (error) {
+    return { failed: error.message, home };
+  }
+  return { ...done, home, names: await placeNames(home, done, ids) };
+}
+
+// POST draft-join to the default workspace's server; null when no server of it takes it (gone, or an older Gallery's).
+async function joinThrough(server, root, slug) {
+  const host = `127.0.0.1:${server.port}`;
+  try {
+    const response = await fetch(`http://${host}/__gallery/workspace/draft-join`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Origin: `http://${host}`, "X-Gallery-Token": server.token },
+      body: JSON.stringify({ root, slug }),
+      signal: AbortSignal.timeout(30000),
+    });
+    const answer = await response.json().catch(() => null);
+    return answer?.ok === true && typeof answer.entry === "string" ? answer : null;
+  } catch {
+    return null;
+  }
+}
+
+// The names a line says of where a draft went: its column's (the user's title, else its workspace's
+// name, else 默认文档, the default workspace's own column, or 链接) and the title of the draft or document it is under.
+async function placeNames(home, { column, under }, ids) {
+  const { groups } = await readOutline(home);
+  const group = groups.find((each) => each.id === column);
+  let name = group?.title ?? null;
+  if (!name && group?.workspace) name = workspaceNames(new Set([group.workspace]), { ids }).get(group.workspace)?.name ?? null;
+  name ??= group?.role === "links" ? "链接" : group?.id === DOCS || !group ? "默认文档" : "未命名栏"; // its own column is the default workspace's
+  let above = null;
+  if (under) {
+    if (draftOf(under)) above = (await draftFacts(under, ids)).title;
+    else {
+      const metadata = await fs.readFile(documentFiles(path.join(home, under)).json, "utf8").then(JSON.parse, () => null);
+      above = oneLine(metadata?.title) || under;
+    }
+  }
+  return { column: name, under: above };
+}
+
+/** The line gallery new and gallery open print of joinDefaultTree's answer (null for none). */
+export function joinedLine(joined) {
+  if (!joined) return null;
+  const where = `默认工作区（${joined.home}）的侧边栏`;
+  if (joined.failed) return `${where}：没有加进去（${joined.failed}）`;
+  if (joined.existing) return `${where}里已经有它（${joined.names.under ? `在「${joined.names.under}」下面` : `「${joined.names.column}」栏`}）`;
+  const more = joined.added.length > 1 ? `，连同它下面的 ${joined.added.length - 1} 篇` : "";
+  return `${where}：已加进${joined.names.under ? `「${joined.names.under}」下面` : `「${joined.names.column}」栏`}${more}（拖动只改那里的显示位置，文件不动）`;
+}
+
+/** Whether a gallery.json at `folder` would be another program's or not readable (what draft-add refuses to make a workspace of). */
+export const foreignMarker = (folder) => existsSync(path.join(folder, "gallery.json")) && !isWorkspace(folder);

package/browser/shared/emoji/line-icons.mjs

@@ -0,0 +1,37 @@
+import { ICON_COLOR_VALUES } from "./icon-value.mjs";
+
+// Gallery's own line icons as a custom page's icon (page.json's `icon`): the look of the workbench's sidebar
+// head, whose 新建 and 搜索 are Lucide's line icons (a 1.75 line in 24 units, workbench/app/components/icons.ts),
+// so that a page Gallery makes stands among them in the same hand (the user's word of 2026-11-09: no filled
+// icon there). A value is `/icons/lucide/<name>.svg`, with no color of its own: the workbench masks it in the
+// color of where it stands (the sidebar's icon gray, as an icon of no icon's color), the browser tab draws it
+// in the tab's gray (as a page with no icon, icon-value.mjs DEFAULT_TAB_ICON). It is none of the three kinds
+// of a document's icon (icon-value.mjs iconKind: no document has one), nor an icon of the 图标 tab: Gallery's
+// default home page's house (src/editor/home-page.mjs HOME_ICON), alone so far. The icon route draws it
+// (src/render/emoji.mjs iconImage).
+
+const LINE_ICONS = {
+  // Lucide's house (1.67.0), the one the sidebar drew for the home page before its page.json said its icon.
+  house: '<path d="M15 21v-8a1 1 0 0 0-1-1h-4a1 1 0 0 0-1 1v8"/><path d="M3 10a2 2 0 0 1 .709-1.528l7-5.999a2 2 0 0 1 2.582 0l7 5.999A2 2 0 0 1 21 10v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/>',
+};
+const LINE = /^\/icons\/lucide\/([a-z0-9-]+)\.svg$/;
+
+/** The value of Gallery's line icon `name` (one LINE_ICONS has). */
+export const lineIconValue = (name) => `/icons/lucide/${name}.svg`;
+
+/** Whether `value` names one of Gallery's line icons. */
+export const isLineIcon = (value) => lineIconSvg(value) !== null;
+
+const [TAB_LIGHT, TAB_DARK] = ICON_COLOR_VALUES.gray;
+
+/**
+ * The SVG of the line icon `value` names, or null (none of them): its lines in `color` (black, the
+ * workbench's mask); with `tab`, a browser tab's, its box cropped to `1 1 22 22` as the tab's icon of a
+ * page with no icon is, in the tab glyphs' gray, light or dark as the system is.
+ */
+export function lineIconSvg(value, { color = "currentColor", tab = false } = {}) {
+  const name = typeof value === "string" ? LINE.exec(value)?.[1] : null;
+  if (!name || !Object.hasOwn(LINE_ICONS, name)) return null;
+  const style = tab ? `<style>svg{color:${TAB_LIGHT}}@media (prefers-color-scheme:dark){svg{color:${TAB_DARK}}}</style>` : "";
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${tab ? "1 1 22 22" : "0 0 24 24"}" fill="none" stroke="${tab ? "currentColor" : color}" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round">${style}${LINE_ICONS[name]}</svg>`;
+}

package/browser/shared/extension-sidebar.mjs

@@ -0,0 +1,126 @@
+import { said } from "./i18n/index.mjs";
+import { isExtensionId } from "./outline-shape.mjs";
+import { linkAddress, linkIcon } from "./web-links.mjs";
+
+// The sidebar column an extension provides (docs/workbench.md "Extension columns", references/extensions.md
+// for the Agent that writes one): <workspace>/extensions/<id>/sidebar.json,
+//   { "title": "语雀", "icon": "📗", "entries": [
+//     { "id": "team", "title": "团队知识库", "url": "https://www.yuque.com/team",
+//       "children": [ { "id": "weekly", "title": "周报", "url": "https://www.yuque.com/team/weekly" } ] },
+//     { "id": "panel", "title": "发布面板", "url": "http://127.0.0.1:4318/" } ] }
+// `title` is the column's name (100 characters at most), `icon` an emoji or an icon of the 图标 tab (no
+// picture is ever loaded from the web). An entry has an `id` (1 to 128 of A-Z a-z 0-9 . _ : -, once in
+// the file: the extension keeps it, for it is what an address and an open entry go by), a `title` (200
+// at most), an `url` (http or https, 2048 at most: none, and the entry only holds its `children`, which
+// a click opens and closes), an `icon` and `children` (8 levels, 2000 entries in all, 1 MB the file).
+// Pure and the same wherever it is read (the server answers the workbench with it, gallery extension
+// check prints it); reading the file is ./extensions.mjs's (Node's). What makes the file unusable is a
+// refusal (`error`, said() of a reason: the column then shows one row, 条目读不出来：<reason>); what is
+// only left out of it (an icon that is none) is a note, said by gallery extension check and shown nowhere.
+
+/** The extension's file in its folder. */
+export const SIDEBAR_FILE = "sidebar.json";
+export const SIDEBAR_LIMITS = { bytes: 1_048_576, levels: 8, entries: 2000, id: 128, title: 200, column: 100 };
+export const entryIdPattern = /^[A-Za-z0-9._:-]{1,128}$/;
+
+/** An entry's key in the workbench's address (`#~<extension id>/<entry id>`), and as its row says it. */
+export const extensionKey = (extension, entry) => `~${extension}/${entry}`;
+/** The extension and the entry a key names: { extension, entry }, or null for what is none. */
+export function parseExtensionKey(value) {
+  if (typeof value !== "string" || !value.startsWith("~")) return null;
+  const at = value.indexOf("/");
+  if (at < 0) return null;
+  const extension = value.slice(1, at);
+  const entry = value.slice(at + 1);
+  return isExtensionId(extension) && entryIdPattern.test(entry) ? { extension, entry } : null;
+}
+
+const tidy = (value) => (typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "");
+const refused = (message) => ({ error: message });
+
+/**
+ * What the text of a sidebar.json says: { sidebar: { title, icon?, entries, count }, notes } with each
+ * entry { id, title, icon?, url?, children? } (the address as the URL spells it, a title's white space
+ * run together), or { error } (said(): why the file is no sidebar), the first reason found. `notes`: said()
+ * of what was left out (an icon that is no emoji nor icon of the 图标 tab).
+ */
+export function readSidebarText(text) {
+  const source = String(text);
+  if (source.length > SIDEBAR_LIMITS.bytes) return refused(said("文件超过 1MB"));
+  let value;
+  try {
+    value = JSON.parse(source.replace(/^/, ""));
+  } catch (error) {
+    return refused(said("不是 JSON：{0}", error.message));
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) return refused(said("最外层要是一个对象，有 title 和 entries"));
+  const title = tidy(value.title);
+  if (!title || title.length > SIDEBAR_LIMITS.column) return refused(said("title 要有，是栏的名字（100 个字以内）"));
+  if (!Array.isArray(value.entries)) return refused(said("entries 要是一个列表"));
+  const notes = [];
+  let icon;
+  if (value.icon !== undefined && value.icon !== null && value.icon !== "") {
+    if (linkIcon(value.icon)) icon = value.icon;
+    else notes.push(said("icon 不是表情，也不是图标页签里的图标，没有显示"));
+  }
+  const ids = new Set();
+  let count = 0;
+  const walk = (list, path, level) => {
+    if (level > SIDEBAR_LIMITS.levels && list.length) return { error: said("条目超过 {0} 层（{1}）", SIDEBAR_LIMITS.levels, path) };
+    const made = [];
+    for (const [index, raw] of list.entries()) {
+      const where = `${path}[${index}]`;
+      if (++count > SIDEBAR_LIMITS.entries) return { error: said("条目超过 {0} 个", SIDEBAR_LIMITS.entries) };
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { error: said("{0} 要是一个对象", where) };
+      if (typeof raw.id !== "string" || !entryIdPattern.test(raw.id)) return { error: said("{0} 的 id 不对（1 到 128 个字符，只能用字母、数字和 . _ : -）", where) };
+      if (ids.has(raw.id)) return { error: said("{0} 的 id「{1}」重复了（同一个文件里 id 不能重）", where, raw.id) };
+      ids.add(raw.id);
+      const name = tidy(raw.title);
+      if (!name || name.length > SIDEBAR_LIMITS.title) return { error: said("{0} 要有 title（名称，200 个字以内）", where) };
+      const entry = { id: raw.id, title: name };
+      if (raw.url !== undefined && raw.url !== null && raw.url !== "") {
+        const address = linkAddress(raw.url);
+        if (address.refused === "scheme") return { error: said("{0} 的 url 只能是 http 或 https 的网址", where) };
+        if (address.refused === "long") return { error: said("{0} 的 url 太长了（最多 2048 个字符）", where) };
+        if (address.refused) return { error: said("{0} 的 url 不是一个网址", where) };
+        entry.url = address.url;
+      }
+      if (raw.icon !== undefined && raw.icon !== null && raw.icon !== "") {
+        if (linkIcon(raw.icon)) entry.icon = raw.icon;
+        else notes.push(said("{0} 的 icon 不是表情，也不是图标页签里的图标，没有显示", where));
+      }
+      if (raw.children !== undefined && raw.children !== null) {
+        if (!Array.isArray(raw.children)) return { error: said("{0} 的 children 要是一个列表", where) };
+        const inner = walk(raw.children, `${where}.children`, level + 1);
+        if (inner.error) return inner;
+        if (inner.entries.length) entry.children = inner.entries;
+      }
+      made.push(entry);
+    }
+    return { entries: made };
+  };
+  const walked = walk(value.entries, "entries", 1);
+  if (walked.error) return refused(walked.error);
+  return { sidebar: { title, ...(icon ? { icon } : {}), entries: walked.entries, count }, notes };
+}
+
+/** The entry `id` of `entries` (a tree: children under each), or null. */
+export function entryIn(entries, id) {
+  for (const entry of entries ?? []) {
+    if (entry.id === id) return entry;
+    const inside = entryIn(entry.children, id);
+    if (inside) return inside;
+  }
+  return null;
+}
+
+/**
+ * The entry key `key` (`~<extension id>/<entry id>`, a workbench's hash, decoded) names among `extensions`
+ * (the columns as GET outline lists them: [{ id, entries }]), or null: what a link to an entry's address
+ * opens (one with an `url`) wherever a page reads it (the workbench, a page alone in a tab, 演示视图).
+ */
+export function entryOfKey(extensions, key) {
+  const named = parseExtensionKey(key);
+  const extension = named && (extensions ?? []).find(({ id }) => id === named.extension);
+  return extension ? entryIn(extension.entries, named.entry) : null;
+}