@heycys/gallery 0.1.2 → 0.2.1

package/browser/shared/outline.mjs

@@ -3,10 +3,53 @@ 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 { shownWorkspaces, snapshotOf } from "./workspace-columns.mjs";
-import { layoutOf, listDocumentSlugs, listLinkSlugs, pageSlug } from "./workspace.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 { forgetSnapshot, shownWorkspaces, snapshotOf } from "./workspace-columns.mjs";
+import { defaultWorkspace, layoutOf, listDocumentSlugs, listLinkSlugs, pageSlug } from "./workspace.mjs";
+import { readRegistry, workspaceId, workspaceKey } from "./workspace-registry.mjs";
 
+/** Registered workspaces share the default workspace's existing tree. Unregistered/temporary
+ * workspaces remain standalone; no registry discovery or copying of document files is needed. */
+export function outlineRoot(root) {
+  const home = defaultWorkspace();
+  return workspaceKey(root) === workspaceKey(home) || readRegistry().workspaces.some(entry => workspaceKey(entry.root) === workspaceKey(root)) ? home : root;
+}
+
+export const sharedOutline = root => workspaceKey(outlineRoot(root)) === workspaceKey(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. Project-only extensions keep local positions.
 // 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:
@@ -38,6 +81,9 @@ import { layoutOf, listDocumentSlugs, listLinkSlugs, pageSlug } from "./workspac
 // got yet comes last (not written until the outline is), one whose extension is gone drops out, and what an
 // outline says of its entries is passed over (an extension's entries are its own, never the outline's).
 // Their place is what the outline keeps of them.
+// The file also keeps the order of the sidebar's head rows (`head`: 新建, 搜索 and the custom pages,
+// ./sidebar-head.mjs), which only a drag of a head row and a new page write (writeHead), and every write
+// of the tree keeps as it was (writeOutline).
 // Written by the workspace's server (src/workbench/service.mjs: the workbench's moves and columns, a new,
 // copied, restored or imported document, a new link, gallery new --under, gallery move and gallery link
 // add while it runs, in the queue its saves go through), and by a gallery command when no server runs
@@ -52,10 +98,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")}`;
@@ -67,13 +113,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 });
   }
@@ -94,7 +144,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)) })));
 }
@@ -109,14 +160,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 })),
@@ -124,6 +177,54 @@ 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, { first = false } = {}) {
+  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;
+  });
+  if (first) groups = [...groups.filter(group => group.id === DOCS), ...groups.filter(group => group.id !== DOCS)];
+  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: sharedOutline(root) });
+  // 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, { first: true });
+  // A project's extensions remain private; public ones still come from the default workspace.
+  outline.groups = withExtensions(outline.groups, await extensionColumnIds(root));
+  const publicIds = new Set(await extensionColumnIds(home));
+  const positions = (await readJson(layoutOf(root).outline))?.extensionPositions;
+  for (const position of Array.isArray(positions) ? [...positions].reverse() : []) {
+    const group = outline.groups.find(group => group.id === position.id && group.extension && !publicIds.has(group.extension));
+    if (!group) continue;
+    outline.groups = outline.groups.filter(item => item !== group);
+    const at = outline.groups.findIndex(item => item.id === position.before);
+    outline.groups.splice(at < 0 ? outline.groups.length : at, 0, group);
+  }
+  outline.children = Object.fromEntries(Object.entries(outline.children).filter(([key]) => !isTop(key) || outline.groups.some(group => topOf(group.id) === key)));
+  for (const group of outline.groups) outline.children[topOf(group.id)] ??= [];
+  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, { first: true }), 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.
@@ -137,6 +238,8 @@ const OLD_DOCS_NAMES = ["文档", "Documents"];
  */
 export function storedOf(file) {
   if (!file || typeof file !== "object" || Array.isArray(file)) return null;
+  // A file that holds the head's order alone (writeHead's, before any tree was written) holds no tree.
+  if (!Object.hasOwn(file, "children") && !Object.hasOwn(file, "groups")) return null;
   const groups = [];
   const children = {};
   const take = (id, own) => {
@@ -367,11 +470,60 @@ export function fileOf(value) {
   };
 }
 
-/** Write outline `value` ({ groups?, children }) of workspace `root` (.gallery/ made when there is none yet). */
+/**
+ * Write outline `value` ({ groups?, children }) of workspace `root` (.gallery/ made when there is none yet),
+ * the head's order the file holds kept as it is (writeHead's).
+ */
 export async function writeOutline(root, value) {
+  const home = outlineRoot(root);
+  if (sharedOutline(root) && !ownsOutline(root, value)) throw Object.assign(new Error("跨工作区请复制，不能只移动目录位置"), { code: "CROSS_WORKSPACE" });
+  if (sharedOutline(root)) 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)) {
+    const current = (await localOutlineAndFile(home)).outline;
+    const translated = projectTree(value, root, home);
+    // The current-column-first projection is presentation only. Keep the shared column order;
+    // deliberate moves of other columns use the relative order submitted by the client.
+    const ownId = workspaceId(root);
+    const at = current.groups.findIndex(group => group.workspace === ownId);
+    const own = translated.groups.find(group => group.workspace === ownId);
+    translated.groups = translated.groups.filter(group => group !== own);
+    if (own) translated.groups.splice(Math.max(0, Math.min(at, translated.groups.length)), 0, own);
+    const publicIds = new Set(await extensionColumnIds(home));
+    const privateGroup = group => group.extension && !publicIds.has(group.extension);
+    const positions = value.groups.filter(privateGroup).map(group => ({ id: group.id, before: value.groups.slice(value.groups.indexOf(group) + 1).find(group => !privateGroup(group))?.id ?? null }));
+    const localFile = layoutOf(root).outline;
+    const local = await readJson(localFile) ?? {};
+    if ((positions.length || local.extensionPositions?.length) && JSON.stringify(positions) !== JSON.stringify(local.extensionPositions)) {
+      await fs.mkdir(path.dirname(localFile), { recursive: true });
+      await writeAtomic(localFile, `${JSON.stringify({ ...local, extensionPositions: positions }, null, 2)}\n`);
+    }
+    translated.groups = translated.groups.filter(group => !group.extension || publicIds.has(group.extension));
+    for (const group of current.groups) if (group.extension && !translated.groups.some(item => item.id === group.id)) translated.groups.push(group);
+    value = translated;
+    root = home;
+  }
+  const file = layoutOf(root).outline;
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const head = storedHead((await readJson(file))?.head);
+  return writeAtomic(file, `${JSON.stringify({ ...fileOf(value), ...(head ? { head } : {}) }, null, 2)}\n`);
+}
+
+/** The head's order as workspace `root`'s outline file keeps it (./sidebar-head.mjs storedHead), or null where it keeps none. */
+export async function readStoredHead(root) {
+  return storedHead((await readJson(layoutOf(root).outline))?.head);
+}
+
+/**
+ * Write the head's order `head` (a stored head: ./sidebar-head.mjs) into workspace `root`'s outline file,
+ * all else it holds as it was (a file there is none of yet holds it alone, which reads as no tree:
+ * storedOf). Run under the outline's lock (withOutlineLock), as every write of the file is.
+ */
+export async function writeHead(root, head) {
   const file = layoutOf(root).outline;
   await fs.mkdir(path.dirname(file), { recursive: true });
-  return writeAtomic(file, `${JSON.stringify(fileOf(value), null, 2)}\n`);
+  const value = await readJson(file);
+  const kept = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  return writeAtomic(file, `${JSON.stringify({ ...kept, head: storedHead(head) ?? [] }, null, 2)}\n`);
 }
 
 /** The key `slug` sits under in `children` (a column's top key at a top level), or null when the outline holds it not. */
@@ -437,6 +589,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 && sharedOutline(root) && !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/pack-manifest.mjs

@@ -23,9 +23,20 @@ export const PACK_FILE = "pack.json";
 /** What a pack's id, a scope, may be: as a block id's scope (shared/components/installed.mjs PACKAGE_ID). */
 export const PACK_ID = /^[a-z0-9][a-z0-9-]*$/;
 
-/** The scope a block of the workspace's own is in (gallery block new local/<name>, or a <name> alone), which no pack takes. */
+/**
+ * The scope a block of the workspace's own is in (gallery block new local/<name>, or a <name> alone), which
+ * no pack installed takes: the default pack (默认块包, DEFAULT_PACK), where an Agent's block goes when it
+ * names no pack, so that a single block needs no pack of its own. It has no pack.json (none may name it):
+ * its name and words are these, and 设置 › 组件列表 lists it first, its blocks or none (shared/block-packs.mjs).
+ */
 export const OWN_SCOPE = "local";
 
+/** What the default pack (OWN_SCOPE's) is called and says of itself, in both languages. */
+export const DEFAULT_PACK = Object.freeze({
+  name: Object.freeze({ zh: "默认块包", en: "Default pack" }),
+  description: Object.freeze({ zh: "Agent 写自定义块时没有指定块包，块就放在这里。只写一个块，不用另建块包。", en: "Where an Agent's custom block goes when it names no pack: a single block needs no pack of its own." }),
+});
+
 const FIELDS = ["id", "name", "description", "version", "author", "homepage", "icon"];
 const VERSION = /^\d+\.\d+\.\d+$/;
 const isTable = (value) => typeof value === "object" && value !== null && !Array.isArray(value);

package/browser/shared/pages.mjs

@@ -6,36 +6,49 @@ import { isDeepStrictEqual } from "node:util";
 import { escapeMarkup, escapeText } from "./escape.mjs";
 import { writeAtomic } from "./files.mjs";
 import { laidOut } from "./json-layout.mjs";
+import { readStoredHead, withOutlineLock, writeHead } from "./outline.mjs";
+import { newPageId } from "./page-links.mjs";
+import { headOrder, headPage, headWithPage } from "./sidebar-head.mjs";
 import { DOCUMENT_FOLDERS, isSlugName, keptName, layoutOf, listTrash, markerOf, slugPattern, slugTaken } from "./workspace.mjs";
 
 // A workspace's custom pages (自定义页: notes/plans/component-pages-plan-2026-11-07.md §5, the spec
 // custom-blocks-spec-2026-11-07.md §5): a page is a folder pages/<slug>/ at the workspace's root, as
-// components/ is, holding page.html (the page an Agent writes: its head, its look, and one or more
-// boards, <div class="gallery-board">, of cards, each <section class="gallery-card" data-card-id
-// data-x data-y data-w data-h> around one instance of a custom block) and page.json ({ title, icon }).
-// Only an Agent makes one (gallery page new); the workbench lists them under 新建 and 搜索, shows one
-// at #@<slug> and renames or trashes it (src/workbench/service.mjs). A page's slug and a document's
-// are one pool (./workspace.mjs slugTaken): no new document takes a page's, nor a new page a
-// document's, and `pages` is a name no new document takes. A page writes no script of its own: the
-// blocks' scripts and styles are put in by the server as it shows it (src/render/page-html.mjs).
-// The home page is pages/home, listed first: the default one (首页, HOME_TITLE, holding a card of each
-// of HOME_CARDS) is made once per workspace by src/editor/home-page.mjs, as the server starts and by
-// gallery init, and gallery.json's pages.homeMade says it was (markHomeMade); nothing makes it again.
-// Node's built-ins only, but ./escape.mjs, ./files.mjs, ./json-layout.mjs and ./workspace.mjs.
+// components/ is, holding page.html (the page an Agent writes, free HTML: its head, its look, its own
+// scripts and frames, and where it wants them one or more boards, <div class="gallery-board">, of
+// cards, each <section class="gallery-card" data-card-id data-x data-y data-w data-h> around one
+// instance of a custom block) and page.json ({ title, icon, defaultCards?, hint? }: pageMetaOf). An Agent
+// makes one (gallery page new), and the workbench's 新建页面 a blank one (blankPageHtml) for an Agent to
+// write; the workbench lists them in the sidebar's head with 新建 and 搜索, in the order the reader drags
+// them to (./sidebar-head.mjs, kept in the outline file), shows one at #@<slug> and renames or trashes
+// it (src/workbench/service.mjs). A page's slug and a document's are one pool (./workspace.mjs
+// slugTaken): no new document takes a page's, nor a new page a document's, and `pages` is a name no new
+// document takes. The blocks' scripts and styles are put in by the server as it shows a page
+// (src/render/page-html.mjs).
+// No page is special by its slug. The default home page (首页, HOME_TITLE, at pages/home, holding a card of
+// each of HOME_CARDS) is a page like any other, made once per workspace by src/editor/home-page.mjs, as
+// the server starts and by gallery init (gallery.json's pages.homeMade says it was: markHomeMade; nothing
+// makes it again), whose page.json says what any page's may: it has the default cards (defaultCards:
+// 恢复默认卡片 in its menu, the note of the default cards it has not got), and its first-open note
+// (hint, until the reader closes it: pageHintClosed).
+// Node's built-ins only, but ./escape.mjs, ./files.mjs, ./json-layout.mjs, ./outline.mjs, ./sidebar-head.mjs
+// and ./workspace.mjs.
 
 /** A custom page's two files. */
 export const PAGE_FILES = { html: "page.html", json: "page.json" };
-/** The home page's slug (首页): listed first, never trashed. */
+/** The slug of the default home page (首页), which src/editor/home-page.mjs makes: a page as any other. */
 export const HOME = "home";
 /** The default home page's title. */
 export const HOME_TITLE = "首页";
 /**
- * The blocks of the default home page's cards (the plan's §5.2: 问候与日期, 便签, 我的待办, 最近编辑, 工作区统计,
- * 编辑热力图), in the order they are placed, each at the first free spot by its default size (a home of
- * 12 x 6 cells, none left empty: shared/board-places.mjs freeSpot); 恢复默认卡片 (the page service's
- * restore-defaults) puts back those of them no card of the home page holds.
+ * The blocks of the default home page's cards (the plan's §5.2, laid out as the pack Gallery 风格's home page,
+ * notes/plans/block-packs-plan-2026-11-09.md §3: 问候与日期, 天气, 倒计时, 习惯打卡, 工作区统计, 我的待办, 编辑热力图,
+ * 最近编辑, 便签, 静态卡片), in the order they are placed, each at the first free spot by its size (HOME_SIZES',
+ * else its block's default: shared/board-places.mjs freeSpot), a home of 12 x 12 cells, none left empty;
+ * 恢复默认卡片 (the page service's restore-defaults) puts back those of them no card of the home page holds.
  */
-export const HOME_CARDS = Object.freeze(["gallery/today", "gallery/note", "gallery/todos", "gallery/recent", "gallery/stats", "gallery/heatmap"]);
+export const HOME_CARDS = Object.freeze(["gallery/today", "gallery/weather", "gallery/countdown", "gallery/habit", "gallery/stats", "gallery/todos", "gallery/heatmap", "gallery/recent", "gallery/note", "gallery/static"]);
+/** The default home page's cards that are not their block's default size, [w, h] each. */
+export const HOME_SIZES = Object.freeze({ "gallery/habit": [2, 2], "gallery/todos": [4, 6], "gallery/note": [4, 4] });
 /**
  * The default cards a home page made before the workspace's data came had (the plan's phase 2: 问候与日期
  * and 便签): what a home whose hints say nothing of its cards was told of, so that it is told once of the
@@ -86,21 +99,51 @@ export async function pageSlugRefused(slug, root) {
   return null;
 }
 
+/**
+ * A slug for a new custom page no name of workspace `root` holds (pageSlugRefused): page- and a random id,
+ * as a new document's is doc- and one (the workbench's 新建页面, whose title is typed after it is made).
+ */
+export async function newPageSlug(root, random = undefined) {
+  for (;;) {
+    const slug = `page-${newPageId(new Set(), random)}`;
+    if (!(await pageSlugRefused(slug, root))) return slug;
+  }
+}
+
 const readJson = (file) => fs.readFile(file, "utf8").then((text) => JSON.parse(text.replace(/^/, ""))).catch(() => null);
 
-/** A page.json's fields as a list shows them: { title (the slug when it names none), icon (or null) }. */
+/**
+ * A page.json's fields as a list shows them: { title (the slug when it names none), icon (or null),
+ * defaultCards (it says `"defaultCards": true`: the page has Gallery's default cards, HOME_CARDS, which
+ * 恢复默认卡片 in its menu puts back where it misses them, and its note tells of those that came after
+ * it), hint (`"hint": true`: its first-open note on its cards shows until the reader closes it) }.
+ * Any page may say either; the default home page says both.
+ */
 export function pageMetaOf(slug, value) {
   const title = typeof value?.title === "string" && value.title.trim() ? value.title.trim() : slug;
   const icon = typeof value?.icon === "string" && value.icon.trim() ? value.icon.trim() : null;
-  return { title, icon };
+  return { title, icon, defaultCards: value?.defaultCards === true, hint: value?.hint === true };
 }
 
-/** Custom page `slug` as a list shows it: { slug, title, icon }, or null when it is not there. */
+/** Custom page `slug` as a list shows it: { slug, title, icon, defaultCards, hint }, or null when it is not there. */
 export async function readPageMeta(slug, root) {
   if (!pageExists(slug, root)) return null;
   return { slug, ...pageMetaOf(slug, await readJson(pageFiles(slug, root).json)) };
 }
 
+/** Custom page `slug`'s meta as its page.json says it now (pageMetaOf), read at once; null when it is not there. */
+export function pageMetaNow(slug, root) {
+  if (!pageExists(slug, root)) return null;
+  let value = null;
+  try {
+    value = JSON.parse(readFileSync(pageFiles(slug, root).json, "utf8").replace(/^/, ""));
+  } catch {}
+  return { slug, ...pageMetaOf(slug, value) };
+}
+
+/** Whether custom page `slug` has the default cards (its page.json's defaultCards): 恢复默认卡片 runs on it. */
+export const pageDefaults = (slug, root) => pageMetaNow(slug, root)?.defaultCards === true;
+
 /**
  * What gallery.json says of the custom pages (the spec §2): { order: the sidebar's order of their
  * slugs, homeMade: whether the default home page was made }; nothing said, or a gallery.json that does
@@ -236,8 +279,9 @@ export function ownLine(text, open, member) {
   return start > open && /^[ \t]*$/.test(before) ? before : null;
 }
 
-// .gallery/hints.json: { home: <when it was closed>, homeCards: [the default cards the reader knows of] },
-// or {} where there is none or it does not read.
+// .gallery/hints.json: { pages: { <slug>: <when its first-open note was closed> }, homeCards: [the default
+// cards the reader knows of] }, or {} where there is none or it does not read. Its `home` (<when>) is what
+// a Gallery said before every page was alike: the note of pages/home closed, the one page that had one.
 function hintsOf(root) {
   try {
     const value = JSON.parse(readFileSync(layoutOf(root).hints, "utf8"));
@@ -246,19 +290,48 @@ function hintsOf(root) {
     return {};
   }
 }
+const closedOf = (hints) => (hints.pages && typeof hints.pages === "object" && !Array.isArray(hints.pages) ? hints.pages : {});
+
+/** What .gallery/hints.json says under `key` (undefined where it says nothing, or does not read). */
+export const hintOf = (root, key) => hintsOf(root)[key];
+
+/** .gallery/hints.json with `patch`'s keys written, its others kept. */
+export async function writeHints(root, patch) {
+  const { hints, gallery } = layoutOf(root);
+  await fs.mkdir(gallery, { recursive: true });
+  await writeAtomic(hints, `${JSON.stringify({ ...hintsOf(root), ...patch }, null, 2)}\n`);
+}
 
 /**
- * Whether the reader closed the home page's first-open note (the plan's §5.2): once for the workspace,
+ * Whether the reader closed custom page `slug`'s first-open note (the plan's §5.2): once for the workspace,
  * whichever browser or port shows it, kept in .gallery/hints.json (what Gallery keeps of its own, never
  * gallery.json, which is the workspace's settings and wakes every page's watcher as it is written).
  */
-export const homeHintClosed = (root) => typeof hintsOf(root).home === "string";
+export function pageHintClosed(root, slug) {
+  const hints = hintsOf(root);
+  return typeof closedOf(hints)[slug] === "string" || (slug === HOME && typeof hints.home === "string");
+}
+
+/** Whether custom page `slug`'s first-open note shows: its page.json says `hint`, and the reader has not closed it. */
+export const pageHintShown = (slug, root) => pageMetaNow(slug, root)?.hint === true && !pageHintClosed(root, slug);
+
+/** Custom page `slug`'s first-open note closed for good (`at`: when, an ISO time), the file's other notes kept. */
+export async function closePageHint(root, slug, at = new Date().toISOString()) {
+  const { hints, gallery } = layoutOf(root);
+  await fs.mkdir(gallery, { recursive: true });
+  const value = hintsOf(root);
+  await writeAtomic(hints, `${JSON.stringify({ ...value, pages: { ...closedOf(value), [slug]: at } }, null, 2)}\n`);
+}
+
+/** The first-open note of pages/home closed (closePageHint's), and whether it is (pageHintClosed's): the older words for them. */
+export const closeHomeHint = (root, at) => closePageHint(root, HOME, at);
+export const homeHintClosed = (root) => pageHintClosed(root, HOME);
 
 /**
- * The default cards (of HOME_CARDS) the reader knows of in workspace `root`: those its home page was made
- * with, or the reader was told of since (the home page's note of new cards, closed or taken up, and
- * 恢复默认卡片 run), kept in .gallery/hints.json as `homeCards`; FIRST_HOME_CARDS where it says none, the
- * cards of a home made before the others came.
+ * The default cards (of HOME_CARDS) the reader knows of in workspace `root`: those its pages with the
+ * default cards were made with, or the reader was told of since (a page's note of new cards, closed or
+ * taken up, and 恢复默认卡片 run), kept in .gallery/hints.json as `homeCards`; FIRST_HOME_CARDS where it
+ * says none, the cards of a home page made before the others came.
  */
 export function homeCardsTold(root) {
   const told = hintsOf(root).homeCards;
@@ -266,43 +339,65 @@ export function homeCardsTold(root) {
 }
 
 /**
- * The default cards the home page's note tells of (the plan's 3.4: a home made before them is not
- * changed, and is told once that 恢复默认卡片 brings them): those of HOME_CARDS the reader was not told of
- * (homeCardsTold) and no card of the home page holds (`held`: the blocks its cards are). Empty where
- * there is none to tell.
+ * The default cards a page's note tells of, on a page with the default cards (pageMetaOf's defaultCards;
+ * the plan's 3.4: a page made before them is not changed, and is told once that 恢复默认卡片 brings them):
+ * those of HOME_CARDS the reader was not told of (homeCardsTold) and no card of the page holds (`held`: the
+ * blocks its cards are). Empty where there is none to tell.
  */
 export const homeCardsNew = (root, held) => HOME_CARDS.filter((id) => !homeCardsTold(root).includes(id) && !held.includes(id));
 
-/** Every default card told of (HOME_CARDS, kept as hints.json's `homeCards`): the home page's note of new cards says nothing again. */
+/** Every default card told of (HOME_CARDS, kept as hints.json's `homeCards`): a page's note of new cards says nothing again. */
 export async function tellHomeCards(root) {
   const { hints, gallery } = layoutOf(root);
   await fs.mkdir(gallery, { recursive: true });
   await writeAtomic(hints, `${JSON.stringify({ ...hintsOf(root), homeCards: [...HOME_CARDS] }, null, 2)}\n`);
 }
 
-/** The home page's first-open note closed for good (`at`: when, an ISO time), the file's other notes kept. */
-export async function closeHomeHint(root, at = new Date().toISOString()) {
-  const { hints, gallery } = layoutOf(root);
-  await fs.mkdir(gallery, { recursive: true });
-  await writeAtomic(hints, `${JSON.stringify({ ...hintsOf(root), home: at }, null, 2)}\n`);
-}
-
 /**
- * Pages in the sidebar's order (the spec §2): home first, then those gallery.json's pages.order
- * names, in its order, then the rest by title (then slug). Pure: `pages` [{ slug, title }].
+ * Pages in the order a page goes by where the reader gave it no place in the sidebar's head (the spec
+ * §2): those gallery.json's pages.order names, in its order, then the rest by title (then slug). Pure:
+ * `pages` [{ slug, title }].
  */
 export function inPageOrder(pages, order = []) {
-  const rank = (slug) => (slug === HOME ? -1 : order.includes(slug) ? order.indexOf(slug) : Infinity);
+  const rank = (slug) => (order.includes(slug) ? order.indexOf(slug) : Infinity);
   const collator = new Intl.Collator("zh-CN", { numeric: true });
   return [...pages].sort((a, b) => rank(a.slug) - rank(b.slug) || collator.compare(a.title, b.title) || (a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0));
 }
 
-/** The custom pages of workspace `root`, in the sidebar's order: [{ slug, title, icon }]. Folders of pages/ that hold no page.html are passed over. */
+/**
+ * Pages in the sidebar's order: as the head's rows go (`head`, the stored head: ./sidebar-head.mjs
+ * headOrder), those it names not after them in inPageOrder's (`order`: gallery.json's pages.order). Pure.
+ */
+export function inHeadOrder(pages, order = [], head = null) {
+  const listed = inPageOrder(pages, order);
+  const bySlug = new Map(listed.map((page) => [page.slug, page]));
+  return headOrder(head, listed.map(({ slug }) => slug)).map(headPage).filter(Boolean).map((slug) => bySlug.get(slug));
+}
+
+/** The custom pages of workspace `root`, in the sidebar's order (inHeadOrder): [{ slug, title, icon, defaultCards, hint }]. Folders of pages/ that hold no page.html are passed over. */
 export async function listPages(root) {
   const { customPages: pages } = layoutOf(root);
   const names = await fs.readdir(pages, { withFileTypes: true }).catch(() => []);
   const found = await Promise.all(names.filter((entry) => entry.isDirectory() && isSlugName(entry.name)).map((entry) => readPageMeta(entry.name, root)));
-  return inPageOrder(found.filter(Boolean), pagesSettings(root).order);
+  return inHeadOrder(found.filter(Boolean), pagesSettings(root).order, await readStoredHead(root));
+}
+
+/** The sidebar's head rows of workspace `root` in their order (./sidebar-head.mjs headOrder): new, search and @<slug> of each of `pages` (listPages'). */
+export async function headOf(root, pages = null) {
+  return headOrder(await readStoredHead(root), (pages ?? await listPages(root)).map(({ slug }) => slug));
+}
+
+/**
+ * Custom page `slug` given its row in the sidebar's head, in the outline file under its lock: right after
+ * page `after`'s row, else last (a page made: createPage's). A head that was never stored is stored as
+ * the sidebar showed it, so that the page made last stands last.
+ */
+export async function placePageInHead(root, slug, after = null) {
+  await withOutlineLock(root, async () => {
+    const stored = await readStoredHead(root);
+    const shown = stored ? null : await headOf(root, (await listPages(root)).filter((page) => page.slug !== slug));
+    await writeHead(root, headWithPage(stored, shown, slug, after));
+  });
 }
 
 /**
@@ -322,10 +417,14 @@ export async function pageVersionNow(slug, root) {
 
 /**
  * The page.html of a new custom page: its title (in `<title>` only: the page draws no big title, its
- * name is the sidebar's, the tab's and the top bar's) and one empty board (`main`), the spec §5's
- * structure. `lang`: its page's lang ("zh-CN" by default).
+ * name is the sidebar's, the tab's and the top bar's) and its <main class="gallery-page">, holding one
+ * empty board (`main`, the spec §5's structure: gallery page new's), or nothing (`blank`: the workbench's
+ * 新建页面, a page an Agent is to write, isBlankPage). `lang`: its page's lang ("zh-CN" by default).
  */
-export function newPageHtml(slug, title, { lang = "zh-CN" } = {}) {
+export function newPageHtml(slug, title, { lang = "zh-CN", blank = false } = {}) {
+  const inside = blank ? "" : `
+    <div class="gallery-board" data-board-id="${FIRST_BOARD}">
+    </div>`;
   return `<!doctype html>
 <html lang="${escapeMarkup(lang)}">
 <head>
@@ -338,9 +437,7 @@ export function newPageHtml(slug, title, { lang = "zh-CN" } = {}) {
   </style>
 </head>
 <body>
-  <main class="gallery-page" data-page-id="${slug}">
-    <div class="gallery-board" data-board-id="${FIRST_BOARD}">
-    </div>
+  <main class="gallery-page" data-page-id="${slug}">${inside}
   </main>
 </body>
 </html>
@@ -348,18 +445,33 @@ export function newPageHtml(slug, title, { lang = "zh-CN" } = {}) {
 }
 
 /**
- * Make custom page `slug` in workspace `root`: pages/<slug>/ with page.html (newPageHtml) and page.json
- * ({ title, icon? }). Throws (code EEXIST) when pageSlugRefused refuses the slug; resolves to its files.
+ * Whether page.html `html` is a blank page, one no one has written yet: its <body> holds an empty
+ * <main class="gallery-page"> and nothing else (comments and blanks aside), as the workbench's 新建页面
+ * writes it (newPageHtml's `blank`). The workbench then shows, in its middle, that an Agent writes it.
+ */
+export function isBlankPage(html) {
+  const body = /<body\b[^>]*>([\s\S]*?)<\/body>/i.exec(String(html ?? "").replace(/<!--[\s\S]*?-->/g, ""))?.[1];
+  return body !== undefined && /^\s*<main\b[^>]*\bclass\s*=\s*["']?gallery-page["']?[^>]*>\s*<\/main>\s*$/i.test(body);
+}
+
+/**
+ * Make custom page `slug` in workspace `root`: pages/<slug>/ with page.html (newPageHtml: one empty
+ * board, or none where `blank`) and page.json ({ title, icon?, defaultCards?, hint? }: pageMetaOf), and its
+ * row in the sidebar's head right after page `after`'s, else last (placePageInHead; a head that cannot be
+ * written leaves it where a page the head names not goes). Throws (code EEXIST) when pageSlugRefused
+ * refuses the slug; resolves to its files.
  */
-export async function createPage(slug, title, { root, icon = null, lang } = {}) {
+export async function createPage(slug, title, { root, icon = null, lang, blank = false, defaultCards = false, hint = false, after = null } = {}) {
   const refused = await pageSlugRefused(slug, root);
   if (refused) throw Object.assign(new Error(refused), { code: "EEXIST" });
   const files = pageFiles(slug, root);
   await fs.mkdir(layoutOf(root).customPages, { recursive: true });
   await fs.mkdir(files.folder, { recursive: false }); // fails when it was made meanwhile
   const name = title.replace(/\s+/g, " ").trim();
-  await fs.writeFile(files.html, newPageHtml(slug, name, { lang }));
-  await fs.writeFile(files.json, `${JSON.stringify({ title: name, ...(icon ? { icon } : {}) }, null, 2)}\n`);
+  await fs.writeFile(files.html, newPageHtml(slug, name, { lang, blank }));
+  const meta = { title: name, ...(icon ? { icon } : {}), ...(defaultCards ? { defaultCards: true } : {}), ...(hint ? { hint: true } : {}) };
+  await fs.writeFile(files.json, `${JSON.stringify(meta, null, 2)}\n`);
+  await placePageInHead(root, slug, after).catch(() => {});
   return files;
 }