@heycys/gallery 0.1.1 → 0.1.2

package/browser/shared/components/index.mjs

@@ -137,9 +137,16 @@ export const EVENTS = {
   "doc-theme-request": "a workbench asks for a theme (ui.js listens)",
   "doc-look-request": "the document's look is asked of the page (字体与布局: the page's session for the workbench, the preview's live reload for doc.json written again; ui.js puts it on <html>, src/shared/document-look.mjs)",
   "doc-look-change": "the look the page shows changed (ui.js): the page editor's session tells the workbench",
-  "doc-layout-change": "a card's size changed where widths do not tell (the editor), or the document's look changed (ui.js)",
+  "doc-layout-change": "a card's size changed where widths do not tell (the editor, a custom page's canvas), or the document's look changed (ui.js)",
+  "doc-workspace-change": "what the workspace holds changed, the kind its detail (the page's live script, as the server's \"data <kind>\" says it): the kit tells the instances that hear data and read that kind",
+  "doc-todo-set": "a block's context.workspace.setTodo asks whoever shows the page to check a to-do of a document (cancelable: a custom page's board or a document's editor cancels it and answers from the workspace's service)",
+  "doc-open-request": "a block's context.workspace.open asks to open a document or a custom page (cancelable: the page's session for the workbench answers it, else the kit goes there)",
   "doc-editable": "the page takes what a component writes from now on (the editor)",
   "doc-component-edit": "a component's context.edit asks to write a part: the editor cancels it to say it took the edit, the kit writing no file (on the instance)",
+  "doc-table-intent": "a view's context.table() asks to change the table it reads (set a cell, move, add or take out a row), or whether it would take such a change now (canEdit, op check): the editor cancels it to say it made the change (or would), one undo step, the kit writing nothing (on the instance)",
+  "doc-settings-changed": "what gallery.json says of the components changed (the page's event stream, its settings line: hidden, disabled, shown, the consents to the net, unlisted and the packs off): the editor's menus follow it, and the kit starts again an instance whose block's consent changed (runtime/net.js)",
+  "doc-net-fetch": "a block's context.fetch asks whoever serves the page to fetch for it (runtime/net.js sends it; the server's live script cancels it and answers from its net route)",
+  "doc-net-consent": "a block's 允许访问 asks the reader to let it online (runtime/net.js sends it; the page's session cancels it and the workbench opens its consent dialog)",
   "doc-export-copy-done": "导出当前视图副本 finished (ui.js)",
   "doc-table-sort": "a table's sort changed (tables/, on the table)",
   "doc-jump-request": "演示视图 asks the kit to go to a block of its own page, a step of the history (runtime/reveal.js listens, editor/page/present-links.mjs sends)",
@@ -171,9 +178,11 @@ export const FLOW_BLOCKS = `${FLOWS.join(", ")}, :is(${GROUPING_FLOWS.join(", ")
  * What the kit's runtime reads of the descriptions (runtime/kernel.js): where each component's
  * instances are (`match`) and what it leaves on the page (`runtime`), of the components that say
  * either. /kit/runtime.js carries these alone (assets.mjs, `define`), so an export holds no prose.
- * A field the kernel starts reading is added to RUNTIME_FIELDS (tests/unit/runtime.mjs checks it).
+ * A field the kernel starts reading is added to RUNTIME_FIELDS (tests/unit/runtime.mjs checks it):
+ * `needs`, what a custom block uses (its context.workspace), which only a package describes (no
+ * component of the kit has it, so the runtime carries none).
  */
-export const RUNTIME_FIELDS = ["match", "runtime", "schema"];
+export const RUNTIME_FIELDS = ["match", "runtime", "schema", "needs"];
 export const runtimeDescriptions = (components = COMPONENTS) => components
   .filter((component) => RUNTIME_FIELDS.some((field) => component[field] !== undefined))
   .map((component) => Object.fromEntries([["id", component.id], ...RUNTIME_FIELDS.filter((field) => component[field] !== undefined).map((field) => [field, component[field]])]));

package/browser/shared/components/installed.mjs

@@ -50,6 +50,19 @@ export function heldBy(node) {
   return owner !== null && edgeAround(edge) === owner ? null : owner;
 }
 
+/**
+ * The region what an element holds stands in (its children, its words): the instance itself for an
+ * instance, the document's (null) inside a slot that opens it again, and otherwise the region the
+ * element stands in, as heldBy says it. heldBy for a child the element does not have yet, or has lost:
+ * where a change of what it holds happened.
+ */
+export function heldWithin(element) {
+  if (!element.matches(REGION)) return heldBy(element);
+  const owner = heldBy(element);
+  if (element.matches(INSTANCE)) return owner ?? element;
+  return owner !== null && edgeAround(element) === owner ? null : owner;
+}
+
 /** Whether an element is a slot that opens the document's region again: one of an instance that stands in the document's. */
 const opensDocument = (node) => node.matches(SLOT_PART) && heldBy(node) !== null && edgeAround(node) === heldBy(node);
 
@@ -110,8 +123,24 @@ export const PACKAGE_MARK = "data-doc-package";
  */
 export const ARRIVING = "data-ge-arriving";
 
-/** What gallery.json's lists make of a package that loads: "disabled", "hidden" or "normal". */
-export const settingState = (id, { hidden, disabled }) => (disabled.includes(id) ? "disabled" : hidden.includes(id) ? "hidden" : "normal");
+/**
+ * Whether the document's insert entries ("/", 在下方新建, the handle's grid, a table's 视图 ›) offer the
+ * block `id` whose manifest's `places` are those (left out: ["document"]), by gallery.json's lists
+ * (`settings`: hidden, shown, disabled, unlisted, packsOff, each left out for none): one that says it stands in a
+ * document is offered unless hidden; one that does not, only where shown; one disabled never, as it does
+ * not load, nor one unlisted (设置 › 组件列表's master switch off: no menu and no library offers it, what
+ * is written of it shows as ever), nor one of a pack switched off (packsOff, the ids of the packs off: the
+ * scope of its id; the same as unlisted, for a whole pack). The one rule, which the server and the page
+ * both run (notes/plans/custom-blocks-spec-2026-11-07.md section 2, block-packs-plan-2026-11-09.md §1).
+ */
+export function inDocumentMenus(places, settings, id) {
+  const { hidden = [], shown = [], disabled = [], unlisted = [], packsOff = [] } = settings ?? {};
+  if (disabled.includes(id) || unlisted.includes(id) || packsOff.includes(String(id).split("/")[0])) return false;
+  return (places ?? ["document"]).includes("document") ? !hidden.includes(id) : shown.includes(id);
+}
+
+/** What gallery.json's lists make of a package that loads, its manifest's `places` with them: "disabled", "hidden" (no document's menu offers it: inDocumentMenus, which a block unlisted is too) or "normal". */
+export const settingState = (id, settings, places) => (settings.disabled.includes(id) ? "disabled" : inDocumentMenus(places, settings, id) ? "normal" : "hidden");
 
 /** The class of the kit's note in such an instance, in a preview alone. */
 export const NOTE = "doc-component-note";
@@ -223,10 +252,13 @@ export default {
     "data-doc-component": "the package an instance is of: <scope>/<name>, on a block-level div or section",
     "data-doc-schema": "the shape an instance holds its content in: a whole number its component chooses, read-only past its manifest's schema",
     "data-doc-slot": "a slot of an instance: the part of its manifest edited as flow, by name, on a block-level div or section in the instance's own region; what it holds is the document's blocks",
+    "data-doc-from": "on an instance of a custom block whose needs hold tables: the key of the table it is a view of, which the table's frame carries as data-doc-chart-source",
   },
   runtime: {
     generated: [".doc-component-note", ".doc-component-data"],
     attrs: { "[data-doc-fallback]": ["data-doc-fallback"], "[data-doc-fallback-control]": ["data-doc-fallback-control", "inert"] },
-    internal: [PACKAGE_MARK, "doc-component-more", DATA_ONE, DATA_LINE, DATA_SHORT], // of what the kit drew of a script of data: a line saying what it left out, and its marks
+    // Of what the kit drew of a script of data: a line saying what it left out, and its marks; and the mark
+    // DocKit.drag (runtime/gestures.js) puts on what a component draws while it is dragged, a class.
+    internal: [PACKAGE_MARK, "doc-component-more", DATA_ONE, DATA_LINE, DATA_SHORT, "doc-dragging"],
   },
 };

package/browser/shared/components/page.mjs

@@ -15,10 +15,12 @@ export function pageLanguage(html) {
 
 /**
  * A document's look on its <html> (字体与布局: its doc.json's look, which the render puts on and the kit's
- * tokens read; src/shared/document-look.mjs), the attribute of each choice. The width's is
- * data-doc-measure (a column's measure, its line length): data-doc-width is the reader's own 全宽.
+ * tokens read; src/shared/document-look.mjs), the attribute of each choice. The 正文宽度's is
+ * data-doc-measure (a column's measure, its line length); 全宽 (the top bar's 更多, under 目录) is
+ * data-doc-width="full", the one attribute the kit's page, the editor's room and the display menu's
+ * 全宽显示 (the reader's own switch in an export) all read: one way to be wide, not two.
  */
-export const LOOK_ATTRIBUTES = Object.freeze({ font: "data-doc-font", size: "data-doc-size", spacing: "data-doc-spacing", width: "data-doc-measure" });
+export const LOOK_ATTRIBUTES = Object.freeze({ font: "data-doc-font", size: "data-doc-size", spacing: "data-doc-spacing", width: "data-doc-measure", full: "data-doc-width" });
 
 export default {
   id: "page",
@@ -37,10 +39,18 @@ export default {
   classes: ["doc-page", "doc-header", "doc-kicker", "doc-title", "doc-button"],
   runtime: {
     generated: [".doc-display", "script[data-doc-state]"],
-    root: { attrs: ["data-doc-ready", "data-doc-drawn", "data-doc-controls"] },
-    // The reader's theme and width (ui.js), and the document's look (字体与布局: its doc.json's, put on by
-    // the render, src/shared/document-look.mjs), which a copy of the view keeps; never written in doc.html.
-    state: { html: ["data-doc-theme", "data-doc-width", ...Object.values(LOOK_ATTRIBUTES)] },
-    internal: ["doc-display*", "data-doc-export-copy", "data-theme", "doc-export-id", "doc-reveal", "doc-kit-error"],
+    // data-doc-effective-theme: the theme the page shows now (ui.js), "light" or "dark", which a custom page's own colors go by.
+    // data-doc-platform: "mac" on an Apple platform (runtime/index.js sets it as the page opens), the text's color and smoothing go by it; a copy of the view lets it go, its reader's machine judges anew.
+    root: { attrs: ["data-doc-ready", "data-doc-drawn", "data-doc-controls", "data-doc-effective-theme", "data-doc-platform"] },
+    // The reader's theme (ui.js) and the document's look (字体与布局 and 全宽: its doc.json's, put on by
+    // the render, src/shared/document-look.mjs; the reader's own 全宽显示 is the same data-doc-width), which
+    // a copy of the view keeps; never written in doc.html.
+    state: { html: ["data-doc-theme", ...Object.values(LOOK_ATTRIBUTES)] },
+    internal: ["doc-display*", "data-doc-export-copy", "data-theme", "doc-export-id", "doc-reveal", "doc-kit-error", "doc-net-consent*", "data-doc-snapshot",
+      // The time an export's snapshot was made (its data-doc-snapshot tag's: render/net-snapshot.mjs), which context.workspace.query answers as `at`.
+      "data-at",
+      // A custom page's (no document's: src/render/page-html.mjs, the kit's board/): its cards' cells, the Agent's
+      // (data-x, data-y, data-w, data-h), and its boards' columns now (data-columns, board.js's).
+      "data-x", "data-y", "data-w", "data-h", "data-columns"],
   },
 };

package/browser/shared/components/state.mjs

@@ -2,7 +2,9 @@
 // a key (data-doc-bind), elements shown for a key's value (data-doc-show),
 // keys forgotten when the page is left (data-doc-transient); and the kit's styles of such
 // controls (styles/state.css). A filter (.doc-filter) is one block: its row of buttons and what
-// they filter below it (a list, say), together.
+// they filter below it (a list, say), together. A <select> of any control or block, bound or not, opens
+// the kit's menu of choices (runtime/choice.js, styles/choice.css), never the browser's popup: a card at
+// the end of <body> while it is open, nothing an author writes, which an export of the view leaves out.
 export default {
   id: "state",
   match: "[data-doc-bind], [data-doc-show]",
@@ -14,7 +16,9 @@ export default {
   classes: ["doc-state-fields", "doc-state-field", "doc-state-actions", "doc-filter", "doc-filter-row", "doc-filter-button", "doc-state-list"],
   wholes: ["doc-filter", "doc-filter-row", "doc-state-fields", "doc-state-list"], // the classes above that are a whole block of their own (the others are parts inside one)
   runtime: {
+    generated: [".doc-choice"],
     attrs: { "[data-doc-show]": ["hidden"] },
     state: { "button[data-doc-bind]": ["aria-pressed"] },
+    internal: ["doc-choice-*"], // the menu's rows, their words, the check and the group headings
   },
 };

package/browser/shared/document-look.mjs

@@ -1,13 +1,15 @@
-// A document's look (字体与布局, under the workbench's 更多: Notion's page format, notion-lite's
-// view/frame/page-format.js): its font, the size of its text, the spacing of its lines and blocks and
-// the width of its reading column. The document's own, as Notion keeps it on the page: `look` in its
+// A document's look (字体与布局 and 全宽, under the workbench's 更多: Notion's page format, notion-lite's
+// view/frame/page-format.js, whose page_full_width is a field of the page as ours is of the document):
+// its font, the size of its text, the spacing of its lines and blocks, the width of its reading column
+// and whether it is shown at the full width of the page whatever that is (全宽). The document's own, as
+// Notion keeps it on the page: `look` in its
 // doc.json (report.json in a document made before Gallery 0.1), over the workspace's default look,
 // `look` in its gallery.json (which the card's 应用到全部文档 writes, every document's own taken away:
 // ./workspace-look.mjs), choice by choice (effectiveLook). The workspace's keeps each choice that is
 // not the default, the field gone when none is; a doc.json each choice that is not the workspace's,
 // the field gone when none is:
 //
-//   "look": { "font": "serif" | "mixed", "size": "small" | "large", "spacing": "compact" | "loose", "width": "narrow" | "wide" }
+//   "look": { "font": "serif" | "mixed", "size": "small" | "large", "spacing": "compact" | "loose", "width": "narrow" | "wide", "full": "full" }
 //
 // A doc.json may say a default too ("font": "sans", "size": "default"…): 默认 chosen on a page while
 // the workspace's default says otherwise. The look a document shows is never written in doc.html: the
@@ -26,6 +28,9 @@ export const LOOK = Object.freeze({
   size: Object.freeze(["default", "small", "large"]), // 字体大小: 小号, 默认, 大号
   spacing: Object.freeze(["default", "compact", "loose"]), // 正文间距: 紧凑, 默认, 宽松
   width: Object.freeze(["default", "narrow", "wide"]), // 正文宽度: 偏窄, 默认, 偏宽
+  // 全宽 (the 更多 menu's switch under 目录): the page at the full width of its area, whatever its 正文宽度 is; its attribute is
+  // the kit's own data-doc-width="full", the reader's display menu's 全宽显示 too (components/page.mjs LOOK_ATTRIBUTES)
+  full: Object.freeze(["default", "full"]),
 });
 
 /** The attribute each choice is on <html> by: the page's description says them (components/page.mjs). */
@@ -80,7 +85,7 @@ export function lookOf(value) {
   return look;
 }
 
-/** Each choice of a look, the default where it makes none: { font, size, spacing, width }. */
+/** Each choice of a look, the default where it makes none: { font, size, spacing, width, full }. */
 export const fullLook = (value) => ({ ...Object.fromEntries(Object.entries(LOOK).map(([key, [first]]) => [key, first])), ...lookOf(value) });
 
 /** Whether two looks are the same. */

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);