@heycys/gallery 0.1.0 → 0.1.2

package/browser/shared/workspace-columns.mjs

@@ -0,0 +1,120 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { iconKind } from "./emoji/icon-value.mjs";
+import { isWorkspace, readRegistry, workspaceId, workspaceKey } from "./workspace-registry.mjs";
+import { defaultWorkspace, documentFiles, isSlugName } from "./workspace.mjs";
+
+// The other workspaces a workspace's sidebar shows a column of (notes/plans/workspaces-links-plan-2026-11-08.md
+// §7.2; docs/workbench.md "Columns"): every workspace of the machine's registry (./workspace-registry.mjs) but
+// this one, a clash of ids (two registered folders sharing one: never guessed) and one whose folder is no
+// workspace now (an external drive away), in this order: the default workspace (./workspace.mjs
+// defaultWorkspace, GALLERY_DEFAULT_WORKSPACE honoured) first, the rest as they were registered. The outline
+// (./outline.mjs) gives each a column the first time it reads it (a "whole" one, all its documents, laid out
+// as its own sidebar has them) and the place of its documents no column holds; the user's order of the
+// columns is the outline's after that.
+//
+// What a workspace's sidebar is read with (snapshotOf): its documents in its own sidebar's order, the document
+// each is under there (a web link or another workspace's draft passed over upward), and what its doc.json
+// says (title, description, an icon of the emoji or 图标 kind: no picture of another workspace's folder). It is
+// read from its files, never written, and kept SNAPSHOT_KEPT ms at most, so that the reads of a burst (a
+// command and the workbench's read after it, the list of 添加其他 Gallery 项目…) read each folder once while a
+// change there shows at the next read after that; the server drops one at once when that workspace's own
+// server tells of a change (src/workbench/service.mjs, through ./elsewhere.mjs). Reads files only.
+
+/** How long a snapshot of another workspace is believed (ms). */
+export const SNAPSHOT_KEPT = 2000;
+
+/**
+ * The registered workspaces by their ids: a Map of id to the roots registered under it (two for one id: a clash
+ * of the hash's six digits, which names neither). `registry`: readRegistry()'s.
+ */
+export function idsOf(registry = readRegistry()) {
+  const ids = new Map();
+  for (const { root } of registry.workspaces) {
+    const id = workspaceId(root);
+    const roots = ids.get(id) ?? [];
+    if (!roots.some((each) => workspaceKey(each) === workspaceKey(root))) roots.push(root);
+    ids.set(id, roots);
+  }
+  return ids;
+}
+
+/**
+ * The other workspaces whose columns the sidebar of workspace `root` shows: [{ id, root, isDefault }], the
+ * default workspace first (when it is registered and not `root`), then the registry's order.
+ */
+export function shownWorkspaces(root, { registry = readRegistry(), env = process.env } = {}) {
+  const own = workspaceKey(root);
+  const home = workspaceKey(defaultWorkspace({ env }));
+  const shown = [];
+  for (const [id, roots] of idsOf(registry)) {
+    if (roots.length !== 1) continue;
+    const [each] = roots;
+    if (workspaceKey(each) === own || !isWorkspace(each)) continue;
+    shown.push({ id, root: each, isDefault: workspaceKey(each) === home });
+  }
+  return [...shown.filter(({ isDefault }) => isDefault), ...shown.filter(({ isDefault }) => !isDefault)];
+}
+
+const oneLine = (value) => (typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "");
+/** A draft's page icon as another workspace's sidebar may show it: an emoji or a glyph of the 图标 tab. */
+export const shownIcon = (value) => (typeof value === "string" && ["emoji", "glyph"].includes(iconKind(value)) ? value : null);
+
+const kept = new Map(); // a workspace's key -> { at, value: Promise }
+
+/**
+ * What the sidebar reads of workspace `root` (another's): { documents: Set of slugs, order: [slug] (its own
+ * sidebar's order, column after column, each entry followed by those under it), parentOf: Map of slug to the
+ * document it is under there (null at a column's top), facts: Map of slug to { title, description, icon, path
+ * (its doc.html, an old one's report.html) } }. `readOwn(root)`: its outline as its own sidebar has it (no
+ * column of any other workspace: ./outline.mjs readOutline with others false). Kept SNAPSHOT_KEPT ms.
+ */
+export function snapshotOf(root, readOwn, { now = Date.now() } = {}) {
+  const key = workspaceKey(root);
+  const known = kept.get(key);
+  if (known && now - known.at < SNAPSHOT_KEPT) return known.value;
+  const value = read(root, readOwn);
+  kept.set(key, { at: now, value });
+  value.catch(() => kept.delete(key));
+  return value;
+}
+
+/** Forget what was read of workspace `root` (none: of every workspace), so that the next read reads it again. */
+export function forgetSnapshot(root = null) {
+  if (root === null) kept.clear();
+  else kept.delete(workspaceKey(root));
+}
+
+async function read(root, readOwn) {
+  const own = await readOwn(root);
+  const documents = new Set();
+  const order = [];
+  const parentOf = new Map();
+  // Its documents alone: its web links, the drafts of others its tree shows and a folder named by no slug are none.
+  const isDocument = (key) => !own.links.includes(key) && !key.startsWith("~") && isSlugName(key);
+  const parentIn = (child) => {
+    for (const [key, list] of Object.entries(own.children)) if (list.includes(child)) return key;
+    return null;
+  };
+  const above = (slug) => {
+    let up = parentIn(slug);
+    while (up !== null && !(up === "" || up.startsWith(":")) && !isDocument(up)) up = parentIn(up);
+    return up === null || up === "" || up.startsWith(":") ? null : up;
+  };
+  const walk = (key) => (own.children[key] ?? []).forEach((slug) => {
+    if (isDocument(slug) && !documents.has(slug)) {
+      documents.add(slug);
+      order.push(slug);
+      parentOf.set(slug, above(slug));
+    }
+    walk(slug);
+  });
+  for (const { id } of own.groups) walk(id === "docs" ? "" : `:${id}`);
+  const facts = new Map(await Promise.all(order.map(async (slug) => {
+    const files = documentFiles(path.join(root, slug));
+    const metadata = await fs.readFile(files.json, "utf8").then((text) => JSON.parse(text.replace(/^/, "")), () => null);
+    const value = metadata && typeof metadata === "object" && !Array.isArray(metadata) ? metadata : {};
+    return [slug, { title: oneLine(value.title) || slug, description: oneLine(value.description), icon: shownIcon(value.icon), path: files.html }];
+  })));
+  return { documents, order, parentOf, facts };
+}

package/browser/shared/workspace-look.mjs

@@ -0,0 +1,91 @@
+import { existsSync, readFileSync } from "node:fs";
+import fs from "node:fs/promises";
+import { effectiveLook, lookOf, withLookField } from "./document-look.mjs";
+import { writeAtomic } from "./files.mjs";
+import { refusal, said } from "./i18n/index.mjs";
+import { WORKSPACE_MARK, documentDirectory, documentFiles, layoutOf, markerOf } from "./workspace.mjs";
+
+// The workspace's default look (字体与布局's 应用到全部文档, src/shared/document-look.mjs): `look` in its
+// gallery.json, beside what the file says of the components, each choice that is not the default
+// kept and the field gone when none is. A document shows its own choices (doc.json's `look`) over it,
+// choice by choice, and a document with none of its own, a new one among them, shows it whole. A
+// workspace without it, an older one's, has every choice at its default. The 写作偏好 page (a doc.json
+// marked "instructions": true) has no look, the workspace's or its own. Here for the server alone: the
+// render, the workbench's service and the preview's watcher read it from disk; a page and the
+// workbench's app are told the look a document shows.
+
+// gallery.json as it reads now: what it holds when it is ours (a workspace without one holds nothing),
+// else why it cannot be taken (its components' messages: src/shared/component-catalog.mjs).
+const UNREAD = said("gallery.json 读不出来：改好这个文件后再试");
+const NOT_OURS = said("gallery.json 不是 Gallery 的文件");
+const NOT_WRITABLE = ["EPERM", "EACCES", "EBUSY", "EROFS"];
+function settingsOf(text) {
+  if (text === null) return { value: null };
+  const { value, ours, reads } = markerOf(text);
+  return ours ? { value } : { problem: reads ? NOT_OURS : UNREAD };
+}
+const readText = (file) => {
+  try {
+    return readFileSync(file, "utf8");
+  } catch (error) {
+    return error.code === "ENOENT" ? null : undefined;
+  }
+};
+
+/** The workspace's default look at `root` (lookOf's form), {} for none, for no gallery.json and for one that does not read or is not ours. */
+export function workspaceLook(root) {
+  const text = readText(layoutOf(root).marker);
+  return text === undefined ? {} : lookOf(settingsOf(text).value?.look);
+}
+
+/**
+ * What document `slug`'s doc.json says of its look at `root`: { own: its `look` as written (null for
+ * none, for a doc.json that does not read and for none at all), instructions: whether it is the 写作偏好
+ * page's, reads: whether what it says can be taken, which a doc.json an Agent is writing may not, a
+ * moment; a document with no doc.json at all (one made by hand: its doc.html alone) says it has no look
+ * of its own, and reads, while one whose folder is gone says nothing }.
+ */
+export function ownLookAt(slug, root) {
+  const files = documentFiles(documentDirectory(slug, root));
+  try {
+    const metadata = JSON.parse(readFileSync(files.json, "utf8"));
+    const reads = Boolean(metadata) && typeof metadata === "object" && !Array.isArray(metadata);
+    return { own: reads ? (metadata.look ?? null) : null, instructions: reads && metadata.instructions === true, reads };
+  } catch (error) {
+    return { own: null, instructions: false, reads: error.code === "ENOENT" && existsSync(files.html) };
+  }
+}
+
+/**
+ * The look document `slug` of the workspace at `root` shows (lookOf's form, {} for the default): its
+ * own over the workspace's (effectiveLook); the workspace's for a doc.json that does not read, none
+ * for the 写作偏好 page.
+ */
+export function documentLook(slug, root) {
+  const { own, instructions } = ownLookAt(slug, root);
+  return instructions ? {} : effectiveLook(own, workspaceLook(root));
+}
+
+/**
+ * gallery.json with `look` as the workspace's default look (lookOf: each default left out, the field
+ * gone when all are), written at once and with all else it holds kept, made when there is none. A
+ * file that does not read, is another program's, changed under this write or cannot be written is
+ * refused (an error that says why: refusal), and stays as it is.
+ */
+export async function writeWorkspaceLook(root, look) {
+  const file = layoutOf(root).marker;
+  const text = await fs.readFile(file, "utf8").catch((error) => {
+    if (error.code === "ENOENT") return null;
+    throw refusal(UNREAD);
+  });
+  const { value, problem } = settingsOf(text);
+  if (problem) throw refusal(problem);
+  if (value === null && Object.keys(lookOf(look)).length === 0) return; // no file, and none needed for the default
+  const written = withLookField(value ?? WORKSPACE_MARK, lookOf(look)); // in its place, else last; gone for the default
+  if (JSON.stringify(written) === JSON.stringify(value)) return;
+  const done = await writeAtomic(file, `${JSON.stringify(written, null, 2)}\n`, { expect: text }).catch((error) => {
+    if (NOT_WRITABLE.includes(error.code)) throw refusal(said("gallery.json 写不进去：可能是只读的，或被别的程序占着"));
+    throw error;
+  });
+  if (!done) throw refusal(said("gallery.json 刚刚被改过：再试一次"));
+}

package/browser/shared/workspace-name.mjs

@@ -0,0 +1,154 @@
+import { readFileSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { writeAtomic } from "./files.mjs";
+import { objectAt, ownLine } from "./pages.mjs";
+import { documentsFolder, layoutOf, markerOf, WORKSPACE_MARK } from "./workspace.mjs";
+
+// What a workspace is called where Gallery names it beside others (gallery workspaces, gallery list
+// --all, and the sidebar's column of another workspace: notes/plans/workspaces-links-plan-2026-11-08.md
+// §0): its own name, `name` in its gallery.json (gallery init --name, gallery workspaces --name, the
+// user in the sidebar); else its folder's name, climbing past a name that says nothing of the project
+// (GENERIC_NAMES: D:\proj\outputs\gallery is "proj") but never to the user's home, their Documents
+// folder or a drive's root (~/Documents/Gallery stays "Gallery"; a workspace that is a drive's root
+// is called by the drive, "E:"). Two of the same name are told apart by the folder above the one
+// named, which the sidebar writes after the name in grey (workspaceLabels), and where that is called
+// alike too, by the workspace's own path; the path is otherwise shown on hover and in the menus, never
+// as the name, and no workspace is numbered. Reads files only, but writeWorkspaceName.
+
+/** The folders' names that say nothing of a project, passed over upward (upper and lower case alike). */
+export const GENERIC_NAMES = ["gallery", "docs", "outputs", "reports", "文档"];
+/** The longest name a workspace is given, in characters. */
+export const NAME_LIMIT = 80;
+
+const isGeneric = (name) => GENERIC_NAMES.includes(name.toLowerCase());
+const keyOf = (folder, platform) => (platform === "win32" ? path.resolve(folder).toLowerCase() : path.resolve(folder));
+const oneLine = (value) => (typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "");
+// A folder's name; a drive's root, which has none, by the drive ("E:", "/").
+const folderName = (folder) => path.basename(folder) || folder.replace(/[\\/]+$/, "") || folder;
+
+/**
+ * What a name given to a workspace is wrong in, or null: empty, longer than NAME_LIMIT characters, or
+ * holding a control character (a line break among them).
+ */
+export function nameProblem(name) {
+  if (typeof name !== "string" || !name.trim()) return "A workspace's name holds a word at least.";
+  if (/[\u0000-\u001f\u007f]/.test(name)) return "A workspace's name is one line, with no control character.";
+  if ([...name.trim()].length > NAME_LIMIT) return `A workspace's name is ${NAME_LIMIT} characters at most.`;
+  return null;
+}
+
+/** The workspace's own name at `root` (gallery.json's `name`, on one line), or null: none, or a gallery.json that is not ours or does not read. */
+export function ownName(root, { readText = (file) => readFileSync(file, "utf8") } = {}) {
+  let text;
+  try {
+    text = readText(layoutOf(root).marker);
+  } catch {
+    return null;
+  }
+  const { value, ours } = markerOf(text);
+  const name = ours ? oneLine(value?.name) : "";
+  return name ? [...name].slice(0, NAME_LIMIT).join("") : null;
+}
+
+/** The folders no name climbs to: the user's home and their Documents folder (each workspace's name is found against these). */
+export function nameStops({ home = os.homedir(), documents = documentsFolder({ home }) } = {}) {
+  return [home, documents].filter(Boolean);
+}
+
+/**
+ * The folder whose name a workspace at `root` goes by when it has none of its own: `root`, or the
+ * nearest folder above it whose name is not generic, climbing no higher than below one of `stops` and
+ * never to a drive's root (a folder there keeps its name, generic or not).
+ */
+export function namedFolder(root, { stops = [], platform = process.platform } = {}) {
+  const stopped = new Set(stops.map((stop) => keyOf(stop, platform)));
+  let folder = path.resolve(root);
+  for (;;) {
+    const parent = path.dirname(folder);
+    const atRoot = parent === folder || path.dirname(parent) === parent;
+    if (!isGeneric(path.basename(folder)) || atRoot || stopped.has(keyOf(parent, platform))) return folder;
+    folder = parent;
+  }
+}
+
+/**
+ * What the workspace at `root` is called: { name, own: whether it is gallery.json's name (else its
+ * folder's), folder: the folder named (the workspace's own for a name of its own), above: that
+ * folder's parent's name (what tells two of the same name apart), parent: that parent's path }.
+ */
+export function workspaceName(root, { stops = [], platform = process.platform, readText } = {}) {
+  const own = ownName(root, readText ? { readText } : undefined);
+  const folder = own ? path.resolve(root) : namedFolder(root, { stops, platform });
+  const parent = path.dirname(folder);
+  return { name: own ?? folderName(folder), own: Boolean(own), folder, above: parent === folder ? null : path.basename(parent) || parent, parent };
+}
+
+/**
+ * The names of several workspaces as the sidebar and the commands write them side by side: each of
+ * `named` (workspaceName's, with its `root`, its path) as { root, name, own, above }, `above` null
+ * but where another has the same name (upper and lower case alike): then the name of the folder above
+ * the one named, and where another of them has that too (two workspaces side by side, or two in one
+ * project climbing to its folder), or there is none (a drive's root), the workspace's own path, which
+ * no other has.
+ */
+export function workspaceLabels(named) {
+  const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+  return named.map((entry) => {
+    const label = { root: entry.root, name: entry.name, own: entry.own, above: null };
+    const others = named.filter((other) => other !== entry && same(other.name, entry.name));
+    if (!others.length) return label;
+    const told = entry.above !== null && !others.some((other) => other.above !== null && same(other.above, entry.above));
+    return { ...label, above: told ? entry.above : entry.root };
+  });
+}
+
+/**
+ * gallery.json at `root` with `name` as the workspace's name (namedIn: in place of the one it had,
+ * else right after what marks it; all else it holds kept, and the file's own layout with it), written
+ * at once; the workspace must be there and its gallery.json ours (ensureWorkspace first). Resolves to
+ * { name: as written, before: the name it had, or null }; throws an Error saying why when the name is
+ * wrong (nameProblem), the file is not ours or does not read, or it kept changing under the write.
+ */
+export async function writeWorkspaceName(root, name) {
+  const problem = nameProblem(name);
+  if (problem) throw new Error(problem);
+  const wanted = name.trim();
+  const file = layoutOf(root).marker;
+  for (let tries = 0; tries < 3; tries++) {
+    const text = await fs.readFile(file, "utf8");
+    const { value, ours, reads } = markerOf(text);
+    if (!ours || !value || typeof value !== "object" || Array.isArray(value)) throw new Error(reads ? `${file} is not Gallery's.` : `${file} does not read as JSON: mend it first.`);
+    const before = oneLine(value.name) || null;
+    if (value.name === wanted) return { name: wanted, before };
+    let next = null;
+    try {
+      next = namedIn(text, wanted);
+    } catch {}
+    // What the text says once written is checked: any doubt, the whole file written as JSON.stringify lays it out.
+    if (next === null || !isDeepStrictEqual(markerOf(next).value, { ...value, name: wanted })) {
+      const { gallery, version, name: _old, ...rest } = value;
+      next = `${JSON.stringify({ gallery: gallery ?? WORKSPACE_MARK.gallery, version: version ?? WORKSPACE_MARK.version, name: wanted, ...rest }, null, 2)}\n`;
+    }
+    if (await writeAtomic(file, next, { expect: text })) return { name: wanted, before };
+  }
+  throw new Error(`${file} kept changing while its name was written: try again.`);
+}
+
+// gallery.json's text (`text`, Gallery's, a JSON object that reads) with `name` as its name, written
+// into it as it stands, as ./pages.mjs writes pages.homeMade (its line ends, indentation, BOM, the order
+// of its keys and what stands on one line kept): the name it had replaced in its place, else one added
+// right after the mark (`gallery`, or `version` where that comes after it), laid out as that member is
+// (on a line of its own at its indentation, or on its line after it, as tightly).
+function namedIn(text, name) {
+  const top = objectAt(text, text.indexOf("{"));
+  const had = top.members.findLast(({ key }) => key === "name");
+  if (had) return `${text.slice(0, had.value)}${JSON.stringify(name)}${text.slice(had.end)}`;
+  const mark = top.members.filter(({ key }) => key === "gallery" || key === "version").at(-1);
+  if (!mark) return null;
+  const indent = ownLine(text, top.open, mark);
+  const gap = indent !== null ? (text.includes("\r\n") ? "\r\n" : "\n") + indent : /[ \t]*$/.exec(text.slice(0, mark.from))[0];
+  return `${text.slice(0, mark.end)},${gap}"name":${mark.colon}${JSON.stringify(name)}${text.slice(mark.end)}`;
+}

package/browser/shared/workspace-query.mjs

@@ -0,0 +1,125 @@
+import { CHART_KEY } from "./table-chart.mjs";
+
+// What a block reads of the workspace (the spec custom-blocks-spec-2026-11-07.md §3, §4; docs/render.md
+// "A custom block on a page", docs/workbench.md "The workspace's facts"): the kinds of
+// context.workspace.query, how many items each gives, the options each takes, and where the kit asks for
+// them, the one list the kit's runtime (render/kit/runtime/workspace.js), the server's facts
+// (src/workbench/index.mjs) and the event stream's "data <kind>" (src/server/routes.mjs) go by; and how a
+// block checks a to-do of another document (workspace.setTodo: the plan's 5.1), what an export embeds of
+// the workspace (the spec §9). Pure: no DOM, no Node.
+
+/** The kinds workspace.query answers: the workspace's facts, and `table`, a keyed table of a document (the plan's 5.2). */
+export const QUERY_KINDS = Object.freeze(["todos", "recent", "stats", "activity", "table"]);
+
+/**
+ * The kinds of the workspace's facts a change may change, each said to the pages as "data <kind>":
+ * `table` whenever a document's text changed (any keyed table of it may have).
+ */
+export const FACT_KINDS = Object.freeze(["todos", "recent", "stats", "activity", "table"]);
+
+/**
+ * The codes workspace.query rejects with (the spec §3), never another: the server's own refusals of a query
+ * (kind, options, missing: no such document, or no table of that key in it, or one with merged cells; and
+ * unsupported, which no server of this version says) as it says them; offline where there is no server to ask
+ * (an export without that kind in its snapshot) or it does not answer; failed where it answered and could
+ * not (a read that failed, a request it refused, no JSON).
+ */
+export const QUERY_CODES = Object.freeze(["kind", "options", "unsupported", "missing", "offline", "failed"]);
+
+/**
+ * How many items a query gives where its options say none, and the most it gives: to-dos, documents edited
+ * last, days of the record (as many as it keeps, src/workbench/activity.mjs KEEP_DAYS: the 编辑热力图's 53
+ * weeks), rows of a table.
+ */
+export const QUERY_LIMITS = Object.freeze({ todos: { default: 200, most: 1000 }, recent: { default: 10, most: 50 }, activity: { default: 365, most: 371 }, table: { default: 200, most: 1000 } });
+
+/**
+ * What an export embeds of the workspace for a document whose blocks read it (the spec §9: its snapshot's
+ * kinds beside `net`), each kind's whole answer to so many at most: to-dos (done or not), documents edited
+ * last, days of the record, and of the tables its instances asked for (the last `tables` of them), rows each.
+ */
+export const SNAPSHOT_LIMITS = Object.freeze({ todos: 200, recent: 50, activity: 371, tables: 20, rows: 1000 });
+
+/** Where a page asks for its to-dos to be checked (POST { slug, items: [{ ref, done }] }, the token's: the workspace's service). */
+export const TODO_ROUTE = "/__gallery/workspace/todo";
+
+/** What workspace.setTodo asks whoever shows the page (cancelable, on the window: { ask: { slug, ref, done }, answer(promise) }). */
+export const TODO_EVENT = "doc-todo-set";
+
+/**
+ * The codes workspace.setTodo rejects with, never another: ref (not a to-do's ref as query gave it, or
+ * `done` no true or false), changed (the item is not as the ref read it: its words changed, or it is gone:
+ * the conflict, which the block reads again after), ambiguous (no block id, the file changed since, and
+ * more than one item of its words under its headings), locked (the item is there as read, in a place the
+ * document's own page cannot check: a list in a table cell, a block of the document's own), missing (no such document), busy (the file kept
+ * changing, or stayed half written), offline (nothing on the page writes the workspace: an exported file,
+ * the 演示视图, a page on its own without a token; or the server does not answer), failed (anything else).
+ */
+export const TODO_CODES = Object.freeze(["ref", "changed", "ambiguous", "locked", "missing", "busy", "offline", "failed"]);
+
+/** How many to-dos one write of a document carries at most (the page merges what waits into one). */
+export const TODO_MOST = 50;
+
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const BLOCK = /^[A-Za-z0-9_-]{1,64}$/;
+const VERSION = /^[a-f0-9]{16}$/;
+
+/**
+ * `ref` as a write carries it, when it is a to-do's ref as workspace.query("todos") gives it ({ slug,
+ * block, text, path, nth, version }: `version` the hash of the file the facts read it from, which may be
+ * missing), or null.
+ */
+export function todoRef(ref) {
+  if (!ref || typeof ref !== "object" || Array.isArray(ref)) return null;
+  const { slug, block = null, text, path, nth, version = null } = ref;
+  if (typeof slug !== "string" || !SLUG.test(slug) || (block !== null && (typeof block !== "string" || !BLOCK.test(block)))) return null;
+  if (typeof text !== "string" || text.length > 4000 || !Array.isArray(path) || path.length > 6 || !path.every((step) => typeof step === "string" && step.length <= 4000)) return null;
+  if (!Number.isInteger(nth) || nth < 0 || (version !== null && (typeof version !== "string" || !VERSION.test(version)))) return null;
+  return { slug, block, text, path: [...path], nth, version };
+}
+
+/** Where a query is asked (GET, ?kind=<kind>&options=<JSON>): the workspace's service. */
+export const QUERY_ROUTE = "/__gallery/workspace/query";
+
+/**
+ * The global a page the server serves holds QUERY_ROUTE in (src/server/routes.mjs, a script of the
+ * server's that no export keeps), which the kit's runtime asks: none there, the workspace is offline.
+ */
+export const WORKSPACE_GLOBAL = "__galleryWorkspace";
+
+/** What workspace.open asks whoever shows the page to open (a cancelable event on the window, detail { slug, block } or { page }). */
+export const OPEN_EVENT = "doc-open-request";
+
+/**
+ * The options of a query of `kind` as they are used: { options } (todos: done, slugs, limit; recent:
+ * limit; activity: days; every count held to its most), or { problem } (what is wrong, in English).
+ */
+export function queryOptions(kind, options) {
+  const given = options ?? {};
+  if (typeof given !== "object" || Array.isArray(given)) return { problem: "its options are an object" };
+  const count = (name, { default: fallback, most }) => {
+    const value = given[name];
+    if (value === undefined) return fallback;
+    if (!Number.isInteger(value) || value < 1) throw new Error(`${name} is a whole number from 1`);
+    return Math.min(value, most);
+  };
+  try {
+    if (kind === "todos") {
+      if (given.done !== undefined && typeof given.done !== "boolean") return { problem: "done is true or false" };
+      if (given.slugs !== undefined && !(Array.isArray(given.slugs) && given.slugs.every((slug) => typeof slug === "string"))) return { problem: "slugs is a list of documents' slugs" };
+      return { options: { done: given.done, slugs: given.slugs ?? null, limit: count("limit", QUERY_LIMITS.todos) } };
+    }
+    if (kind === "recent") return { options: { limit: count("limit", QUERY_LIMITS.recent) } };
+    if (kind === "table") {
+      if (typeof given.slug !== "string" || !SLUG.test(given.slug)) return { problem: "slug is a document's slug" };
+      if (typeof given.key !== "string" || !CHART_KEY.test(given.key)) return { problem: "key is a table's key (data-doc-chart-source)" };
+      const where = given.where ?? {};
+      if (typeof where !== "object" || Array.isArray(where) || !Object.values(where).every((value) => typeof value === "string")) return { problem: "where maps each column to the words its cells are to hold" };
+      return { options: { slug: given.slug, key: given.key, where: { ...where }, limit: count("limit", QUERY_LIMITS.table) } };
+    }
+    if (kind === "activity") return { options: { days: count("days", QUERY_LIMITS.activity) } };
+    return { options: {} };
+  } catch (error) {
+    return { problem: error.message };
+  }
+}