@heycys/gallery 0.1.0 → 0.1.2

package/browser/shared/json-layout.mjs

@@ -0,0 +1,47 @@
+// JSON written back as it was laid out (references/block-script.md, "Writing back"): what a
+// package's script of data holds, rewritten by a reader's gesture, changes on the lines that gesture
+// means and no others. One copy for every side: the kit's context.editJSON (runtime/kernel.js) writes
+// by it, and gallery block check (cli/component-look.mjs) says by it how a part not laid out so
+// would be. Pure, no DOM and no Node.
+
+// A value that stands alone on a line's end: no object, no list.
+const isValue = (value) => value === null || typeof value !== "object";
+
+/** Whether an object or a list holds values alone, or lists of values: what stands on one line (`{ "name": "价格", "weight": 3 }`, `[[1, 2], [3, 4]]`). */
+export const isFlat = (value) => Object.values(value).every((each) => isValue(each) || (Array.isArray(each) && each.every(isValue)));
+
+/**
+ * `value` as JSON laid out as a person writes it: what isFlat says on one line, with a space inside an
+ * object's braces (`{ "name": "价格", "weight": 3 }`, `[4, 3, 5]`), anything else a line for each
+ * entry, two spaces a level from `indent`, so that a change of one value changes its line alone.
+ * @param {unknown} value
+ * @param {string} indent
+ * @returns {string}
+ */
+export function laidOut(value, indent) {
+  if (typeof value?.toJSON === "function") return laidOut(value.toJSON(), indent); // a Date, as JSON.stringify writes it
+  if (isValue(value)) return JSON.stringify(value) ?? "null";
+  const list = Array.isArray(value);
+  // An object's entry of no JSON (undefined, a function) is left out, as JSON.stringify leaves it; a
+  // value with toJSON (a Date) is what that gives.
+  const entries = Object.entries(value).map(([key, each]) => [key, typeof each?.toJSON === "function" ? each.toJSON() : each]).filter(([, each]) => list || (each !== undefined && typeof each !== "function"));
+  const items = entries.map(([key, each]) => `${list ? "" : `${JSON.stringify(key)}: `}${laidOut(each, `${indent}  `)}`);
+  if (items.length === 0) return list ? "[]" : "{}";
+  if (isFlat(Object.fromEntries(entries))) return list ? `[${items.join(", ")}]` : `{ ${items.join(", ")} }`;
+  return `${list ? "[" : "{"}\n${items.map((item) => `${indent}  ${item}`).join(",\n")}\n${indent}${list ? "]" : "}"}`;
+}
+
+/**
+ * The JSON of `value` in place of what `text` holds (a script of data's text): on one line where it
+ * was on one, else laid out (laidOut) from the indentation its first character stands at; the blanks
+ * around it kept, and `</` and `<!--`, which could end the script it stands in, escaped.
+ * @param {string} text
+ * @param {unknown} value
+ */
+export function jsonIn(text, value) {
+  const start = text.length - text.trimStart().length;
+  const end = text.trimEnd().length;
+  const indent = text.slice(text.lastIndexOf("\n", start) + 1, start);
+  const json = text.slice(start, end).includes("\n") ? laidOut(value, indent) : JSON.stringify(value) ?? "null";
+  return text.slice(0, start) + json.replaceAll("</", "<\\/").replaceAll("<!--", "\\u003c!--") + text.slice(end);
+}

package/browser/shared/long-runs.mjs

@@ -0,0 +1,39 @@
+// Where a line may break inside a word: one rule for the kit's runtime (runtime/spacing.js: the
+// reading page holds each long run in a span that breaks anywhere), its flowcharts' line model
+// (runtime/flowchart.js piecesOf) and the page editor (page/long-runs.mjs: a text block holding one
+// breaks anywhere as a whole). Ordinary words stay whole at a line's end, in a Chinese page as in an
+// English one; a run of more than LONG_RUN characters with no place to break inside it (a path, a
+// URL, a long identifier) breaks where its line ends, never carried whole to the next line leaving
+// the line before it short (the user's words of 2026-11-07, and of 2026-11-06 before them).
+//
+// A run is what stands between spaces, Chinese, Japanese or Korean characters, full-width forms and
+// the general punctuation (dashes, curly quotes, an ellipsis, a zero-width space: where a line breaks
+// already, or what a path or an identifier does not hold): letters, digits and the marks of paths and
+// URLs (. : / \ _ = & % # @ …). Inside one Chrome breaks a line after a hyphen and after a question
+// mark, and at no other mark of ASCII (Chrome 156: not at a slash, a dot, a colon, a backslash or an
+// underscore), so a run is counted by its pieces there: state-of-the-art is three short pieces, never
+// long; D:\code\FinHarness\FinHarness-Demo.html is long by its first piece (30 characters).
+// DOM-free.
+
+/** A run longer than this many characters (by its longest piece) breaks anywhere. */
+export const LONG_RUN = 20;
+
+const RUNS = /[^\s\u2000-\u206f\u2e80-\u9fff\uac00-\ud7af\uf900-\ufaff\ufe30-\ufe4f\uff00-\uffef]+/gu;
+const PIECES = /(?<=[-?])/u;
+
+const long = (run) => run.length > LONG_RUN && run.split(PIECES).some((piece) => [...piece].length > LONG_RUN);
+
+/** The long runs of `text`, in order: { index, length } each (code units). */
+export function longRuns(text) {
+  const found = [];
+  if (text.length <= LONG_RUN) return found;
+  for (const match of text.matchAll(RUNS)) if (long(match[0])) found.push({ index: match.index, length: match[0].length });
+  return found;
+}
+
+/** Whether `text` holds a long run. */
+export function holdsLongRun(text) {
+  if (text.length <= LONG_RUN) return false;
+  for (const match of text.matchAll(RUNS)) if (long(match[0])) return true;
+  return false;
+}

package/browser/shared/net-cache.mjs

@@ -0,0 +1,133 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { writeAtomic } from "./files.mjs";
+import { layoutOf } from "./workspace.mjs";
+
+// What the server's net route kept of the web (src/server/net-route.mjs; docs/render.md, "A block
+// online"): each answer by the address a block asked for (its href, `{key}` as the block wrote it, never
+// the key: ./net-policy.mjs), in memory and in the workspace's .gallery/cache/net/, a file each
+// (<hash>.json: { url, at, type, text }), the last FILES of them. Which document's instances asked for
+// which address, and as what, is kept beside them (documents/<slug>.json: { <url>: { at, as } }), the
+// last PER_DOCUMENT of each: what an export of that document embeds (netSnapshot, the spec §9), so that
+// the file shows what the reader saw last. Anything here may be thrown away: the next ask fetches again.
+// Gallery's own, never served by a route, never in a file of the user's.
+
+/** How many answers stay on disk. */
+export const FILES = 200;
+/** How many addresses a document's index keeps. */
+export const PER_DOCUMENT = 20;
+/** What an export's snapshot holds of the net at most: addresses, and the bytes of their answers. */
+export const SNAPSHOT = { count: 20, bytes: 512 * 1024 };
+
+const folderOf = (root) => layoutOf(root).netCache;
+const fileOf = (root, url) => path.join(folderOf(root), `${createHash("sha256").update(url).digest("hex").slice(0, 24)}.json`);
+const indexOf = (root, slug) => path.join(folderOf(root), "documents", `${slug}.json`);
+const readJson = (file) => {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+};
+const isEntry = (entry, url) => entry && entry.url === url && typeof entry.at === "string" && typeof entry.text === "string" && typeof entry.type === "string";
+
+/** An answer as a block asked for it (`as`: "json" or "text"): its JSON read, or its text; undefined for JSON that does not read. */
+export function dataOf(entry, as) {
+  if (as === "text") return entry.text;
+  try {
+    return JSON.parse(entry.text);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The cache of workspace `root`: get(url) (the entry kept, from memory or disk, or null), put(url,
+ * { type, text, at }) (kept in both; the oldest files beyond FILES go), used(url, slug, as) (a document's
+ * instance asked for it: its index says so). Writes go on after the call returns; `settled()` waits for them.
+ */
+export function createNetCache(root, { memory = 100 } = {}) {
+  const held = new Map(); // url -> entry, the most recent last
+  let writes = Promise.resolve();
+  const later = (task) => {
+    writes = writes.then(task).catch(() => {});
+    return writes;
+  };
+  const hold = (url, entry) => {
+    held.delete(url);
+    held.set(url, entry);
+    while (held.size > memory) held.delete(held.keys().next().value);
+  };
+  const prune = () => {
+    const folder = folderOf(root);
+    let names = [];
+    try {
+      names = fs.readdirSync(folder).filter((name) => name.endsWith(".json"));
+    } catch {
+      return;
+    }
+    if (names.length <= FILES) return;
+    const dated = names.map((name) => ({ name, at: fs.statSync(path.join(folder, name), { throwIfNoEntry: false })?.mtimeMs ?? 0 })).sort((a, b) => a.at - b.at);
+    for (const { name } of dated.slice(0, dated.length - FILES)) fs.rmSync(path.join(folder, name), { force: true });
+  };
+  return {
+    get(url) {
+      if (held.has(url)) return held.get(url);
+      const entry = readJson(fileOf(root, url));
+      if (!isEntry(entry, url)) return null;
+      hold(url, entry);
+      return entry;
+    },
+    put(url, { type, text, at }) {
+      const entry = { url, at, type, text };
+      hold(url, entry);
+      later(async () => {
+        await fs.promises.mkdir(folderOf(root), { recursive: true });
+        await writeAtomic(fileOf(root, url), `${JSON.stringify(entry)}\n`);
+        prune();
+      });
+      return entry;
+    },
+    used(url, slug, as) {
+      if (typeof slug !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) return;
+      later(async () => {
+        const file = indexOf(root, slug);
+        const index = readJson(file) ?? {};
+        delete index[url];
+        index[url] = { at: new Date().toISOString(), as };
+        const kept = Object.entries(index).slice(-PER_DOCUMENT);
+        await fs.promises.mkdir(path.dirname(file), { recursive: true });
+        await writeAtomic(file, `${JSON.stringify(Object.fromEntries(kept))}\n`);
+      });
+    },
+    settled: () => writes,
+  };
+}
+
+/**
+ * What an export of document `slug` of workspace `root` embeds of the net (the spec §9 `net`): { <url>:
+ * { data, at } } of the answers its instances asked for last, the most recent first, at most
+ * SNAPSHOT.count of them and SNAPSHOT.bytes of their text, `data` as each was asked for; only those on a
+ * host `allowed(url)` says (an address of a block the document holds, on a host of its needs); null
+ * where it has none.
+ */
+export function netSnapshot(root, slug, allowed = () => true) {
+  const index = readJson(indexOf(root, slug));
+  if (!index || typeof index !== "object") return null;
+  const snapshot = {};
+  let bytes = 0;
+  let count = 0;
+  for (const [url, use] of Object.entries(index).reverse()) {
+    if (count >= SNAPSHOT.count) break;
+    const entry = readJson(fileOf(root, url));
+    if (!isEntry(entry, url) || !allowed(url)) continue;
+    const data = dataOf(entry, use?.as === "text" ? "text" : "json");
+    if (data === undefined) continue;
+    bytes += Buffer.byteLength(entry.text);
+    if (bytes > SNAPSHOT.bytes) break;
+    snapshot[url] = { data, at: entry.at };
+    count += 1;
+  }
+  return count > 0 ? snapshot : null;
+}

package/browser/shared/net-keys.mjs

@@ -0,0 +1,32 @@
+import fs from "node:fs";
+import { writeAtomic } from "./files.mjs";
+import { HOST } from "./net-policy.mjs";
+import { layoutOf } from "./workspace.mjs";
+
+// The workspace's keys for the sites its blocks reach (docs/render.md, "A block online"): .gallery/keys.json,
+// { "<host>": "<key>" }, written by gallery block key, read by the server's net route as a block's
+// address names one ({key}: ./net-policy.mjs), which it writes in there itself. A file of Gallery's own,
+// apart from gallery.json: that one's settings are told to every page and read by Agents, and a
+// workspace is handed on with it; a key is neither's. No route serves this file, no page holds a key,
+// and the cache, a snapshot and an export know an address by what the block wrote ({key}), never by
+// the key.
+
+/** The keys of workspace `root`, by host ({} where there are none, or the file does not read). */
+export function readKeys(root) {
+  try {
+    const keys = JSON.parse(fs.readFileSync(layoutOf(root).keys, "utf8"));
+    if (!keys || typeof keys !== "object" || Array.isArray(keys)) return {};
+    return Object.fromEntries(Object.entries(keys).filter(([host, key]) => HOST.test(host) && typeof key === "string" && key !== ""));
+  } catch {
+    return {};
+  }
+}
+
+/** Workspace `root` with `host`'s key `key` (null takes it away); the other keys as they were. */
+export async function writeKey(root, host, key) {
+  const keys = readKeys(root);
+  if (key === null) delete keys[host];
+  else keys[host] = key;
+  await fs.promises.mkdir(layoutOf(root).gallery, { recursive: true });
+  await writeAtomic(layoutOf(root).keys, `${JSON.stringify(keys, null, 2)}\n`);
+}

package/browser/shared/net-policy.mjs

@@ -0,0 +1,177 @@
+// What a custom block may reach of the web, and how its address is read (notes/plans/custom-blocks-spec-2026-11-07.md
+// §3; docs/render.md, "A block online"): pure, no Node, read by the catalog (a manifest's needs), the
+// server's net route (src/server/net-route.mjs: which address a block asks for is its to ask, which
+// machine a name stands for may be reached) and the export's snapshot (shared/net-cache.mjs).
+//
+// A block names each host it reaches in its needs, "net:<host>": a lowercase host name, no port and no
+// path, "*." before it for any name under it (never the name itself: write both where both are meant).
+// What it asks for is an absolute http or https address on that host, at the scheme's own port, with no
+// user or password in it; `{key}` in it (its path or its query) is where the server writes the
+// workspace's key for that host, which no page ever holds (keyIn, withKey).
+//
+// A machine is reached only at an address of the public internet: none of this computer (127/8, ::1),
+// of a private network (10/8, 172.16/12, 192.168/16, fc00::/7, 100.64/10 a carrier's), of a link
+// (169.254/16, fe80::/10), of what is no host (0/8, multicast, the reserved 240/4, the broadcast) or of
+// the ranges kept for documents and tests (192.0.2/24, 198.51.100/24, 203.0.113/24, 2001:db8::/32); an
+// IPv6 address that holds an IPv4 one (::ffff:a.b.c.d, ::a.b.c.d, 64:ff9b::a.b.c.d, 2002:…) is held to
+// that one. 198.18.0.0/15 (benchmarking) is what a proxy's fake-ip DNS answers with (Clash and its
+// kind): it is one only where the address is handed to that proxy (FAKE_IP, proxyHere). A name this
+// computer's resolver answers with addresses of this computer or unique-local ones alone (a proxy that
+// maps names to 127.x or fd00::/8 addresses of its own: mapsHere) is reached by its name through such a
+// proxy, for https alone, its TLS the guard (src/server/net-route.mjs); never a name kept for this
+// computer (keptHere), nor one answered with a private IPv4 network's address.
+
+/** The word a manifest's needs say a host after. */
+export const NET = "net:";
+/** A host a manifest's needs may name: a lowercase name, "*." before it for any name under it. */
+export const HOST = /^(?:\*\.)?[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/;
+
+/** The hosts a block's needs name ("net:<host>" each), in its order. */
+export const netHostsOf = (needs) => (Array.isArray(needs) ? needs.filter((need) => typeof need === "string" && need.startsWith(NET)).map((need) => need.slice(NET.length)) : []);
+
+/** Whether `host` (an address's, lowercase) is one a needs' host names: itself, or, for "*.<name>", a name under it. */
+export function hostMatches(host, pattern) {
+  if (pattern.startsWith("*.")) return host.endsWith(pattern.slice(1)) && host.length > pattern.length - 1;
+  return host === pattern;
+}
+
+/** The first of `hosts` (a block's needs' hosts) that `host` is, or null. */
+export const hostIn = (host, hosts) => hosts.find((pattern) => hostMatches(host, pattern)) ?? null;
+
+// `{key}` as written, and as an address's path writes it (%7B key %7D).
+const KEY = /\{key\}|%7Bkey%7D/gi;
+
+/** Whether an address names the workspace's key for its host. */
+export const keyIn = (address) => new RegExp(KEY.source, "i").test(address);
+
+/** The address with the key written where it names it (`{key}`), encoded as a part of an address. */
+export const withKey = (address, key) => address.replace(KEY, () => encodeURIComponent(key));
+
+/**
+ * What a block's `raw` address is: { url } (a URL, its href what the cache and a snapshot name it by), or
+ * { code: "url", why } when it is no address a block may ask for.
+ */
+export function addressOf(raw) {
+  if (typeof raw !== "string" || raw.length > 4096) return { code: "url", why: "an address is a string of at most 4096 characters" };
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return { code: "url", why: "not an absolute address" };
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return { code: "url", why: "only http and https addresses" };
+  if (url.username || url.password) return { code: "url", why: "an address with a user or a password in it" };
+  if (url.port !== "") return { code: "url", why: "an address at another port than its scheme's: a needs' host names none" };
+  url.hash = "";
+  return { url };
+}
+
+// ---------- addresses ----------
+
+// An IPv4 address as its four numbers, or null.
+function ipv4(text) {
+  const parts = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(text);
+  if (!parts) return null;
+  const numbers = parts.slice(1).map(Number);
+  return numbers.every((number) => number <= 255) ? numbers : null;
+}
+
+// An IPv6 address as its eight groups (numbers), a zone (%…) left out, or null.
+function ipv6(text) {
+  let rest = text.replace(/^\[|\]$/g, "").replace(/%.*$/, "").toLowerCase();
+  let tail = [];
+  const dotted = /^(.*:)(\d+\.\d+\.\d+\.\d+)$/.exec(rest);
+  if (dotted) {
+    const four = ipv4(dotted[2]);
+    if (!four) return null;
+    tail = [(four[0] << 8) | four[1], (four[2] << 8) | four[3]];
+    rest = dotted[1].endsWith("::") ? dotted[1] : dotted[1].slice(0, -1);
+  }
+  const halves = rest.split("::");
+  if (halves.length > 2) return null;
+  const groups = (half) => (half === "" ? [] : half.split(":"));
+  const [head, after = null] = [groups(halves[0]), halves.length === 2 ? groups(halves[1]) : null];
+  if (![...head, ...(after ?? [])].every((group) => /^[0-9a-f]{1,4}$/.test(group))) return null;
+  const known = head.length + (after?.length ?? 0) + tail.length;
+  if (after === null ? known !== 8 : known > 7) return null;
+  const numbers = (list) => list.map((group) => Number.parseInt(group, 16));
+  return [...numbers(head), ...Array(8 - known).fill(0), ...numbers(after ?? []), ...tail];
+}
+
+const inRange = (numbers, [first, ...rest], bits) => {
+  // `numbers` (an IPv4's four) within first.rest…/bits
+  const value = (list) => list.reduce((sum, number) => sum * 256 + number, 0);
+  const shift = 2 ** (32 - bits);
+  return Math.floor(value(numbers) / shift) === Math.floor(value([first, ...rest]) / shift);
+};
+
+// The IPv4 ranges no block reaches: this network, the private ones, a carrier's, loopback, link-local,
+// the protocols', the documents' and tests', the old 6to4 relay, multicast, the reserved and the broadcast.
+const V4_REFUSED = [
+  [[0, 0, 0, 0], 8], [[10, 0, 0, 0], 8], [[100, 64, 0, 0], 10], [[127, 0, 0, 0], 8], [[169, 254, 0, 0], 16],
+  [[172, 16, 0, 0], 12], [[192, 0, 0, 0], 24], [[192, 0, 2, 0], 24], [[192, 88, 99, 0], 24], [[192, 168, 0, 0], 16],
+  [[198, 51, 100, 0], 24], [[203, 0, 113, 0], 24], [[224, 0, 0, 0], 4], [[240, 0, 0, 0], 4],
+];
+/** The fake-ip range a proxy's DNS answers with (198.18.0.0/15, benchmarking's). */
+export const FAKE_IP = [[198, 18, 0, 0], 15];
+
+const v4Kind = (four) => (inRange(four, ...FAKE_IP) ? "fake-ip" : V4_REFUSED.some(([start, bits]) => inRange(four, start, bits)) ? "private" : "public");
+const embedded = (groups, at) => [groups[at] >> 8, groups[at] & 255, groups[at + 1] >> 8, groups[at + 1] & 255];
+
+// What an IPv6 address is: of the public internet (2000::/3 but the documents', benchmarking's and
+// ORCHID's), what the IPv4 address it holds is, or none to reach.
+function v6Kind(groups) {
+  const zeros = (count) => groups.slice(0, count).every((group) => group === 0);
+  if (zeros(5) && groups[5] === 0xffff) return v4Kind(embedded(groups, 6)); // ::ffff:a.b.c.d
+  if (zeros(6)) return groups[6] === 0 && groups[7] <= 1 ? "private" : v4Kind(embedded(groups, 6)); // ::, ::1, ::a.b.c.d
+  if (groups[0] === 0x64 && groups[1] === 0xff9b && groups.slice(2, 6).every((group) => group === 0)) return v4Kind(embedded(groups, 6)); // NAT64
+  if (groups[0] === 0x2002) return v4Kind(embedded(groups, 1)); // 6to4
+  if ((groups[0] & 0xe000) !== 0x2000) return "private"; // not global unicast: fc00::/7, fe80::/10, ff00::/8, 100::/64…
+  if (groups[0] === 0x2001 && (groups[1] === 0x0db8 || groups[1] === 0x0002 || (groups[1] & 0xfff0) === 0x0010)) return "private";
+  return "public";
+}
+
+/**
+ * What `address` (an IP address, as a resolver gives it) is to a block: "public" (it may be reached),
+ * "fake-ip" (198.18.0.0/15, a proxy's DNS: FAKE_IP), "private" (this computer, a private network, or no
+ * host to reach), or "none" (no IP address).
+ */
+export function addressKind(address) {
+  const four = ipv4(String(address));
+  if (four) return v4Kind(four);
+  const groups = ipv6(String(address));
+  return groups ? v6Kind(groups) : "none";
+}
+
+/**
+ * Whether `address` (one addressKind calls private) is what a proxy of this computer that maps names
+ * answers with: this computer's (127/8, ::1, ::ffff:127.x) or an IPv6 unique-local one (fc00::/7).
+ * Never a private IPv4 network's (10/8, 172.16/12, 192.168/16), a carrier's or a link's: a network's own
+ * machines are there (a company's names that its DNS answers inside), which no name may reach.
+ */
+export function mapsHere(address) {
+  const four = ipv4(String(address));
+  if (four) return four[0] === 127;
+  const groups = ipv6(String(address));
+  if (!groups) return false;
+  if (groups.slice(0, 5).every((group) => group === 0) && groups[5] === 0xffff) return groups[6] >> 8 === 127;
+  return groups.every((group, index) => group === (index === 7 ? 1 : 0)) || (groups[0] & 0xfe00) === 0xfc00;
+}
+
+/** Whether `host` (an address's) is a name a resolver keeps for this computer: localhost and the names under it (RFC 6761). */
+export const keptHere = (host) => /(?:^|\.)localhost\.?$/i.test(String(host));
+
+/**
+ * Whether a proxy's address (`proxy`, a URL or null) is a program on this computer: what a fake-ip
+ * answer is handed to, and the name of an https address whose answer here is none of the public internet.
+ */
+export function proxyHere(proxy) {
+  if (!proxy) return false;
+  try {
+    const host = new URL(proxy).hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    const loopback6 = ipv6(host)?.every((group, index) => group === (index === 7 ? 1 : 0)) ?? false;
+    return host === "localhost" || ipv4(host)?.[0] === 127 || loopback6;
+  } catch {
+    return false;
+  }
+}

package/browser/shared/new-names.mjs

@@ -1,5 +1,5 @@
 import { parse } from "parse5";
-import { isInstance } from "./components/index.mjs";
+import { instanceSlots, isInstance } from "./components/index.mjs";
 import { mayHoldOldNames, newAttributeName, newAttributeValue, newScriptNames, newStyleNames } from "./old-names.mjs";
 
 // A file's text with the format's old names new (old-names.mjs says which, and where the tools read
@@ -50,7 +50,10 @@ export function newNames(html) {
   }
   const visit = (node) => {
     for (const child of node.childNodes ?? []) {
-      if (isInstance(child)) continue;
+      if (isInstance(child)) {
+        instanceSlots(child).forEach(visit); // what its slots hold is the document's, its own region the component's
+        continue;
+      }
       if (child.tagName) element(child);
       visit(child.tagName === "template" && child.content ? child.content : child);
     }

package/browser/shared/outline-shape.mjs

@@ -0,0 +1,128 @@
+// The shape of the sidebar's tree (the workspace's outline, ./outline.mjs reads and writes its file),
+// pure, the same on the server and in the workbench (workspace/meta.ts): the columns of the sidebar,
+// each a list of entries under one another, and what names them.
+//
+// A column (栏) is { id, title?, role?, workspace?, picked?, hidden?, left? }: "docs" is the workspace's own
+// column (its own documents; 默认文档 when it is the default workspace, else called by the workspace's
+// name), always there and never removed; workspace "<ws-id>" is another registered workspace's column
+// (./workspace-columns.mjs: one for each registered workspace, made as the outline is read; "whole",
+// holding all its documents, those no column holds coming last in it but the ones in its `left` (the slugs
+// there of the documents the user took out: 从文档树移除), or `picked`, holding only the documents put in
+// it: 添加其他 Gallery 项目… with a document; `hidden` once the user removed it from the sidebar, kept so
+// that it comes back as it was); another is one the user made (a column's ⋯ › 新建栏),
+// or of an older kind still read: role "links" (链接, where the web links went before 2026-11-09);
+// extension "<id>" for the column an extension provides
+// (extensions/<id>/sidebar.json: ./extension-sidebar.mjs): its place is kept here, so that it can be
+// dragged, but its title and its entries are the extension's, never the outline's. `title` is the
+// user's name for it; none, the name it goes by in the UI's language (文档, 链接, …). Its order is the sidebar's.
+// An entry is a document's or a web link's slug of this workspace; "~<ws-id>/<slug>" names a draft of
+// another workspace (./drafts.mjs: kept in the outline whether it is there or not).
+// In the outline as read, every list is one of `children`: under a top key, a column's top level (""
+// the 文档 column's, as before columns came, ":<id>" another's), under a slug, the entries under that
+// entry. So an entry moved to another column is an entry moved under another parent, and the 文档
+// column's tree is what an outline of version 1 was.
+
+/** The 文档 column's id: the workspace's own documents, never removed. */
+export const DOCS = "docs";
+/** A column's id: a slug's letters ("docs", "g-7k2m", "ws-3f2a9c"), 64 at most. */
+export const groupIdPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** An entry: a slug of this workspace, or a draft of another, "~ws-<6 hex>/<slug>". */
+export const entryPattern = /^(?:~ws-[0-9a-f]{6}\/)?[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** The roles a column can have: the one web links went to before 2026-11-09 (none is made any more; one there stays). */
+export const GROUP_ROLES = ["links"];
+export const GROUP_LIMITS = { groups: 50, title: 100, left: 1000 };
+/** A slug of a workspace (a document's, a web link's folder name). */
+const slugPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/**
+ * An extension's id, the name of its folder under extensions/: a slug of 48 letters, digits and dashes
+ * at most (its column's id is ext-<id>, 64 at most), and never the notation of a workspace's id
+ * (ws-<6 hex>: the address `#~ws-…/<slug>` names a draft of another workspace, `#~<id>/<entry>` an
+ * entry of an extension).
+ */
+export const EXTENSION_ID_MAX = 48;
+export const extensionIdPattern = /^(?!ws-[0-9a-f]{6}$)[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const isExtensionId = (id) => typeof id === "string" && id.length <= EXTENSION_ID_MAX && extensionIdPattern.test(id);
+/** The id of the column extension `id` makes. */
+export const extensionGroupId = (id) => `ext-${id}`;
+
+/** A column's top key in the outline's children: "" for 文档 (as before columns came), ":<id>" for another. */
+export const topOf = (id) => (id === DOCS ? "" : `:${id}`);
+/** Whether a key of the children is a column's top level (else it is an entry's). */
+export const isTop = (key) => key === "" || key.startsWith(":");
+/** The column whose top key `key` is. */
+export const groupOfTop = (key) => (key === "" ? DOCS : key.slice(1));
+/** Whether `entry` names a draft of another workspace. */
+export const isForeign = (entry) => entry.startsWith("~");
+
+const tidy = (value) => (typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "");
+
+/** A whole column's `left` as it is kept: the slugs once each, 1000 at most; none when there are none. */
+const leftOf = (value) => {
+  const left = [...new Set(value.filter((slug) => typeof slug === "string" && slugPattern.test(slug)))].slice(0, GROUP_LIMITS.left);
+  return left.length ? { left } : {};
+};
+
+/**
+ * Column `value` as it is kept ({ id, title?, role?, workspace?, picked?, hidden?, left? } or an extension's { id, extension }),
+ * or null for one that is none. An extension's column is its id's, whatever else a file says of it: no
+ * title (the extension's own), role or workspace.
+ */
+export function groupOf(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const { id, role, workspace, extension } = value;
+  if (typeof id !== "string" || id.length > 64 || !groupIdPattern.test(id)) return null;
+  if (isExtensionId(extension) && id === extensionGroupId(extension)) return { id, extension };
+  const title = tidy(value.title).slice(0, GROUP_LIMITS.title);
+  const isWorkspaceColumn = typeof workspace === "string" && /^ws-[0-9a-f]{6}$/.test(workspace) && id !== DOCS;
+  return {
+    id,
+    ...(title ? { title } : {}),
+    ...(GROUP_ROLES.includes(role) && id !== DOCS ? { role } : {}),
+    ...(isWorkspaceColumn ? { workspace } : {}),
+    // A workspace's column alone is picked or hidden (the user's columns and 链接 are removed, never hidden).
+    ...(isWorkspaceColumn && value.picked === true ? { picked: true } : {}),
+    ...(isWorkspaceColumn && value.hidden === true ? { hidden: true } : {}),
+    // What the user took out of a whole one (a picked one holds what was put in it: nothing to leave out).
+    ...(isWorkspaceColumn && value.picked !== true && Array.isArray(value.left) ? leftOf(value.left) : {}),
+  };
+}
+
+/** Whether `groups` is a list of columns to keep: each a column, ids once each, 文档 among them, 50 at most. */
+export function validGroups(groups) {
+  if (!Array.isArray(groups) || groups.length === 0 || groups.length > GROUP_LIMITS.groups) return false;
+  const ids = new Set();
+  for (const value of groups) {
+    const group = groupOf(value);
+    if (!group || ids.has(group.id)) return false;
+    if (value.title !== undefined && (typeof value.title !== "string" || tidy(value.title).length > GROUP_LIMITS.title)) return false;
+    if (value.role !== undefined && !GROUP_ROLES.includes(value.role)) return false;
+    if (value.extension !== undefined && group.extension !== value.extension) return false;
+    if (value.left !== undefined && (!Array.isArray(value.left) || value.left.length > GROUP_LIMITS.left || !value.left.every((slug) => typeof slug === "string" && slugPattern.test(slug)))) return false;
+    ids.add(group.id);
+  }
+  return ids.has(DOCS);
+}
+
+/** A new column's id, none of `groups`' (g- and four letters or digits). */
+export function newGroupId(groups, random = Math.random) {
+  for (;;) {
+    const id = `g-${Math.floor(random() * 36 ** 4).toString(36).padStart(4, "0")}`;
+    if (!groups.some((group) => group.id === id)) return id;
+  }
+}
+
+/** The top key of the column `slug` is in (walking up `children`), or null when the outline holds it not. */
+export function topIn(children, slug) {
+  const parentOf = (entry) => {
+    for (const [key, list] of Object.entries(children)) if (list.includes(entry)) return key;
+    return null;
+  };
+  const seen = new Set();
+  for (let key = parentOf(slug); key !== null; key = parentOf(key)) {
+    if (isTop(key)) return key;
+    if (seen.has(key)) return null;
+    seen.add(key);
+  }
+  return null;
+}