@heycys/gallery 0.1.1 → 0.1.2

package/browser/shared/pages.mjs

@@ -0,0 +1,388 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { escapeMarkup, escapeText } from "./escape.mjs";
+import { writeAtomic } from "./files.mjs";
+import { laidOut } from "./json-layout.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.
+
+/** 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. */
+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.
+ */
+export const HOME_CARDS = Object.freeze(["gallery/today", "gallery/note", "gallery/todos", "gallery/recent", "gallery/stats", "gallery/heatmap"]);
+/**
+ * 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
+ * others (homeCardsTold, the home page's note of new cards).
+ */
+export const FIRST_HOME_CARDS = Object.freeze(["gallery/today", "gallery/note"]);
+/** The board a new page has, and the board gallery page add puts a card on when none is named. */
+export const FIRST_BOARD = "main";
+/** Whether `name` is one of a custom page's own files. */
+export const isPageFile = (name) => name === PAGE_FILES.html || name === PAGE_FILES.json;
+
+/**
+ * Where custom page `slug` is: <root>/pages/<slug>/, and its two files and its own files' folder
+ * (assets/, which the server serves at /pages/<slug>/assets/<file>). Where pages/ has no folder of
+ * that name, a scratch copy's of .gallery/try/ that holds a page.html (gallery page try's and gallery
+ * page check's, try-<8 hex>: src/cli/page-try.mjs, served and written as any page's, listed nowhere,
+ * gone once its command ends), as a document's slug finds one (workspace.mjs documentDirectory).
+ */
+export function pageFiles(slug, root) {
+  const { customPages, scratch } = layoutOf(root);
+  const own = path.join(customPages, slug);
+  const copy = path.join(scratch, slug);
+  const folder = !existsSync(own) && existsSync(path.join(copy, PAGE_FILES.html)) ? copy : own;
+  return { folder, html: path.join(folder, PAGE_FILES.html), json: path.join(folder, PAGE_FILES.json), assets: path.join(folder, PAGE_ASSETS) };
+}
+
+/** The folder of a custom page's own files (pictures a card shows), in its folder: served at /pages/<slug>/assets/<file>. */
+export const PAGE_ASSETS = "assets";
+
+/** Where the server serves file `value` of custom page `slug`'s assets/ (`value`: assets/<file>, as a page writes it). */
+export const pageAssetAddress = (slug, value) => `/pages/${slug}/${value}`;
+
+/** Whether custom page `slug` is there: its folder holds page.html. */
+export const pageExists = (slug, root) => isSlugName(slug) && existsSync(pageFiles(slug, root).html);
+
+/**
+ * Why `slug` names no new custom page in workspace `root`, or null: not lowercase kebab-case; a name
+ * the workspace keeps (exports, components, pages…); assets or materials, which a document called
+ * pages keeps in that folder; taken by a document, the 写作偏好 page or another custom page (one pool,
+ * ./workspace.mjs slugTaken); a slug the trash holds, whose address would open the new page.
+ */
+export async function pageSlugRefused(slug, root) {
+  if (typeof slug !== "string" || !slugPattern.test(slug)) return `"${slug}" is no slug: lowercase letters, digits and single hyphens (reading-list).`;
+  if (keptName(slug) || DOCUMENT_FOLDERS.includes(slug)) return `"${slug}" is a name the workspace keeps for itself: choose another slug.`;
+  if (existsSync(pageFiles(slug, root).folder)) return `A custom page "${slug}" exists already: ${pageFiles(slug, root).folder}`;
+  if (slugTaken(slug, root)) return `"${slug}" is a document's slug (documents and custom pages share one set of names): choose another slug.`;
+  if ((await listTrash(root)).some((entry) => entry.slug === slug)) return `"${slug}" is the slug of something in the trash: choose another slug.`;
+  return null;
+}
+
+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) }. */
+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 };
+}
+
+/** Custom page `slug` as a list shows it: { slug, title, icon }, 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)) };
+}
+
+/**
+ * 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
+ * not read: { order: [], homeMade: false }.
+ */
+export function pagesSettings(root) {
+  let value = null;
+  try {
+    value = markerOf(readFileSync(layoutOf(root).marker, "utf8")).value;
+  } catch {}
+  const pages = value?.pages && typeof value.pages === "object" && !Array.isArray(value.pages) ? value.pages : {};
+  const order = Array.isArray(pages.order) ? pages.order.filter((slug, at, all) => typeof slug === "string" && all.indexOf(slug) === at) : [];
+  return { order, homeMade: pages.homeMade === true };
+}
+
+/**
+ * Write into workspace `root`'s gallery.json that the default home page was made (the spec §2's
+ * pages.homeMade), every other key and value of it kept as it was (its pages.order too), and the file's
+ * own layout with them (homeMadeIn: a write no reader asked for, on a workspace's first start of a
+ * Gallery that makes the home page, changes no line but those it adds). Resolves to true once it says
+ * so; false where gallery.json does not read as Gallery's, which nothing then writes over (the home
+ * waits for a gallery.json that reads: made once, and said so). Throws where it cannot be written
+ * (writeAtomic's EPERM, EBUSY…: makeDefaultHome says so).
+ */
+export async function markHomeMade(root) {
+  const file = layoutOf(root).marker;
+  for (let tries = 0; tries < 3; tries++) {
+    const text = await fs.readFile(file, "utf8").catch(() => null);
+    if (text === null) return false;
+    const { value, ours } = markerOf(text);
+    if (!ours || !value || typeof value !== "object" || Array.isArray(value)) return false;
+    const pages = value.pages && typeof value.pages === "object" && !Array.isArray(value.pages) ? value.pages : {};
+    if (pages.homeMade === true) return true;
+    const wanted = { ...value, pages: { ...pages, homeMade: true } };
+    let next = null;
+    try {
+      next = homeMadeIn(text);
+    } catch {}
+    // What the text says once written is checked: any doubt (a key twice, say), the whole file written as JSON.stringify lays it out.
+    if (next === null || !isDeepStrictEqual(markerOf(next).value, wanted)) next = `${JSON.stringify(wanted, null, 2)}\n`;
+    if (await writeAtomic(file, next, { expect: text })) return true;
+  }
+  return false;
+}
+
+// gallery.json's text (`text`, a JSON object that reads: markerOf) with pages.homeMade true, written into
+// it as it stands: its line ends, indentation, BOM, what stands on one line kept, the new member laid out
+// as the one before it is (on a line of its own at its indentation, the file's own indentation inside
+// it, or on its line after it, as tightly as it is), a value that is not true or a pages that is no
+// object (or an empty one) replaced in its place. Never more than that member's text changes.
+function homeMadeIn(text) {
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const top = objectAt(text, text.indexOf("{"));
+  const unit = top.members.map((member) => ownLine(text, top.open, member)).find(Boolean) ?? "  ";
+  const blanksBefore = (member) => /[ \t]*$/.exec(text.slice(0, member.from))[0];
+  // `value`'s text where `member` stands: lines of its own from `indent`, or on one line (spaced as `spaced` says).
+  const laid = (value, indent, spaced) => (indent !== null ? JSON.stringify(value, null, unit).split("\n").join(eol + indent) : spaced ? laidOut(value, "") : JSON.stringify(value));
+  const added = (object, key, value) => {
+    const last = object.members.at(-1);
+    const indent = ownLine(text, object.open, last);
+    const gap = indent !== null ? eol + indent : blanksBefore(last);
+    return `${text.slice(0, last.end)},${gap}${JSON.stringify(key)}:${last.colon}${laid(value, indent, gap !== "")}${text.slice(last.end)}`;
+  };
+  const replaced = (object, member, value) => `${text.slice(0, member.value)}${laid(value, ownLine(text, object.open, member), blanksBefore(member) !== "")}${text.slice(member.end)}`;
+  const pages = top.members.findLast(({ key }) => key === "pages");
+  if (!pages) return added(top, "pages", { homeMade: true });
+  const inner = text[pages.value] === "{" ? objectAt(text, pages.value) : null;
+  if (!inner?.members.length) return replaced(top, pages, { homeMade: true });
+  const made = inner.members.findLast(({ key }) => key === "homeMade");
+  return made ? replaced(inner, made, true) : added(inner, "homeMade", true);
+}
+
+const blank = (char) => char === " " || char === "\t" || char === "\n" || char === "\r";
+
+// Where the JSON value starting at `at` in `text` ends (the index past it), in JSON that reads; past the
+// text's end, a throw (homeMadeIn's caller then lays the whole file out), never a loop that does not end.
+function pastValue(text, at) {
+  if (text[at] === '"') {
+    let next = at + 1;
+    while (text[next] !== '"') {
+      if (next >= text.length) throw new Error("unended string");
+      next += text[next] === "\\" ? 2 : 1;
+    }
+    return next + 1;
+  }
+  if (text[at] === "{" || text[at] === "[") {
+    for (let next = at, depth = 0; ; next++) {
+      if (next >= text.length) throw new Error("unended " + text[at]);
+      const char = text[next];
+      if (char === '"') next = pastValue(text, next) - 1;
+      else if (char === "{" || char === "[") depth++;
+      else if ((char === "}" || char === "]") && --depth === 0) return next + 1;
+    }
+  }
+  let next = at;
+  while (next < text.length && !blank(text[next]) && !",}]".includes(text[next])) next++;
+  return next;
+}
+
+/**
+ * The object whose "{" is at `open` in `text`: { open, members: [{ key, from (its key's quote), value
+ * (where its value starts), end (past it), colon (the blanks after its colon) }] }. Also what
+ * ./workspace-name.mjs writes gallery.json's name by.
+ */
+export function objectAt(text, open) {
+  const members = [];
+  let at = open + 1;
+  const skip = () => {
+    while (blank(text[at])) at++;
+  };
+  skip();
+  while (text[at] !== "}") {
+    const from = at;
+    at = pastValue(text, at);
+    const key = JSON.parse(text.slice(from, at));
+    skip();
+    const colon = ++at;
+    skip();
+    const value = at;
+    at = pastValue(text, at);
+    members.push({ key, from, value, end: at, colon: text.slice(colon, value) });
+    skip();
+    if (text[at] === ",") at++;
+    skip();
+  }
+  return { open, members };
+}
+
+/** The indentation `member` of the object opening at `open` stands at on a line of its own, or null where it shares its line. */
+export function ownLine(text, open, member) {
+  const start = text.lastIndexOf("\n", member.from - 1) + 1;
+  const before = text.slice(start, member.from);
+  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.
+function hintsOf(root) {
+  try {
+    const value = JSON.parse(readFileSync(layoutOf(root).hints, "utf8"));
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Whether the reader closed the home page'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";
+
+/**
+ * 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.
+ */
+export function homeCardsTold(root) {
+  const told = hintsOf(root).homeCards;
+  return Array.isArray(told) && told.every((id) => typeof id === "string") ? told : [...FIRST_HOME_CARDS];
+}
+
+/**
+ * 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.
+ */
+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. */
+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 }].
+ */
+export function inPageOrder(pages, order = []) {
+  const rank = (slug) => (slug === HOME ? -1 : 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. */
+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);
+}
+
+/**
+ * A page's version as the event stream says it (`page <version>`, the spec §7): its page.html and
+ * page.json as they are, 16 hex digits. The page compares it with the one it was served with.
+ */
+export function pageVersion(html, json = "") {
+  return createHash("sha256").update(html ?? "").update("\u0000").update(json ?? "").digest("hex").slice(0, 16);
+}
+
+/** A page's version as its files are now (pageVersion). */
+export async function pageVersionNow(slug, root) {
+  const { html, json } = pageFiles(slug, root);
+  const [page, meta] = await Promise.all([fs.readFile(html, "utf8").catch(() => ""), fs.readFile(json, "utf8").catch(() => "")]);
+  return pageVersion(page, meta);
+}
+
+/**
+ * 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).
+ */
+export function newPageHtml(slug, title, { lang = "zh-CN" } = {}) {
+  return `<!doctype html>
+<html lang="${escapeMarkup(lang)}">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeText(title)}</title>
+  <style>
+    /* This page's own look. Colors of its own are written for both themes:
+       :root[data-doc-effective-theme="dark"] { … } holds the dark ones. */
+  </style>
+</head>
+<body>
+  <main class="gallery-page" data-page-id="${slug}">
+    <div class="gallery-board" data-board-id="${FIRST_BOARD}">
+    </div>
+  </main>
+</body>
+</html>
+`;
+}
+
+/**
+ * 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.
+ */
+export async function createPage(slug, title, { root, icon = null, lang } = {}) {
+  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`);
+  return files;
+}
+
+/**
+ * Custom page `slug`'s title written into its page.json (the workbench's 重命名), every other field as
+ * it was; page.html is not touched (its <title> and header are the Agent's). Resolves to its meta, or
+ * null when the page is not there; throws for a title that is empty or longer than 200 characters.
+ */
+export async function renamePage(slug, title, root) {
+  const name = typeof title === "string" ? title.replace(/\s+/g, " ").trim() : "";
+  if (!name || name.length > 200) throw Object.assign(new Error("A page's title is 1 to 200 characters."), { code: "title" });
+  if (!pageExists(slug, root)) return null;
+  const { json } = pageFiles(slug, root);
+  for (let tries = 0; tries < 3; tries++) {
+    const text = await fs.readFile(json, "utf8").catch(() => null);
+    let value = {};
+    try {
+      value = text === null ? {} : JSON.parse(text.replace(/^/, ""));
+    } catch {}
+    if (!value || typeof value !== "object" || Array.isArray(value)) value = {};
+    const next = `${JSON.stringify({ ...value, title: name }, null, 2)}\n`;
+    const written = text === null ? (await fs.writeFile(json, next, { flag: "wx" }).then(() => true, () => false)) : await writeAtomic(json, next, { expect: text });
+    if (written) break;
+  }
+  return readPageMeta(slug, root);
+}

package/browser/shared/paths.mjs

@@ -51,6 +51,12 @@ export const previewLogFile = workspace.serverLog;
 const inPackage = (built, ...source) => path.join(packageRoot, ...(release ? built : source));
 export const kitSourceDirectory = path.join(packageRoot, "src", "render", "kit"); // the source checkout's only
 export const starterDirectory = inPackage(["starter"], "src", "render", "starter");
+/**
+ * Gallery's own block packs (自定义块包), a folder each (src/packs/<pack>/: its pack.json and a folder of each
+ * of its blocks, <pack>/<name>/, the scope <pack>): what a workspace's first start installs as any shared
+ * pack is installed, and gallery block add copies a block of (shared/block-packs.mjs, shared/shipped-blocks.mjs).
+ */
+export const packsDirectory = inPackage(["packs"], "src", "packs");
 export const vendorDirectory = inPackage(["vendor"], "public", "vendor");
 export const kitPublicDirectory = inPackage(["kit"], "public", "kit");
 /** The editor's browser modules, at their path under src/ (the preview serves them so: src/server/routes.mjs). */

package/browser/shared/preview-server.mjs

@@ -4,6 +4,7 @@ import fs from "node:fs/promises";
 import net from "node:net";
 import path from "node:path";
 import { packageRoot } from "./paths.mjs";
+import { compareVersions } from "./versions.mjs";
 import { layoutOf } from "./workspace.mjs";
 
 // Where a workspace's Gallery server listens (one a gallery command started, kind "cli", or npm run
@@ -168,13 +169,8 @@ export const portIsFree = (port) => new Promise((resolve) => {
   }));
 });
 
-/** -1, 0 or 1 as version `a` is older than, the same as or newer than `b` (numbers by dots: 0.1.0 < 0.1.10 < 0.2.0). */
-export function compareVersions(a, b) {
-  const parts = (version) => String(version ?? "0").split(/[.+-]/).slice(0, 3).map((part) => Number.parseInt(part, 10) || 0);
-  const [x, y] = [parts(a), parts(b)];
-  for (let index = 0; index < 3; index++) if ((x[index] ?? 0) !== (y[index] ?? 0)) return (x[index] ?? 0) < (y[index] ?? 0) ? -1 : 1;
-  return 0;
-}
+/** -1, 0 or 1 as version `a` is older than, the same as or newer than `b` (./versions.mjs, which gallery --version reads too). */
+export { compareVersions };
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 // Whether process `pid` is gone within `ms` (asked every 100 ms).

package/browser/shared/session.mjs

@@ -1,7 +1,9 @@
 // The session between a report page and a workbench that shows it in an iframe of the same origin
 // (docs/workbench.md): the page's side is src/editor/page/session.mjs, the workbench's
 // src/workbench/app/session/. Every message is { protocol: PROTOCOL, v: VERSION, type, slug, ... },
-// posted to the other window for this origin only.
+// posted to the other window for this origin only; or, for a draft of another workspace, between the
+// page and a workbench of another origin each side's server vouched for (the page's ?shell=<origin>,
+// GET /__gallery/workspace/shell; the workbench's POST elsewhere: src/workbench/elsewhere.mjs).
 //
 //   report -> workbench   ready    once the editor started: { commands, title, icon, look, state, annotations, card }
 //                         state    when the state, the title, the page's icon, the look it shows, how many 批注 it
@@ -31,9 +33,14 @@
 //                         workspace a page was made under this one (a page block's box, the page itself
 //                                  staying as it is): the workbench reads the list of pages again and
 //                                  shows this page's row open
+//                         consent  a block's card asks to be let online (its 允许访问: the kit's net.js):
+//                                  { block (its id), hosts (those of its needs waiting) }: the workbench
+//                                  opens its consent dialog, which writes what the reader says
 //                         annotations-removed
 //                                  a 批注 deleted from its card: { items }: the workbench says so, as
 //                                  it does for 全部删除, and its 撤销 puts them back
+//                         bye      the page goes (pagehide), to a workbench of another origin alone, which
+//                                  cannot see it go: its session ends there
 //   workbench -> report   command  { id, name, ... }
 
 export const PROTOCOL = "gallery/session";