@heycys/gallery 0.1.1 → 0.2.0

package/browser/shared/outline.mjs

@@ -2,20 +2,52 @@ import { randomBytes } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { writeAtomic } from "./files.mjs";
-import { layoutOf, listDocumentSlugs, pageSlug, slugPattern } from "./workspace.mjs";
-
-// The workspace's outline: which document sits under which, in what order (the sidebar's tree,
-// <workspace>/.gallery/outline.json, docs/workbench.md "Workspace commands"):
-//   { version: 1, children: { "": [top-level slugs], "<slug>": [slugs under it] } }
-// Hierarchy and order only: a document's folder never moves with it, and no file of a document
-// names where it is (links between documents are relative links between their files). Read, it
-// lists every document of the workspace once but the 写作偏好 page (listed apart, in .gallery/pages/):
-// slugs that are gone drop out, documents it does not know yet come last at the top.
-// Written by the workspace's server (src/workbench/service.mjs: the workbench's moves, a new, copied,
-// restored or imported document, gallery new --under and gallery move while it runs, in the queue its
-// saves go through), and by a gallery command when no server runs (src/cli/tree.mjs), with the same
-// functions, each change read, made and written under the outline's lock (withOutlineLock: a file
-// that two processes cannot both make), so that two writers never lose each other's change.
+import { extensionColumnIds } from "./extensions.mjs";
+import { DOCS, entryPattern, extensionGroupId, GROUP_LIMITS, groupOf, isForeign, isTop, newGroupId, topIn, topOf, validGroups } from "./outline-shape.mjs";
+import { storedHead } from "./sidebar-head.mjs";
+import { shownWorkspaces, snapshotOf } from "./workspace-columns.mjs";
+import { layoutOf, listDocumentSlugs, listLinkSlugs, pageSlug } from "./workspace.mjs";
+
+// 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:
+//   { version: 2, children: { "": [the 文档 column's top], "<slug>": [entries under it] },
+//     groups: [{ id: "docs", title? }, { id, title?, role?, workspace?, children: { "": [its top], "<slug>": […] } }] }
+// The 文档 column's tree is the top-level `children`, as in version 1 ({ version: 1, children }, the
+// 文档 column alone, read as such), so that an older Gallery reads the documents' order as before.
+// Hierarchy and order only: an entry's folder never moves with it, and no file of a document names
+// where it is (links between documents are relative links between their files). Read, it lists every
+// document and web link of the workspace once but the 写作偏好 page (listed apart, in .gallery/pages/):
+// entries that are gone drop out, documents it does not know yet come last in the own column (文档's
+// place, top key ""), links last in a column of the links an older Gallery made (else in the own column).
+// Every other registered workspace has a column (./workspace-columns.mjs; the plan §7.2): one the file
+// holds not yet is made as it is read (the default workspace's right after the own column, the others
+// last), and a "whole" column (not `picked`) holds every document of its workspace the outline holds not
+// but those the user took out (its `left`): under its own parent's entry when the outline holds that,
+// else last in the column, the first time laid out as its own sidebar has them. A draft of another
+// workspace ("~<ws id>/<slug>": ./drafts.mjs) stays where the file has it while its document is there;
+// one gone from a workspace the sidebar shows leaves, one of a workspace it does not show (not
+// registered, a clash of ids, its folder away) stays, shown grey (找不到底稿), until it is removed; one of a
+// workspace whose folder did not read this time (an error of the disk: otherWorkspaces' `failed`) stays
+// too, and its column is not filled. A column the sidebar does not draw (the user removed it, `hidden`;
+// its workspace not shown) keeps its workspace's drafts alone: any other entry there (a document of this
+// workspace, a web link, a draft of a third, dragged in) comes last in the own column with what is under it,
+// so that nothing the user put there is out of sight. `others: false` reads the workspace's tree alone (what
+// another workspace's sidebar reads of it, and what the commands of that workspace's own tree read).
+// The columns extensions provide (extensions/<id>/sidebar.json: ./extensions.mjs) are among the groups as
+// { id: "ext-<id>", extension: "<id>" }, each there while its extension has a sidebar.json: one it has not
+// 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
+// (src/cli/tree.mjs), with the same functions, each change read, made and written under the outline's
+// lock (withOutlineLock: a file that two processes cannot both make), so that two writers never lose
+// each other's change.
 
 /** The outline file's lock (.gallery/outline.lock): who holds it, until when it counts. */
 const LOCK_STALE = 10_000; // a lock older than this was left by a process that ended: taken over
@@ -53,91 +85,337 @@ export async function withOutlineLock(root, task) {
 
 const readJson = (file) => fs.readFile(file, "utf8").then(JSON.parse).catch(() => null);
 
-/** The outline of workspace `root` as it is read: every document but the 写作偏好 page once (above). */
-export async function readOutline(root) {
-  return (await outlineAndFile(root)).outline;
+/** The outline of workspace `root` as it is read: every entry once (above). `others`: with the other workspaces' columns. */
+export async function readOutline(root, { others = true } = {}) {
+  return (await outlineAndFile(root, { others })).outline;
+}
+
+/**
+ * The other workspaces the sidebar of workspace `root` shows a column of, each with what its own sidebar
+ * holds (./workspace-columns.mjs shownWorkspaces, snapshotOf): [{ id, root, isDefault, documents, order,
+ * parentOf, facts, failed }]. `failed`: its folder did not read this time (EPERM, EBUSY, EIO: a network or
+ * removable drive), none of its documents known, so that the outline drops none of its drafts for it.
+ */
+export async function otherWorkspaces(root, { env = process.env } = {}) {
+  const shown = shownWorkspaces(root, { env });
+  const readOwn = (other) => readOutline(other, { others: false });
+  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)) })));
 }
 
 /**
- * The outline as it is read and what its file holds: { outline, stored: the file's children, or null }.
- * A change is written when what it makes is not what the file holds (writtenAs), a document the file
- * does not hold yet too (one made since, listed last at the top only as it is read), so that the file
- * keeps every place a command or the workbench gave.
+ * The outline as it is read and what its file holds: { outline: { version: 2, groups, children,
+ * links: the slugs of its web links, drafts: the entries of other workspaces' drafts, shown: the other
+ * workspaces whose columns it shows ([{ id, root, isDefault }]: otherWorkspaces) }, stored: the file's
+ * columns and children as the outline has them (storedOf), or null; others: otherWorkspaces' answer }. A
+ * change is written when what it makes is not what the file holds (writtenAs), a document or a link the
+ * file does not hold yet too (one made since, placed only as it is read), so that the file keeps every
+ * 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) {
+export async function outlineAndFile(root, { others: withOthers = true } = {}) {
   const instructions = await pageSlug(root);
-  const slugs = (await listDocumentSlugs(root)).filter((slug) => slug !== instructions);
-  const stored = await readJson(layoutOf(root).outline);
-  const outline = { version: 1, children: ordered(stored, slugs) };
-  return { outline, stored: stored?.children ?? null };
+  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 outline = {
+    version: 2, ...shown, links, drafts: Object.values(shown.children).flat().filter(isForeign),
+    shown: others.map(({ id, root: other, isDefault }) => ({ id, root: other, isDefault })),
+  };
+  return { outline, stored, 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.
+const OLD_DOCS_NAMES = ["文档", "Documents"];
+
+/**
+ * What outline.json's value `file` holds, as the outline has it: { groups, children } (the 文档 column's
+ * tree from the file's own `children`, every other column's from its `children`, its top under its top
+ * key), or null for a file that is not there or not an outline. A file of version 1 is the 文档 column alone.
+ * The own column titled with its old name (OLD_DOCS_NAMES) has none.
+ */
+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) => {
+    if (!own || typeof own !== "object" || Array.isArray(own)) return;
+    for (const [key, list] of Object.entries(own)) {
+      if (!Array.isArray(list)) continue;
+      const at = key === "" ? topOf(id) : key;
+      if (!children[at]) children[at] = list.filter((entry) => typeof entry === "string");
+    }
+  };
+  for (const value of Array.isArray(file.groups) ? file.groups : []) {
+    const group = groupOf(value);
+    if (!group || groups.some(({ id }) => id === group.id)) continue;
+    if (group.id === DOCS && OLD_DOCS_NAMES.includes(group.title)) delete group.title;
+    groups.push(group);
+    take(group.id, group.id === DOCS ? file.children : value.children);
+  }
+  if (!groups.some(({ id }) => id === DOCS)) {
+    groups.unshift({ id: DOCS });
+    take(DOCS, file.children);
+  }
+  return { groups, children };
+}
+
+/** The keys of `children` whose lists are not empty: what two outlines are compared by. */
+const lists = (children) => Object.keys(children ?? {}).filter((key) => Array.isArray(children[key]) && children[key].length > 0);
+
+/** The part of `children` the 文档 column holds: its top and the lists under its entries. */
+function docsPart(children) {
+  const part = {};
+  const walk = (key) => {
+    const list = children?.[key];
+    if (!Array.isArray(list) || list.length === 0 || Object.hasOwn(part, key)) return;
+    part[key] = list;
+    list.forEach(walk);
+  };
+  walk("");
+  return part;
+}
+
+/**
+ * Whether outline `value` ({ groups?, children }) is what `stored` holds (outlineAndFile's, or an outline
+ * read): the same columns in the same order, and the same lists (an empty one as none), in whatever order
+ * the keys come. One without `groups` (an outline of version 1: a test's, an older workbench's) is held
+ * to the 文档 column alone. Also whether an outline a workbench changed (POST outline's `base`) is the one read now.
+ */
+export function writtenAs(value, stored) {
+  if (!stored || typeof stored !== "object" || !value || typeof value !== "object") return false;
+  const ours = value.children ?? {};
+  const theirs = value.groups ? stored.children : docsPart(stored.children);
+  const [a, b] = [lists(ours), lists(theirs)];
+  if (a.length !== b.length || !a.every((key) => JSON.stringify(ours[key]) === JSON.stringify(theirs[key]))) return false;
+  if (!value.groups) return true;
+  const same = (groups) => JSON.stringify((groups ?? []).map(groupOf));
+  return same(value.groups) === same(stored.groups);
 }
 
 /**
- * Whether `children` is what the outline's file holds (`stored`, outlineAndFile's): the same lists
- * (an empty one as none), in whatever order the file has its keys. Also whether an outline a
- * workbench changed (POST outline's `base`) is the one read now.
+ * `groups` with the columns of the extensions `ids` (those with a sidebar.json): the extension columns the
+ * outline kept stay where it put them, once each and only while their extension is there; an extension
+ * with none comes last, while there is room (50 columns at most: validGroups, or no change of the outline
+ * would be written).
  */
-export function writtenAs(children, stored) {
-  if (!stored || typeof stored !== "object") return false;
-  const lists = (value) => Object.keys(value).filter((key) => Array.isArray(value[key]) && value[key].length > 0);
-  const [ours, theirs] = [lists(children), lists(stored)];
-  return ours.length === theirs.length && ours.every((key) => JSON.stringify(children[key]) === JSON.stringify(stored[key]));
+function withExtensions(groups, ids) {
+  const wanted = new Set(ids);
+  const seen = new Set();
+  const kept = groups.filter((group) => {
+    if (!group.extension) return true;
+    if (!wanted.has(group.extension) || seen.has(group.extension)) return false;
+    seen.add(group.extension);
+    return true;
+  });
+  const coming = ids.filter((id) => !seen.has(id)).map((id) => ({ id: extensionGroupId(id), extension: id }));
+  return [...kept, ...coming.slice(0, Math.max(0, GROUP_LIMITS.groups - kept.length))];
+}
+
+/**
+ * `groups` with a column for each of the workspaces `others` (otherWorkspaces') that none has yet (hidden or
+ * not): a whole one (no `picked`), its id the workspace's when no column has that, the default workspace's
+ * right after the own column, the others last, in the registry's order; `limit` columns at most (the room
+ * the extensions' columns to come leave of the 50).
+ */
+export function withWorkspaces(groups, others, limit = GROUP_LIMITS.groups) {
+  const result = [...groups];
+  const lacking = others.filter(({ id }) => !result.some((group) => group.workspace === id));
+  for (const { id, isDefault } of lacking) {
+    if (result.length >= limit) break; // 50 columns at most (validGroups)
+    const column = { id: result.some((group) => group.id === id) ? newGroupId(result) : id, workspace: id };
+    if (isDefault) result.splice(result.findIndex((group) => group.id === DOCS) + 1, 0, column);
+    else result.push(column);
+  }
+  return result;
 }
 
-// The outline's children of the documents `slugs`, in the order `stored` (the file's value) gives.
-function ordered(stored, slugs) {
-  const children = { "": [] };
+const DRAFT = /^~(ws-[0-9a-f]{6})\/(.+)$/;
+
+/**
+ * The outline of the entries `documents` and `links` (the web links), in the order `stored` (storedOf's)
+ * gives, with the columns of the other workspaces `others` (otherWorkspaces'): { groups, children }, every
+ * column's top key there (an empty list for an empty column). Each entry once, under the first place it
+ * has; one of this workspace's that is gone is left out, a draft of another workspace ("~<ws id>/<slug>")
+ * left out when its workspace is among `others` and holds it no more (its folder read), else kept wherever
+ * the file has it. A document no column holds comes last in the own column; a link, last in a column of the
+ * links (role "links", an older Gallery's), else last in the own column; a document of another workspace
+ * whose column is whole, under its own parent's entry when that is held, else last in that column, in its
+ * own sidebar's order, but one the user took out of it (the column's `left`, kept to those still there).
+ * `drawn` (the sidebar's read, not a workspace's own tree alone): a workspace's column the sidebar does not
+ * draw (`hidden`, or its workspace not among `others`) keeps that workspace's drafts alone, any other entry
+ * there coming last in the own column with what is under it.
+ */
+function ordered(stored, documents, links, extensions = [], others = [], { drawn = false } = {}) {
+  const listed = new Set([...documents, ...links]);
+  const shownById = new Map(others.map((each) => [each.id, each]));
+  const known = {
+    has: (slug) => {
+      if (listed.has(slug)) return true;
+      if (!isForeign(slug) || !entryPattern.test(slug)) return false;
+      const [, ws, own] = DRAFT.exec(slug);
+      const other = shownById.get(ws);
+      return other && !other.failed ? other.documents.has(own) : true;
+    },
+  };
+  // A whole column's `left`: those its workspace still has (its folder read), none when none is.
+  const kept = (group) => {
+    const other = group.left ? shownById.get(group.workspace) : null;
+    if (!other || other.failed) return group;
+    const { left, ...rest } = group;
+    const still = left.filter((slug) => other.documents.has(slug));
+    return still.length ? { ...rest, left: still } : rest;
+  };
+  const base = stored?.groups ?? [{ id: DOCS }];
+  // The room of the 50 columns an extension's column to come takes first (one the outline has not got yet).
+  const coming = extensions.filter((id) => !base.some((group) => group.extension === id)).length;
+  const groups = withExtensions(withWorkspaces(base, others, GROUP_LIMITS.groups - coming), extensions).map(kept);
+  const children = Object.fromEntries(groups.map(({ id }) => [topOf(id), []]));
   const seen = new Set();
-  const place = (parent) => {
+  // Drawn not: the user removed it, or its workspace is not shown (forgotten, its folder away, a clash of ids).
+  const undrawn = (group) => drawn && Boolean(group.workspace) && (group.hidden === true || !shownById.has(group.workspace));
+  const astray = []; // entries of a column not drawn that are not its workspace's drafts: last in the own column
+  const place = (parent, only = null) => {
     for (const slug of stored?.children?.[parent] ?? []) {
-      if (!slugs.includes(slug) || seen.has(slug)) continue;
+      if (!known.has(slug) || seen.has(slug)) continue;
+      if (only && !slug.startsWith(`~${only}/`)) {
+        astray.push(slug);
+        continue;
+      }
       seen.add(slug);
       (children[parent] ??= []).push(slug);
-      place(slug);
+      place(slug, only);
     }
   };
-  place("");
-  for (const slug of slugs) if (!seen.has(slug)) children[""].push(slug);
-  return children;
+  for (const group of groups) if (!group.extension) place(topOf(group.id), undrawn(group) ? group.workspace : null);
+  for (const slug of astray) {
+    if (seen.has(slug)) continue;
+    seen.add(slug);
+    children[""].push(slug);
+    place(slug);
+  }
+  const linked = groups.find(({ role }) => role === "links");
+  for (const slug of documents) if (!seen.has(slug)) children[""].push(slug);
+  for (const slug of links) if (!seen.has(slug)) children[linked ? topOf(linked.id) : ""].push(slug);
+  for (const other of others) {
+    const column = groups.find((group) => group.workspace === other.id);
+    if (!column || column.picked || other.failed) continue;
+    const left = new Set(column.left ?? []);
+    for (const slug of other.order) {
+      const entry = `~${other.id}/${slug}`;
+      if (seen.has(entry) || left.has(slug)) continue;
+      const parent = other.parentOf.get(slug);
+      const above = parent ? `~${other.id}/${parent}` : null;
+      (children[above !== null && seen.has(above) ? above : topOf(column.id)] ??= []).push(entry);
+      seen.add(entry);
+    }
+  }
+  return { groups, children };
 }
 
-/** Whether `value` is an outline to store: each document at most once, never under itself. */
+/**
+ * Whether `value` ({ groups?, children }) is an outline to store: its columns valid (validGroups: 文档
+ * among them), each list's key a column's top or an entry, each entry at most once, never under itself.
+ * Without `groups` (an outline of version 1) the only top is 文档's ("").
+ */
 export function validOutline(value) {
   const children = value?.children;
   if (!children || typeof children !== "object" || Array.isArray(children)) return false;
+  if (value.groups !== undefined && !validGroups(value.groups)) return false;
+  const tops = new Set((value.groups ?? [{ id: DOCS }]).map(({ id }) => topOf(id)));
+  // An extension's column holds none of the outline's entries: they are the extension's own.
+  const extensionTops = new Set((value.groups ?? []).filter((group) => groupOf(group)?.extension).map(({ id }) => topOf(id)));
   const listed = new Set();
   for (const [parent, list] of Object.entries(children)) {
-    if (parent !== "" && !slugPattern.test(parent)) return false;
-    if (!Array.isArray(list)) return false;
+    if (!tops.has(parent) && !entryPattern.test(parent)) return false;
+    if (!Array.isArray(list) || (extensionTops.has(parent) && list.length > 0)) return false;
     for (const slug of list) {
-      if (typeof slug !== "string" || !slugPattern.test(slug) || listed.has(slug) || slug === parent) return false;
+      if (typeof slug !== "string" || !entryPattern.test(slug) || listed.has(slug) || slug === parent) return false;
       listed.add(slug);
     }
   }
   return true;
 }
 
-/** Write outline `value` ({ children }) of workspace `root` (.gallery/ made when there is none yet). */
+/**
+ * Outline `value` ({ groups?, children }) as outline.json holds it, version 2: the 文档 column's tree in
+ * `children`, where version 1 had the whole tree (an older Gallery reads its documents' order as before:
+ * it sees no column, and writes version 1 back, which this one reads as 文档 alone), and every column in
+ * `groups`, in the sidebar's order, the others each with its own `children` ("" its top).
+ */
+export function fileOf(value) {
+  const groups = value.groups ?? [{ id: DOCS }];
+  const own = (top) => {
+    const tree = { "": [] };
+    const walk = (key, as) => {
+      const list = value.children[key];
+      if (!Array.isArray(list) || list.length === 0) return;
+      tree[as] = [...list];
+      for (const entry of list) if (!Object.hasOwn(tree, entry)) walk(entry, entry);
+    };
+    walk(top, "");
+    return tree;
+  };
+  return {
+    version: 2,
+    children: own(""),
+    groups: groups.map((group) => {
+      const kept = groupOf(group);
+      return kept.id === DOCS || kept.extension ? kept : { ...kept, children: own(topOf(kept.id)) };
+    }),
+  };
+}
+
+/**
+ * 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 file = layoutOf(root).outline;
   await fs.mkdir(path.dirname(file), { recursive: true });
-  return writeAtomic(file, `${JSON.stringify({ version: 1, children: value.children }, null, 2)}\n`);
+  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);
 }
 
-/** The document `slug` sits under in `children` ("" at the top), or null when the outline holds it not. */
+/**
+ * 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 });
+  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. */
 export function parentIn(children, slug) {
   for (const [parent, list] of Object.entries(children)) if (list.includes(slug)) return parent;
   return null;
 }
 
-/** The documents above `slug` in `children`, from the top down (itself not among them). */
+/** The entries above `slug` in `children`, from the top down (itself and its column not among them). */
 export function ancestorsIn(children, slug) {
   const above = [];
-  for (let parent = parentIn(children, slug); parent; parent = parentIn(children, parent)) above.unshift(parent);
+  for (let parent = parentIn(children, slug); parent !== null && !isTop(parent) && !above.includes(parent); parent = parentIn(children, parent)) above.unshift(parent);
   return above;
 }
 
-/** Every document under `slug` in `children` ("": all), depth first, in the sidebar's order. */
+/** Every entry under `slug` in `children` (a top key: the column's), depth first, in the sidebar's order. */
 export function descendantsIn(children, slug) {
   const found = [];
   const walk = (parent) => (children[parent] ?? []).forEach((child) => { found.push(child); walk(child); });
@@ -146,18 +424,18 @@ export function descendantsIn(children, slug) {
 }
 
 /**
- * Document `slug` moved in `children` (an outline as read: changed in place) with the documents under
- * it, to where `where` says: `parent` ("" the top; undefined: where it is now, or `after`'s parent),
- * right after `after` (one of that parent's), first (`first`), else last. Resolves to { ok: true,
- * moved: whether its place changed, parent, index, from: { parent, index } } or { ok: false, reason }:
- * "missing" (no such document in the outline), "parent" (no such parent), "after" (no such document
- * to go after), "level" (`after` is not under `parent`), "itself" (after itself), "inside" (under
- * itself or one of the documents under it).
+ * Entry `slug` moved in `children` (an outline as read: changed in place) with the entries under it, to
+ * where `where` says: `parent` ("" the top level of the column it is in; a column's top key, that
+ * column's; undefined: where it is now, or `after`'s parent), right after `after` (one of that parent's),
+ * first (`first`), else last. Resolves to { ok: true, moved: whether its place changed, parent, index,
+ * from: { parent, index } } or { ok: false, reason }: "missing" (no such entry in the outline), "parent"
+ * (no such parent), "after" (no such entry to go after), "level" (`after` is not under `parent`),
+ * "itself" (after itself), "inside" (under itself or one of the entries under it).
  */
 export function moveIn(children, slug, { parent = undefined, after = null, first = false } = {}) {
   const from = parentIn(children, slug);
   if (from === null) return { ok: false, reason: "missing" };
-  let to = parent;
+  let to = parent === "" ? topIn(children, slug) ?? "" : parent;
   if (after !== null) {
     if (after === slug) return { ok: false, reason: "itself" };
     const its = parentIn(children, after);
@@ -166,29 +444,43 @@ export function moveIn(children, slug, { parent = undefined, after = null, first
     to = its;
   }
   to ??= from;
-  if (to !== "" && parentIn(children, to) === null) return { ok: false, reason: "parent" };
+  if (isTop(to) ? !Object.hasOwn(children, to) : parentIn(children, to) === null) return { ok: false, reason: "parent" };
   if (to === slug || ancestorsIn(children, to).includes(slug)) return { ok: false, reason: "inside" };
   const index = children[from].indexOf(slug);
   children[from].splice(index, 1);
   const list = (children[to] ??= []);
   const at = after !== null ? list.indexOf(after) + 1 : first ? 0 : list.length;
   list.splice(at, 0, slug);
-  for (const key of Object.keys(children)) if (key !== "" && children[key].length === 0) delete children[key];
+  for (const key of Object.keys(children)) if (!isTop(key) && children[key].length === 0) delete children[key];
   return { ok: true, moved: to !== from || at !== index, parent: to, index: at, from: { parent: from, index } };
 }
 
 /**
- * Move document `slug` of workspace `root` where `where` says (moveIn), under the outline's lock: the
- * outline read, changed and written when that is not what its file holds (writtenAs: a move, or a
- * document the file does not hold yet placed where it is read). Resolves to moveIn's answer, with
+ * Move entry `slug` of workspace `root` where `where` says (moveIn), under the outline's lock: the
+ * outline read, changed and written when that is not what its file holds (writtenAs: a move, or an
+ * entry the file does not hold yet placed where it is read). Resolves to moveIn's answer, with
  * `written`: whether the file was written.
  */
 export function moveDocument(root, slug, where) {
   return withOutlineLock(root, async () => {
     const { outline, stored } = await outlineAndFile(root);
     const result = moveIn(outline.children, slug, where);
-    const written = result.ok && !writtenAs(outline.children, stored);
+    const written = result.ok && !writtenAs(outline, stored);
     if (written) await writeOutline(root, outline);
     return { ...result, ...(result.ok ? { written } : {}) };
   });
 }
+
+/**
+ * Entry `slug` put in `outline` (changed in place: on disk already, so that the outline as read lists
+ * it somewhere) under `parent` (a column's top key or an entry; one the outline holds not: the 文档
+ * column's top) at `index` (the end when past it).
+ */
+export function placeIn(outline, slug, parent = "", index = Infinity) {
+  const { children } = outline;
+  for (const list of Object.values(children)) if (list.includes(slug)) list.splice(list.indexOf(slug), 1);
+  const known = parent !== slug && (isTop(parent) ? Object.hasOwn(children, parent) : Object.values(children).some((list) => list.includes(parent)));
+  const list = (children[known ? parent : ""] ??= []);
+  list.splice(Math.max(0, Math.min(index, list.length)), 0, slug);
+  for (const key of Object.keys(children)) if (!isTop(key) && children[key].length === 0) delete children[key];
+}

package/browser/shared/pack-manifest.mjs

@@ -0,0 +1,88 @@
+import { refusal, said } from "./i18n/index.mjs";
+import { DEVICE_NAMES } from "./workspace.mjs";
+
+// A block pack's manifest (自定义块包: notes/plans/block-packs-plan-2026-11-09.md §1; docs/render.md "Block
+// packs"): pack.json at the top of a pack, a folder of components/ whose blocks are its scope's
+// (components/<id>/<name>/, the block's id <id>/<name>), what a pack says of itself to whoever lists it
+// (设置 › 组件列表's pack cards, gallery block pack list) and to whoever installs it (./block-packs.mjs).
+// Plain data, as a block's manifest is: a field it does not know keeps it from reading, so that a pack
+// made for a later Gallery says so rather than half reads.
+//
+//   id           the scope its blocks are of: lowercase letters, digits and hyphens (my-cards); not
+//                local, the workspace's own blocks' scope, nor a name Windows keeps for a device
+//   name         what a reader calls it: words, or { zh, en } in both languages
+//   description  what it is, the same way (optional)
+//   version      x.y.z
+//   author       who made it, words (optional)
+//   homepage     where it comes from, an http(s) address (optional)
+//   icon         an emoji or a character or two its card shows (optional; a card has the custom block's mark)
+
+/** The file that makes a folder of components/ a pack. */
+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 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);
+const isWords = (value) => typeof value === "string" && value.trim() !== "";
+const fail = (message) => {
+  throw refusal(message, { code: "manifest" });
+};
+
+// Words a reader reads, in both languages: one string for both, or { zh, en }.
+function bothOf(value, field) {
+  if (isWords(value) && value.length <= 300) return { zh: value.trim(), en: value.trim() };
+  if (isTable(value) && Object.keys(value).length === 2 && isWords(value.zh) && isWords(value.en) && value.zh.length <= 300 && value.en.length <= 300) return { zh: value.zh.trim(), en: value.en.trim() };
+  fail(said("pack.json 的 {0} 要写成一段文字，或 { zh, en } 两种语言的文字", field));
+}
+
+/**
+ * pack.json's text read as a pack's manifest: { id, name: { zh, en }, description: { zh, en } | null,
+ * version, author, homepage, icon (each null where it says none) }. One that does not read as one is
+ * refused (code "manifest") with why, said()'s.
+ */
+export function readPackManifest(text) {
+  let value;
+  try {
+    value = JSON.parse(String(text).replace(/^/, ""));
+  } catch {
+    fail(said("pack.json 不是 JSON"));
+  }
+  if (!isTable(value)) fail(said("pack.json 要写成一张表"));
+  for (const key of Object.keys(value)) if (!FIELDS.includes(key)) fail(said("{0} 不是 pack.json 能写的字段", key));
+  const { id, name, description, version, author, homepage, icon } = value;
+  if (id === undefined) fail(said("pack.json 缺少 {0}", "id"));
+  if (typeof id !== "string" || !PACK_ID.test(id) || DEVICE_NAMES.has(id)) fail(said("pack.json 的 id 只用小写字母、数字和连字符，如 my-cards"));
+  if (id === OWN_SCOPE) fail(said("{0} 留给工作区自己的块，块包换一个 id", OWN_SCOPE));
+  if (name === undefined) fail(said("pack.json 缺少 {0}", "name"));
+  if (version === undefined) fail(said("pack.json 缺少 {0}", "version"));
+  if (typeof version !== "string" || !VERSION.test(version)) fail(said("pack.json 的 version 要写成 1.0.0 这样的三段数字"));
+  if (author !== undefined && !(isWords(author) && author.length <= 100)) fail(said("pack.json 的 {0} 要写成一段文字", "author"));
+  if (homepage !== undefined && !(typeof homepage === "string" && /^https?:\/\/\S+$/.test(homepage) && homepage.length <= 500)) fail(said("pack.json 的 homepage 要写成 http 或 https 开头的地址"));
+  if (icon !== undefined && !(isWords(icon) && [...icon].length <= 8 && !/[<>&"]/.test(icon))) fail(said("pack.json 的 icon 要写成一个表情或一两个字"));
+  return {
+    id,
+    name: bothOf(name, "name"),
+    description: description === undefined ? null : bothOf(description, "description"),
+    version,
+    author: author?.trim() ?? null,
+    homepage: homepage ?? null,
+    icon: icon?.trim() ?? null,
+  };
+}