@heycys/gallery 0.1.1 → 0.1.2

package/browser/shared/shipped-blocks.mjs

@@ -0,0 +1,299 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { beforeCatalogRead } from "./component-catalog.mjs";
+import { packsDirectory } from "./paths.mjs";
+import { PACKAGE_MANIFEST, layoutOf } from "./workspace.mjs";
+
+// Gallery's own custom blocks (自带块): the blocks of Gallery's own block packs (./block-packs.mjs), a
+// folder each in the package (src/packs/<pack>/<name>/ in the source checkout, packs/<pack>/<name>/ in
+// the release), each a block of the scope <pack> as any workspace's is, its manifest's id <pack>/<name>:
+// the pack gallery's (Gallery 风格) and gallery-soft's (柔光风格). A workspace's first start installs each
+// pack as any shared pack is installed (./block-packs.mjs installOfficialPacks); gallery block add <name>
+// (gallery's, or <pack>/<name>) copies one unchanged into a workspace, components/<pack>/<name>/, and records its
+// version and a fingerprint of what it copied in .gallery/blocks.json; adding it again updates a copy
+// that is as it was put there, and never one whose fingerprint has changed since, which is someone's
+// work (gallery block new <id> --recipe <name> starts a block of one's own from a shipped one instead).
+// The scopes of Gallery's packs are kept for these: gallery block new refuses them. A custom page's
+// service (phase 2) adds one the same way when a card asks for it.
+//
+// A workspace's copies follow Gallery (the user, 2026-11-09: a home page made with 1.0.0's cards kept
+// their plain look after 1.1.0 brought the cards' design): a copy that is as it was added and behind
+// Gallery's is updated in place, as gallery block add would update it, without the command
+// (followShipped): as a server starts (src/server/index.mjs, production.mjs), whenever its catalog
+// reads the workspace's blocks (readCatalog, by followOnRead's hook) and when the page service reads
+// them (its library, an add), once a process for each block and version, told once in the server's
+// log. A copy changed since it was added is someone's work and stays as it is: the log says so once,
+// and 设置 › 组件列表 and gallery block list say that Gallery has a newer one and how to take it.
+
+/** The scope of Gallery's own blocks that a bare name names (gallery block add card): the pack gallery's. */
+export const SHIPPED_SCOPE = "gallery";
+
+// What a system writes into a folder it shows, which nobody wrote: macOS's Finder (.DS_Store, and ._
+// files beside each on a disk of another format), Windows' Explorer (Thumbs.db, desktop.ini). No
+// fingerprint counts them, no add takes them out, and a recipe copies none.
+const SYSTEM_FILE = /^(?:\.DS_Store|\._.*|Thumbs\.db|ehthumbs\.db|desktop\.ini)$/i;
+
+/** Whether a file called `name` (its last part) is one a system wrote into a folder it showed. */
+export const isSystemFile = (name) => SYSTEM_FILE.test(name);
+
+/** The files of a folder, by their paths in it with "/", sorted, what a system wrote there left out. */
+export function filesIn(folder) {
+  return fs.readdirSync(folder, { recursive: true, withFileTypes: true }).filter((entry) => entry.isFile() && !SYSTEM_FILE.test(entry.name))
+    .map((entry) => path.relative(folder, path.join(entry.parentPath, entry.name)).split(path.sep).join("/")).sort();
+}
+
+/**
+ * The names of a block's files in the order they are written: its manifest last, what makes a folder a
+ * block to whoever watches (a running server's watcher, the catalog), so that a block that appears is
+ * whole, and one a write stopped partway through is a folder with no manifest, which loads as nothing.
+ */
+export const writingOrder = (names) => [...names.filter((name) => name !== PACKAGE_MANIFEST), ...(names.includes(PACKAGE_MANIFEST) ? [PACKAGE_MANIFEST] : [])];
+
+/** What a folder holds, as a hash of each file's path and bytes (what a system wrote there aside), or null when there is no such folder. */
+export function fingerprintOf(folder) {
+  if (!fs.existsSync(folder)) return null;
+  return fingerprintOfFiles(filesIn(folder).map((name) => ({ name, data: fs.readFileSync(path.join(folder, name)) })));
+}
+
+/** What fingerprintOf says of a folder that holds `files` alone ([{ name, data }], each by its path in it with "/"). */
+export function fingerprintOfFiles(files) {
+  const hash = createHash("sha256");
+  const named = files.filter(({ name }) => !SYSTEM_FILE.test(name.split("/").at(-1))).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  for (const { name, data } of named) hash.update(`${name}\u0000`).update(data).update("\n");
+  return hash.digest("hex").slice(0, 16);
+}
+
+// The folders right in `directory`, by name, or none where it is not there.
+const foldersOf = (directory) => {
+  try {
+    return fs.readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+  } catch {
+    return [];
+  }
+};
+
+/** The ids of Gallery's own packs in `directory` (the package's): each folder of it, by name. */
+export const shippedPackIds = (directory = packsDirectory) => foldersOf(directory);
+
+/**
+ * Gallery's own blocks in `directory` (the package's packs): [{ name, id, pack, folder, version, title:
+ * { zh, en }, description: { zh, en }, places }], by pack and name; a folder whose manifest does not read
+ * as its pack's block of its name is none.
+ */
+export function shippedBlocks(directory = packsDirectory) {
+  return foldersOf(directory).flatMap((pack) => foldersOf(path.join(directory, pack)).flatMap((name) => {
+    const folder = path.join(directory, pack, name);
+    try {
+      const manifest = JSON.parse(fs.readFileSync(path.join(folder, PACKAGE_MANIFEST), "utf8"));
+      if (manifest.id !== `${pack}/${name}`) return [];
+      return [{ name, id: manifest.id, pack, folder, version: manifest.version, title: manifest.name, description: manifest.description, places: manifest.places ?? ["document"] }];
+    } catch {
+      return [];
+    }
+  }));
+}
+
+/** The shipped block `written` names (card, gallery/card, gallery-soft/todos: a bare name is the pack gallery's), or null. */
+export function shippedBlock(written, directory = packsDirectory) {
+  const id = written.includes("/") ? written : `${SHIPPED_SCOPE}/${written}`;
+  return shippedBlocks(directory).find((block) => block.id === id) ?? null;
+}
+
+/** Whether `id` is of a scope of Gallery's own packs (gallery/…, gallery-soft/…). */
+export const isShippedId = (id, directory = packsDirectory) => shippedPackIds(directory).includes(String(id).split("/")[0]);
+
+/**
+ * .gallery/blocks.json: { "<id>": { version, fingerprint } } of each block added or installed (one of
+ * Gallery's own, or of a pack), and `packs`, { "<pack id>": { version, fingerprint, blocks, official? } } of
+ * each pack installed (./block-packs.mjs); {} for none or a file that does not read.
+ */
+export function recordOf(root) {
+  try {
+    const record = JSON.parse(fs.readFileSync(layoutOf(root).blocks, "utf8"));
+    return record && typeof record === "object" && !Array.isArray(record) ? record : {};
+  } catch {
+    return {};
+  }
+}
+
+/** .gallery/blocks.json as `record` says. */
+export function writeRecord(root, record) {
+  const file = layoutOf(root).blocks;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`);
+}
+
+/** Where a block of the workspace at `root` is. */
+const folderIn = (root, id) => path.join(layoutOf(root).components, ...id.split("/"));
+
+/**
+ * What the workspace at `root` holds of the shipped `block`: { added (a folder of its id is there),
+ * version (what its manifest says, or null), changed (its files are not what was added: changed since,
+ * or put there by some other hand), behind (it is as added, and Gallery's is another now) }.
+ */
+export function shippedState(root, block) {
+  const folder = folderIn(root, block.id);
+  const now = fingerprintOf(folder);
+  if (now === null) return { added: false, version: null, changed: false, behind: false };
+  let version = null;
+  try {
+    version = JSON.parse(fs.readFileSync(path.join(folder, PACKAGE_MANIFEST), "utf8")).version ?? null;
+  } catch {}
+  const kept = recordOf(root)[block.id];
+  const shipped = fingerprintOf(block.folder);
+  const changed = now !== shipped && now !== kept?.fingerprint;
+  return { added: true, version, changed, behind: !changed && now !== shipped };
+}
+
+/**
+ * Copies the shipped `block` into the workspace at `root`, unchanged: { did: "added", "updated" (from a
+ * copy as it was added, `from` its version) or "same" (nothing to do), folder }. A copy whose files
+ * changed since it was added (or that no add put there) is left as it is: an error with code "changed".
+ * The manifest is written last, what makes a folder a block to a running server's watcher, so that a
+ * block that appears is whole; files of the old copy that the new one has not go first.
+ */
+export function addShipped(root, block) {
+  const folder = folderIn(root, block.id);
+  const state = shippedState(root, block);
+  if (state.changed) throw Object.assign(new Error(`${block.id} was changed after it was added`), { code: "changed", folder });
+  const shipped = fingerprintOf(block.folder);
+  const record = recordOf(root);
+  if (state.added && !state.behind) {
+    if (record[block.id]?.fingerprint !== shipped) writeRecord(root, { ...record, [block.id]: { version: block.version, fingerprint: shipped } });
+    return { did: "same", folder };
+  }
+  const files = filesIn(block.folder);
+  if (state.added) for (const old of filesIn(folder)) if (!files.includes(old)) fs.rmSync(path.join(folder, old));
+  for (const file of writingOrder(files)) {
+    fs.mkdirSync(path.dirname(path.join(folder, file)), { recursive: true });
+    fs.copyFileSync(path.join(block.folder, file), path.join(folder, file));
+  }
+  writeRecord(root, { ...record, [block.id]: { version: block.version, fingerprint: shipped } });
+  return { did: state.added ? "updated" : "added", from: state.version, folder };
+}
+
+// A version's numbers (1.10.0: [1, 10, 0]), or null for one that is not three of them.
+const numbersOf = (version) => (/^\d+\.\d+\.\d+$/.test(String(version ?? "")) ? version.split(".").map(Number) : null);
+
+/** Whether version `a` comes after `b` (both x.y.z); `b` none or not of that form: whether they differ. */
+export function versionAfter(a, b) {
+  const [x, y] = [numbersOf(a), numbersOf(b)];
+  if (!x || !y) return a !== b;
+  const at = x.findIndex((number, index) => number !== y[index]);
+  return at !== -1 && x[at] > y[at];
+}
+
+/**
+ * The version of the shipped `block` that the workspace at `root` does not take because its copy was
+ * changed since it was added (or no add put it there), when Gallery's comes after the copy's; else null.
+ */
+export function shippedNewer(root, block) {
+  const state = shippedState(root, block);
+  return state.changed && versionAfter(block.version, state.version) ? block.version : null;
+}
+
+const looked = new Map(); // a workspace's root and a shipped block's folder -> the version of it looked at
+let told = () => {}; // where followShipped tells what it did when it is not given a log: the server's (followOnRead)
+
+// What followShipped did, as lines of the log.
+function followedLines(root, { updated, kept, failed }) {
+  const lines = [];
+  if (updated.length) lines.push(`Gallery's own blocks in ${root}, as they were added, updated to this Gallery's: ${updated.map(({ id, from, to }) => `${id} ${from ?? "?"} -> ${to}`).join(", ")}`);
+  for (const { id, version, shipped } of kept) lines.push(`${id} in ${root} was changed after it was added, so it stays at ${version ?? "its version"}: Gallery's is ${shipped} (设置 › 组件列表 says how to take it)`);
+  for (const { id, to, why } of failed) lines.push(`${id} in ${root} could not be updated to Gallery's ${to}: ${why}`);
+  return lines;
+}
+
+/**
+ * Bring the workspace at `root`'s copies of Gallery's own blocks (of `ids`, by default each one) up to
+ * Gallery's (in `directory`): one that is as it was added and behind is updated as addShipped updates
+ * it (the manifest written last); one changed since it was added is kept as it is. Each block and
+ * version is looked at once a process, a later call for it doing nothing, so that what reads the blocks
+ * again and again (a server's catalog, its page service) pays once. `log`: told once of what was done,
+ * a line each (by default the one followOnRead set: none in a command). Never throws: { updated: [{ id,
+ * from, to }], kept: [{ id, version, shipped }] (changed, Gallery's newer), failed: [{ id, to, why }] }.
+ */
+export function followShipped(root, { ids = null, directory = packsDirectory, log = null } = {}) {
+  const done = { updated: [], kept: [], failed: [] };
+  const key = path.resolve(root);
+  for (const block of shippedBlocks(directory)) {
+    if (ids && !ids.includes(block.id)) continue;
+    const at = `${key}\u0000${path.resolve(block.folder)}`;
+    if (looked.get(at) === block.version) continue;
+    looked.set(at, block.version);
+    try {
+      const state = shippedState(root, block);
+      if (state.changed && versionAfter(block.version, state.version)) done.kept.push({ id: block.id, version: state.version, shipped: block.version });
+      if (!state.behind) continue;
+      if (addShipped(root, block).did === "updated") done.updated.push({ id: block.id, from: state.version, to: block.version });
+    } catch (error) {
+      done.failed.push({ id: block.id, to: block.version, why: error?.message ?? String(error) });
+    }
+  }
+  for (const line of followedLines(key, done)) (log ?? told)(line);
+  return done;
+}
+
+const following = new Set(); // the workspaces whose server runs in this process (followOnRead), by their resolved root
+const keyOf = (root) => (process.platform === "win32" ? path.resolve(root).toLowerCase() : path.resolve(root));
+
+/**
+ * From now on in this process, the catalog brings the copies of Gallery's own blocks of the workspace at
+ * `root` up to Gallery's before it reads them (followShipped, its ids those of the scopes of Gallery's
+ * packs it finds), and what is done of it is told to `log` (a line): a server's, set as it starts for
+ * its own workspace (another's blocks are its own server's to follow, and a test's process reads the
+ * repository's reports/ too, which nothing of it is to write).
+ */
+export function followOnRead(root, log) {
+  following.add(keyOf(root));
+  told = log;
+  beforeCatalogRead((read, ids) => {
+    if (following.has(keyOf(read))) followShipped(read, { ids });
+  }, shippedPackIds());
+}
+
+// The words of a shipped block's files that name it, and what a recipe's copy names instead: its id,
+// and the id with "-" for "/" (a class, a chart type).
+const namesOf = (id) => [id, id.replace("/", "-")];
+const escaped = (words) => words.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * The shipped block whose preview.svg the file `bytes` is, byte for byte, as Gallery ships it or as a
+ * recipe of it for the block `id` has it (every word that named it naming `id`), or null: a block made
+ * by --recipe keeps its recipe's picture until someone draws its own, which gallery block check notes.
+ */
+export function shippedPreviewOf(bytes, id, directory = packsDirectory) {
+  for (const block of shippedBlocks(directory)) {
+    if (block.id === id) continue; // a shipped block's own picture is its own
+    let shipped;
+    try {
+      shipped = fs.readFileSync(path.join(block.folder, "preview.svg"));
+    } catch {
+      continue;
+    }
+    if (shipped.equals(bytes) || Buffer.from(recipeFiles(block, id)["preview.svg"] ?? "").equals(bytes)) return block;
+  }
+  return null;
+}
+
+/**
+ * The files of a new block `id` made from the shipped `block` (gallery block new <id> --recipe <name>),
+ * by name, the manifest last: each as Gallery ships it, every word that names the shipped block naming
+ * the new one, all in one pass, so that a new name holding an old one (local/gallery-card, made of
+ * gallery/card) is not renamed again; its version 0.1.0.
+ */
+export function recipeFiles(block, id) {
+  const [from, to] = [namesOf(block.id), namesOf(id)];
+  const names = new RegExp(from.map(escaped).join("|"), "g");
+  const files = {};
+  for (const file of filesIn(block.folder)) {
+    const bytes = fs.readFileSync(path.join(block.folder, file));
+    if (/\.(?:json|html|md|css|js|svg)$/.test(file)) {
+      let text = bytes.toString("utf8").replace(names, (name) => to[from.indexOf(name)]);
+      if (file === PACKAGE_MANIFEST) text = text.replace(/"version":\s*"[^"]*"/, '"version": "0.1.0"');
+      files[file] = text;
+    } else files[file] = bytes;
+  }
+  return Object.fromEntries(writingOrder(Object.keys(files)).map((name) => [name, files[name]]));
+}

package/browser/shared/table-chart.mjs

@@ -13,11 +13,21 @@ import { isMissingValue, numberReading } from "./number-reading.mjs";
 // copy or delete either block (a copied pair takes a key of its own:
 // src/editor/page/clipboard/own/chart-keys.mjs, and the commit makes sure of it against the file:
 // src/editor/source/chart-keys.mjs).
+//
+// A view of a table (plan 阶段 4: a task board, a count, a chart card of a custom block's) is the same
+// link: an instance of a custom block whose manifest's needs hold "tables" names the table by that key
+// (VIEW_FROM), reads its rows as a chart does (the kit's runtime/table-reading.js, context.table()) and
+// changes them only by asking the page editor (an intent: docs/editor.md, "Table views"). A key is one
+// table's, which any number of charts and views read: TABLE_READERS are the attributes that read one.
 
 /** On a chart's host: the key of the table it draws. */
 export const CHART_DATA = "data-doc-chart-data";
 /** On a table's frame (.doc-table-wrap): the key a chart reads it by. */
 export const CHART_SOURCE = "data-doc-chart-source";
+/** On an instance of a custom block whose needs hold "tables": the key of the table it is a view of (context.table()). */
+export const VIEW_FROM = "data-doc-from";
+/** The attributes that name a table by its key, a chart's host's and a view's. */
+export const TABLE_READERS = [CHART_DATA, VIEW_FROM];
 /** A key: a letter, then letters, digits, "_" or "-", 32 at most. */
 export const CHART_KEY = /^[A-Za-z][\w-]{0,31}$/;
 
@@ -38,6 +48,28 @@ const FORMULA = /\\\(([\s\S]*?)\\\)|\\\[([\s\S]*?)\\\]|\$\$([\s\S]*?)\$\$/g;
  */
 export const cellWords = (text) => text.replace(FORMULA, (_, inline, display, dollars) => inline ?? display ?? dollars).replaceAll(ZWSP, "").replace(/\s+/g, " ").trim();
 
+// A formula KaTeX drew on a page: its TeX is its annotation (its drawing's text is its glyphs, twice over).
+const TEX = 'annotation[encoding="application/x-tex"]';
+
+/**
+ * A cell's text on a page as the file writes it, as near as the page tells: a formula KaTeX drew as its
+ * TeX, the editor's chip of an empty one as nothing (the file's \(\)). Its words are then cellWords'.
+ * For the kit, which reads a table on a page (runtime/table-reading.js: a chart's, a view's and a package's rows).
+ * @param {Node} node
+ * @returns {string}
+ */
+export function cellText(node) {
+  if (node.nodeType === 3) return /** @type {Text} */ (node).data;
+  if (node.nodeType !== 1) return "";
+  const element = /** @type {Element} */ (node);
+  if (element.hasAttribute("data-ge-empty")) return "";
+  const tex = element.classList.contains("katex") ? element.querySelector(TEX) : null;
+  if (tex) return tex.textContent ?? "";
+  let text = "";
+  for (const child of element.childNodes) text += cellText(child);
+  return text;
+}
+
 // A header's data-sort-type that says its column holds no numbers: its values are its words.
 const WORD_TYPES = new Set(["text", "date"]);
 
@@ -66,7 +98,7 @@ export function cellValue(cell, type = null) {
  * row of header cells alone; null when it has neither), its header cells' data-sort-type (null where
  * none), its rows of data in the file's order (never a <tfoot>'s), each cell { words, sort } (its
  * words, cellWords', and its data-sort-value, or null), and whether a cell of the header or the rows
- * spans rows or columns (charts/from-table.js tableCells reads it from the page,
+ * spans rows or columns (runtime/table-reading.js readTable reads it from the page,
  * chart-declarations.mjs tableCells from the file).
  *
  * `data` is what d3.csvParse gives: an object for each row of data, in their order, its values by

package/browser/shared/todos.mjs

@@ -0,0 +1,83 @@
+import { parse } from "parse5";
+import { TODO } from "./components/list.mjs";
+import { sha256 } from "./files.mjs";
+import { attr, BLOCK_LEVEL, elementsOf, hasClass } from "./html-tree.mjs";
+
+// A document's to-dos as its pages show them (the items of its to-do lists, ul.doc-todo): what the
+// workspace's facts list (src/workbench/index.mjs, workspace.query("todos")) and what a check of one
+// from another page finds it by (src/editor/todos.mjs, workspace.setTodo: the plan's 5.1), the one
+// reading for both, so that a ref the facts gave names the item the write looks for. Pure but for the
+// parser and the hash: no DOM.
+
+const SKIPPED = new Set(["script", "style", "template", "noscript", "svg", "math"]);
+const HEADING = /^h([1-6])$/;
+const tidy = (text) => text.replace(/[\s​]+/g, " ").trim();
+
+// The words an element holds, as a reader reads them: its text, a line break a space, nothing of a script,
+// a style or a drawing; `stop(child)`: a child left out with what it holds.
+function wordsOf(node, stop = () => false) {
+  let text = "";
+  const visit = (current) => {
+    for (const child of current.childNodes ?? []) {
+      if (child.nodeName === "#text") text += child.value;
+      else if (child.tagName === "br") text += " ";
+      else if (child.tagName && !SKIPPED.has(child.tagName) && !stop(child)) visit(child);
+    }
+  };
+  visit(node);
+  return tidy(text);
+}
+
+// A to-do's own words: what the item holds before its lists and the blocks it holds (a paragraph, a
+// picture), or, where it holds no words of its own (an item written <li><p>…</p></li>), its first block's.
+function itemWords(item) {
+  const own = wordsOf(item, (child) => BLOCK_LEVEL.has(child.tagName));
+  if (own) return own;
+  const first = elementsOf(item).find((child) => BLOCK_LEVEL.has(child.tagName) && child.tagName !== "ul" && child.tagName !== "ol");
+  return first ? wordsOf(first, (child) => child.tagName === "ul" || child.tagName === "ol") : "";
+}
+
+/**
+ * The to-dos of a document's `text` (its page's HTML, as its pages see it), in their order: [{ text,
+ * done, block, path, nth }], `path` the headings above it (their words, the outermost first: an h2 under
+ * an h1 of the body, the document's title never one), `nth` which of the to-dos of the same words under
+ * the same path it is (0 the first). With `at`, each says where its <li> starts in `text` too (`at`, the
+ * offset of its start tag), which the editor's units name it by (source/units.mjs elStart).
+ */
+export function todosOf(text, { at = false } = {}) {
+  const root = parse(String(text), { sourceCodeLocationInfo: at });
+  const headings = []; // [{ level, words }]
+  const todos = [];
+  const seen = new Map();
+  const visit = (node) => {
+    for (const child of elementsOf(node)) {
+      if (SKIPPED.has(child.tagName)) continue;
+      const heading = HEADING.exec(child.tagName);
+      if (heading && !hasClass(child, "doc-title")) {
+        const level = Number(heading[1]);
+        while (headings.length && headings.at(-1).level >= level) headings.pop();
+        const words = wordsOf(child);
+        if (words) headings.push({ level, words });
+        continue;
+      }
+      if (child.tagName === "li" && child.parentNode?.tagName === "ul" && hasClass(child.parentNode, TODO)) {
+        const path = headings.map(({ words }) => words);
+        const words = itemWords(child);
+        const key = JSON.stringify([words, path]);
+        const nth = seen.get(key) ?? 0;
+        seen.set(key, nth + 1);
+        todos.push({ text: words, done: attr(child, "data-checked") !== undefined, block: attr(child, "data-block-id") ?? null, path, nth, ...(at ? { at: child.sourceCodeLocation?.startOffset ?? -1 } : {}) });
+      }
+      visit(child);
+    }
+  };
+  visit(root);
+  return todos;
+}
+
+/**
+ * The version of a document's file the facts read its to-dos from (the hash of its text, as a to-do's
+ * ref carries it: workspace.query("todos")), which a check of one finds it by its place in (`nth`) while
+ * the file is still that one.
+ */
+export const fileVersion = (source) => sha256(source).slice(0, 16);

package/browser/shared/user-directory.mjs

@@ -0,0 +1,24 @@
+import os from "node:os";
+import path from "node:path";
+
+// The user's own folders for Gallery, outside every workspace: "cache", what may be thrown away (the
+// update check's answer, src/cli/updates.mjs), and "data", what Gallery keeps of the machine (the
+// registry of the workspaces used on it, ./workspace-registry.mjs). One function, so that every system
+// finds them alike. Node's built-ins only: gallery --version reads it, and stays as fast as Node's start.
+
+/**
+ * The folder of `kind` ("cache" or "data"): GALLERY_CACHE_DIR or GALLERY_DATA_DIR when set (the tests
+ * name folders of their own); else on Windows %LOCALAPPDATA%\gallery for both; on macOS
+ * ~/Library/Caches/gallery and ~/Library/Application Support/gallery; elsewhere $XDG_CACHE_HOME/gallery
+ * (~/.cache/gallery) and $XDG_STATE_HOME/gallery (~/.local/state/gallery). Only a path: nothing is made.
+ */
+export function userDirectory(kind, { env = process.env, platform = process.platform, home = os.homedir() } = {}) {
+  const cache = kind === "cache";
+  const own = cache ? env.GALLERY_CACHE_DIR : env.GALLERY_DATA_DIR;
+  if (own) return path.resolve(own);
+  if (platform === "win32") return path.join(env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "gallery");
+  if (platform === "darwin") return path.join(home, "Library", cache ? "Caches" : "Application Support", "gallery");
+  return cache
+    ? path.join(env.XDG_CACHE_HOME || path.join(home, ".cache"), "gallery")
+    : path.join(env.XDG_STATE_HOME || path.join(home, ".local", "state"), "gallery");
+}

package/browser/shared/versions.mjs

@@ -0,0 +1,14 @@
+// Gallery's versions compared, with nothing imported: the preview server's choice of a server to use
+// or replace (./preview-server.mjs) and gallery --version's notes (src/cli/updates.mjs, which loads
+// nothing it can do without) read it.
+
+/** -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;
+}
+
+/** A released version as npm writes one, numbers alone (0.1.2): what a registry's answer must be to be believed. */
+export const RELEASED = /^\d{1,6}\.\d{1,6}\.\d{1,6}$/;

package/browser/shared/web-links.mjs

@@ -0,0 +1,134 @@
+import { iconKind } from "./emoji/icon-value.mjs";
+
+// A web link of the sidebar (docs/workbench.md "Web links"): a folder at the workspace's root, named by
+// a slug from the pool documents and custom pages share, holding link.json alone:
+//   { "url": "https://open-meteo.com/en/docs", "title": "天气接口文档", "icon": "🌤️", "siteIcon": "data:image/png;base64,…" }
+// `url` an http or https address of 2048 characters at most, `title` 1 to 200 characters, `icon` an
+// emoji or an icon of the 图标 tab, the user's (no picture: a link keeps no files), `siteIcon` the site's
+// own icon, fetched once as the link is added (src/editor/unfurl.mjs siteIcon) and kept in the file as a
+// data: address (PNG, ICO, SVG, JPEG, WebP or GIF, 16 KB at most: SITE_ICON_BYTES), shown when the
+// user chose none (the grid globe when neither is there). The workbench shows it in its
+// content area in a sandboxed frame (features/link/LinkView.tsx), never as a document: no session, no
+// export, no check, no search of its text. A folder holding doc.html (or report.html) is a document
+// whatever else it holds. What is read and checked here is the same on the server, in the gallery
+// command and in the workbench; reading and writing the file is ./workspace.mjs's (Node's).
+
+/** A link's file in its folder. */
+export const LINK_FILE = "link.json";
+export const LINK_LIMITS = { url: 2048, title: 200 };
+/** The largest site icon a link keeps, in bytes (its data: address holds them in base64). */
+export const SITE_ICON_BYTES = 16 * 1024;
+/** The media types of a site icon a link keeps. */
+export const SITE_ICON_TYPES = ["image/png", "image/x-icon", "image/vnd.microsoft.icon", "image/svg+xml", "image/jpeg", "image/webp", "image/gif"];
+
+/** Whether `value` is a site icon a link keeps: a base64 data: address of one of SITE_ICON_TYPES, SITE_ICON_BYTES at most. */
+export function isSiteIcon(value) {
+  if (typeof value !== "string") return false;
+  const match = /^data:([a-z+./-]+);base64,([A-Za-z0-9+/]+={0,2})$/.exec(value);
+  if (!match || !SITE_ICON_TYPES.includes(match[1])) return false;
+  const bytes = (match[2].length * 3) / 4 - (match[2].endsWith("==") ? 2 : match[2].endsWith("=") ? 1 : 0);
+  return bytes > 0 && bytes <= SITE_ICON_BYTES;
+}
+
+/**
+ * The sandbox of a web page's frame, the embed block's (Notion's): scripts, its own origin (a page of
+ * another site, which can then not reach the workbench's), forms, popups that leave the sandbox, a
+ * top navigation only by the reader's own click.
+ */
+export const WEB_SANDBOX = "allow-scripts allow-popups allow-top-navigation-by-user-activation allow-forms allow-same-origin allow-storage-access-by-user-activation allow-popups-to-escape-sandbox";
+
+const tidy = (value) => (typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "");
+
+/**
+ * Address `value` as a link takes it: { url } (the URL's own spelling, a scheme written in) or
+ * { refused, message } — "url" (no address), "scheme" (not http or https: javascript:, file:, data:…),
+ * "long" (over 2048 characters). An address written without a scheme (example.com/a) is taken as https.
+ */
+export function linkAddress(value) {
+  const written = tidy(value);
+  if (!written) return { refused: "url", message: "网址不能是空的" };
+  const withScheme = /^[a-z][a-z0-9+.-]*:/i.test(written) ? written : `https://${written}`;
+  let url;
+  try {
+    url = new URL(withScheme);
+  } catch {
+    return { refused: "url", message: "这不是一个网址" };
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return { refused: "scheme", message: "只能链接 http 或 https 的网址" };
+  if (!url.hostname) return { refused: "url", message: "这不是一个网址" };
+  if (url.href.length > LINK_LIMITS.url) return { refused: "long", message: "网址太长了（最多 2048 个字符）" };
+  return { url: url.href };
+}
+
+/** Whether `icon` is one a link takes: an emoji or an icon of the 图标 tab. */
+export const linkIcon = (icon) => ["emoji", "glyph"].includes(iconKind(icon));
+
+/**
+ * A link's file as it is to be written: { value: { url, title, icon?, siteIcon? } } or { refused, message }
+ * (linkAddress's, "title": empty or over 200 characters, "icon": no emoji nor icon of the 图标 tab). A site
+ * icon that is none (isSiteIcon) is left out, never refused: the add never fails for it.
+ */
+export function linkValue({ url, title, icon = null, siteIcon = null }) {
+  const address = linkAddress(url);
+  if (address.refused) return address;
+  const name = tidy(title);
+  if (!name || name.length > LINK_LIMITS.title) return { refused: "title", message: "名称不能是空的，也不能超过 200 个字" };
+  if (icon !== null && icon !== undefined && icon !== "" && !linkIcon(icon)) return { refused: "icon", message: "图标只能是表情或图标页签里的图标" };
+  return { value: { url: address.url, title: name, ...(icon ? { icon } : {}), ...(isSiteIcon(siteIcon) ? { siteIcon } : {}) } };
+}
+
+/** What link.json's text says, as a link: { url, title, icon?, siteIcon? }, or null for a file that is no link (one written by hand wrong). */
+export function readLinkText(text) {
+  let value;
+  try {
+    value = JSON.parse(String(text).replace(/^/, ""));
+  } catch {
+    return null;
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const made = linkValue({ url: value.url, title: value.title, icon: linkIcon(value.icon) ? value.icon : null, siteIcon: value.siteIcon });
+  return made.value ?? null;
+}
+
+/**
+ * Whether address `url` is this Gallery's own (`port` its server's): the workbench's host by any of
+ * its names (127.0.0.1, localhost, ::1) and port. A link there is refused: framed with the sandbox's
+ * allow-same-origin and scripts, the workbench's own page could reach the workbench.
+ */
+export function ownAddress(url, port) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  const host = parsed.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  const given = parsed.port || (parsed.protocol === "https:" ? "443" : "80");
+  return ["127.0.0.1", "localhost", "::1", "0.0.0.0"].includes(host) && String(port) === given;
+}
+
+/**
+ * A slug made of words: their Latin letters and digits, lowercase, kebab-case, 60 characters at most
+ * (cut where a word ends); "" when none of them is a word of three letters (a title in Chinese, or one
+ * whose Latin is a version alone: "… v2.2 …"). gallery import's, and a link's.
+ */
+export const kebab = (text) => {
+  const words = String(text ?? "").normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  if (!/[a-z]{3}/.test(words)) return "";
+  return words.length <= 60 ? words : words.slice(0, 61).replace(/-[^-]*$/, "") || words.slice(0, 60);
+};
+
+/**
+ * The stem of a new link's slug (a number added after it when it is taken: the workspace's freeSlug):
+ * its title's Latin words, else its site's name (open-meteo of open-meteo.com, www passed over), else "link".
+ */
+export function linkStem(title, url) {
+  const words = kebab(title);
+  if (words) return words;
+  let host = "";
+  try {
+    host = new URL(url).hostname.replace(/^www\./, "");
+  } catch {}
+  const site = kebab(host.split(".")[0] ?? "");
+  return site || "link";
+}