@heycys/gallery 0.0.0-stage → 0.1.0

package/browser/shared/reports.mjs

@@ -0,0 +1,46 @@
+import fs from "node:fs/promises";
+import { namedLinks, pageLinks } from "./page-links.mjs";
+import { reportsDirectory } from "./paths.mjs";
+import { documentDirectory, documentFiles, listDocumentSlugs, listTrash, slugPattern } from "./workspace.mjs";
+
+// The documents' layout, as every system reads it (./workspace.mjs): one folder a document,
+// <workspace>/<slug>/ with doc.html and doc.json (report.html and report.json in one made before
+// Gallery 0.1), its slug lowercase kebab-case. Dot names (.gallery/) and exports/ are never documents.
+
+export { slugPattern };
+
+// A workspace with no documents yet has none: gallery new makes the folder with its first one.
+export async function listReportSlugs(directory = reportsDirectory) {
+  return listDocumentSlugs(directory);
+}
+
+/**
+ * The links of the documents of the workspace at `directory`, by their titles as they are now
+ * (./page-links.mjs): { links: a Map of slug to link of those of the sidebar, named: those and the
+ * trash's, what an address written for anyone goes by }. A doc.json that cannot be read now (an Agent
+ * writing it) names no title, and its document goes by its page id alone.
+ */
+export async function documentLinks(directory = reportsDirectory) {
+  const page = async (slug) => ({ slug, title: await fs.readFile(documentFiles(documentDirectory(slug, directory)).json, "utf8").then((text) => JSON.parse(text).title).catch(() => null) });
+  const links = pageLinks(await Promise.all((await listDocumentSlugs(directory)).map(page)));
+  return { links, named: namedLinks(links, await listTrash(directory)) };
+}
+
+// The page of the user's writing preferences (写作偏好: `"instructions": true` in its doc.json, one at
+// most, in <workspace>/.gallery/pages/<slug>/): a page like any other to edit, which the workbench
+// opens from 设置 and lists apart from the documents, and writes as <workspace>/preferences.md for
+// Agents to read before they write (src/shared/writing-preferences.mjs). Any other doc.json field names
+// no role: an old one's "template" is read as nothing, the document an ordinary one.
+export async function isInstructions(directory) {
+  return (await roleOf(directory)) === "instructions";
+}
+
+/** What a document is besides a document: "instructions", or null (an ordinary one). */
+export async function roleOf(directory) {
+  try {
+    const metadata = JSON.parse(await fs.readFile(documentFiles(directory).json, "utf8"));
+    return metadata?.instructions === true ? "instructions" : null;
+  } catch {
+    return null;
+  }
+}

package/browser/shared/search.mjs

@@ -0,0 +1,85 @@
+import { unescapeText } from "./escape.mjs";
+
+// 搜索文档 in a report's text (the workbench's search: GET /__gallery/workspace/search). A report's text is
+// read as its blocks' lines: the text of its main below the header (the title is matched apart), a
+// line a block, no script, style or drawing, a formula its TeX. The words are found in a line as they
+// are typed (one phrase, upper and lower case alike, runs of spaces as one), each hit shown as a
+// snippet of its line around it; `before` (the text just before it in its line) and `index` (which
+// time the words occur in the report) let the page find it again (editor/page/find/).
+
+const SKIPPED = /<(script|style|template|noscript|svg)\b[\s\S]*?<\/\1>/gi;
+const FORMULA = /\\\(([\s\S]*?)\\\)|\\\[([\s\S]*?)\\\]/g;
+const BLOCK = /<\/?(p|li|ul|ol|h[1-6]|table|tr|td|th|caption|summary|details|figure|figcaption|pre|blockquote|div|section|article|aside|dl|dt|dd|hr|br)\b[^>]*>/gi;
+
+/** Runs of spaces as one, the ends trimmed: a query as it is matched. */
+export const tidyQuery = (text) => String(text).replace(/\s+/g, " ").trim().slice(0, 100);
+
+/** The lines of report `html` (a whole report.html, or the inside of its main): its blocks' text. */
+export function reportLines(html) {
+  let body = String(html);
+  const main = /<main\b[^>]*>([\s\S]*)<\/main>/i.exec(body);
+  if (main) body = main[1];
+  body = body.replace(/^\s*<header\b[^>]*>[\s\S]*?<\/header>/i, " "); // the page's header: its title and icon
+  const text = body
+    .replace(SKIPPED, " ")
+    .replace(FORMULA, (_, inline, display) => ` ${inline ?? display} `)
+    .replace(BLOCK, "\n")
+    .replace(/<[^>]*>/g, "")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)))
+    .replace(/&#x([0-9a-f]+);/gi, (_, code) => String.fromCodePoint(parseInt(code, 16)));
+  return unescapeText(text).replace(/\u200b/g, "").split("\n").map(tidyQuery).filter(Boolean);
+}
+
+/**
+ * Where `query` occurs in `lines`: { count, hits }, hits the first `most` lines it is in (once a
+ * line), each { text (the snippet), start, end (the words in it), before, index }.
+ */
+export function findIn(lines, query, { most = 3, ahead = 16, length = 90 } = {}) {
+  const words = tidyQuery(query).toLowerCase();
+  const hits = [];
+  let count = 0;
+  if (!words) return { count, hits };
+  for (const line of lines) {
+    const lower = line.toLowerCase();
+    let shown = false;
+    for (let at = lower.indexOf(words); at >= 0; at = lower.indexOf(words, at + words.length)) {
+      if (!shown && hits.length < most) {
+        shown = true;
+        const from = at <= ahead ? 0 : at - ahead;
+        const to = Math.min(line.length, Math.max(from + length, at + words.length));
+        const head = from > 0 ? "…" : "";
+        hits.push({
+          text: `${head}${line.slice(from, to)}${to < line.length ? "…" : ""}`,
+          start: head.length + at - from,
+          end: head.length + at - from + words.length,
+          before: line.slice(Math.max(0, at - 16), at),
+          index: count,
+        });
+      }
+      count += 1;
+    }
+  }
+  return { count, hits };
+}
+
+/**
+ * gallery list's choice of the reports `words` name (src/cli/list.mjs): of `reports`
+ * ([{ slug, title, description, edited }]), those whose title, description or slug holds at least
+ * one of the words (upper and lower case alike; a word anywhere in them, as Chinese is written
+ * without spaces between words), the best first: those holding more of the words, then more of them
+ * in the title, then in the slug, then the one edited last. `words`: what was typed, split at spaces.
+ */
+export function rankReports(reports, words) {
+  const wanted = [...new Set(tidyQuery(words).toLowerCase().split(" ").filter(Boolean))];
+  if (!wanted.length) return [...reports].sort((a, b) => b.edited - a.edited);
+  const scored = reports.map((report) => {
+    const [title, slug, description] = [report.title, report.slug, report.description].map((value) => String(value ?? "").toLowerCase());
+    const found = wanted.filter((word) => title.includes(word) || slug.includes(word) || description.includes(word));
+    return { report, found: found.length, title: wanted.filter((word) => title.includes(word)).length, slug: wanted.filter((word) => slug.includes(word)).length };
+  });
+  return scored
+    .filter(({ found }) => found > 0)
+    .sort((a, b) => b.found - a.found || b.title - a.title || b.slug - a.slug || b.report.edited - a.report.edited)
+    .map(({ report }) => report);
+}

package/browser/shared/session.mjs

@@ -0,0 +1,76 @@
+// The session between a report page and a workbench that shows it in an iframe of the same origin
+// (docs/workbench.md): the page's side is src/editor/page/session.mjs, the workbench's
+// src/workbench/app/session/. Every message is { protocol: PROTOCOL, v: VERSION, type, slug, ... },
+// posted to the other window for this origin only.
+//
+//   report -> workbench   ready    once the editor started: { commands, title, icon, state, annotations, card }
+//                         state    when the state, the title, the page's icon, how many 批注 it has or whether a
+//                                  detail card is open changed: { title, icon, state, annotations, card }
+//                                  (icon: the page's icon, an emoji, or null; card: a detail card is open)
+//                         reply    to a command, once it is done: { id, ok, ... }
+//                         key      a key combination the workbench registered, pressed in the page: { key }
+//                         notice   something to tell the reader, as the workbench's toast: { text, tone, hold,
+//                                  room }
+//                         noticeRoom
+//                                  the room the page's bottom panels take changed: { room }, px above the
+//                                  frame's bottom (0: none), which the workbench's toasts stand above
+//                         reload   show the report again (the file changed): the workbench loads it in a
+//                                  hidden frame (data-pending) and swaps it in once that page is ready,
+//                                  so the reader never sees a page being reloaded; this page has
+//                                  stopped (it commits and stores nothing more)
+//                         open     go to another document (a link in the page): { target, block }
+//                                  (`target` its slug, as `slug` stays the sender's; `block` a block's id
+//                                  or null), or { hash } (a workbench's address, which the page cannot
+//                                  read without the titles); unsaved text is as for a click in the sidebar
+//                         jump     a link goes to a block of this page, sent before the page goes there:
+//                                  { block, place } (`place` where the reader is: x, y, top and tabs as
+//                                  reading-place.mjs's placeIn gives them, the caret's unit, self and
+//                                  offset, the detail cards open as modals): the workbench adds a history
+//                                  entry, the way back to it being the command show-place
+//                         workspace a page was made under this one (a page block's box, the page itself
+//                                  staying as it is): the workbench reads the list of pages again and
+//                                  shows this page's row open
+//                         annotations-removed
+//                                  a 批注 deleted from its card: { items }: the workbench says so, as
+//                                  it does for 全部删除, and its 撤销 puts them back
+//   workbench -> report   command  { id, name, ... }
+
+export const PROTOCOL = "gallery/session";
+// The protocol's id before the product's rename (2026-10-26). A workbench and a page of different
+// versions meet when one was open before the server was updated and the other loaded after: each
+// side takes either id. The page, until the workbench has spoken to it (its first command), sends
+// every message under both ids, PROTOCOL first; once it has, only under the id the workbench used,
+// and it answers a command under the id the command came in. The workbench sends a frame its
+// commands under the id the frame last spoke, and takes an OLD_PROTOCOL message from a page that has
+// spoken PROTOCOL as the copy it is (ignored). So an old workbench still hears a new page's reload
+// and notices, and a new workbench drives an old page; nothing the page says is lost on either.
+export const OLD_PROTOCOL = "html-report-studio/session";
+/** The ids a message may carry: the new one first. */
+export const PROTOCOLS = [PROTOCOL, OLD_PROTOCOL];
+export const VERSION = 2;
+
+/**
+ * Where a page finds, as it starts, where its reader was ({ x, y, top, unit, self, offset, modals,
+ * notice }, once: autosave.mjs takeView; `top` as reading-place.mjs's placeIn gives it, which the way
+ * back from another document keeps): sessionStorage, which a workbench and its frames share. A page
+ * puts it there before it is shown again; the workbench before the way back comes to it.
+ */
+export const viewKey = (slug) => `gallery-edit:${slug}:view`;
+
+/**
+ * What `state` reports, in this order: editing (the editor runs: the page edits from the start),
+ * pending (changes wait to be saved, or are on their way), saving (a commit is on its way), offline
+ * (commits do not get through; the changes wait in the browser), conflicts (how many the reader has
+ * to decide, a number), changed (someone else wrote the file; the page shows it once nothing waits).
+ */
+export const STATE_FLAGS = ["editing", "pending", "saving", "offline", "conflicts", "changed"];
+
+/**
+ * A key combination as the protocol names it: "Mod" (Ctrl, or ⌘ on a Mac), "Alt", "Shift", then
+ * the key (a letter upper-cased), joined by "+": "Mod+K", "Mod+\\", "Mod+Shift+P".
+ */
+export function keyCombo(event, mac = /Mac|iPhone|iPad/.test(globalThis.navigator?.platform ?? "")) {
+  const mod = mac ? event.metaKey : event.ctrlKey;
+  const key = event.key.length === 1 ? event.key.toUpperCase() : event.key;
+  return [mod && "Mod", event.altKey && "Alt", event.shiftKey && "Shift", key].filter(Boolean).join("+");
+}

package/browser/shared/table-chart.mjs

@@ -0,0 +1,113 @@
+import { ZWSP } from "./inline-spacing.mjs";
+import { isMissingValue, numberReading } from "./number-reading.mjs";
+
+// A chart drawn from a table (docs/render.md, "Charts from a table"). An Agent writes an ordinary
+// table with data-doc-chart="<type>", a type its report's script defines (DocCharts.define); the
+// intake (src/editor/source/natural.mjs) makes it two blocks, the table's frame, which carries a key
+// (CHART_SOURCE), and right after it a chart card whose host names the table by that key
+// (CHART_DATA). The kit (src/render/kit/charts/from-table.js) reads the table as the page shows it and
+// draws the chart again when the table changes; the checks (src/render/chart-declarations.mjs) read it
+// from the file. Both take the rows a table gives a chart from here (tableRows): plain, predictable,
+// d3.csvParse's shape, each value read as the table's own sort reads it (number-reading.mjs). The
+// link is that pair of attributes alone, never an id or the blocks' order, so the reader may move,
+// 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).
+
+/** 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";
+/** A key: a letter, then letters, digits, "_" or "-", 32 at most. */
+export const CHART_KEY = /^[A-Za-z][\w-]{0,31}$/;
+
+/** The first key of t1, t2 … that `taken` (a Set) does not hold. */
+export function nextChartKey(taken) {
+  for (let index = 1; ; index++) if (!taken.has(`t${index}`)) return `t${index}`;
+}
+
+// A formula in a cell's text as the file writes it (and the page, before KaTeX draws it): its TeX
+// between \( \), \[ \] or $$ $$.
+const FORMULA = /\\\(([\s\S]*?)\\\)|\\\[([\s\S]*?)\\\]|\$\$([\s\S]*?)\$\$/g;
+
+/**
+ * A cell's words as a chart reads them, from the file (the checks) and from the page (the kit) alike:
+ * `text` its text, where a formula is its TeX (written between its delimiters in the file; the kit
+ * reads one KaTeX drew by its TeX: charts/from-table.js), the editor's zero-width pads none, blanks
+ * one space, none at either end.
+ */
+export const cellWords = (text) => text.replace(FORMULA, (_, inline, display, dollars) => inline ?? display ?? dollars).replaceAll(ZWSP, "").replace(/\s+/g, " ").trim();
+
+// 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"]);
+
+/**
+ * A cell's value for a chart (`cell`: { words, sort }, undefined where its row has none; `type`: its
+ * header's data-sort-type), as the table's sort reads it (number-reading.mjs, rawCellValue): its sort
+ * value when it has one, else its words; null for none (no cell, an empty one, a dash, n/a); its words
+ * in a column its header says holds words or dates; the number they write when they write one (12.5%
+ * 12.5, 3.6亿 360000000, 1,234 1234, (12) -12, 约 20 20, 120 ms 120); else its words (a range, 3–5 天,
+ * which a sort reads by its first number, is no one number: its words; so is 3 / 4).
+ */
+export function cellValue(cell, type = null) {
+  if (!cell) return null;
+  const raw = cell.sort ?? cell.words;
+  if (isMissingValue(raw)) return null;
+  if (WORD_TYPES.has(type)) return cell.words;
+  const reading = numberReading(raw);
+  return reading && !reading.range ? reading.value : cell.words;
+}
+
+/**
+ * The rows a table gives a chart drawn from it: { data } or, when it gives none, { error, message }
+ * (`error` for a check and the host's layout note, `message` the card's line for its reader, as the
+ * kit's words name it: [key, ...values], said in the page's language by src/render/kit/words.js).
+ * `table`: { names, types, rows, merged }: its header row's words (its head's first row, else a first
+ * 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,
+ * 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
+ * the header's words (cellValue: a number, its words, or null; a row shorter than the header null
+ * where it has no cell, the cells past the header not read), and `data.columns` the header's words in
+ * order. With no header row the first row is the header, as csvParse takes it; a header cell with no
+ * words is the key "", and of two alike the later column's value is the one kept (the checks note
+ * both: rowsReading). Merged cells give nothing: a value has one cell.
+ */
+export function tableRows(table) {
+  const fail = (error, ...message) => ({ error, message });
+  if (table.merged) return fail("has merged cells: write each value in its own cell, the category on every row", "merged-cells");
+  let { names, types, rows } = table;
+  if (!names) [names, types, rows] = rows.length > 0 ? [rows[0].map((cell) => cell?.words ?? ""), null, rows.slice(1)] : [[], null, []];
+  const data = rows.map((row) => {
+    const values = {};
+    names.forEach((name, column) => {
+      values[name] = cellValue(row[column], types?.[column] ?? null);
+    });
+    return values;
+  });
+  data.columns = [...names];
+  return { data };
+}
+
+/**
+ * What a table gave a chart (`table` as tableRows takes it, plus `foot`, its <tfoot>'s rows, which no
+ * chart reads; `data`: tableRows' rows), for the checks to say (chart-declarations.mjs
+ * tableChartReadings, chartDeclarationNotes): { rows: how many, columns: [{ name, numbers, words,
+ * empty }] how many of its values are numbers, words and null, column by column in the header's
+ * order (a name the header gives twice once: its later column's), blank: whether a header cell has no
+ * words, twice: the names the header gives twice, foot: how many <tfoot> rows were left out, extra:
+ * how many rows have cells past the header (not read) }.
+ */
+export function rowsReading(table, data) {
+  const names = data.columns;
+  const twice = [...new Set(names.filter((name, at) => names.indexOf(name) !== at))];
+  const columns = [...new Set(names)].map((name) => {
+    const values = data.map((row) => row[name]);
+    return { name, numbers: values.filter((value) => typeof value === "number").length, words: values.filter((value) => typeof value === "string").length, empty: values.filter((value) => value === null).length };
+  });
+  const rows = table.names ? table.rows : table.rows.slice(1);
+  return { rows: data.length, columns, blank: names.includes(""), twice, foot: table.foot?.length ?? 0, extra: rows.filter((row) => row.length > names.length).length };
+}

package/browser/shared/table-hides.mjs

@@ -0,0 +1,120 @@
+// What a table's frame hides at rest (scrolled to its start): the one measure of the kit's layout
+// notes of a frame and of its fading right edge (render/kit/tables/scrollbars.js: columns-hidden,
+// rows-hidden, data-more; docs/render.md, "Table layout internals") and of gallery qa's look at a
+// table (src/cli/qa.mjs), which puts these functions in the page it looks at as their text
+// (tableHidesScript): so they read nothing outside themselves but each other.
+//
+// A column hides what its words hide, never its cells' padding: the words of each of its cells (the
+// header's and the body's, a merged cell's in the last column it covers) as the page draws them, so a
+// table a few pixels wider than its frame hides nothing, and a long word deep in the body that
+// reaches past the edge is a column cut though its header fits. A column is out of sight when none of
+// its words starts before the frame's right edge, cut when some reach past it and some start before
+// it. The first column that stays as the frame scrolls (a sticky first column, a header column:
+// tables/sticky.js) never hides. A row (of the body's, those a filter hides aside) is shown when its
+// words end above the frame's bottom edge.
+
+/**
+ * The column each cell of `table` ends in, by the HTML table model's slots as src/shared/table-slots.mjs
+ * tiles them (tileSlots: a cell takes the first slot of its row no cell above covers, and covers its
+ * rowspan and colspan from there), read here on its own so that it can go into a page as its text,
+ * and so that a table that does not tile (a hole, a span past its section, a span of 0, read as 1)
+ * still gives each cell a column: { columnOf: Map(cell → its last column), columns: how many }.
+ * tests/unit/qa.mjs holds it to tileSlots on tables that tile.
+ */
+export function cellColumns(table) {
+  const taken = [];
+  const columnOf = new Map();
+  let columns = 0;
+  [...table.rows].forEach((row, r) => {
+    let c = 0;
+    for (const cell of row.cells) {
+      while (taken[r]?.[c]) c++;
+      const across = Math.max(1, cell.colSpan);
+      for (let i = 0; i < Math.max(1, cell.rowSpan); i++) for (let j = 0; j < across; j++) (taken[r + i] ??= [])[c + j] = true;
+      columnOf.set(cell, c + across - 1);
+      c += across;
+      columns = Math.max(columns, c);
+    }
+  });
+  return { columnOf, columns };
+}
+
+/**
+ * Where the words of `cell` are drawn, as one box ({ left, right, top, bottom }, the page's): the
+ * boxes of its text's lines and of what it shows that is no text (a picture, a drawing, a control),
+ * never an element's own box (a list or a paragraph in a cell is as wide as the cell, its words are
+ * not; a formula's MathML, laid out unseen, is no words of it); null when it shows none.
+ */
+export function wordsBox(cell) {
+  const boxes = [];
+  const range = document.createRange();
+  const walker = document.createTreeWalker(cell, NodeFilter.SHOW_TEXT);
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    if (!node.nodeValue.trim() || node.parentElement?.closest(".katex-mathml")) continue;
+    range.selectNodeContents(node);
+    boxes.push(...range.getClientRects());
+  }
+  for (const element of cell.querySelectorAll("img, svg, canvas, input, video")) boxes.push(element.getBoundingClientRect());
+  const drawn = boxes.filter((box) => box.width > 0 || box.height > 0);
+  if (drawn.length === 0) return null;
+  return {
+    left: Math.min(...drawn.map((box) => box.left)), right: Math.max(...drawn.map((box) => box.right)),
+    top: Math.min(...drawn.map((box) => box.top)), bottom: Math.max(...drawn.map((box) => box.bottom)),
+  };
+}
+
+/**
+ * What the frame `wrapper` (its client box) hides of its `table` at rest: { columns: how many, away
+ * and cut: the columns out of sight and cut, [{ column, name: its first words, the header's }], said:
+ * those columns in words ("of 6 columns, 1 cut at the frame's edge ("结论")", "" for none), reach:
+ * how far from the table's left edge the words past the frame's right edge end (px; 0 when none lies
+ * past it: what the fading edge shows while the frame is not scrolled to it), rows: the body's rows
+ * shown, shown: how many of them the frame shows }.
+ */
+export function tableHides(wrapper, table) {
+  const width = wrapper.clientWidth;
+  const height = wrapper.clientHeight;
+  const box = table.getBoundingClientRect();
+  const holds = (cell) => Boolean((cell.textContent ?? "").trim() || cell.querySelector("img, svg, canvas, input, video"));
+  const { columnOf, columns } = cellColumns(table);
+  const fixed = table.classList.contains("doc-table--sticky-first") || Boolean(table.querySelector(':scope > tbody > tr > th[scope="row"]:first-child'));
+  const before = new Set(); // columns some of whose words start before the edge
+  const past = new Set(); // columns some of whose words reach past it
+  const names = [];
+  let reach = 0;
+  for (const row of table.rows) {
+    if (row.getClientRects().length === 0) continue;
+    for (const cell of row.cells) {
+      const column = columnOf.get(cell);
+      if (names[column] === undefined && cell.colSpan <= 1 && holds(cell)) names[column] = (cell.textContent ?? "").replace(/\s+/g, " ").trim();
+      if (fixed && column === 0) continue;
+      if (cell.getBoundingClientRect().right - box.left <= width + 1) {
+        if (holds(cell)) before.add(column);
+        continue;
+      }
+      const found = wordsBox(cell);
+      if (!found) continue;
+      if (found.left - box.left < width - 1) before.add(column);
+      if (found.right - box.left > width + 1) {
+        past.add(column);
+        reach = Math.max(reach, found.right - box.left);
+      }
+    }
+  }
+  const named = (column) => ({ column, name: names[column] ?? "" });
+  const away = [...past].filter((column) => !before.has(column)).sort((a, b) => a - b).map(named);
+  const cut = [...past].filter((column) => before.has(column)).sort((a, b) => a - b).map(named);
+  const quoted = (list) => `${list.slice(0, 4).map(({ column, name }) => (name ? `"${name.length > 16 ? `${name.slice(0, 15)}…` : name}"` : `column ${column + 1}`)).join(", ")}${list.length > 4 ? ", …" : ""}`;
+  const parts = [cut.length && `${cut.length} cut at the frame's edge (${quoted(cut)})`, away.length && `${away.length} out of sight (${quoted(away)})`].filter(Boolean);
+  const rows = [...table.tBodies].flatMap((body) => [...body.rows]).filter((row) => row.getClientRects().length > 0);
+  const shown = rows.filter((row) => {
+    const { top, bottom } = row.getBoundingClientRect();
+    if (bottom - box.top <= height + 1) return true;
+    if (top - box.top >= height - 1) return false;
+    return Math.max(-Infinity, ...[...row.cells].map(wordsBox).filter(Boolean).map((found) => found.bottom)) - box.top <= height + 1;
+  }).length;
+  return { columns, away, cut, said: parts.length ? `of ${columns} columns, ${parts.join(", ")}` : "", reach, rows: rows.length, shown };
+}
+
+/** tableHides as a script's text, with what it reads (an expression: the function), for a page to measure a table as the kit does. */
+export const tableHidesScript = () => `(() => { ${cellColumns}; ${wordsBox}; return ${tableHides}; })()`;

package/browser/shared/table-slots.mjs

@@ -0,0 +1,75 @@
+// A table's slots (the HTML table model; docs/editor.md, "Tables"): each row has a slot in each
+// column, and a cell covers a rectangle of them, one slot or more when it is merged (its rowspan and
+// colspan). A cell is where its top left slot is ({ r, c }), the table's columns are its slots'
+// columns. The one reading of a table's cells that the kit lays columns out by (render/kit/tables/),
+// the page editor's table tools and operations (editor/components/table/, editor/page/table/) and the
+// server's writing of a table (editor/source/table.mjs, components/table/file.mjs) share: tileSlots
+// is the one tiling, slotsOf and tileSpans give it the cells of a DOM or the spans of an operation,
+// and the cell that holds a column's width is the one columnCells / widthHolder say.
+
+/**
+ * Where cells stand, from their spans alone: rows [{ section, cells: [{ ref, rowspan, colspan }] }]
+ * in order (`section`: what the row belongs to, a thead or a tbody; a cell never spans past it) →
+ * { matrix: per row, the ref covering each slot; places: Map(ref → { r, c, rows, cols }), in reading
+ * order; columns }, or null when the cells do not tile a rectangle (a hole, an overlap, a span past
+ * its section or the table, a span of 0).
+ */
+export function tileSlots(rows) {
+  const matrix = rows.map(() => []);
+  const places = new Map();
+  for (let r = 0; r < rows.length; r++) {
+    let c = 0;
+    for (const { ref, rowspan, colspan } of rows[r].cells) {
+      while (matrix[r][c]) c++;
+      if (!(rowspan >= 1) || !(colspan >= 1)) return null;
+      for (let i = 0; i < rowspan; i++) {
+        if (rows[r + i]?.section !== rows[r].section) return null;
+        for (let j = 0; j < colspan; j++) {
+          if (matrix[r + i][c + j]) return null;
+          matrix[r + i][c + j] = ref;
+        }
+      }
+      places.set(ref, { r, c, rows: rowspan, cols: colspan });
+      c += colspan;
+    }
+  }
+  const columns = matrix[0]?.length ?? 0;
+  // Array holes count as undefined: a slot no cell covers.
+  if (columns === 0 || matrix.some((row) => row.length !== columns || row.includes(undefined))) return null;
+  return { matrix, places, columns };
+}
+
+/**
+ * The slots of a table's rows (tr elements, the thead's first): tileSlots with the cells themselves
+ * as refs, each row's section its parent.
+ */
+export const slotsOf = (rows) => tileSlots(rows.map((row) => ({ section: row.parentElement, cells: [...row.cells].map((cell) => ({ ref: cell, rowspan: cell.rowSpan, colspan: cell.colSpan })) })));
+
+/**
+ * Where cells given by their spans stand, without a DOM (the server's reading of an operation's rows
+ * and of a new table): rows [{ head, cells: [[rowspan, colspan]] }] (the head rows first) → tileSlots
+ * with each cell's "row:index" as its ref.
+ */
+export const tileSpans = (rows) => tileSlots(rows.map((row, r) => ({ section: row.head, cells: row.cells.map(([rowspan, colspan], index) => ({ ref: `${r}:${index}`, rowspan, colspan })) })));
+
+/** The refs of the cells of column `c` alone (beginning there, one column wide), top down. */
+export const columnCells = (slots, c) => [...slots.places].filter(([, place]) => place.c === c && place.cols === 1).map(([ref]) => ref);
+
+/**
+ * The cell that holds column `c`'s width where the table's tools write it (the page editor's
+ * COLUMN_WIDTH): the topmost cell of that column alone, or null (a merged cell holds none).
+ */
+export const widthHolder = (slots, c) => columnCells(slots, c)[0] ?? null;
+
+/**
+ * Each column's width as it is read (the kit lays the table out at them): the first cell of that
+ * column alone, top down, that has one (`widthOf(cell)`: a truthy width or null); null each where
+ * none has.
+ */
+export const columnWidths = (slots, widthOf) => Array.from({ length: slots.columns }, (_, c) => {
+  for (const cell of columnCells(slots, c)) {
+    const width = widthOf(cell);
+    if (width) return width;
+  }
+  return null;
+});

package/browser/shared/words.mjs

@@ -0,0 +1,23 @@
+import { unescapeText } from "./escape.mjs";
+
+// How many words a report holds, as Notion counts a page's (the workbench's menus say it: 129 个字):
+// each Chinese, Japanese or Korean character one, each run of other letters and digits one. What is
+// counted is the text of its main below the header (the title and the icon are not the body): no
+// script, style or template, a formula one word (its TeX is no prose).
+
+const SKIPPED = /<(script|style|template|noscript|svg)\b[\s\S]*?<\/\1>/gi;
+const FORMULA = /\\\([\s\S]*?\\\)|\\\[[\s\S]*?\\\]/g;
+const CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/gu;
+const WORD = /[\p{L}\p{N}]+(?:['’.-][\p{L}\p{N}]+)*/gu;
+
+/** The words of report `html` (a whole report.html, or the inside of its main). */
+export function countWords(html) {
+  let body = String(html);
+  const main = /<main\b[^>]*>([\s\S]*)<\/main>/i.exec(body);
+  if (main) body = main[1];
+  body = body.replace(/^\s*<header\b[^>]*>[\s\S]*?<\/header>/i, " "); // the page's header: its title and icon
+  const text = unescapeText(body.replace(SKIPPED, " ").replace(FORMULA, " 公式 ").replace(/<[^>]*>/g, " ").replace(/&nbsp;/g, " ").replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code))));
+  const formulas = (body.match(FORMULA) ?? []).length;
+  const cjk = (text.match(CJK) ?? []).length - formulas * 2; // "公式" stands for a formula: one word, not two characters
+  return cjk + formulas + (text.replace(CJK, " ").match(WORD) ?? []).length;
+}