@heycys/gallery 0.0.0-stage → 0.1.1

package/browser/shared/code-lines.mjs

@@ -0,0 +1,30 @@
+// The number a code block's first line shows, written once: the kit's code.js numbers its lines from
+// it in the reading view, the page editor in its line numbers' column, and the export takes it in
+// from what an Agent writes (src/editor/source/natural.mjs: data-line-start, or Prism's data-start).
+// An excerpt of a file shows the file's own numbers so: data-line-start="38" numbers its lines 38,
+// 39 … Its folded lines (data-folded-lines) are counted in the block, from 1, whatever it shows.
+
+/** The class of a code block (div.doc-code) whose long lines scroll, each on one line. */
+export const NOWRAP = "doc-code--nowrap";
+
+/** The attribute on a code block that says the lines whose structure is folded: their numbers (1-based), ascending, spaces between. */
+export const FOLDED_LINES = "data-folded-lines";
+const FOLDED_NUMBERS = /^[1-9]\d{0,5}( [1-9]\d{0,5}){0,499}$/;
+
+/** Whether a value is folded lines as data-folded-lines takes them. */
+export const validFolded = (value) => typeof value === "string" && FOLDED_NUMBERS.test(value);
+
+/** The attribute on a code block (div.doc-code) that numbers its first line. */
+export const LINE_START = "data-line-start";
+
+/**
+ * A first line's number as an attribute writes it: a whole number from 1 (six digits at most, zeros
+ * before them as a file's listing may pad it: 038), blanks around it.
+ */
+const NUMBER = /^\s*0*([1-9]\d{0,5})\s*$/;
+
+/** The number a value of data-line-start gives the first line, or null when it gives none (1 then). */
+export function lineStart(value) {
+  const found = NUMBER.exec(value ?? "");
+  return found ? Number(found[1]) : null;
+}

package/browser/shared/colors.mjs

@@ -0,0 +1,30 @@
+// The kit's nine colors (Notion's text and background colors, light and dark), written once: their
+// names, what the reader calls them and their values (a text color, a block's fill and the deeper
+// fill of words in a line). The kit's stylesheets (render/kit/styles/
+// base.css: .doc-text-* and .doc-highlight-*, tokens.css) are written by hand, as CSS is;
+// tests/unit/clipboard.mjs holds them to these values. Everything else that needs a value reads it
+// here: the editor's color pickers (names), pasted colors matched onto the nine (clipboard/import/
+// colors.mjs) and the colors a copy carries to other programs (clipboard/own/export.mjs).
+
+/**
+ * Each color in Notion's order: `name` (the classes are doc-text-<name> and doc-highlight-
+ * <name>), `label` (what the reader calls it), and its text color, its background as a block's
+ * (`fill`, base.css's --doc-fill) and its background on words in a line (`mark`, base.css's
+ * --doc-mark, deeper than the fill) as [light, dark].
+ */
+export const COLORS = [
+  { name: "gray", label: "灰色", text: ["#6e6e73", "#a1a1a6"], fill: ["#f0efed", "#383836"], mark: ["#e0dfdd", "#454542"] },
+  { name: "brown", label: "棕色", text: ["#9f765a", "#ba856f"], fill: ["#f5ede9", "#45362d"], mark: ["#efdbce", "#534034"] },
+  { name: "orange", label: "橙色", text: ["#d27b2d", "#c77d48"], fill: ["#fbebde", "#53361f"], mark: ["#fbddc5", "#654025"] },
+  { name: "yellow", label: "黄色", text: ["#cb9434", "#ca9849"], fill: ["#f9f3dc", "#504425"], mark: ["#f8eab6", "#614f26"] },
+  { name: "green", label: "绿色", text: ["#50946e", "#529e72"], fill: ["#e8f1ec", "#263d30"], mark: ["#cfead9", "#2c4b3a"] },
+  { name: "blue", label: "蓝色", text: ["#387dc9", "#5e87c9"], fill: ["#e5f2fc", "#233850"], mark: ["#cde5fb", "#294564"] },
+  { name: "purple", label: "紫色", text: ["#9a6bb4", "#9d68d3"], fill: ["#f3ebf9", "#3c2d47"], mark: ["#ebdaf6", "#4b3859"] },
+  { name: "pink", label: "粉色", text: ["#c14c8a", "#d15796"], fill: ["#fae9f1", "#4e2b3c"], mark: ["#f8d7e6", "#5d3548"] },
+  { name: "red", label: "红色", text: ["#cf5148", "#df5452"], fill: ["#fce9e7", "#502c29"], mark: ["#fed7d1", "#663632"] },
+];
+
+export const COLOR_NAMES = COLORS.map(({ name }) => name);
+
+/** The page's own text color and background (tokens.css --doc-text, --doc-surface) as [light, dark]: what no color is. */
+export const BODY = { text: ["#2c2c2b", "#f3f3f3"], background: ["#ffffff", "#202020"] };

package/browser/shared/component-catalog.mjs

@@ -0,0 +1,573 @@
+import { isUtf8 } from "node:buffer";
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parseFragment, serializeOuter } from "parse5";
+import { isInstance, parseCompound, parsePart, parseSelector, partOf } from "./components/index.mjs";
+import { ATTRIBUTE, NO_TEXT, PACKAGE_ID, PACKAGE_MARK, SLOT, instanceMatch, refusedInCopy, settingState } from "./components/installed.mjs";
+import { writeAtomic } from "./files.mjs";
+import { attr, walk } from "./html-tree.mjs";
+import { inLanguage, refusal, said, saying, told } from "./i18n/index.mjs";
+import { DEVICE_NAMES, PACKAGE_MANIFEST, WORKSPACE_MARK, findWorkspace, layoutOf, markerOf, packageFolders } from "./workspace.mjs";
+
+// 组件包: what the workspace's component packages say of themselves to Gallery, read from
+// <workspace>/components/<scope>/<name>/component.json, plain data, whose code no system runs here. A
+// package is a description as a kit component's is (src/shared/components/): its id, where its
+// instances are, its parts and what it leaves on a page, so that what reads a built-in's reads a
+// package's: the scan and the checks here, the kit on the page by DocKit.describe, the same object.
+// A manifest offers only FIELDS, no unit, box, host, rank or category: those are the engines', and a
+// field it does not know keeps its package from loading.
+//
+// The catalog is { packages, problems, settings, stamp }. `packages`, by id, are those that load. A
+// package that does not load (a manifest that does not read as one, one for an apiVersion this Gallery
+// does not run, which counts as disabled, or one the settings turned off) stands in `problems`, by its
+// id in lowercase, as an instance names it, with why (`problem`, said()'s, in either language by
+// problemIn), and touches nothing else: its instances show as those of a package that is not there,
+// and whoever reads them says why. `settings` is what gallery.json says of the components (设置 › 组件列表,
+// componentSettings): `hidden` and `disabled`, by the id of a package or the name of a built-in
+// component, and `problem` where the file cannot be read as saying anything (settingsNow). A package
+// hidden runs as any other and is left out of the lists that offer one, each of which reads its state
+// (menuOf, packageStates); one disabled is one that does not load, so that nothing that loads a
+// package has a case for it. A stamp is a hash of what files hold: `stamp`, of a package, over what
+// reaches a page of it (STAMPED and the files `assets` names), of one that does not load over those
+// and why, and of the catalog, over its packages', what is hidden and whether gallery.json reads;
+// `definition`, over the manifest alone, is what a page's commit is to be held to.
+//
+// readCatalog reads the disk; what reads a catalog for use (the scan, the checks, a page) asks
+// currentCatalog, which reads it once a process and keeps it: a command's or a job's life is short,
+// and the server's watcher (src/server/catalog-watch.mjs) puts a new one in its place. This file runs
+// on the server alone (no page imports it): the workspace it reads is the one GALLERY_WORKSPACE names
+// at each read, as the gallery command and the tests set it.
+
+/** The apiVersion this Gallery runs. */
+export const API_VERSION = 1;
+
+/** The kit's files a package may ask for by id in `assets`, as src/render/assets.mjs names them (the others are on every page). */
+export const KIT_ASSETS = new Set(["code", "state", "sheets", "tokens", "dialogs", "katex-styles", "katex", "katex-auto-render", "math", "d3", "charts", "tables"]);
+
+// What a manifest may hold, a part of one and its `runtime`.
+const FIELDS = ["id", "apiVersion", "version", "name", "description", "words", "parts", "runtime", "assets", "markdown", "schema"];
+const PART_FIELDS = ["at", "edit", "optional", "min", "max"];
+const RUNTIME_FIELDS = ["generated", "attrs"];
+
+// What a package's part may be edited as: its text, its data through the kit's edit, the document's
+// blocks (a slot, marked data-doc-slot="<name>" in its markup), or not at all.
+const EDITS = ["text", "data", "flow", "none"];
+// What a slot's name may be: it is written in an attribute's value, and a selector finds it there.
+const SLOT_NAME = /^[a-z][a-z0-9-]*$/;
+/** Where a part edited as flow is in an instance: the slot of its name. */
+export const slotAt = (name) => `div[${SLOT}="${name}"], section[${SLOT}="${name}"]`;
+// A manifest's parts as the engines read them: a slot's `at` is its mark, which the manifest does not write.
+const partsRead = (parts) => Object.fromEntries(Object.entries(parts).map(([name, part]) => [name, part.edit === "flow" ? { ...part, at: slotAt(name) } : part]));
+const MARKDOWN = ["parts", "text"];
+
+// The files of a package by their fixed names: those served from its folder (kit.js and style.css are
+// the page's that uses it, preview.svg the menu's), and with them what a stamp reads.
+// example.html and writing.md are for who writes with it, and reach no page: a change of them is no
+// change of the catalog, which every open page hears.
+const SERVED = ["kit.js", "style.css", "preview.svg"];
+const TEMPLATE = "template.html";
+const STAMPED = [PACKAGE_MANIFEST, TEMPLATE, ...SERVED];
+// What a package's stamp reads, its `files` being what `assets` named besides.
+const stamped = (files) => [...new Set([...STAMPED, ...files])].sort();
+
+// A file of the package's own that `assets` names: a relative path of plain names, with an extension.
+const OWN_FILE = /^(?:[A-Za-z0-9_-][A-Za-z0-9._-]*\/)*[A-Za-z0-9_-][A-Za-z0-9._-]*\.[A-Za-z0-9]+$/;
+// What Gallery and the kit mark a page with, which no package sets or takes off, in any case, as HTML
+// reads an attribute's name.
+const OWN_NAME = /^(?:doc-|data-doc-|data-ge-)|^data-block-id$/i;
+// What every page of the workspace holds of a package, whichever it uses: its manifest's words and
+// its template are in each page's map.
+const ON_EVERY_PAGE = 256 * 1024;
+
+const isTable = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isWords = (value) => typeof value === "string" && value.trim() !== "";
+const byId = (a, b) => (a.id < b.id ? -1 : 1);
+const fail = (message) => {
+  throw refusal(message);
+};
+const hashOf = (write) => {
+  const hash = createHash("sha256");
+  write(hash);
+  return hash.digest("hex").slice(0, 16);
+};
+
+/** Where a file of the package's folder is, or null: none there, or a link that leads out of it. */
+function ownPath(folder, name) {
+  const found = path.join(folder, name);
+  try {
+    const stat = lstatSync(found, { throwIfNoEntry: false });
+    if (!stat) return null;
+    if (!stat.isSymbolicLink() && !name.includes("/")) return found; // right in it: no walk through the path
+    const real = realpathSync.native(found);
+    return real.startsWith(realpathSync.native(folder) + path.sep) ? real : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The bytes of a file of the package's folder, or null. */
+function ownFile(folder, name) {
+  try {
+    const real = ownPath(folder, name);
+    return real && readFileSync(real);
+  } catch {
+    return null;
+  }
+}
+
+// What a file holds, as a hash kept by its size and its time, so that a look over a package read a
+// moment ago reads none of it again, however large (a font, a file of data). A file written this very
+// moment is read each time: the write that comes next can carry the same size and time.
+const digests = new Map(); // a file's path -> { size, time, digest }
+const SETTLED = 2000;
+function digestOf(real) {
+  const { size, mtimeMs } = statSync(real);
+  const known = digests.get(real);
+  if (known?.size === size && known.time === mtimeMs) return known.digest;
+  const digest = hashOf((hash) => hash.update(readFileSync(real)));
+  if (Date.now() - mtimeMs > SETTLED) digests.set(real, { size, time: mtimeMs, digest });
+  return digest;
+}
+
+const stampOf = (folder, names) => hashOf((hash) => {
+  for (const name of names) {
+    const real = ownPath(folder, name);
+    let digest = "none"; // no such file, or one gone between the two
+    try {
+      if (real) digest = digestOf(real);
+    } catch {}
+    hash.update(`${name}\u0000${digest}\n`);
+  }
+});
+
+// A file's words, no byte-order mark, which an editor on Windows may write.
+const wordsOf = (bytes) => bytes.toString("utf8").replace(/^\uFEFF/, "");
+const notTooLong = (bytes, name) => {
+  if (bytes.length > ON_EVERY_PAGE) fail(said("{0} 有 {1} KB，而每一页都带着它，最多 {2} KB", name, Math.ceil(bytes.length / 1024), ON_EVERY_PAGE / 1024));
+};
+
+const onlyFields = (table, fields, where = "") => {
+  for (const key of Object.keys(table)) if (!fields.includes(key)) fail(said("{0} 不是组件包能写的字段", `${where}${key}`));
+};
+const required = (manifest, fields) => {
+  for (const field of fields) if (manifest[field] === undefined) fail(said("缺少 {0}", field));
+};
+const bothLanguages = (value, field) => {
+  if (!isTable(value) || !isWords(value.zh) || !isWords(value.en) || Object.keys(value).length !== 2) fail(said("{0} 要写成 { zh, en } 两种语言的文字", field));
+};
+
+// The tags a part's `at` ends on, where it names one.
+const tailTags = (at) => at.split(",").map((piece) => piece.split(">").at(-1).trim()).filter((step) => step !== "*").map((step) => parseCompound(step).tag);
+
+function checkPart(name, part) {
+  const where = `parts.${name}`;
+  if (!isTable(part)) fail(said("{0} 要写成一张表", where));
+  onlyFields(part, PART_FIELDS, `${where}.`);
+  if (part.edit === "flow") {
+    // A slot: found by its mark, one to an instance.
+    if (!SLOT_NAME.test(name)) fail(said("{0} 是插槽，名字只用小写字母、数字和连字符", where));
+    if (part.at !== undefined) fail(said("{0} 是插槽，由 data-doc-slot=\"{1}\" 标出，不写 at", where, name));
+    if (part.min !== undefined || part.max !== undefined) fail(said("{0} 是插槽，一个实例里只有一个，不写 min、max", where));
+    if (part.optional !== undefined && typeof part.optional !== "boolean") fail(said("{0} 要写成 true 或 false", `${where}.optional`));
+    return;
+  }
+  if (!isWords(part.at)) fail(said("缺少 {0}", `${where}.at`));
+  try {
+    parsePart(part.at);
+  } catch (error) {
+    fail(said("{0} 写错了：{1}", `${where}.at`, error.message));
+  }
+  if (!EDITS.includes(part.edit)) fail(said("{0} 的 edit 只能是 text、data、flow 或 none", where));
+  if (part.optional !== undefined && typeof part.optional !== "boolean") fail(said("{0} 要写成 true 或 false", `${where}.optional`));
+  for (const bound of ["min", "max"]) if (part[bound] !== undefined && !(Number.isInteger(part[bound]) && part[bound] >= 0)) fail(said("{0} 要写成不小于 0 的整数", `${where}.${bound}`));
+  if (part.min > part.max) fail(said("{0} 的 min 比 max 大，没有实例能满足", where));
+  if (part.edit === "text") for (const tag of tailTags(part.at)) if (NO_TEXT.has(tag)) fail(said("{0} 不能按文字编辑：<{1}> 不是能打字的文字", where, tag));
+}
+
+// Whether a selector takes the instance itself, or all it holds: what a copy of the view would lose with it.
+const takesAll = (selector) => selector.split(",").some((one) => one.split(">").every((step) => [":scope", "*"].includes(step.trim())));
+
+// `runtime` as the kit reads it: DocKit.dehydrate looks through the whole page, so each selector is
+// given the package's instances as its root.
+function runtimeOf(runtime, id) {
+  if (runtime === undefined) return null;
+  if (!isTable(runtime)) fail(said("{0} 要写成一张表", "runtime"));
+  onlyFields(runtime, RUNTIME_FIELDS, "runtime.");
+  const root = `[${ATTRIBUTE}="${id}"]`;
+  const scoped = (selector, where) => {
+    try {
+      if (!isWords(selector)) throw new Error("no selector");
+      parseSelector(selector);
+    } catch (error) {
+      fail(said("{0} 写错了：{1}", where, error.message));
+    }
+    return selector.split(",").map((one) => (one.trim().startsWith(":scope") ? one.trim().replace(":scope", root) : `${root} ${one.trim()}`)).join(", ");
+  };
+  const { generated = [], attrs = {} } = runtime;
+  if (!Array.isArray(generated)) fail(said("{0} 要写成一串文字", "runtime.generated"));
+  if (!isTable(attrs)) fail(said("{0} 要写成一张表", "runtime.attrs"));
+  for (const names of Object.values(attrs)) {
+    if (!Array.isArray(names) || !names.every(isWords)) fail(said("{0} 要写成一串文字", "runtime.attrs"));
+    for (const name of names) if (OWN_NAME.test(name)) fail(said("{0} 是 Gallery 自己的名字，组件包不能用", name));
+  }
+  const made = (selector) => {
+    const written = scoped(selector, "runtime.generated");
+    if (takesAll(selector)) fail(said("{0} 的 {1} 是整个实例，而这里只写它生成的节点", "runtime.generated", selector));
+    return written;
+  };
+  return {
+    generated: generated.map(made),
+    attrs: Object.fromEntries(Object.entries(attrs).map(([selector, names]) => [scoped(selector, "runtime.attrs"), names])),
+  };
+}
+
+// `assets`: the kit's files a package asks for, by id, and files of its own, by their path in its folder.
+function assetsOf(assets, folder) {
+  if (assets === undefined) return { kit: [], own: [] };
+  if (!Array.isArray(assets) || !assets.every(isWords)) fail(said("{0} 要写成一串文字", "assets"));
+  const own = assets.filter((asset) => !KIT_ASSETS.has(asset));
+  for (const asset of own) {
+    if (!OWN_FILE.test(asset)) fail(said("assets 里的 {0} 既不是套件的资源，也不是包里的文件", asset));
+    if (!ownPath(folder, asset)) fail(said("assets 写了 {0}，包里没有这个文件", asset));
+  }
+  return { kit: assets.filter((asset) => KIT_ASSETS.has(asset)), own };
+}
+
+// A package as `manifest` says it, or the error that says why not. An apiVersion it does not run
+// comes first of all that is about its contents, which a later Gallery may have changed.
+function packageOf(id, folder, text) {
+  let manifest;
+  try {
+    manifest = JSON.parse(text);
+  } catch (error) {
+    fail(said("component.json 不是 JSON：{0}", error.message));
+  }
+  if (!isTable(manifest)) fail(said("component.json 写的不是一个对象"));
+  if (!PACKAGE_ID.test(id)) fail(said("{0} 不能做组件包的 id：范围和名字都只用小写字母、数字和连字符", id));
+  for (const name of id.split("/")) if (DEVICE_NAMES.has(name)) fail(said("{0} 不能做组件包的 id：{1} 是 Windows 留给设备的名字", id, name));
+  if (manifest.id !== id) fail(said("清单的 id 是 {0}，和它的文件夹 {1} 不一样", String(manifest.id), id));
+  required(manifest, ["apiVersion"]);
+  if (!Number.isInteger(manifest.apiVersion) || manifest.apiVersion < 1) fail(said("apiVersion 要写成一个正整数"));
+  if (manifest.apiVersion !== API_VERSION) throw refusal(said("这个组件包要 apiVersion {0}，这一版 Gallery 只支持 {1}", manifest.apiVersion, API_VERSION), { disabled: true, version: isWords(manifest.version) ? manifest.version : null });
+  onlyFields(manifest, FIELDS);
+  required(manifest, ["version", "name", "description", "parts"]);
+  if (!isWords(manifest.version)) fail(said("{0} 要写成文字", "version"));
+  bothLanguages(manifest.name, "name");
+  bothLanguages(manifest.description, "description");
+  if (manifest.words !== undefined && typeof manifest.words !== "string") fail(said("{0} 要写成文字", "words"));
+  if (!isTable(manifest.parts)) fail(said("{0} 要写成一张表", "parts"));
+  for (const [name, part] of Object.entries(manifest.parts)) checkPart(name, part);
+  const runtime = runtimeOf(manifest.runtime, id);
+  const { kit, own } = assetsOf(manifest.assets, folder);
+  if (manifest.markdown !== undefined && !MARKDOWN.includes(manifest.markdown)) fail(said("markdown 只能是 parts 或 text"));
+  if (manifest.schema !== undefined && !(Number.isInteger(manifest.schema) && manifest.schema >= 1)) fail(said("schema 要写成一个正整数"));
+  const template = ownFile(folder, TEMPLATE);
+  if (template) notTooLong(template, TEMPLATE);
+  return {
+    id,
+    match: instanceMatch(id),
+    parts: partsRead(manifest.parts),
+    ...(runtime ? { runtime } : {}),
+    ...(manifest.schema !== undefined ? { schema: manifest.schema } : {}),
+    apiVersion: manifest.apiVersion,
+    version: manifest.version,
+    name: manifest.name,
+    description: manifest.description,
+    words: manifest.words ?? "",
+    assets: kit,
+    markdown: manifest.markdown ?? "parts",
+    files: [...new Set([...SERVED.filter((file) => ownPath(folder, file)), ...own])],
+    template: template && wordsOf(template),
+    folder,
+    definition: hashOf((hash) => hash.update(text)),
+    stamp: stampOf(folder, stamped(own)),
+  };
+}
+
+// What a folder holds: a package, or what keeps it from being one.
+function readPackage(id, folder) {
+  try {
+    const bytes = ownFile(folder, PACKAGE_MANIFEST);
+    if (!bytes) fail(said("读不出 component.json"));
+    if (!isUtf8(bytes)) fail(said("{0} 不是 UTF-8 编码：请存成 UTF-8", PACKAGE_MANIFEST));
+    notTooLong(bytes, PACKAGE_MANIFEST);
+    return packageOf(id, folder, wordsOf(bytes));
+  } catch (error) {
+    const problem = saying(error);
+    const stamp = hashOf((hash) => hash.update(`${stampOf(folder, stamped([]))} ${JSON.stringify(problem)}`));
+    return { id: id.toLowerCase(), stamp, problem, disabled: error.disabled === true, version: error.version ?? null };
+  }
+}
+
+const workspaceRoot = () => findWorkspace().root;
+
+// A file edited by hand holds what it holds: of its lists, what can be an id is read, once each, and
+// the rest is passed over, one that names nothing there doing nothing. An id may be of a package that
+// comes back, so it stays. Only a package can be disabled.
+const NAMED = /^[a-z0-9][a-z0-9-]*(?:\/[a-z0-9][a-z0-9-]*)?$/;
+const idsIn = (list, shape) => [...new Set(Array.isArray(list) ? list.filter((id) => typeof id === "string" && shape.test(id)) : [])];
+const settingsIn = (file) => ({ hidden: idsIn(file?.components?.hidden, NAMED), disabled: idsIn(file?.components?.disabled, PACKAGE_ID) });
+
+// gallery.json's text (null: no file) as what it holds, `value`, or `problem`, why it cannot be taken
+// for a workspace's: what the catalog goes on through (settingsNow) and no writer writes over.
+const UNREAD = said("gallery.json 读不出来：改好这个文件后再试");
+const NOT_OURS = said("gallery.json 不是 Gallery 的文件");
+function fileOf(text) {
+  if (text === null) return { value: null };
+  const { value, ours, reads } = markerOf(text);
+  return ours ? { value } : { problem: reads ? NOT_OURS : UNREAD };
+}
+
+function fileAt(root) {
+  try {
+    return fileOf(readFileSync(layoutOf(root).marker, "utf8"));
+  } catch (error) {
+    return error.code === "ENOENT" ? fileOf(null) : { problem: UNREAD };
+  }
+}
+
+/**
+ * What gallery.json says of the components: { hidden, disabled }, ids of packages and, in `hidden`,
+ * names of built-in components. One that is not there says nothing, and neither does one that does not
+ * read or is another program's: what goes on using a workspace goes by the catalog (readCatalog).
+ */
+export const componentSettings = (root = workspaceRoot()) => settingsIn(fileAt(root).value);
+
+// What a system says of a file it will not let be written, after writeAtomic's own tries.
+const NOT_WRITABLE = ["EPERM", "EACCES", "EBUSY", "EROFS"];
+
+/**
+ * gallery.json with `id` hidden or not and disabled or not, as `hidden` and `disabled` say (true,
+ * false, or left out for as it is), written at once and with all else it holds kept. A file that does
+ * not read, is another program's, changed under this write or cannot be written is refused, and stays
+ * as it is: it is not this write's to mend.
+ */
+export async function writeComponentSettings(root, { id, hidden, disabled }) {
+  const file = layoutOf(root).marker;
+  const text = await fs.readFile(file, "utf8").catch((error) => {
+    if (error.code === "ENOENT") return null;
+    fail(UNREAD);
+  });
+  const { value, problem } = fileOf(text);
+  if (problem) fail(problem);
+  const named = (list, on) => (on === undefined ? list : on ? [...new Set([...list, id])] : list.filter((other) => other !== id));
+  const { hidden: wasHidden, disabled: wasDisabled } = settingsIn(value);
+  const components = { ...(isTable(value?.components) ? value.components : {}), hidden: named(wasHidden, hidden), disabled: named(wasDisabled, disabled) };
+  const written = await writeAtomic(file, `${JSON.stringify({ ...(value ?? WORKSPACE_MARK), components }, null, 2)}\n`, { expect: text }).catch((error) => {
+    if (NOT_WRITABLE.includes(error.code)) fail(said("gallery.json 写不进去：可能是只读的，或被别的程序占着"));
+    throw error;
+  });
+  if (!written) fail(said("gallery.json 刚刚被改过：再试一次"));
+}
+
+// A package the settings turned off: to all that loads one, one that does not load, what its manifest
+// says kept for who lists it (`off`).
+const turnedOff = (found) => ({ ...found, off: true, disabled: true, problem: said("在设置里停用了"), stamp: hashOf((hash) => hash.update(`${found.stamp} off`)) });
+
+const NO_SETTINGS = settingsIn(null);
+
+/** The stamp of a catalog: of what its packages are, those that do not load and why too, of what is hidden and of why gallery.json does not read, neither of which changes a package. */
+export const catalogStamp = ({ packages, problems, settings = NO_SETTINGS }) => hashOf((hash) => {
+  for (const { id, stamp } of [...packages.values(), ...problems.values()].sort(byId)) hash.update(`${id} ${stamp}\n`);
+  hash.update(`hidden ${[...settings.hidden].sort().join(" ")}\n`);
+  hash.update(`settings ${settings.problem?.message ?? ""}\n`);
+});
+
+// The settings a catalog goes by: what gallery.json says or, while it cannot be read as saying
+// anything, what was in use (`held`, a broken manifest's hold, for a slip by hand), with why (`problem`).
+function settingsNow(root, held) {
+  const { value, problem } = fileAt(root);
+  return problem ? { hidden: held.hidden, disabled: held.disabled, problem } : settingsIn(value);
+}
+
+/**
+ * The workspace's packages as they are on disk now: the catalog, whatever a package or gallery.json
+ * holds. `held`: the settings of the catalog in use, for a file that does not read; a process with
+ * none has nothing to go by. `on`: a package read as its files say whatever gallery.json says of it,
+ * for what holds it to them (gallery component check).
+ */
+export function readCatalog(root = workspaceRoot(), held = NO_SETTINGS, { on = null } = {}) {
+  const settings = settingsNow(root, held);
+  const packages = new Map();
+  const problems = new Map();
+  for (const { id, folder } of packageFolders(root)) {
+    const found = readPackage(id, folder);
+    (found.problem ? problems : packages).set(found.id, found);
+  }
+  for (const id of packages.keys()) problems.delete(id); // a folder of its name in another case, on a system that tells the two apart
+  for (const id of settings.disabled) {
+    if (!packages.has(id) || id === on) continue;
+    problems.set(id, turnedOff(packages.get(id)));
+    packages.delete(id);
+  }
+  return { packages, problems, settings, stamp: catalogStamp({ packages, problems, settings }) };
+}
+
+const kept = new Map(); // a workspace's root -> the catalog in use
+
+/** The catalog in use: the one kept, read the first time it is asked for. */
+export function currentCatalog(root = workspaceRoot()) {
+  const key = path.resolve(root);
+  if (!kept.has(key)) kept.set(key, readCatalog(key));
+  return kept.get(key);
+}
+
+/** `catalog` in use from now on (the server's watcher). */
+export const keepCatalog = (root, catalog) => void kept.set(path.resolve(root), catalog);
+
+/** The next ask reads the disk (a job of the worker, which hears no watcher; a test that wrote a package). */
+export const forgetCatalog = (root = workspaceRoot()) => void kept.delete(path.resolve(root));
+
+/** Why a package does not load, in `language` ("zh" or "en"), whatever the language in use. */
+export const problemIn = (language, problem) => inLanguage(language, () => told(problem));
+
+// Why a package does not load, in both languages, as a page and a list say it.
+const bothProblems = (problem) => ({ zh: problemIn("zh", problem), en: problemIn("en", problem) });
+
+/** Why gallery.json cannot be read, in both languages, as 设置 › 组件列表 says it, or null. */
+export const settingsProblem = ({ settings }) => (settings.problem ? bothProblems(settings.problem) : null);
+
+// What a package is now: "normal", "hidden", "disabled" (turned off, or for an apiVersion this Gallery
+// does not run), or "broken", one that does not load of itself.
+const stateOf = (found, settings) => (found.problem ? (found.disabled ? "disabled" : "broken") : settingState(found.id, settings));
+
+/** What the kit is told of a package: where its instances are, its parts, what it leaves on a page and how far its content's shape goes. */
+export const descriptionOf = ({ id, match, parts, runtime, schema }) => ({ id, match, parts, ...(runtime ? { runtime } : {}), ...(schema !== undefined ? { schema } : {}) });
+
+/**
+ * What the kit is told of a catalog, each by DocKit.describe, the one way a page learns a package's
+ * parts: of a package its description, of one that does not load why, in both languages, its note
+ * saying it in the page's.
+ */
+export const descriptionsOf = ({ packages, problems }) => [
+  ...[...packages.values()].map(descriptionOf),
+  ...[...problems.values()].map(({ id, problem }) => ({ id, problem: bothProblems(problem) })),
+];
+
+/** The line that tells the kit of `description`, safe in a script of a page. */
+export const describeLine = (description) => `DocKit.describe(${JSON.stringify(description)});`.replace(/</g, "\\u003c");
+
+/** Where a page has a file of a package from, by the stamp that keeps it for good (src/server/component-route.mjs). */
+export const packageAddress = ({ id, stamp }, file) => `/__gallery/components/${id}/${file}?v=${stamp}`;
+
+/**
+ * The tags that load a package in a page, by kind, each a string of HTML: `styles`, a link to its
+ * style.css; `scripts`, the line that tells the kit of it, written here from its manifest so that a
+ * package's script says nothing of itself, and a script of its kit.js, which that line then says
+ * comes with the page (`script`: the kit marks an instance its script did not start). A package with no
+ * script gets the line all the same: that is what makes its instances a package's and no fallback. The
+ * one place these are written; a page that has its tags has all of a package.
+ */
+export function packageTags(found) {
+  const mark = `${PACKAGE_MARK}="${found.id}"`;
+  const has = (file) => found.files.includes(file);
+  return {
+    styles: has("style.css") ? [`<link rel="stylesheet" href="${packageAddress(found, "style.css")}" ${mark}>`] : [],
+    scripts: [
+      `<script ${mark}>${describeLine({ ...descriptionOf(found), ...(has("kit.js") ? { script: true } : {}) })}</script>`,
+      ...(has("kit.js") ? [`<script src="${packageAddress(found, "kit.js")}" ${mark}></script>`] : []),
+    ],
+  };
+}
+
+/** Where a file of a package is now, or null. */
+export const packagePath = ({ folder }, file) => ownPath(folder, file);
+
+/** A package's stamp as its files are now, for the moment before the catalog in use has taken them. */
+export const packageStampNow = ({ folder, files }) => stampOf(folder, stamped(files));
+
+// The element `text` is, when it is one instance of the package `id` and nothing else (a comment
+// aside), closed by an end tag of its own, or null: what the parser closed at the end of the text
+// (an end tag left out, a comment or a field left open) would take in what stands after it in a file.
+function instanceIn(text, id) {
+  const nodes = parseFragment(text, { sourceCodeLocationInfo: true }).childNodes.filter((node) => node.tagName || (node.nodeName === "#text" && node.value.trim()));
+  const [root] = nodes;
+  return nodes.length === 1 && root.tagName && isInstance(root) && attr(root, ATTRIBUTE) === id && root.sourceCodeLocation.endTag ? root : null;
+}
+
+/**
+ * What a file is to hold of the instance `text` is, the one way a template or a copy's markup gets
+ * there, or null: { markup, root }. Its markup is written anew from what was read, so that what the
+ * parser put right is right in the file and what it dropped stays out (an end tag of nothing here
+ * would close what stands around the block there), and `root` is that markup read again: what the
+ * file will read, the thing to look at.
+ */
+export function instanceMarkup(text, id) {
+  const read = instanceIn(text, id);
+  const markup = read && serializeOuter(read);
+  const root = markup && instanceIn(markup, id);
+  return root ? { markup, root } : null;
+}
+
+// What the template of a package is: { markup } as a new instance is written, or { problem }, or
+// neither where it has none. It is to be what a new instance is: one instance of the package in one
+// piece, holding nothing a clipboard could not bring (refusedInCopy: a script, which would run from
+// the next load on alone, a handler, the editor's marks, which a page takes for its own), and the parts
+// its manifest asks for, or the block a reader makes keeps the document from passing gallery check.
+function readTemplate({ id, template, parts }) {
+  if (!template) return {};
+  const read = instanceMarkup(template, id);
+  if (!read) return { problem: said("template.html 要是这个组件包的一个实例，有自己的结束标签，此外什么都没有") };
+  const held = [];
+  walk({ childNodes: [read.root] }, (node) => { if (refusedInCopy(node.tagName, node.attrs)) held.push(node.tagName); });
+  if (held.length > 0) return { problem: said("template.html 里的 <{0}> 进不了新建的块：脚本、事件、样式和 Gallery 自己的标记都不写在模板里", held[0]) };
+  const short = Object.entries(parts).find(([, part]) => {
+    const count = partOf(read.root, part.at).length;
+    return count < (part.optional ? 0 : part.min ?? 1) || count > (part.edit === "flow" ? 1 : part.max ?? Infinity);
+  });
+  return short ? { problem: said("template.html 的 {0} 和清单写的数目不符", short[0]) } : { markup: read.markup };
+}
+
+/** Why no menu offers the template of `found`, said()'s, for `gallery component check` to say, or null: it has none, or one no reason keeps out. */
+export const templateProblem = (found) => readTemplate(found).problem ?? null;
+
+/** The markup of an instance of `found` as a new one is written, or null: it has no template a menu offers. */
+export const templateOf = (found) => readTemplate(found).markup ?? null;
+
+/**
+ * What the page the editor runs on holds of a catalog: its MAP's `components` (src/editor/service.mjs),
+ * no route and no dynamic import. One entry for each package that loads, by id: { id, version, name:
+ * { zh, en }, description: { zh, en }, words, definition, stamp, template (the markup "/" puts in: one
+ * instance of it, or null), preview (the address of its picture, or null), state ("normal", or "hidden": a menu offers what is "normal" and reads no setting), markdown, assets (the kit's files it asks for,
+ * by id), tags (packageTags: what loads it in a page that was served without it, the line that tells the
+ * kit of its parts among them) }. A page knows what it holds of a package's parts from the kit
+ * (descriptionsOf), and of one that came after it was served from these tags.
+ */
+export const menuOf = ({ packages, settings = NO_SETTINGS }) => [...packages.values()].sort(byId).map((found) => ({
+  id: found.id,
+  version: found.version,
+  name: found.name,
+  description: found.description,
+  words: found.words,
+  definition: found.definition,
+  stamp: found.stamp,
+  template: templateOf(found),
+  preview: found.files.includes("preview.svg") ? packageAddress(found, "preview.svg") : null,
+  state: stateOf(found, settings),
+  markdown: found.markdown,
+  assets: found.assets,
+  tags: packageTags(found),
+}));
+
+/**
+ * The workspace's packages as who lists them says them, by id: { id, version, name, description (what
+ * a manifest says, null where it does not read), state ("normal", "hidden", "disabled" or "broken":
+ * stateOf), reason ({ zh, en }, why it does not load of itself, or null), template (whether it has one
+ * a menu can put in: with none, none can), hidden and disabled (what gallery.json says of it) }.
+ */
+export const packageStates = ({ packages, problems, settings = NO_SETTINGS }) => [...packages.values(), ...problems.values()].sort(byId).map((found) => ({
+  id: found.id,
+  version: found.version ?? null,
+  name: found.name ?? null,
+  description: found.description ?? null,
+  state: stateOf(found, settings),
+  reason: found.problem && !found.off ? bothProblems(found.problem) : null,
+  template: Boolean(templateOf(found)),
+  hidden: settings.hidden.includes(found.id),
+  disabled: settings.disabled.includes(found.id),
+}));
+
+/** The message that tells a page of `settings` on its event stream, its two lists by commas: what it offers follows them, whatever it holds. */
+export const settingsLine = ({ hidden, disabled }) => `settings ${hidden.join(",")} ${disabled.join(",")}`;