@heycys/gallery 0.1.1 → 0.2.0

package/browser/shared/workspace-registry.mjs

@@ -0,0 +1,272 @@
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { writeAtomic } from "./files.mjs";
+import { userDirectory } from "./user-directory.mjs";
+import { layoutOf, markerOf } from "./workspace.mjs";
+
+// The registry of the workspaces used on this machine (notes/plans/workspaces-links-plan-2026-11-08.md
+// §2.3): one file in the user's data folder (../shared/user-directory.mjs "data": %LOCALAPPDATA%\gallery
+// on Windows, ~/Library/Application Support/gallery on macOS, $XDG_STATE_HOME/gallery or
+// ~/.local/state/gallery elsewhere; GALLERY_DATA_DIR in its place, which the tests set), so that a
+// workspace an Agent made in a project's folder is found from any other (gallery workspaces, gallery
+// list --all, and the sidebar's columns of other workspaces):
+//   { "version": 1, "workspaces": [{ "root": "<absolute path>", "seen": "<ISO time>" }] }
+// A workspace is registered once a gallery command has found it (src/cli/gallery.mjs: every command
+// but stop and skill; init and workspaces --name once they made it) and when its server starts
+// (src/server/routes.mjs listening), `seen` written again an hour later at the soonest; never one in
+// the system's temporary folder (the tests', a trial's, a check's), nor a folder whose gallery.json is
+// not Gallery's. A path is one entry however it is spelt (upper and lower case alike on Windows). A
+// change is made under the registry's lock (workspaces.json.lock), on the file as it is then, and
+// written whole to a file beside it renamed over it, so that two commands registering at once each
+// keep the other's (updateRegistry). A workspace whose folder
+// is gone stays registered (an external drive comes back) until gallery workspaces --forget forgets it.
+// Each workspace has a short id that never changes while its path does not: ws- and six hex digits of
+// the hash of its path (workspaceId), for the sidebar's places and addresses.
+
+export const REGISTRY_FILE = "workspaces.json";
+/** How long a registration's `seen` is believed before a command writes it again. */
+export const SEEN_EVERY = 60 * 60 * 1000;
+
+/** The registry's file: <data folder>/workspaces.json. Only a path. */
+export const registryFile = (options = {}) => path.join(userDirectory("data", options), REGISTRY_FILE);
+
+/** A workspace's path as one key, however it is spelt: absolute, and lower case on Windows. */
+export const workspaceKey = (root, platform = process.platform) => (platform === "win32" ? path.resolve(root).toLowerCase() : path.resolve(root));
+
+/** The workspace's short id: ws- and the first six hex digits of the SHA-256 of its key. */
+export const workspaceId = (root, platform = process.platform) => `ws-${createHash("sha256").update(workspaceKey(root, platform)).digest("hex").slice(0, 6)}`;
+
+/** Whether `value` names a workspace's id (ws- and six hex digits). */
+export const isWorkspaceId = (value) => /^ws-[0-9a-f]{6}$/.test(String(value ?? ""));
+
+/**
+ * The registry as `text` (the file's) holds it: { version: 1, workspaces: [{ root, seen }] }, each
+ * path absolute and once (the latest `seen` of two spellings kept), in the file's order; an entry that
+ * is not one left out, a file that does not read an empty registry.
+ */
+export function registryOf(text, platform = process.platform) {
+  let stored = null;
+  try {
+    stored = JSON.parse(String(text ?? "").replace(/^/, ""));
+  } catch {}
+  const workspaces = [];
+  const at = new Map();
+  for (const entry of Array.isArray(stored?.workspaces) ? stored.workspaces : []) {
+    if (typeof entry?.root !== "string" || !path.isAbsolute(entry.root)) continue;
+    const seen = typeof entry.seen === "string" && Number.isFinite(Date.parse(entry.seen)) ? entry.seen : new Date(0).toISOString();
+    const key = workspaceKey(entry.root, platform);
+    if (!at.has(key)) {
+      at.set(key, workspaces.length);
+      workspaces.push({ root: path.resolve(entry.root), seen });
+    } else if (Date.parse(seen) > Date.parse(workspaces[at.get(key)].seen)) workspaces[at.get(key)].seen = seen;
+  }
+  return { version: 1, workspaces };
+}
+
+/** The registry as read now (registryOf of its file; none there: an empty one). */
+export function readRegistry({ file = registryFile() } = {}) {
+  try {
+    return registryOf(readFileSync(file, "utf8"));
+  } catch {
+    return { version: 1, workspaces: [] };
+  }
+}
+
+// The registry's lock (workspaces.json.lock beside it): a file one process alone can make ("wx"),
+// removed after; one older than LOCK_STALE was left by a process that ended and is taken over, and so is
+// one held past LOCK_WAIT (a writer holds it for a read and a rename: a command never waits long).
+// EPERM is a lock being removed (Windows: a file whose removal is pending) and a folder that cannot be
+// written as well (Windows' rights, the sandbox of macOS an Agent may run in, which allows writes in its
+// project alone): where no lock is there, LOCK_REFUSED of them in a row are the folder's, thrown at once,
+// so that a command in such a sandbox is not held LOCK_WAIT twice over by every registration.
+const LOCK_STALE = 10_000;
+const LOCK_WAIT = 3_000;
+const LOCK_REFUSED = 3;
+async function withLock(file, task) {
+  const lock = `${file}.lock`;
+  const mine = `${process.pid} ${Math.random().toString(16).slice(2)}`;
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  for (let refused = 0, until = Date.now() + LOCK_WAIT; ;) {
+    try {
+      await fs.writeFile(lock, mine, { flag: "wx" });
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST" && error.code !== "EPERM") throw error;
+      // The lock's age; null where there is none (removed meanwhile, or never made: a folder refusing it).
+      const age = await fs.stat(lock).then(({ mtimeMs }) => Date.now() - mtimeMs, (statError) => (statError.code === "ENOENT" ? null : 0));
+      refused = error.code === "EPERM" && age === null ? refused + 1 : 0;
+      if (refused >= LOCK_REFUSED) throw error; // a folder that cannot be written
+      if (Date.now() > until + LOCK_WAIT) throw error; // neither made nor taken over
+      if (age !== null && (age > LOCK_STALE || Date.now() > until)) await fs.rm(lock, { force: true }).catch(() => {});
+      await new Promise((resolve) => setTimeout(resolve, 10 + Math.random() * 20));
+    }
+  }
+  try {
+    return await task();
+  } finally {
+    if ((await fs.readFile(lock, "utf8").catch(() => null)) === mine) await fs.rm(lock, { force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Change the registry: `change(registry)` gives the registry to write, or null for nothing to write.
+ * Under the registry's lock, so that two commands writing at once each make their change on what the
+ * other wrote: read, changed and written whole (a file beside it, renamed over it), made again on what
+ * the file holds when it changed between the read and the rename all the same (a lock taken over).
+ * Resolves to the registry as it stands after.
+ */
+export async function updateRegistry(change, { file = registryFile() } = {}) {
+  return withLock(file, async () => {
+    for (let tries = 0; tries < 8; tries++) {
+      const text = await fs.readFile(file, "utf8").catch((error) => (error.code === "ENOENT" ? null : Promise.reject(error)));
+      const current = registryOf(text);
+      const next = change(current);
+      if (!next) return current;
+      if (await writeAtomic(file, `${JSON.stringify({ version: 1, workspaces: next.workspaces }, null, 2)}\n`, { expect: text })) return next;
+    }
+    throw new Error(`${file} kept changing while it was written: try again.`);
+  });
+}
+
+// The system's temporary folders, each as its path is written and as it really is (macOS's /var is
+// /private/var, its /tmp /private/tmp): os.tmpdir()'s (`tmp`), and /tmp but on Windows, for macOS's
+// os.tmpdir() is a folder of the user's under /var/folders while Agents' trials go to /tmp, which a
+// restart clears.
+function temporaryFolders(tmp, platform) {
+  const folders = [];
+  for (const folder of [tmp, ...(platform === "win32" ? [] : ["/tmp"])]) {
+    folders.push(path.resolve(folder));
+    try {
+      folders.push(realpathSync.native(folder));
+    } catch {}
+  }
+  return folders;
+}
+
+/** Whether `root` is in one of the system's temporary folders (`tmp`, os.tmpdir()'s, and /tmp but on Windows), or is one. */
+export function isTemporary(root, { tmp = os.tmpdir(), platform = process.platform } = {}) {
+  const roots = [path.resolve(root)];
+  try {
+    roots.push(realpathSync.native(root));
+  } catch {}
+  return temporaryFolders(tmp, platform).some((folder) => {
+    const base = workspaceKey(folder, platform);
+    return roots.some((each) => {
+      const key = workspaceKey(each, platform);
+      return key === base || key.startsWith(base.endsWith(path.sep) ? base : `${base}${path.sep}`);
+    });
+  });
+}
+
+/** Whether the folder `root` is a workspace now: its gallery.json there, and Gallery's. */
+export function isWorkspace(root) {
+  try {
+    return markerOf(readFileSync(layoutOf(root).marker, "utf8")).ours;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Register the workspace at `root`: added with `seen` now, or its `seen` written again when it is
+ * SEEN_EVERY old (`force`: whatever its age). Nothing is written for a folder in the system's
+ * temporary folder or one that is no workspace of Gallery's. Resolves to "added", "seen", "fresh" (its
+ * `seen` recent: nothing written), "temporary" or "none" (no workspace there).
+ */
+export async function registerWorkspace(root, { file = registryFile(), now = Date.now(), tmp = os.tmpdir(), force = false } = {}) {
+  const resolved = path.resolve(root);
+  if (isTemporary(resolved, { tmp })) return "temporary";
+  if (!isWorkspace(resolved)) return "none";
+  const key = workspaceKey(resolved);
+  const recent = (entry) => {
+    const age = now - Date.parse(entry.seen);
+    return !force && age >= 0 && age < SEEN_EVERY;
+  };
+  // Seen within the hour, as most commands find it: read alone, no lock taken.
+  const known = readRegistry({ file }).workspaces.find((each) => workspaceKey(each.root) === key);
+  if (known && recent(known)) return "fresh";
+  let did = "fresh";
+  await updateRegistry((registry) => {
+    const seen = new Date(now).toISOString();
+    const entry = registry.workspaces.find((each) => workspaceKey(each.root) === key);
+    if (!entry) {
+      did = "added";
+      return { version: 1, workspaces: [...registry.workspaces, { root: resolved, seen }] };
+    }
+    if (recent(entry)) {
+      did = "fresh";
+      return null;
+    }
+    did = "seen";
+    return { version: 1, workspaces: registry.workspaces.map((each) => (each === entry ? { root: each.root, seen } : each)) };
+  }, { file });
+  return did;
+}
+
+/** registerWorkspace for a command or a server, which never fails for it: a registry that cannot be read or written is passed over ("failed"). */
+export const registerQuietly = (root, options) => registerWorkspace(root, options).catch(() => "failed");
+
+/**
+ * Forget the registered workspaces `target` names (a path, as the registry holds it in any spelling, or
+ * a ws- id): nothing on disk but the registry changes. Resolves to the roots forgotten ([] for none).
+ */
+export async function forgetWorkspace(target, { file = registryFile(), cwd = process.cwd() } = {}) {
+  const byId = isWorkspaceId(target);
+  const key = byId ? null : workspaceKey(path.resolve(cwd, target));
+  const named = (entry) => (byId ? workspaceId(entry.root) === target : workspaceKey(entry.root) === key);
+  let forgotten = [];
+  await updateRegistry((registry) => {
+    forgotten = registry.workspaces.filter(named).map((entry) => entry.root);
+    return forgotten.length ? { version: 1, workspaces: registry.workspaces.filter((entry) => !named(entry)) } : null;
+  }, { file });
+  return forgotten;
+}
+
+/**
+ * The folders a scan passes over by name (upper and lower case alike), besides every dot folder: a
+ * package's and a repository's own, and Windows' own on a drive, its recycle bin among them (a workspace
+ * thrown away there is no workspace to find).
+ */
+export const SCAN_SKIPS = new Set(["node_modules", ".git", "$recycle.bin", "recycler", "system volume information"]);
+/** How deep a scan looks below its folder, and how many folders it reads at most. */
+export const SCAN_DEPTH = 6;
+export const SCAN_LIMIT = 50_000;
+
+/**
+ * The workspaces in `folder` and below it, `depth` levels down at most (gallery workspaces --scan):
+ * each folder whose gallery.json is Gallery's, sorted, none looked in further (a workspace holds
+ * documents, not workspaces). Passed over: dot folders, those SCAN_SKIPS names (node_modules, the
+ * recycle bin), links (they lead out of it) and folders that cannot be read. Resolves to { found:
+ * [root], read: folders read, cut: whether it stopped at `limit` folders }.
+ */
+export async function scanForWorkspaces(folder, { depth = SCAN_DEPTH, limit = SCAN_LIMIT } = {}) {
+  const found = [];
+  let read = 0;
+  let cut = false;
+  let level = [path.resolve(folder)];
+  for (let at = 0; at <= depth && level.length && !cut; at++) {
+    const next = [];
+    for (const directory of level) {
+      if (read >= limit) {
+        cut = true;
+        break;
+      }
+      read++;
+      if (isWorkspace(directory)) {
+        found.push(directory);
+        continue;
+      }
+      if (at === depth) continue;
+      const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith(".") || SCAN_SKIPS.has(entry.name.toLowerCase())) continue;
+        next.push(path.join(directory, entry.name));
+      }
+    }
+    level = next;
+  }
+  return { found: found.sort(), read, cut };
+}

package/browser/shared/workspace.mjs

@@ -4,6 +4,8 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { DOC_SLUG, earlierId, newPageId, pageId } from "./page-links.mjs";
+import { LINK_FILE, readLinkText } from "./web-links.mjs";
 
 // 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
@@ -11,20 +13,26 @@ import path from "node:path";
 // 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:
+// gallery.json, preferences.md (写作偏好), exports/, components/, pages/ and extensions/ 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>/pages/<slug>/page.html, page.json  a custom page (./pages.mjs), no document
+//   <workspace>/extensions/<id>/sidebar.json  the sidebar column an extension provides (./extensions.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>/<slug>/link.json  a web link of the sidebar (./web-links.mjs), no document
 //   <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.
+//     previews, the server's announcement, port and log, what was adopted of an old layout, and the
+//     scratch copies gallery block try makes a trial on (try/try-<8 hex>/, each gone once its trial ends).
 //
 // 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).
+// devices: a workspace moves between systems) and not a dot name. components/, pages/ and extensions/
+// hold no document, but one of those names made before they came stays one, and no new one takes it
+// (COMPONENTS_FOLDER, PAGES_FOLDER, EXTENSIONS_FOLDER). A custom page's slug and a document's are one pool: no new
+// document takes a page's slug, nor a new page a document's (slugTaken).
 // 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.
 
@@ -50,12 +58,27 @@ export const RESERVED = new Set(["exports", "generated", ...DEVICE_NAMES]);
  * name no new document takes (slugTaken, keptName), the next free one coming instead.
  */
 export const COMPONENTS_FOLDER = "components";
+/**
+ * The folder of a workspace's custom pages (pages/<slug>/: ./pages.mjs). As components/, it hides
+ * nothing: a document called so, made before the custom pages came, keeps its folder and stays a
+ * document beside them; it is only a name no new document or page takes.
+ */
+export const PAGES_FOLDER = "pages";
+/**
+ * The folder of a workspace's extensions (extensions/<id>/: ./extensions.mjs), each of which may provide a
+ * column of the sidebar (sidebar.json) and holds whatever else the extension keeps. As components/ and
+ * pages/, it hides nothing: a document called so, made before extensions came, keeps its folder and stays
+ * a document beside them; it is only a name no new document or page takes.
+ */
+export const EXTENSIONS_FOLDER = "extensions";
 /** 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. */
+/** The folders a document keeps beside its files: what is its own of a folder it shares with the packages or the custom pages. */
 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;
+/** The folders at the root that hold no document but may share their name with one made before them. */
+export const SHARED_FOLDERS = [COMPONENTS_FOLDER, PAGES_FOLDER, EXTENSIONS_FOLDER];
+/** Whether a new document (or custom page) may not be called `name`, whatever the workspace holds. */
+export const keptName = (name) => RESERVED.has(name) || SHARED_FOLDERS.includes(name);
 /** 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). */
@@ -98,6 +121,15 @@ const markerAt = (file) => {
   }
 };
 
+/**
+ * The default workspace, where a command goes when nothing names one and none is found up from the
+ * current folder: Gallery in the user's Documents folder, or the folder GALLERY_DEFAULT_WORKSPACE names
+ * (the browser scenarios', whose studio is the default workspace for a draft made elsewhere: src/shared/drafts.mjs).
+ */
+export const defaultWorkspace = ({ env = process.env, home = os.homedir(), cwd = process.cwd() } = {}) => (env.GALLERY_DEFAULT_WORKSPACE
+  ? path.resolve(cwd, env.GALLERY_DEFAULT_WORKSPACE)
+  : path.join(documentsFolder({ home, env }), "Gallery"));
+
 /**
  * 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).
@@ -109,7 +141,7 @@ export function findWorkspace({ flag = null, env = process.env, cwd = process.cw
     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" };
+  return { root: defaultWorkspace({ env, home, cwd }), how: "default" };
 }
 
 // Where Windows keeps the Documents folder Explorer shows as 文档: the Personal shell folder, as the
@@ -193,14 +225,34 @@ export function layoutOf(root) {
     preferences: path.join(resolved, "preferences.md"),
     exports: path.join(resolved, "exports"),
     components: path.join(resolved, COMPONENTS_FOLDER),
+    // The custom pages (./pages.mjs), at the root as the packages are: the user's and the Agent's. Not
+    // called pages, which named .gallery/pages/ before (preferencesPage now): code written for that
+    // meaning finds no such key and fails, never reading this folder for the 写作偏好 page's.
+    customPages: path.join(resolved, PAGES_FOLDER),
+    // The extensions (./extensions.mjs: extensions/<id>/sidebar.json), the user's and the Agent's.
+    extensions: path.join(resolved, EXTENSIONS_FOLDER),
     gallery,
     outline: path.join(gallery, "outline.json"),
+    blocks: path.join(gallery, "blocks.json"),
+    // What the reader closed of Gallery's own notes, once for the workspace: the home page's first-open
+    // note (src/shared/pages.mjs homeHintClosed).
+    hints: path.join(gallery, "hints.json"),
+    // The keys of the sites the workspace's blocks reach, by host (./net-keys.mjs: gallery block key),
+    // never in gallery.json, whose settings every page is told; and what the net route fetched for them
+    // (./net-cache.mjs), which may be thrown away.
+    keys: path.join(gallery, "keys.json"),
+    netCache: path.join(gallery, "cache", "net"),
     trash: path.join(gallery, "trash"),
     emojiLibrary: path.join(gallery, "emoji-library"),
-    pages: path.join(gallery, "pages"),
+    // The 写作偏好 page's folder (.gallery/pages/<slug>/: a document of Gallery's own, never a custom page).
+    preferencesPage: path.join(gallery, "pages"),
     state,
+    // The workspace's record of edits by day (src/workbench/activity.mjs): what the 编辑热力图 shows; losable.
+    activity: path.join(state, "activity.json"),
     history: path.join(state, "history"),
     qa: path.join(gallery, "qa"),
+    // The scratch copies gallery block try makes a trial on (try-<8 hex>/: ownOrScratch).
+    scratch: path.join(gallery, "try"),
     backups: path.join(gallery, "backups"),
     built: path.join(gallery, "built"),
     logs: path.join(gallery, "logs"),
@@ -252,17 +304,81 @@ export function documentFiles(directory) {
   };
 }
 
-/** Where document `slug` is: the 写作偏好 page's folder under .gallery/pages/ when it is one, else <root>/<slug>. */
+/** Where document `slug` is: the 写作偏好 page's folder under .gallery/pages/ when it is one, else ownOrScratch's. */
 export function documentDirectory(slug, root) {
-  const page = path.join(layoutOf(root).pages, slug);
-  return existsSync(page) ? page : path.join(path.resolve(root), slug);
+  const page = path.join(layoutOf(root).preferencesPage, slug);
+  return existsSync(page) ? page : ownOrScratch(slug, root);
+}
+
+/**
+ * Where document `slug` that is no 写作偏好 page is: <root>/<slug>; or, where no folder at the root has
+ * that name, a scratch copy's in .gallery/try/ (gallery block try's, try-<8 hex>: served and edited
+ * as any document, listed nowhere, and gone once its trial ends, src/cli/component-try.mjs).
+ */
+function ownOrScratch(slug, root) {
+  const own = path.join(path.resolve(root), slug);
+  const copy = path.join(layoutOf(root).scratch, slug);
+  return !existsSync(own) && existsSync(copy) ? copy : own;
 }
 
-/** Whether `slug` can name no new document: a name kept, or held by a folder at the root or a page. */
+/**
+ * Whether `slug` can name no new document or custom page (one pool): a name kept, or held by a folder
+ * at the root, the 写作偏好 page or a custom page (pages/<slug>/).
+ */
 export function slugTaken(slug, root) {
-  return keptName(slug) || existsSync(path.join(path.resolve(root), slug)) || existsSync(path.join(layoutOf(root).pages, slug));
+  const layout = layoutOf(root);
+  return keptName(slug) || [layout.root, layout.preferencesPage, layout.customPages].some((folder) => existsSync(path.join(folder, slug)));
+}
+
+/**
+ * The folder names a page id may come of in a workspace, every one that has an address: a folder at
+ * the root (a document, a web link, whatever else), a custom page's, the 写作偏好 page's, and the slug
+ * of everything in the trash (a document there goes by its id until it is restored).
+ */
+export async function pageNames(root) {
+  const layout = layoutOf(root);
+  const names = new Set();
+  await Promise.all([layout.root, layout.preferencesPage, layout.customPages].map(async (folder) => {
+    for (const entry of await fs.readdir(folder, { withFileTypes: true }).catch(() => [])) if (entry.isDirectory() && !entry.name.startsWith(".")) names.add(entry.name);
+  }));
+  for (const { slug } of await listTrash(root)) if (typeof slug === "string") names.add(slug);
+  return names;
+}
+
+/**
+ * The folder name of a new document: doc-<a new page id> (DOC_SLUG), an id that no name of the
+ * workspace has (pageNames: the hash id of an old name counts as the id of a doc-<id> one, and the
+ * earlier id of a doc-<eight> name, which its old addresses still open), its folder
+ * free (slugTaken: the root, the 写作偏好 page and the custom pages; the trash's slugs are among the
+ * names). `random` is newPageId's, for the tests.
+ * @param {string} root
+ * @param {{ random?: () => number }} [options]
+ */
+export async function newDocSlug(root, { random = undefined } = {}) {
+  const taken = new Set();
+  for (const name of await pageNames(root)) for (const id of [pageId(name), earlierId(name)]) if (id !== null) taken.add(id);
+  for (;;) {
+    const slug = `doc-${newPageId(taken, random)}`;
+    if (!slugTaken(slug, root)) return slug;
+    taken.add(slug.slice(4));
+  }
+}
+
+/**
+ * Another name of the workspace that has the page id of `slug` (pageNames), or null: what makes a
+ * doc-<id> name a document may not take, its id being another's.
+ * @param {string} slug
+ * @param {string} root
+ */
+export async function idHolder(slug, root) {
+  const id = pageId(slug);
+  for (const name of await pageNames(root)) if (name !== slug && pageId(name) === id) return name;
+  return null;
 }
 
+/** Whether `slug` is a name the workbench's new documents have (doc-<eight>: DOC_SLUG), whose id is in it. */
+export const isDocSlug = (slug) => DOC_SLUG.test(slug);
+
 // The folders right in `directory`, by name, sorted: no dot name, and no link, which leads out of it.
 const foldersIn = (directory) => {
   try {
@@ -325,20 +441,55 @@ export async function listDocumentSlugs(root) {
   return (await documentsIn(path.resolve(root))).filter((entry) => !entry.instructions).map((entry) => entry.slug);
 }
 
+/**
+ * The web links of a workspace (./web-links.mjs), by slug, sorted: the folders at its root, named as
+ * documents are, holding a link.json that reads as a link and no doc.html or report.html (a document,
+ * whatever else it holds).
+ */
+export async function listLinkSlugs(root) {
+  const directory = path.resolve(root);
+  const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+  const found = await Promise.all(entries
+    .filter((entry) => entry.isDirectory() && isSlugName(entry.name))
+    .map(async ({ name }) => {
+      const folder = path.join(directory, name);
+      if (existsSync(path.join(folder, NEW.html)) || existsSync(path.join(folder, OLD.html))) return null;
+      return (await readLink(folder)) ? name : null;
+    }));
+  return found.filter(Boolean).sort();
+}
+
+/** The web link of folder `folder` ({ url, title, icon? }), or null where there is none or it does not read. */
+export async function readLink(folder) {
+  const text = await fs.readFile(path.join(folder, LINK_FILE), "utf8").catch(() => null);
+  return text === null ? null : readLinkText(text);
+}
+
 /** 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;
+  return (await documentsIn(layoutOf(root).preferencesPage))[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 }). */
+/**
+ * What a trash entry holds: a document, a custom page (./pages.mjs) or a web link (./web-links.mjs).
+ * An entry written before the custom pages came holds a document.
+ */
+export const TRASH_KINDS = ["document", "page", "link"];
+
+/**
+ * What the trash holds, the latest first: each folder's entry.json ({ id, kind, slug, title, at,
+ * parent, index }), `kind` "document" (its folder report/), "page" (its folder page/, parent "" and
+ * index -1: a custom page has no place in the outline) or "link" (its folder link/); one written before
+ * kinds came is a document's.
+ */
 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);
+  return entries.filter(Boolean).map((entry) => (TRASH_KINDS.includes(entry.kind) ? entry : { ...entry, kind: "document" })).sort((a, b) => b.at - a.at);
 }
 
 // ---------- copying an old layout ----------
@@ -423,8 +574,8 @@ export async function copyOldDocuments({ from, to, state = undefined }) {
     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));
+        await fs.mkdir(layout.preferencesPage, { recursive: true });
+        await copyTree(folder, path.join(layout.preferencesPage, slug));
         page = "copied";
       }
       continue;
@@ -514,7 +665,7 @@ export async function adoptOldLayout(root, { devState = null } = {}) {
   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 (oldPage && !(await pageSlug(layout.root))) await once("page", oldPage.folder, path.join(layout.preferencesPage, oldPage.slug));
 
   if (devState && (await isFolder(devState))) {
     const slugs = [...(await listDocumentSlugs(layout.root)), ...(oldPage ? [oldPage.slug] : [])];

package/dist/chunk-2OHANJ6Q.mjs

@@ -0,0 +1,2 @@
+import { createRequire as __galleryRequire } from "node:module"; import { fileURLToPath as __galleryPath } from "node:url"; const require = __galleryRequire(import.meta.url); const __filename = __galleryPath(import.meta.url); const __dirname = __galleryPath(new URL(".", import.meta.url));
+import{constants as G}from"node:buffer";import E from"node:fs";import{Transform as H}from"node:stream";import{pipeline as P}from"node:stream/promises";import b from"node:zlib";import{refusal as k,said as M}from"../browser/shared/i18n/index.mjs";var A=67324752,Z=33639248,F=101010256,W=101075792,X=117853008,U=4294967295,T=2048;function v(t=new Date){let o=t.getHours()<<11|t.getMinutes()<<5|Math.floor(t.getSeconds()/2),e=Math.max(1980,t.getFullYear())-1980<<9|t.getMonth()+1<<5|t.getDate();return[o,e]}function tt(t){let[o,e]=v(),c=[],h=[],n=0;for(let a of t){let s=Buffer.isBuffer(a.data)?a.data:Buffer.from(a.data??"","utf8"),r=Buffer.from(a.name,"utf8"),u=s.length>64?b.deflateRawSync(s):null,w=u&&u.length<s.length?u:s,L=w===s?0:8,g=b.crc32(s);if(s.length>=U||n>=U)throw new Error("\u538B\u7F29\u5305\u592A\u5927\uFF08\u8D85\u8FC7 4GB\uFF09");let l=Buffer.alloc(30);l.writeUInt32LE(A,0),l.writeUInt16LE(20,4),l.writeUInt16LE(T,6),l.writeUInt16LE(L,8),l.writeUInt16LE(o,10),l.writeUInt16LE(e,12),l.writeUInt32LE(g,14),l.writeUInt32LE(w.length,18),l.writeUInt32LE(s.length,22),l.writeUInt16LE(r.length,26),l.writeUInt16LE(0,28);let d=Buffer.alloc(46);d.writeUInt32LE(Z,0),d.writeUInt16LE(20,4),d.writeUInt16LE(20,6),d.writeUInt16LE(T,8),d.writeUInt16LE(L,10),d.writeUInt16LE(o,12),d.writeUInt16LE(e,14),d.writeUInt32LE(g,16),d.writeUInt32LE(w.length,20),d.writeUInt32LE(s.length,24),d.writeUInt16LE(r.length,28),d.writeUInt32LE(n,42),c.push(l,r,w),h.push(d,r),n+=l.length+r.length+w.length}if(t.length>=65535)throw new Error("\u538B\u7F29\u5305\u91CC\u7684\u6587\u4EF6\u592A\u591A");let i=Buffer.concat(h),f=Buffer.alloc(22);return f.writeUInt32LE(F,0),f.writeUInt16LE(t.length,8),f.writeUInt16LE(t.length,10),f.writeUInt32LE(i.length,12),f.writeUInt32LE(n,16),Buffer.concat([...c,i,f])}var Y=new TextDecoder("utf-8",{fatal:!0}),j=new TextDecoder("gbk");function q(t,o){if(o&T)return t.toString("utf8");try{return Y.decode(t)}catch{return j.decode(t)}}var et=t=>t.length>=4&&t.readUInt32LE(0)===A,m=()=>new Error("ZIP \u6587\u4EF6\u5DF2\u635F\u574F"),I=(t,o)=>Number(t.readBigUInt64LE(o));function N(t,o){let e=Math.min(o,65557),c=t(o-e,e),h=-1;for(let r=c.length-22;r>=0;r-=1)if(c.readUInt32LE(r)===F){h=r;break}if(h<0)throw new Error("\u4E0D\u662F\u6709\u6548\u7684 ZIP \u6587\u4EF6");let n=c.readUInt16LE(h+10),i=c.readUInt32LE(h+12),f=c.readUInt32LE(h+16);if(n===65535||i===U||f===U){let r=t(o-e+h-20,20);if(r.readUInt32LE(0)!==X)throw m();let u=t(I(r,8),56);if(u.readUInt32LE(0)!==W)throw m();n=I(u,32),i=I(u,40),f=I(u,48)}let a=t(f,i),s=[];for(let r=0,u=0;u<n;u+=1){if(a.readUInt32LE(r)!==Z)throw m();let w=a.readUInt16LE(r+8),L=a.readUInt16LE(r+10),g=a.readUInt32LE(r+20),l=a.readUInt32LE(r+24),d=a.readUInt16LE(r+28),D=a.readUInt16LE(r+30),_=a.readUInt16LE(r+32),R=a.readUInt32LE(r+42),B=q(a.subarray(r+46,r+46+d),w),p=a.subarray(r+46+d,r+46+d+D);for(let x=0;x+4<=p.length;x+=4+p.readUInt16LE(x+2)){if(p.readUInt16LE(x)!==1)continue;let z=x+4;l===U&&(l=I(p,z),z+=8),g===U&&(g=I(p,z),z+=8),R===U&&(R=I(p,z))}if(r+=46+d+D+_,!B.endsWith("/")){if(w&1)throw k(M("{0} \u5DF2\u52A0\u5BC6",B));if(L!==0&&L!==8)throw k(M("{0}\uFF1A\u4E0D\u652F\u6301\u7684\u538B\u7F29\u65B9\u5F0F",B));s.push({name:B,method:L,packedSize:g,size:l,local:R})}}return s}var S=t=>k(M("{0}\uFF1A\u5927\u5C0F\u4E0D\u7B26",t.name),{code:"size"});function C(t,o){try{return b.inflateRawSync(t,{maxOutputLength:Math.min(G.MAX_LENGTH,Math.max(1,o.size))})}catch(e){throw e?.code==="ERR_BUFFER_TOO_LARGE"?S(o):e}}function O(t,o){let e=t(o.local,30);if(e.readUInt32LE(0)!==A)throw m();return o.local+30+e.readUInt16LE(26)+e.readUInt16LE(28)}function nt(t){let o=(e,c)=>{if(e<0||e+c>t.length)throw m();return t.subarray(e,e+c)};return N(o,t.length).map(e=>{let c=o(O(o,e),e.packedSize),h=e.method===0?Buffer.from(c):C(c,e);if(h.length!==e.size)throw S(e);return{name:e.name,data:h}})}function rt(t){let o=E.openSync(t,"r"),e=E.fstatSync(o).size,c=(n,i)=>{if(n<0||n+i>e)throw m();let f=Buffer.alloc(i);for(let a=0;a<i;){let s=E.readSync(o,f,a,i-a,n+a);if(s===0)throw m();a+=s}return f},h;try{h=N(c,e)}catch(n){throw E.closeSync(o),n}return{entries:h,read(n){let i=c(O(c,n),n.packedSize),f=n.method===0?i:C(i,n);if(f.length!==n.size)throw S(n);return f},async extract(n,i){let f=O(c,n);if(n.packedSize===0)await E.promises.writeFile(i,"");else{let a=E.createReadStream(t,{start:f,end:f+n.packedSize-1}),s=0,r=new H({transform(u,w,L){s+=u.length,L(s>n.size?S(n):null,u)}});await P(...n.method===0?[a]:[a,b.createInflateRaw()],r,E.createWriteStream(i))}if((await E.promises.stat(i)).size!==n.size)throw S(n)},close:()=>E.closeSync(o)}}export{tt as a,et as b,nt as c,rt as d};