@heycys/gallery 0.2.3 → 0.2.4

package/browser/editor/page/handle/index.mjs

@@ -132,6 +132,7 @@ export function createHandle({ info, active, selection, drag, menu, openMenu, dr
   let barShown = null; // the section the bar stands beside
   let shown = null; // the block the handle stands beside
   let noted = null; // the block the 批注 button stands beside
+  let noteWait = null; // { target, ready, timer }: a new block must stay eligible for 400 ms
   let pointer = null; // { x, y, target }: where the pointer last moved over the page, and what it was on
   let typing = false; // the handle hides while the reader types, until the pointer moves
   let still = null; // the page scrolled with the pointer here: the handle hides until it moves away
@@ -281,8 +282,19 @@ export function createHandle({ info, active, selection, drag, menu, openMenu, dr
 
   // The 批注 button beside `target` (shown by its `shape`) at `spot`, or none.
   function placeNote(target, shape, spot) {
+    if (noteWait?.target !== target) {
+      clearTimeout(noteWait?.timer);
+      noteWait = null;
+      noted = null;
+      note.remove();
+      if (target) {
+        const waiting = { target, ready: false, timer: null };
+        waiting.timer = setTimeout(() => { waiting.ready = true; schedule(); }, 400);
+        noteWait = waiting;
+      }
+    }
+    if (!target || !noteWait?.ready) return;
     noted = target;
-    if (!target) return void note.remove();
     own(note, "note button", { owner: target, alive: () => noted === target && target.isConnected });
     drawAt(note, shape.layer, spot.left - shape.origin.left, spot.top - shape.origin.top);
   }
@@ -613,7 +625,7 @@ export function createHandle({ info, active, selection, drag, menu, openMenu, dr
         handle.remove();
       }
       if (!handle.isConnected || !dimmed?.isConnected) undim();
-      if (noted && !noted.isConnected) placeNote(null);
+      if (noteWait && !noteWait.target.isConnected) placeNote(null);
       if (barShown && !barShown.isConnected) {
         barShown = null;
         bar.remove();

package/browser/editor/page/links/index.mjs

@@ -595,7 +595,7 @@ function keep(href, restore, page) {
     const before = ownHTML(host);
     link.replaceWith(mentionOf(link).title);
     use.recordStep(host, before);
-    use.say(t("链接已移除。"));
+    use.say(t("链接已移除"));
     return;
   }
   const before = ownHTML(host);
@@ -616,7 +616,7 @@ function keep(href, restore, page) {
     }
   } else return;
   use.recordStep(host, before);
-  use.say(href ? t("链接：{0}", wordsFor(href, page)) : entry ? t("入口已移除：页面上没有地方能打开这张详情卡片了 · Ctrl+Z 撤销") : t("链接已移除。"));
+  use.say(href ? t("链接：{0}", wordsFor(href, page)) : entry ? t("入口已移除：页面上没有地方能打开这张详情卡片了 · Ctrl+Z 撤销") : t("链接已移除"));
 }
 
 // The gray 链接 given its address: a link of it in its place, its words the address or a page's title

package/browser/editor/page/quiet.mjs

@@ -27,13 +27,13 @@ const ROUTINE = () => [
   t("{0} · Ctrl+Z 撤销"), // whatever was just done
   t("已新建分区 · 标题、分割线都可以按需加"),
   t("已复制 {0} · 在要放的块里按 Ctrl+V 粘贴到它后面"), t("已复制 {0} 格"),
-  t("已保存。"), t("{0}。", t("标题已更新")),
-  t("已取消调整。"), t("已取消移动。"), t("位置没有变化。"),
+  t("已保存"), t("标题已更新"),
+  t("已取消调整"), t("已取消移动"), t("位置没有变化"),
   t("已选中 {0} 块 · Delete 删除 · 拖动手柄一起移动 · Esc 取消"), t("已选中{0} · Delete 删除{1} · Esc 取消"),
   t("已选中{0} · Delete 删除 · Esc 取消{1}"), t("已选中这一块的文字 · 再按 {0} 选中{1}"), t("已选中这一块的文字"), // Ctrl+A (select-all/)
   t("正在移动{0} · 拖到要放的位置后松开 · 停在选项卡上切换，停在折叠块标题上展开 · Esc 取消"),
   t("接着打的字：{0} · 再按一次取消"), t("接着打的字照旧"),
-  t("链接：{0}"), t("链接已移除。"),
+  t("链接：{0}"), t("链接已移除"),
   t("这一项上面没有同级的项，不能再缩进。"), t("这一项已经在最外层。"), t("选中的项上面没有同级的项，不能再缩进。"), t("选中的项已经在最外层。"),
   t("{0}已经在{1}。"), t("这里只有{0}；可以拖动手柄移到别处。"),
 ];

package/browser/editor/page/resize/index.mjs

@@ -319,7 +319,7 @@ export function createResize({ units, active, look, say, settle = () => {}, owns
   document.addEventListener("pointerup", () => { if (drag) finish(true); }, true);
   // After pointerup the drag is over already; any other way it ends, it is cancelled (gesture.mjs).
   endsGesture({ active: () => Boolean(drag), cancel: () => finish(false) });
-  cancelOnEscape({ active: () => Boolean(drag), cancel: () => { finish(false); say(t("已取消调整。")); } });
+  cancelOnEscape({ active: () => Boolean(drag), cancel: () => { finish(false); say(t("已取消调整")); } });
 
   return {
     /** A table's width ("x", from its right edge) or scroll height ("y", from its bottom edge) dragged, the press `event` on it (the table tools' armed edge). */

package/browser/editor/page/session.mjs

@@ -27,7 +27,8 @@ export const SOLO = new URLSearchParams(location.search).has("solo");
  * workbench shows it: a toast, `room` px above the frame's bottom, what the page's bottom panels take;
  * text "" takes it away), noticeRoom(room) (that room changed: the workbench's toasts stand above it),
  * reload() (the workbench shows the report
- * again in a new page, swapped in once drawn), annotationsRemoved(items) (批注 deleted in the page:
+ * again in a new page, swapped in once drawn), focus({ caret, selection }) (where the reader is: the block the caret is in, the
+ * words or blocks selected; the workbench reports it to the server, gallery status), annotationsRemoved(items) (批注 deleted in the page:
  * the workbench says so and offers them back), open({ target, block } or { hash }) (the workbench
  * goes to another document), jump({ block, place }) (a link goes to a block of this page: the
  * workbench adds a history entry, `place` where the reader was, for the way back: `show-place`),
@@ -131,6 +132,8 @@ export function connectWorkbench({ slug, snapshot, commands, modals }) {
     // this page's place once drawn; this page does nothing more meanwhile.
     reload: () => send("reload", {}),
     annotationsRemoved: (items) => send("annotations-removed", { items }),
+    // Where the reader is, for gallery status (focus.mjs): { caret, selection }, told when it changed.
+    focus: (where) => send("focus", where),
     open: (place) => send("open", place),
     jump: (fields) => send("jump", fields),
     workspace: () => send("workspace", {}),

package/browser/editor/page/ui.mjs

@@ -44,7 +44,7 @@ export function loadScript(src, ready, { before } = {}) {
 
 /** An address on the clipboard, and said so: called right in the click that asked, as a browser takes no write after a wait. */
 export function copyAddress(address, say) {
-  navigator.clipboard?.writeText(address).then(() => say(t("已复制链接。")), () => say(t("没能复制：浏览器不允许写剪贴板。"), "error"));
+  navigator.clipboard?.writeText(address).then(() => say(t("已复制链接")), () => say(t("没能复制：浏览器不允许写剪贴板。"), "error"));
 }
 
 export function button(label, action, { primary = false, ...props } = {}) {

package/browser/shared/annotations.mjs

@@ -5,7 +5,7 @@ import { BLOCK_ID, randomId } from "./ids.mjs";
 // local Agent, each about a piece of a report: words of its text, or blocks taken whole. One has
 // words: an item with none is none (cleanItem). Kept in reports/<slug>/annotations.json, never in report.html:
 //
-//   { v: 1, items: [{ id, created, updated, text, anchor }] }
+//   { v: 1, items: [{ id, created, updated, text, anchor, done? }] }   (done: true once an Agent has acted on it: gallery notes done)
 //   anchor: { kind: "text", blocks: [data-block-id…], quote, prefix, suffix }
 //         | { kind: "blocks", blocks: [data-block-id…], quote }
 //
@@ -396,9 +396,28 @@ export function cleanItem(item, now = new Date().toISOString()) {
   if (!anchor) return null;
   const text = item.text.replace(/\r\n?/g, "\n").slice(0, TEXT_MOST);
   if (!text.trim()) return null;
-  return { id: item.id, created: typeof item.created === "string" ? item.created : now, updated: now, text, anchor };
+  return { id: item.id, created: typeof item.created === "string" ? item.created : now, updated: now, text, anchor, ...(item.done === true ? { done: true } : {}) };
 }
 
+/** `items` with those whose id `ids` holds marked done (`done` true) or not done (false), the others as they were. */
+export function markItems(items, ids, done, now = new Date().toISOString()) {
+  const named = new Set(ids);
+  return items.map((item) => (named.has(item.id) && Boolean(item.done) !== done ? cleanItem({ ...item, done }, now) : item));
+}
+
+/**
+ * `items` without those a request takes out: `ids` (those ids), `done` (every one marked done), `all`: { items (the rest),
+ * removed (those taken out, as they were, for 撤销) }.
+ */
+export function withoutItems(items, { ids = [], done = false, all = false } = {}) {
+  const named = new Set(ids);
+  const takes = (item) => all || named.has(item.id) || (done && item.done === true);
+  return { items: items.filter((item) => !takes(item)), removed: items.filter(takes) };
+}
+
+/** The ids of `ids` that no item of `items` has. */
+export const unknownIds = (items, ids) => ids.filter((id) => !items.some((item) => item.id === id));
+
 /** The annotations of a file's text (annotations.json), those it holds that are not annotations left out. */
 export function readItems(text) {
   let data = null;
@@ -555,7 +574,7 @@ export function cardTops(items, front = null) {
  * the section bar's line at +12 to +16); the card's width by its words or blocks, in the column, where
  * the margin has no room for cards (those are margin.mjs's: MARGIN.card).
  */
-export const RAIL = Object.freeze({ marker: 24, markerAt: 14, bar: 7, card: 280 });
+export const RAIL = Object.freeze({ marker: 24, markerAt: 10, bar: 7, card: 280 });
 
 /**
  * Where a marker stands across a window `width` wide, the column's right edge being `right`: `markerAt`

package/browser/shared/block-packs.mjs

@@ -4,7 +4,7 @@ import { componentSettings, problemIn, writeComponentSettings } from "./componen
 import { refusal, said } from "./i18n/index.mjs";
 import { DEFAULT_PACK, OWN_SCOPE, PACK_FILE, PACK_ID, readPackManifest } from "./pack-manifest.mjs";
 import { packsDirectory } from "./paths.mjs";
-import { filesIn, fingerprintOf, fingerprintOfFiles, isSystemFile, recordOf, shippedBlocks, shippedPackIds, versionAfter, writeRecord, writingOrder } from "./shipped-blocks.mjs";
+import { filesIn, fingerprintOf, fingerprintOfFiles, followedAlready, isSystemFile, recordOf, shippedBlocks, shippedPackIds, versionAfter, writeRecord, writingOrder } from "./shipped-blocks.mjs";
 import { DEVICE_NAMES, PACKAGE_MANIFEST, layoutOf, markerOf, packageFolders } from "./workspace.mjs";
 
 // Block packs (自定义块包: notes/plans/block-packs-plan-2026-11-09.md; docs/render.md "Block packs"). A pack
@@ -312,6 +312,7 @@ export function workspacePacks(root, { settings = null, shippedIds = shippedPack
     for (const name of fs.readdirSync(components)) if (PACK_ID.test(name) && fs.existsSync(path.join(components, name, PACK_FILE))) scopes.add(name);
   } catch {}
   const switches = (settings ?? componentSettings(root)).packs ?? {};
+  let ownBlocks;
   const listed = [...scopes].map((id) => {
     const folder = path.join(components, id);
     let manifest = null;
@@ -348,8 +349,12 @@ export function workspacePacks(root, { settings = null, shippedIds = shippedPack
         return null;
       }
     };
-    const ownBlocks = official ? shippedBlocks(directory) : [];
-    const behind = official && shipped && changed.some((block) => (block.endsWith(`/${PACK_FILE}`) ? versionAfter(shipped.version, manifest?.version ?? null) : (ownBlocks.some((one) => one.id === block) && versionAfter(ownBlocks.find((one) => one.id === block).version, versionAt(block)))));
+    const behind = official && shipped && changed.some((block) => {
+      if (block.endsWith(`/${PACK_FILE}`)) return versionAfter(shipped.version, manifest?.version ?? null);
+      ownBlocks ??= new Map(shippedBlocks(directory).map((one) => [one.id, one]));
+      const own = ownBlocks.get(block);
+      return own && versionAfter(own.version, versionAt(block));
+    });
     const newer = behind ? shipped.version : null;
     const told = id === OWN_SCOPE ? DEFAULT_PACK : manifest ?? (problem ? null : shipped);
     return {
@@ -392,7 +397,8 @@ function installedLines(root, made, first) {
  * cannot be written leaves that pack for the next start), one installed is brought up to Gallery's.
  * `env`: whose NO_PACKS is read; `log`: told what was done, a line each. Never rejects: { did: "off"
  * (NO_PACKS), "unread" (gallery.json does not read as Gallery's) or "done", packs: [installPack's answer
- * with `first`, or { id, failed }] }.
+ * with `first`, or { id, failed }] }. The blocks it leaves as Gallery ships them (added, updated or the
+ * same) are followShipped's looked at (followedAlready): nothing for it to do of them in this process.
  */
 export async function installOfficialPacks(root, { directory = packsDirectory, env = process.env, log = () => {} } = {}) {
   if (packsSkipped(env)) return { did: "off", packs: [] };
@@ -402,6 +408,7 @@ export async function installOfficialPacks(root, { directory = packsDirectory, e
   } catch {}
   if (!marker.ours) return { did: "unread", packs: [] };
   const ids = shippedPackIds(directory);
+  const shipped = shippedBlocks(directory);
   const packs = [];
   for (const id of ids) {
     try {
@@ -409,6 +416,8 @@ export async function installOfficialPacks(root, { directory = packsDirectory, e
       if (first && OFF_AT_FIRST.includes(id) && componentSettings(root).packs[id] === undefined) await writeComponentSettings(root, { pack: id, enabled: false });
       const made = installPack(root, folderFiles(path.join(directory, id)), { official: true, shippedIds: ids });
       packs.push({ ...made, first });
+      const current = new Set([...made.added, ...made.updated, ...made.same]);
+      followedAlready(root, shipped.filter((block) => current.has(block.id)));
       for (const line of installedLines(root, made, first)) log(line);
     } catch (error) {
       log(`Gallery's pack ${id} could not be installed in ${path.resolve(root)}: ${error?.message ?? error}`);

package/browser/shared/document-look.mjs

@@ -123,6 +123,20 @@ export function ownLookFor(look, workspace) {
   return Object.fromEntries(Object.keys(LOOK).filter((key) => shown[key] !== base[key]).map((key) => [key, shown[key]]));
 }
 
+/** A legacy full-look request: retain explicit choices for fields whose displayed value did not change. */
+export function updatedOwnLook(own, workspace, look) {
+  const before = fullLook(effectiveLook(own, workspace));
+  const after = fullLook(look);
+  const changed = ownLookFor(look, workspace);
+  const kept = ownLookOf(own);
+  for (const key of Object.keys(LOOK)) {
+    if (before[key] === after[key]) continue;
+    if (Object.hasOwn(changed, key)) kept[key] = changed[key];
+    else delete kept[key];
+  }
+  return kept;
+}
+
 /**
  * A document's doc.json (its parsed object) with its own look as given (ownLookOf: an explicit default
  * kept): in the field's place when it had one, else last; the field gone when it makes no choice.

package/browser/shared/drafts.mjs

@@ -53,7 +53,7 @@ export const clashingIds = (ids = registeredIds()) => [...ids].filter(([, 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)]);
+  const [html, metadata] = await Promise.all([exists(files.html), fs.readFile(files.json, "utf8").then((text) => JSON.parse(text.replace(/^/, ""))).catch(() => null)]);
   return { files, html, metadata: metadata && typeof metadata === "object" && !Array.isArray(metadata) ? metadata : null };
 }
 

package/browser/shared/extension-manifest.mjs

@@ -6,6 +6,12 @@ import { isExtensionId } from "./outline-shape.mjs";
 import { sha256, writeAtomic } from "./files.mjs";
 import { withOutlineLock } from "./outline.mjs";
 
+// The recursive workspace watcher covers imported modules as well as manifest entries.
+// Requests never rescan the whole extension tree just to serve a single asset.
+const generations = new Map();
+let generation = 0;
+export function invalidateExtension(folder) { generations.set(path.resolve(folder), ++generation); }
+
 export const extensionDirectory = id => {
   if (!isExtensionId(id)) throw new Error("扩展 ID 不正确");
   return path.join(layoutOf(defaultWorkspace()).extensions, id);
@@ -42,42 +48,64 @@ export async function readManifest(folder) {
   const value = JSON.parse(text);
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("extension.json 必须是对象");
   if (value.id !== undefined && !isExtensionId(value.id)) throw new Error("扩展 ID 不正确");
+  for (const key of ["name", "version", "description"]) if (value[key] !== undefined && (typeof value[key] !== "string" || value[key].length > 1000)) throw new Error("扩展名称、版本和描述必须是短文本");
+  if (value.icon !== undefined) {
+    if (typeof value.icon !== "string" || !value.icon || value.icon.length > 256) throw new Error("icon 不正确");
+    if (/\.(?:png|jpe?g|webp|gif|svg)$/i.test(value.icon)) await extensionFile(folder, value.icon);
+    else if (value.icon.length > 16 || /[/\\]/.test(value.icon)) throw new Error("icon 必须是表情或扩展里的图片");
+  }
   if (value.workbench !== undefined && (!value.workbench || typeof value.workbench !== "object" || Array.isArray(value.workbench))) throw new Error("workbench 必须是对象");
   for (const name of [value.workbench?.script, value.workbench?.style, value.agent].filter(value => value !== undefined)) await extensionFile(folder, name);
   if (value.server !== undefined) {
     const command = value.server?.command;
     if (!Array.isArray(command) || !command.length || command.length > 32 || command.some(word => typeof word !== "string" || !word || word.includes("\0"))) throw new Error("server.command 必须是非空的参数数组");
+    if (value.server.timeout !== undefined && (!Number.isInteger(value.server.timeout) || value.server.timeout < 1000 || value.server.timeout > 600000)) throw new Error("server.timeout 必须是 1000 到 600000 毫秒");
   }
-  return { ...value, revision: sha256(text) };
+  // Files named by the manifest can change while extension.json stays byte-for-byte identical.
+  // Their metadata gives clients and the backend manager a fresh revision after a replacement.
+  const named = [value.workbench?.script, value.workbench?.style, ...(value.server?.command?.slice(1) ?? [])].filter(name => typeof name === "string" && !path.isAbsolute(name));
+  const stamps = await Promise.all(named.map(async name => {
+    try { const file = await extensionFile(folder, name); const stat = await fs.stat(file); return [name, stat.size, stat.mtimeMs]; } catch { return [name, null]; }
+  }));
+  return { ...value, revision: sha256(JSON.stringify([text, stamps, generations.get(path.resolve(folder)) ?? 0])) };
 }
 
 const configFile = () => path.join(defaultWorkspace(), "gallery.json");
 const configuration = async () => JSON.parse(await fs.readFile(configFile(), "utf8"));
 
-export async function listCapabilities() {
+export async function listCapabilities({ ids = null } = {}) {
   const config = await configuration();
-  return Promise.all((await extensionFolders(defaultWorkspace())).map(async ({ id, folder }) => {
+  const wantedIds = ids === null ? null : new Set(ids);
+  const folders = await extensionFolders(defaultWorkspace());
+  return Promise.all(folders.filter(({ id }) => !wantedIds || wantedIds.has(id)).map(async ({ id, folder }) => {
+    const wanted = config.extensions?.[id]?.enabled === true;
+    const configured = Object.hasOwn(config.extensions ?? {}, id);
     try {
       const manifest = await readManifest(folder);
-      const grant = config.extensions?.[id];
-      return { id, folder, manifest, enabled: grant?.enabled === true && grant.revision === manifest.revision,
-        confirmed: grant?.revision === manifest.revision, agent: manifest.agent ? path.join(folder, manifest.agent) : null };
+      return { id, folder, manifest, enabled: wanted, wanted, agent: manifest.agent ? path.join(folder, manifest.agent) : null };
     } catch (error) {
-      return { id, folder, enabled: false, confirmed: false, manifest: null, error: error.code === "ENOENT" ? null : error.message };
+      let message = error.message;
+      if (error.code === "ENOENT") {
+        const hasManifest = await fs.lstat(path.join(folder, "extension.json")).then(() => true, () => false);
+        const hasSidebar = await fs.lstat(path.join(folder, "sidebar.json")).then(() => true, () => false);
+        message = hasManifest ? "扩展引用的文件不存在" : (!configured && hasSidebar ? null : "找不到 extension.json");
+      }
+      return { id, folder, enabled: false, wanted, manifest: null, error: message };
     }
   }));
 }
 
-export async function setExtensionEnabled({ id, enabled, revision, confirmed = false }) {
+export async function setExtensionEnabled({ id, enabled }) {
   const folder = extensionDirectory(id);
   if (typeof enabled !== "boolean") throw new Error("扩展开关的值不正确");
   return withOutlineLock(defaultWorkspace(), async () => {
-    const manifest = await readManifest(folder);
-    if (manifest.revision !== revision) throw new Error("扩展刚刚更新，请重新打开设置");
+    if (enabled) await readManifest(folder);
+    else if (!(await fs.lstat(folder).catch(() => null))) throw new Error("找不到扩展");
     const config = await configuration();
-    if (enabled && config.extensions?.[id]?.revision !== revision && !confirmed) throw new Error("请先确认扩展的脚本和后台权限");
-    config.extensions = { ...config.extensions, [id]: { enabled, revision } };
+    if ((config.extensions?.[id]?.enabled === true) === enabled) return { changed: false };
+    config.extensions = { ...config.extensions, [id]: { enabled } };
     await writeAtomic(configFile(), JSON.stringify(config, null, 2) + "\n");
+    return { changed: true };
   });
 }
 

package/browser/shared/favorite-merge.mjs

@@ -0,0 +1,17 @@
+// What the workbench shows as 收藏 when it reads the list again (pure, so that the page imports it; the file side is ./favorites.mjs).
+// The browser keeps its own list (localStorage) and the user's data folder keeps one that gallery favorite and every browser share: `local`
+// is the browser's, `seen` what the shared list held when this browser last read it, `server` what it holds now. A three-way merge: an
+// entry the shared list dropped since (in `seen`, not in `server`) leaves the browser's; one it gained since (in `server`, not in `seen`)
+// joins it; one the browser took out since (in `seen` and `server`, not in `local`) stays out and is for the shared list to drop (`drop`:
+// a read that lands while the browser's own removal is on its way never brings the star back); one only the browser has is for the
+// shared list to take (`push`). The browser's order stays, the shared list's new entries last.
+export function mergeFavorites({ local, seen, server }) {
+  const gone = new Set(seen.filter((key) => !server.includes(key)));
+  const own = local.filter((key) => !gone.has(key));
+  const gained = server.filter((key) => !seen.includes(key) && !own.includes(key));
+  return {
+    favorites: [...own, ...gained],
+    push: own.filter((key) => !server.includes(key)),
+    drop: server.filter((key) => seen.includes(key) && !local.includes(key)),
+  };
+}

package/browser/shared/favorites.mjs

@@ -0,0 +1,77 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeAtomic } from "./files.mjs";
+import { entryPattern, isForeign } from "./outline-shape.mjs";
+import { outlineRoot, withOutlineLock } from "./outline.mjs";
+import { userDirectory } from "./user-directory.mjs";
+import { workspaceId, workspaceKey } from "./workspace-registry.mjs";
+
+// The sidebar's 收藏 (favorites): entries (a slug of the workspace, a web link's, or "~<ws id>/<slug>" for a draft of
+// another workspace) the reader starred. The workbench keeps them in its browser (localStorage, which no command can
+// reach) and, since gallery favorite, in favorites.json of the user's data folder too (beside the registry of
+// workspaces: ./user-directory.mjs), as the one place a gallery command and the browsers of this machine share; never
+// in a workspace's files: a star is the reader's, not the project's (a workspace synced or shared carries none). The
+// list is written under the default workspace's outline lock; its keys are the ones the default
+// workspace's sidebar names the entries by, so that a workspace's own entries are plain slugs there and another
+// workspace's are "~<ws id>/<slug>" (the projection ./outline.mjs does for the tree): `favoriteKey` and `favoriteSlug`
+// turn one into the other for a command working in a workspace other than the default.
+
+const readJson = (file) => fs.readFile(file, "utf8").then(JSON.parse).catch(() => null);
+
+/** The file the shared list is kept in: favorites.json of the user's data folder (GALLERY_DATA_DIR in the tests). */
+export const favoritesFile = () => path.join(userDirectory("data"), "favorites.json");
+
+/** The key entry `slug` of workspace `root` has in the stored list: plain in the default workspace, "~<id>/<slug>" elsewhere. */
+export function favoriteKey(root, slug) {
+  const home = outlineRoot(root);
+  if (workspaceKey(root) === workspaceKey(home)) return slug;
+  const homes = `~${workspaceId(home)}/`;
+  if (slug.startsWith(homes)) return slug.slice(homes.length); // the default workspace's own, as the file names them
+  return isForeign(slug) ? slug : `~${workspaceId(root)}/${slug}`;
+}
+
+/** A stored key as workspace `root`'s sidebar names the entry (its own entries lose the prefix, the default workspace's gain one: the projection ./outline.mjs does for the tree). */
+export function favoriteSlug(root, key) {
+  const home = outlineRoot(root);
+  if (workspaceKey(root) === workspaceKey(home)) return key;
+  const prefix = `~${workspaceId(root)}/`;
+  if (key.startsWith(prefix)) return key.slice(prefix.length);
+  return isForeign(key) ? key : `~${workspaceId(home)}/${key}`; // the default workspace's own entries are another workspace's drafts here
+}
+
+/** The favorites as a file holds them: entries once each, only valid ones. */
+const kept = (value) => [...new Set((Array.isArray(value) ? value : []).filter((entry) => typeof entry === "string" && entryPattern.test(entry)))];
+
+/**
+ * The file's lists are kept by the default workspace whose sidebar they belong to (`workspaces`: its id -> its list), so that
+ * another default workspace (GALLERY_DEFAULT_WORKSPACE, a test's) never sees a list that names other entries.
+ */
+const listIn = (document, root) => kept(document?.workspaces?.[workspaceId(outlineRoot(root))]);
+
+/** The stored favorites seen from workspace `root` (its own entries as plain slugs). Read alone. */
+export async function readFavorites(root) {
+  return listIn(await readJson(favoritesFile()), root).map((key) => favoriteSlug(root, key));
+}
+
+/**
+ * Favorites changed in the stored list under the outline's lock: `add` and `remove` are entries as workspace `root`'s
+ * sidebar names them. Resolves to { favorites (seen from `root`), changed }. The other default workspaces' lists stay as they are.
+ */
+export function changeFavorites(root, { add = [], remove = [] }) {
+  return withOutlineLock(root, async () => {
+    const file = favoritesFile();
+    const value = await readJson(file);
+    const document = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    const id = workspaceId(outlineRoot(root));
+    const before = listIn(document, root);
+    const dropped = new Set(kept(remove).map((slug) => favoriteKey(root, slug)));
+    const after = [...before.filter((key) => !dropped.has(key)), ...kept(add).map((slug) => favoriteKey(root, slug)).filter((key) => !before.includes(key))];
+    const changed = JSON.stringify(before) !== JSON.stringify(after);
+    if (changed) {
+      await fs.mkdir(path.dirname(file), { recursive: true });
+      const workspaces = document.workspaces && typeof document.workspaces === "object" && !Array.isArray(document.workspaces) ? document.workspaces : {};
+      await writeAtomic(file, `${JSON.stringify({ version: 1, workspaces: { ...workspaces, [id]: after } }, null, 2)}\n`);
+    }
+    return { favorites: after.map((key) => favoriteSlug(root, key)), changed };
+  });
+}