@heycys/gallery 0.2.0 → 0.2.2

package/browser/shared/outline.mjs

@@ -3,11 +3,47 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { writeAtomic } from "./files.mjs";
 import { extensionColumnIds } from "./extensions.mjs";
-import { DOCS, entryPattern, extensionGroupId, GROUP_LIMITS, groupOf, isForeign, isTop, newGroupId, topIn, topOf, validGroups } from "./outline-shape.mjs";
+import { DOCS, columnWorkspaceId, entryWorkspace, entryPattern, extensionGroupId, GROUP_LIMITS, groupOf, groupOfTop, isForeign, isTop, newGroupId, topIn, topOf, validGroups } from "./outline-shape.mjs";
 import { storedHead } from "./sidebar-head.mjs";
-import { shownWorkspaces, snapshotOf } from "./workspace-columns.mjs";
-import { layoutOf, listDocumentSlugs, listLinkSlugs, pageSlug } from "./workspace.mjs";
+import { forgetSnapshot, shownWorkspaces, snapshotOf } from "./workspace-columns.mjs";
+import { defaultWorkspace, layoutOf, listDocumentSlugs, listLinkSlugs, pageSlug } from "./workspace.mjs";
+import { readRegistry, workspaceId, workspaceKey } from "./workspace-registry.mjs";
 
+/** All document folders share the default workspace’s outline. */
+export const outlineRoot = () => defaultWorkspace();
+
+/** Moving a reference across owners must use the confirmed copy command. */
+export function ownsOutline(root, value) {
+  const self = workspaceId(root);
+  const available = new Set([self, ...shownWorkspaces(root).map(workspace => workspace.id)]);
+  return Object.entries(value.children).every(([parent, list]) => {
+    const owner = isTop(parent) ? columnWorkspaceId(value.groups?.find(group => topOf(group.id) === parent), self) : entryWorkspace(parent, self);
+    // Missing legacy references remain removable and must not block edits to healthy documents.
+    return list.every(entry => !available.has(entryWorkspace(entry, self)) || entryWorkspace(entry, self) === owner);
+  });
+}
+
+// Earlier versions allowed mixed-workspace nesting. Return misplaced roots to their owner,
+// retaining same-owner order and descendants. This changes directory positions, never files.
+function ownedTree(tree, self) {
+  const children = Object.fromEntries(tree.groups.map(group => [topOf(group.id), []]));
+  const ownTop = owner => { const group = tree.groups.find(group => owner === self ? group.id === DOCS : group.workspace === owner); return group ? topOf(group.id) : null; };
+  const walk = (parent, owner) => {
+    for (const entry of tree.children[parent] ?? []) {
+      const belongs = entryWorkspace(entry, self);
+      const at = belongs === owner ? parent : ownTop(belongs) ?? parent;
+      (children[at] ??= []).push(entry);
+      walk(entry, belongs);
+    }
+  };
+  for (const group of tree.groups) if (!group.extension) walk(topOf(group.id), columnWorkspaceId(group, self));
+  return { ...tree, children };
+}
+
+// Registered workspaces project one shared tree, partitioned by file owner. Their former local files
+// only seed new entries; the default workspace stores subsequent order/hierarchy edits. The format
+// below is also the standalone/legacy reader. Its picked/hidden/left rules are not applied to shared
+// trees, which list every registered document and link. Extensions are read from home alone.
 // The workspace's outline: the sidebar's columns and which entry sits under which, in what order
 // (<workspace>/.gallery/outline.json, docs/workbench.md "Workspace commands"; its shape: ./outline-shape.mjs).
 // The file, version 2:
@@ -56,10 +92,10 @@ const LOCK_WAIT = 15_000;
 /**
  * Run `task` holding the outline's lock of workspace `root`: a file made with "wx", which one
  * process alone can make, removed after; one older than 10 s is a crashed writer's and is taken over.
- * Waits for it 15 s at most, then takes it all the same (a writer that holds it that long holds
- * nothing any more).
+ * A live writer refreshes its lock. Waits 15 s at most and then refuses rather than stealing it.
  */
-export async function withOutlineLock(root, task) {
+export async function withOutlineLock(root, task, { local = false } = {}) {
+  if (!local) root = outlineRoot(root);
   const { gallery } = layoutOf(root);
   const lock = path.join(gallery, "outline.lock");
   const mine = `${process.pid} ${randomBytes(4).toString("hex")}`;
@@ -71,13 +107,17 @@ export async function withOutlineLock(root, task) {
     } catch (error) {
       if (error.code !== "EEXIST") throw error;
       const age = await fs.stat(lock).then(({ mtimeMs }) => Date.now() - mtimeMs, () => 0);
-      if (age > LOCK_STALE || Date.now() > until) await fs.rm(lock, { force: true });
+      if (age > LOCK_STALE) await fs.rm(lock, { force: true });
+      else if (Date.now() > until) throw Object.assign(new Error("文档目录刚在别处改过"), { code: "stale" });
       else await new Promise((resolve) => setTimeout(resolve, 20));
     }
   }
+  const heartbeat = setInterval(() => fs.utimes(lock, new Date(), new Date()).catch(() => {}), LOCK_STALE / 3);
+  heartbeat.unref();
   try {
     return await task();
   } finally {
+    clearInterval(heartbeat);
     // Removed only while it is still this writer's (one taken over meanwhile is the next writer's).
     if ((await fs.readFile(lock, "utf8").catch(() => null)) === mine) await fs.rm(lock, { force: true });
   }
@@ -98,7 +138,8 @@ export async function readOutline(root, { others = true } = {}) {
  */
 export async function otherWorkspaces(root, { env = process.env } = {}) {
   const shown = shownWorkspaces(root, { env });
-  const readOwn = (other) => readOutline(other, { others: false });
+  // Project-local files seed entries not yet in the shared tree; never recurse into its projection.
+  const readOwn = async (other) => (await localOutlineAndFile(other, { others: false })).outline;
   const unread = () => ({ documents: new Set(), order: [], parentOf: new Map(), facts: new Map(), failed: true });
   return Promise.all(shown.map(async (each) => ({ ...each, failed: false, ...(await snapshotOf(each.root, readOwn).catch(unread)) })));
 }
@@ -113,14 +154,16 @@ export async function otherWorkspaces(root, { env = process.env } = {}) {
  * place a command or the workbench gave. `others: false`: the workspace's own tree alone (no column of
  * another workspace made, none filled).
  */
-export async function outlineAndFile(root, { others: withOthers = true } = {}) {
+async function localOutlineAndFile(root, { others: withOthers = true, shared = false } = {}) {
   const instructions = await pageSlug(root);
   const documents = (await listDocumentSlugs(root)).filter((slug) => slug !== instructions);
   const links = await listLinkSlugs(root);
   const extensions = await extensionColumnIds(root);
   const stored = storedOf(await readJson(layoutOf(root).outline));
   const others = withOthers ? await otherWorkspaces(root) : [];
-  const shown = ordered(stored, documents, links, extensions, others, { drawn: withOthers });
+  const base = shared && stored ? { ...stored, groups: stored.groups.map(({ picked, hidden, left, ...group }) => group.workspace || group.extension || group.id === DOCS ? group : { ...group, owner: group.owner ?? workspaceId(root) }) } : stored;
+  let shown = ordered(base, documents, links, extensions, others, { drawn: withOthers });
+  if (shared) shown = ownedTree(shown, workspaceId(root));
   const outline = {
     version: 2, ...shown, links, drafts: Object.values(shown.children).flat().filter(isForeign),
     shown: others.map(({ id, root: other, isDefault }) => ({ id, root: other, isDefault })),
@@ -128,6 +171,40 @@ export async function outlineAndFile(root, { others: withOthers = true } = {}) {
   return { outline, stored, others };
 }
 
+/** Translate the same tree between the default workspace's ids and a project's local ids.
+ * No second ordering is kept: only the current workspace's column is displayed first. */
+function projectTree(value, from, to) {
+  if (!value || workspaceKey(from) === workspaceKey(to)) return value;
+  const fromId = workspaceId(from), toId = workspaceId(to);
+  const own = value.groups.find(group => group.workspace === toId);
+  const ownId = own?.id ?? toId;
+  const groupId = id => id === DOCS ? fromId : id === ownId ? DOCS : id;
+  const entry = key => key.startsWith(`~${toId}/`) ? key.slice(toId.length + 2) : isForeign(key) ? key : `~${fromId}/${key}`;
+  const key = value => isTop(value) ? topOf(groupId(groupOfTop(value))) : entry(value);
+  let groups = value.groups.map(group => {
+    if (group.id === DOCS) return { ...group, id: fromId, workspace: fromId };
+    if (group.id === ownId) {
+      const { workspace, picked, hidden, left, ...rest } = group;
+      return { ...rest, id: DOCS };
+    }
+    return group;
+  });
+  return { ...value, groups, children: Object.fromEntries(Object.entries(value.children).map(([parent, list]) => [key(parent), list.map(entry)])) };
+}
+
+export async function outlineAndFile(root, { others: withOthers = true } = {}) {
+  const home = outlineRoot(root);
+  if (workspaceKey(home) === workspaceKey(root)) return localOutlineAndFile(root, { others: withOthers, shared: true });
+  // A command may just have created/trashed a local item before placing it in the shared tree.
+  forgetSnapshot(root);
+  const shared = await localOutlineAndFile(home, { shared: true });
+  let outline = projectTree(shared.outline, home, root);
+  const ownLinks = await listLinkSlugs(root);
+  const others = await otherWorkspaces(root);
+  outline = { ...outline, links: ownLinks, drafts: Object.values(outline.children).flat().filter(isForeign), shown: others.map(({ id, root: other, isDefault }) => ({ id, root: other, isDefault })) };
+  return { outline, stored: projectTree(shared.stored, home, root), others };
+}
+
 // The own column's name before it was 默认文档 or the workspace's (文档, Documents in English), which a
 // rename of it confirmed unchanged wrote as its title (the field opens with the name shown): read as no
 // title, so that the name it goes by now shows. A title of another column, or any other, is the user's.
@@ -378,6 +455,13 @@ export function fileOf(value) {
  * the head's order the file holds kept as it is (writeHead's).
  */
 export async function writeOutline(root, value) {
+  const home = outlineRoot(root);
+  if (!ownsOutline(root, value)) throw Object.assign(new Error("跨工作区请复制，不能只移动目录位置"), { code: "CROSS_WORKSPACE" });
+  value = { ...value, groups: (value.groups ?? [{ id: DOCS }]).map(group => group.id === DOCS || group.workspace || group.extension ? group : { ...group, owner: group.owner ?? workspaceId(root) }) };
+  if (workspaceKey(home) !== workspaceKey(root)) {
+    value = projectTree(value, root, home);
+    root = home;
+  }
   const file = layoutOf(root).outline;
   await fs.mkdir(path.dirname(file), { recursive: true });
   const head = storedHead((await readJson(file))?.head);
@@ -465,6 +549,7 @@ export function moveDocument(root, slug, where) {
   return withOutlineLock(root, async () => {
     const { outline, stored } = await outlineAndFile(root);
     const result = moveIn(outline.children, slug, where);
+    if (result.ok && !ownsOutline(root, outline)) return { ok: false, reason: "cross-workspace" };
     const written = result.ok && !writtenAs(outline, stored);
     if (written) await writeOutline(root, outline);
     return { ...result, ...(result.ok ? { written } : {}) };

package/browser/shared/page-address.mjs

@@ -1,4 +1,5 @@
-import { earlierLink, pageLink, pageOfLink } from "./page-links.mjs";
+import { localPath } from "./workspace-address.mjs";
+import { pageLink, pageOfLink } from "./page-links.mjs";
 
 // A document's address, as a link, a paste or the address bar may write it (docs/workbench.md, "A
 // document's addresses"), read in one place: { slug, block }, block null for the page itself. Pure: the
@@ -16,11 +17,8 @@ import { earlierLink, pageLink, pageOfLink } from "./page-links.mjs";
 // one form that needs `links` (pageLinks: a Map of slug to link), for only the list can say which
 // document an id is or whether a name is a slug at all; given, `links` also turns away every slug it
 // does not hold. Without it such an address is none here, and workbenchHash hands it to the workbench,
-// which has the list. pageAddress reads no port, as a link outlives a server; but this computer runs
-// other programs too, and other workspaces, whose folder of one name has one page id, so an address
-// on another port (elsewhere) is a document's only if the list holds it, by its folder name or its
-// link of now (addressOn), or for a folder named doc- and eight characters, the link it had before
-// those eight were its id (shared/page-links.mjs earlierId).
+// which has the list. pageAddress parses a shape; addressOn additionally requires the current
+// service’s port. An address of another port is always external, even when its slug matches.
 
 const SLUG = "[a-z0-9]+(?:-[a-z0-9]+)*"; // shared/workspace.mjs slugPattern, which needs Node
 const FILE = "(?:doc|report)\\.html";
@@ -71,7 +69,7 @@ export function pageAddress(text, links = null) {
   if (inFile) return known(inFile[1], decoded(inFile[2] ?? ""));
   const url = ownAddress(address);
   if (!url) return null;
-  const path = PAGE.exec(url.pathname) ?? OWN_FILE.exec(url.pathname);
+  const path = PAGE.exec(localPath(url.pathname)) ?? OWN_FILE.exec(localPath(url.pathname));
   if (path) return known(path[1], decoded(url.hash.slice(1)));
   return url.pathname === "/" && url.hash.length > 1 ? hashAddress(decoded(url.hash.slice(1)), links) : null;
 }
@@ -87,19 +85,14 @@ export function workbenchHash(text) {
 
 /**
  * The document and block `text` names of those in `links` (a Map, or null with no list) as read on the
- * server of `origin`, as pageAddress reads it; but a workbench's address on another port says what it
- * is by its words, the folder name or the link the document has now, for the same id there may be
- * another workspace's page. With no `origin`, as a file is read, every port is another.
+ * server of `origin`, as pageAddress reads it. Another port is always external; with no origin
+ * supplied, no running service’s port is inferred from matching titles or folder names.
  * @param {string} text
  * @param {Map<string, string> | null} links
  * @param {string} [origin]
  */
 export function addressOn(text, links, origin = "http://127.0.0.1") {
-  const place = pageAddress(text, links);
-  const name = place && elsewhere(text, origin) ? workbenchHash(text)?.split("/")[0] : undefined;
-  if (name === undefined || links.has(name)) return place;
-  const link = links.get(place.slug);
-  return link === name || earlierLink(place.slug, link) === name ? place : null;
+  return elsewhere(text, origin) ? null : pageAddress(text, links);
 }
 
 /** Whether `text` is an address of a document of this workspace, as far as can be told with no list. */

package/browser/shared/paths.mjs

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { serviceLocation } from "./service-location.mjs";
 import { findWorkspace, layoutOf } from "./workspace.mjs";
 
 // Where everything is on disk, for every system, in two kinds: the workspace's (the user's documents
@@ -42,7 +43,7 @@ export const qaDirectory = workspace.qa; // gallery qa's pictures of what it fla
 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;
+export const previewLogFile = serviceLocation().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

package/browser/shared/preferences.mjs

@@ -1,3 +1,4 @@
+import { documentKey } from "./workspace-address.mjs";
 // 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
@@ -88,7 +89,7 @@ function openSlugs() {
 
 /** 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);
+  return typeof slug === "string" && slug !== "" && openSlugs().includes(documentKey(slug));
 }
 
 /**
@@ -96,6 +97,7 @@ export function outlineOpen(slug) {
  * reports, the one switched on longest ago let go); off, it is taken out.
  */
 export function setOutlineOpen(slug, on) {
+  slug = documentKey(slug);
   if (typeof slug !== "string" || slug === "") return;
   try {
     const slugs = openSlugs().filter((one) => one !== slug);

package/browser/shared/preview-server.mjs

@@ -5,18 +5,11 @@ import net from "node:net";
 import path from "node:path";
 import { packageRoot } from "./paths.mjs";
 import { compareVersions } from "./versions.mjs";
-import { layoutOf } from "./workspace.mjs";
+import { defaultWorkspace } from "./workspace.mjs";
+import { serviceLocation } from "./service-location.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.
+// One service per data directory: commands verify the announcement before reusing its port.
+// Documents in every registered folder use the same service and retain owner-qualified paths.
 
 // 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.
@@ -24,10 +17,10 @@ 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). */
+/** Whether two paths name the same directory (a service home or data directory). */
 export const sameDirectory = (a, b) => canonical(a) === canonical(b);
 
-const fileOf = (reportsDirectory) => layoutOf(reportsDirectory).serverFile;
+const fileOf = () => serviceLocation().serverFile;
 /** Gallery's version, as its package says it (a server of another version is another Gallery's). */
 export const galleryVersion = (() => {
   try {
@@ -47,30 +40,33 @@ const runs = (pid) => {
   }
 };
 
-/**
- * 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);
+/** Acquire the data-directory lifetime lease and publish the sole service identity.
+ * The returned closer removes only this instance’s announcement and lease. */
+export async function announcePreviewServer({ home = defaultWorkspace(), port, token, kind = "dev", version = galleryVersion, every = 1000 }) {
+  const file = fileOf();
   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 text = `${JSON.stringify({ port, pid: process.pid, home: path.resolve(home), 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);
+  const lease = path.join(path.dirname(file), "server.lock");
+  for (let attempt = 0; ; attempt++) {
+    try { await fs.writeFile(lease, text, { flag: "wx", mode: 0o600 }); break; }
+    catch (error) {
+      if (error.code !== "EEXIST" || attempt > 3) throw error;
+      const owner = await fs.readFile(lease, "utf8").then(JSON.parse).catch(() => null);
+      if (!owner) throw new Error("Gallery is starting; retry shortly.");
+      if (runs(owner.pid)) {
+        if (owner.pid === process.pid && owner.port === port) { await fs.writeFile(lease, text); break; }
+        throw new Error(`Gallery already runs on port ${owner.port} (pid ${owner.pid}).`);
+      }
+      await fs.rm(lease, { force: true });
+    }
+  }
+  try { await save(text); } catch (error) {
+    const owner = await fs.readFile(lease, "utf8").then(JSON.parse).catch(() => null);
+    if (owner?.nonce === nonce) await fs.rm(lease, { force: true });
+    throw error;
+  }
   let closed = false;
   const look = async () => {
     let there = null;
@@ -91,29 +87,22 @@ export async function announcePreviewServer({ reportsDirectory, port, token, kin
     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(() => {});
+    const announcement = await fs.readFile(file, "utf8").then(JSON.parse).catch(() => null);
+    if (announcement?.nonce === nonce) await fs.rm(file, { force: true }).catch(() => {});
+    const owner = await fs.readFile(lease, "utf8").then(JSON.parse).catch(() => null);
+    if (owner?.nonce === nonce) await fs.rm(lease, { 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 }) {
+// The data-directory service announcement, while its process runs.
+export async function readAnnouncement() {
   let found;
   try {
-    found = JSON.parse(await fs.readFile(fileOf(reportsDirectory), "utf8"));
+    found = JSON.parse(await fs.readFile(fileOf(), "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;
+  if (!Number.isInteger(found?.port) || !Number.isInteger(found.pid) || typeof found.token !== "string" || typeof found.home !== "string") return null;
   return runs(found.pid) ? found : null;
 }
 
@@ -122,17 +111,16 @@ 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 (GET /__gallery/workspace/info there names the announcement's token, its process, home and data directory, 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) {
+export async function answerOf(found, timeout = 10_000) {
   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);
+    const same = info?.token === found.token && info.server?.pid === found.pid && typeof info.server.home === "string" && sameDirectory(info.server.home, found.home) && sameDirectory(info.server.data, serviceLocation().data);
     return same ? "yes" : "no";
   } catch (error) {
     return error?.name === "TimeoutError" ? "busy" : "no";
@@ -140,15 +128,15 @@ export async function answerOf(found, reportsDirectory, timeout) {
 }
 
 /**
- * The running server of this workspace: { port, token, pid }, or null when none says it runs. With
+ * The running server for this data directory: { 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;
+export async function findPreviewServer({ answering = false, timeout = 10_000 } = {}) {
+  const found = await readAnnouncement();
+  if (!found || (answering && await answerOf(found, timeout) !== "yes")) return null;
   return { port: found.port, token: found.token, pid: found.pid };
 }
 
@@ -199,7 +187,7 @@ export async function stopServer(found, { wait = 10_000 } = {}) {
     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 (status === 409) return { ok: false, reason: "dev", message: `The shared Gallery 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);
@@ -209,7 +197,7 @@ export async function stopServer(found, { wait = 10_000 } = {}) {
 }
 
 /**
- * This workspace's server, for a command that needs one (src/cli/server-process.mjs serverFor): the
+ * The shared service, 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
@@ -218,12 +206,12 @@ export async function stopServer(found, { wait = 10_000 } = {}) {
  * 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
+ * version, newer }`: the shared Gallery 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";
+export async function previewServerFor({ ports, start, stop = stopServer, timeout = 10_000, version = galleryVersion }) {
+  const found = await readAnnouncement();
+  const answer = found ? await answerOf(found, 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 } };

package/browser/shared/service-location.mjs

@@ -0,0 +1,18 @@
+import path from "node:path";
+import { userDirectory } from "./user-directory.mjs";
+import { defaultWorkspace } from "./workspace.mjs";
+import { workspaceId, workspaceKey } from "./workspace-registry.mjs";
+import { projectBase } from "./workspace-address.mjs";
+
+export const workspaceBase = root => workspaceKey(root) === workspaceKey(defaultWorkspace()) ? "" : projectBase(workspaceId(root));
+
+// A service belongs to a Gallery data directory, never to a document storage directory.
+export function serviceLocation() {
+  const data = userDirectory("data");
+  return {
+    data,
+    serverFile: path.join(data, "server.json"),
+    lastPortFile: path.join(data, "last-port"),
+    serverLog: path.join(data, "logs", "server.log"),
+  };
+}

package/browser/shared/session.mjs

@@ -1,9 +1,8 @@
+import { documentKey } from "./workspace-address.mjs";
 // The session between a report page and a workbench that shows it in an iframe of the same origin
 // (docs/workbench.md): the page's side is src/editor/page/session.mjs, the workbench's
 // src/workbench/app/session/. Every message is { protocol: PROTOCOL, v: VERSION, type, slug, ... },
-// posted to the other window for this origin only; or, for a draft of another workspace, between the
-// page and a workbench of another origin each side's server vouched for (the page's ?shell=<origin>,
-// GET /__gallery/workspace/shell; the workbench's POST elsewhere: src/workbench/elsewhere.mjs).
+// posted to the other window for this origin only. Every document uses this service.
 //
 //   report -> workbench   ready    once the editor started: { commands, title, icon, look, state, annotations, card }
 //                         state    when the state, the title, the page's icon, the look it shows, how many 批注 it
@@ -39,8 +38,6 @@
 //                         annotations-removed
 //                                  a 批注 deleted from its card: { items }: the workbench says so, as
 //                                  it does for 全部删除, and its 撤销 puts them back
-//                         bye      the page goes (pagehide), to a workbench of another origin alone, which
-//                                  cannot see it go: its session ends there
 //   workbench -> report   command  { id, name, ... }
 
 export const PROTOCOL = "gallery/session";
@@ -63,7 +60,7 @@ export const VERSION = 2;
  * back from another document keeps): sessionStorage, which a workbench and its frames share. A page
  * puts it there before it is shown again; the workbench before the way back comes to it.
  */
-export const viewKey = (slug) => `gallery-edit:${slug}:view`;
+export const viewKey = (slug) => `gallery-edit:${documentKey(slug)}:view`;
 
 /**
  * What `state` reports, in this order: editing (the editor runs: the page edits from the start),

package/browser/shared/workspace-address.mjs

@@ -0,0 +1,19 @@
+// All projects share one origin. Only document resources and operations carry an owner;
+// package assets and the workbench itself stay at the root of that origin.
+export const projectBase = (id) => `/~${id}`;
+export function projectItem(value) {
+  const match = /^~(ws-[0-9a-f]{6})\/([^/]+)$/.exec(String(value ?? ""));
+  return match ? { ws: match[1], slug: match[2], base: projectBase(match[1]) } : null;
+}
+const PROJECT = /^(\/~(ws-[0-9a-f]{6}))(?=\/|$)/;
+export const projectOfPath = (pathname) => PROJECT.exec(pathname)?.[2] ?? null;
+export const localPath = (pathname) => pathname.replace(PROJECT, "") || "/";
+export const currentProjectBase = () => PROJECT.exec(globalThis.location?.pathname ?? "")?.[1] ?? "";
+export function workspaceAddress(address, base = currentProjectBase()) {
+  if (!base || typeof address !== "string" || projectOfPath(address)) return address;
+  return /^\/(?:__gallery\/|generated\/|pages\/)/.test(address) ? base + address : address;
+}
+
+/** Browser state is shared by origin, so a document's owner is part of its identity. */
+export const documentKey = (slug, base = currentProjectBase()) => base && typeof slug === "string" && slug && !slug.startsWith("~") ? base.slice(1) + "/" + slug : slug;
+export const workspaceStoragePrefix = (base = currentProjectBase()) => base ? "gallery-project:" + base.slice(1) + ":" : "";

package/browser/shared/workspace-columns.mjs

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { iconKind } from "./emoji/icon-value.mjs";
 import { isWorkspace, readRegistry, workspaceId, workspaceKey } from "./workspace-registry.mjs";
-import { defaultWorkspace, documentFiles, isSlugName } from "./workspace.mjs";
+import { defaultWorkspace, documentFiles, isSlugName, readLink } from "./workspace.mjs";
 
 // The other workspaces a workspace's sidebar shows a column of (notes/plans/workspaces-links-plan-2026-11-08.md
 // §7.2; docs/workbench.md "Columns"): every workspace of the machine's registry (./workspace-registry.mjs) but
@@ -13,13 +13,12 @@ import { defaultWorkspace, documentFiles, isSlugName } from "./workspace.mjs";
 // as its own sidebar has them) and the place of its documents no column holds; the user's order of the
 // columns is the outline's after that.
 //
-// What a workspace's sidebar is read with (snapshotOf): its documents in its own sidebar's order, the document
-// each is under there (a web link or another workspace's draft passed over upward), and what its doc.json
+// What a workspace's sidebar is read with (snapshotOf): its documents and links in its former local order,
+// their same-workspace parents, and what their doc.json or link.json
 // says (title, description, an icon of the emoji or 图标 kind: no picture of another workspace's folder). It is
 // read from its files, never written, and kept SNAPSHOT_KEPT ms at most, so that the reads of a burst (a
 // command and the workbench's read after it, the list of 添加其他 Gallery 项目…) read each folder once while a
-// change there shows at the next read after that; the server drops one at once when that workspace's own
-// server tells of a change (src/workbench/service.mjs, through ./elsewhere.mjs). Reads files only.
+// change there shows at the next read after that; the cache is dropped when the storage runtime reports a change in the same process (src/server/projects.mjs). Reads files only.
 
 /** How long a snapshot of another workspace is believed (ms). */
 export const SNAPSHOT_KEPT = 2000;
@@ -90,19 +89,19 @@ async function read(root, readOwn) {
   const documents = new Set();
   const order = [];
   const parentOf = new Map();
-  // Its documents alone: its web links, the drafts of others its tree shows and a folder named by no slug are none.
-  const isDocument = (key) => !own.links.includes(key) && !key.startsWith("~") && isSlugName(key);
+  // Own documents and links; another workspace's reference is not a second file here.
+  const isEntry = (key) => !key.startsWith("~") && isSlugName(key);
   const parentIn = (child) => {
     for (const [key, list] of Object.entries(own.children)) if (list.includes(child)) return key;
     return null;
   };
   const above = (slug) => {
     let up = parentIn(slug);
-    while (up !== null && !(up === "" || up.startsWith(":")) && !isDocument(up)) up = parentIn(up);
+    while (up !== null && !(up === "" || up.startsWith(":")) && !isEntry(up)) up = parentIn(up);
     return up === null || up === "" || up.startsWith(":") ? null : up;
   };
   const walk = (key) => (own.children[key] ?? []).forEach((slug) => {
-    if (isDocument(slug) && !documents.has(slug)) {
+    if (isEntry(slug) && !documents.has(slug)) {
       documents.add(slug);
       order.push(slug);
       parentOf.set(slug, above(slug));
@@ -111,6 +110,10 @@ async function read(root, readOwn) {
   });
   for (const { id } of own.groups) walk(id === "docs" ? "" : `:${id}`);
   const facts = new Map(await Promise.all(order.map(async (slug) => {
+    if (own.links.includes(slug)) {
+      const link = await readLink(path.join(root, slug));
+      return [slug, { ...link, kind: "link", title: link?.title ?? slug, description: "", path: path.join(root, slug, "link.json") }];
+    }
     const files = documentFiles(path.join(root, slug));
     const metadata = await fs.readFile(files.json, "utf8").then((text) => JSON.parse(text.replace(/^/, "")), () => null);
     const value = metadata && typeof metadata === "object" && !Array.isArray(metadata) ? metadata : {};