@heycys/gallery 0.0.0-stage → 0.1.1

package/browser/shared/i18n/index.mjs

@@ -0,0 +1,132 @@
+import EN from "./en.mjs";
+import { KEYS, OLD_KEYS } from "../renamed-storage.mjs";
+
+// The language of Gallery's own UI (the workbench, the page editor's menus, cards and notices),
+// chosen in the workbench's 设置 › 语言: Chinese (the source's own words) or English. A report's
+// content is never translated. Each string is written in Chinese where it is used and goes through
+// t(): its English is looked up in en.mjs by that Chinese text (tests/unit/i18n.mjs holds every
+// one to having an entry), so the code reads as before and nothing is named twice. A string with
+// parts filled in writes them as {0}, {1}… (t("已导入 {0} 个页面", count)).
+// The choice is kept in localStorage, which the workbench and every preview page share (one
+// origin); changing it reloads the workbench, so every string, those made once as a module loads
+// too, is made again in the language chosen. Without a choice: the browser's language (Chinese for
+// zh-*, else English).
+
+/** The languages, by code, each named in itself. */
+export const LANGUAGES = { zh: "中文", en: "English" };
+const KEY = KEYS.language;
+
+function stored() {
+  try {
+    const value = globalThis.localStorage?.getItem(KEY);
+    return Object.hasOwn(LANGUAGES, value ?? "") ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+// The language in use, of the one kept (a code of LANGUAGES, or null) and the browser's: one rule for
+// the UI's modules (language) and a report page's first script (languageScript), which runs it as text.
+function inUse(kept, browser) {
+  return kept ?? (/^zh\b/i.test(browser ?? "zh") ? "zh" : "en");
+}
+
+/** The language in use: "zh" or "en". */
+export const language = inUse(stored(), globalThis.navigator?.language);
+// The language t() says things in: the one in use, but while inLanguage runs.
+let speaking = language;
+
+/**
+ * What a report page Gallery shows (the page edited, presented, the 写作偏好 dialog's) runs first, in
+ * its head (src/server/routes.mjs): the UI's language on its root as data-ge-language, which the kit's
+ * own words follow (src/render/kit/words.js: its chrome, an empty code block's title), read as
+ * `language` reads it, before the kit draws anything. An export of the view takes every data-ge-*
+ * attribute off (the kit's ui.js), so an exported file speaks its own lang.
+ */
+export const languageScript = () => {
+  const run = (keys, codes, browser) => {
+    let kept = null;
+    try {
+      kept = keys.map((key) => localStorage.getItem(key)).find((value) => codes.includes(value)) ?? null;
+    } catch {}
+    document.documentElement.setAttribute("data-ge-language", inUse(kept, browser));
+  };
+  // KEYS' own, else the old name's (src/shared/renamed-storage.mjs carries it over as the UI's modules load).
+  return `document.currentScript.remove(); (() => { const inUse = ${inUse}; (${run})(${JSON.stringify([KEY, OLD_KEYS.language])}, ${JSON.stringify(Object.keys(LANGUAGES))}, navigator.language); })();`;
+};
+
+/** Keep `code` as the language (the workbench reloads after, so everything is made in it). */
+export function chooseLanguage(code) {
+  if (!Object.hasOwn(LANGUAGES, code)) return;
+  try {
+    globalThis.localStorage?.setItem(KEY, code);
+  } catch {}
+}
+
+/**
+ * `text` (Chinese, as written in the source) in the language in use, its {0}, {1}… filled with
+ * `values`. One Chinese word with two meanings in English says which it is after an @ ("标题@caption":
+ * 标题 in Chinese, its own entry in English).
+ */
+export function t(text, ...values) {
+  const own = /^([\s\S]*)@[a-z]+$/.exec(text)?.[1] ?? text;
+  return fill(speaking === "en" ? EN[text] ?? own : own, values);
+}
+
+// `text`'s {0}, {1}… filled with `values` (t's and said's one rule).
+const fill = (text, values) => (values.length === 0 ? text : text.replace(/\{(\d+)\}/g, (whole, index) => (index < values.length ? String(values[index]) : whole)));
+
+/**
+ * A message the server sends the UI with parts filled in (a size, a name, an exit code, an Agent's
+ * check lines), which no whole string of en.mjs could match: `text` the Chinese as t() takes it, a
+ * literal with {0}, {1}… (tests/unit/i18n.mjs holds each one to its entry), `values` its parts, never
+ * translated (a part that is itself a UI word is a template of its own: 图片太大 and 文件太大).
+ * { message: the Chinese filled in, what the log, the CLI and an older page read, text, values }: an
+ * answer spreads it ({ ok: false, reason, ...said(…) }), an error carries it (Object.assign(new
+ * Error(), said(…))). Filled here, never through t(): the server speaks Chinese whatever its machine's
+ * language.
+ */
+export function said(text, ...values) {
+  return { message: fill(text, values), text, values };
+}
+
+/**
+ * What a failure's answer carries of `message`: a string as { message }; an error or said()'s object as
+ * { message } with its text and values when it has them; nothing for none.
+ */
+export function saying(message) {
+  if (message === undefined || message === null) return {};
+  if (typeof message === "string") return { message };
+  return { message: message.message, ...(typeof message.text === "string" && Array.isArray(message.values) ? { text: message.text, values: message.values } : {}) };
+}
+
+/** An error that says `message` (a string, or said()'s), with `fields` (its reason): saying() carries it into an answer. */
+export const refusal = (message, fields = {}) => Object.assign(new Error(typeof message === "string" ? message : message.message), saying(message), fields);
+
+/**
+ * What a server's answer (or an error made of one: saying()) says, in the UI's language: t(text,
+ * ...values) when it carries said()'s template, else t(message) (a whole message: its entry, else as
+ * it is); null when it says nothing. The UI's funnels read a failure through it (post.mjs failure,
+ * the workbench's api.ts and transfer.ts).
+ */
+export function told(answer) {
+  if (typeof answer?.text === "string" && Array.isArray(answer.values)) return t(answer.text, ...answer.values);
+  return typeof answer?.message === "string" && answer.message ? t(answer.message) : null;
+}
+
+/**
+ * What `run` returns, its t() said in `code` ("zh" or "en") whatever the language in use: for what
+ * the server writes into a page it serves, which is not in the server's language but the page's
+ * (src/editor/components/placeholder.mjs: what is empty, in Chinese, said again in English as the
+ * page starts when its UI is). Synchronous only.
+ */
+export function inLanguage(code, run) {
+  if (!Object.hasOwn(LANGUAGES, code)) throw new Error(`No UI language "${code}".`);
+  const before = speaking;
+  speaking = code;
+  try {
+    return run();
+  } finally {
+    speaking = before;
+  }
+}

package/browser/shared/ids.mjs

@@ -0,0 +1,24 @@
+// The random ids the page and the server both make and check, in one place: a block's id (the one
+// a block made on the page proposes, as the server makes them) and the id a commit is sent with
+// (the server keeps its answer by it). Web Crypto is in the browser and in Node alike.
+
+const CHARS = "abcdefghijklmnopqrstuvwxyz0123456789";
+
+/** A random string of `length` lowercase letters and digits, a letter first when `letterFirst`. */
+export const randomId = (length, { letterFirst = false } = {}) => [...crypto.getRandomValues(new Uint8Array(length))]
+  .map((byte, index) => CHARS[byte % (letterFirst && index === 0 ? 26 : 36)]).join("");
+
+/** A block's id (data-block-id): eight letters and digits, a letter first. */
+export const BLOCK_ID = /^[a-z][a-z0-9]{7}$/;
+export const randomBlockId = () => randomId(8, { letterFirst: true });
+
+/** A commit's id: the page makes sixteen letters and digits of it; the server takes eight to forty. */
+export const REQUEST_ID = /^[a-z0-9]{8,40}$/;
+export const randomRequestId = () => randomId(16);
+
+/**
+ * The key of a text block outside any unit in a commit's answer (`outside`, by key: what the file
+ * says of its text): "title" for the report's title, "id:<id>" for any other, by the id of its own
+ * element, so that no element's id can be taken for the title; null for a block with neither.
+ */
+export const outsideKey = (title, id) => (title ? "title" : id ? `id:${id}` : null);

package/browser/shared/import-types.mjs

@@ -0,0 +1,23 @@
+// What the workbench's 导入 takes (notion-lite's src/editor/transfer/import-types.js, Notion's
+// 基于文件导入): by extension, each kind a converter of src/transfer/import.mjs. The import dialog's
+// file picker offers them (accept), the server converts by them.
+
+/** { kind: [extensions] } */
+export const IMPORT_EXT = {
+  markdown: [".md", ".markdown", ".mdx", ".txt", ".text"],
+  html: [".html", ".htm", ".xhtml"],
+  csv: [".csv", ".tsv"],
+  docx: [".docx"],
+  pdf: [".pdf"],
+  epub: [".epub"],
+  zip: [".zip"],
+};
+
+/** The lower-cased extension of a file's name, with its dot ("" for none). */
+export const extOf = (name) => /\.[^./\\]+$/.exec(String(name).toLowerCase())?.[0] ?? "";
+
+/** The kind of file `name` is ("markdown", "html", "csv", "docx", "pdf", "epub", "zip"), or null for one the import does not take. */
+export const kindOf = (name) => Object.keys(IMPORT_EXT).find((kind) => IMPORT_EXT[kind].includes(extOf(name))) ?? null;
+
+/** The biggest file the import takes (Notion's: "最大支持 5GB 的 ZIP 文件"). */
+export const IMPORT_LIMIT = 5 * 1024 ** 3;

package/browser/shared/inline-spacing.mjs

@@ -0,0 +1,97 @@
+// The one rule for the space beside inline code and formulas, read by the kit's runtime/spacing.js
+// (the reading view, for the report's own text) and by the page editor (marks.mjs, typing/, core.mjs
+// prepareBlock, the paste): inline code and a formula stand an ordinary space apart from a letter,
+// a digit or a Chinese character right beside them, and from one another; none beside a space,
+// punctuation or the line's edge. What is beside an element is looked for as the reader sees it:
+// out of the wrappers it stands in (strong, a link, a span...) and into those beside it, up to the
+// edge of its line (a paragraph, a list item, a cell, a break, a list...) or of the editing host.
+// A formula left empty (\(\), which shows nothing) and a link left empty are not there to either
+// side. The editor's zero-width pads (pads.mjs) hold no text. DOM only: no globals.
+
+// The magnitudes and measure words a number goes with, written with no space before them (3.6亿, 5个,
+// 2024年, 30天), and 第 before a number (第3名): the page editor's typing keeps them together (typing/ autoSpace).
+const UNITS = new Set([..."个万亿千百十元角分厘毛倍年月日号时点秒天周岁人位名次家条项种台只件篇页张套份组批期届代级层轮步米克斤吨度里公毫微寸尺两升户所座栋辆架艘本部章节场局首句字行列遍回番成"]);
+const DIGIT = /[0-9]/;
+/** Whether characters `a` and `b` (`before` the one ahead of `a`) stay together: a number and its unit (3万5千 too). */
+export const numberWithUnit = (a, b, before = "") => (DIGIT.test(a) && UNITS.has(b)) || (a === "第" && DIGIT.test(b)) || (UNITS.has(a) && DIGIT.test(b) && DIGIT.test(before));
+
+/** The editor's pads (pads.mjs) hold nothing but this. */
+export const ZWSP = String.fromCharCode(0x200b);
+/** What a space is put beside: a letter or a digit (a Chinese character is a letter). */
+export const WORD = /[\p{L}\p{N}]/u;
+
+const ITEM = "code, .doc-math-inline, .katex";
+// What ends a line of text: nothing beyond it is a neighbour.
+const LINE = /^(P|LI|H[1-6]|TD|TH|DT|DD|DIV|SECTION|ARTICLE|ASIDE|HEADER|FOOTER|MAIN|NAV|FIGURE|FIGCAPTION|CAPTION|SUMMARY|DETAILS|BLOCKQUOTE|UL|OL|TABLE|THEAD|TBODY|TR|PRE|BR|HR|DIALOG|BODY|BUTTON|svg)$/;
+
+/** Whether `node` is a text node holding nothing but pads (or nothing). */
+export const blank = (node) => node?.nodeType === 3 && node.data.replaceAll(ZWSP, "") === "";
+
+// A formula left empty: \(\) as written, KaTeX's drawing of nothing, or the page editor's chip for
+// it (data-ge-empty, as the editor's server serves the page; one that does not read has TeX in it).
+const emptyFormula = (element) => element.matches(".doc-math-inline") && (element.getAttribute("data-ge-empty") === "formula" || !element.textContent.replace(/\\[()]/g, "").trim());
+
+/** Whether `node` is inline code or a formula with something in it: what the rule spaces. */
+export const isInlineItem = (node) => node?.nodeType === 1 && node.matches(ITEM) && !emptyFormula(node);
+
+/** The inline code and formulas under `root` (itself too) that stand in the text, not in another formula or code. */
+export function inlineItems(root) {
+  const items = root.nodeType === 1 && root.matches(ITEM) ? [root, ...root.querySelectorAll(ITEM)] : [...root.querySelectorAll(ITEM)];
+  return items.filter((item) => isInlineItem(item) && !item.parentElement?.closest(".doc-math-inline, .katex, .katex-display, code"));
+}
+
+// The text at one end of a node: its first (or last) character, true for inline code or a formula,
+// null at a line's edge, undefined when it holds no text.
+function endOf(node, after) {
+  if (node.nodeType === 3) {
+    const characters = [...node.data.replaceAll(ZWSP, "")];
+    return characters.length === 0 ? undefined : after ? characters[0] : characters.at(-1);
+  }
+  if (node.nodeType !== 1) return undefined;
+  if (LINE.test(node.tagName)) return null;
+  if (node.matches(ITEM)) return emptyFormula(node) ? undefined : true;
+  if (node.hasAttribute("data-ge-empty")) return undefined;
+  const children = [...node.childNodes];
+  for (const child of after ? children : children.reverse()) {
+    const found = endOf(child, after);
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}
+
+/**
+ * What is beside `node` in its line, before it or `after` it: the character next to it, true where
+ * inline code or a formula is, null where there is nothing on the line.
+ */
+export function sideOf(node, after) {
+  for (let at = node; at;) {
+    const next = after ? at.nextSibling : at.previousSibling;
+    if (!next) {
+      at = at.parentElement;
+      if (!at || LINE.test(at.tagName) || at.hasAttribute("contenteditable")) return null;
+      continue;
+    }
+    const found = endOf(next, after);
+    if (found !== undefined) return found;
+    at = next;
+  }
+  return null;
+}
+
+/**
+ * A space on each side of the inline code or formula `element` where a word or another one is
+ * beside it, as an ordinary text node (inside the wrapper the element stands in, where it stands
+ * at the wrapper's edge). Returns the spaces put in: { before, after }, text nodes or null.
+ */
+export function spaceAround(element) {
+  const put = { before: null, after: null };
+  for (const after of [false, true]) {
+    const side = sideOf(element, after);
+    if (side !== true && !(typeof side === "string" && WORD.test(side))) continue;
+    const space = element.ownerDocument.createTextNode(" ");
+    if (after) element.after(space);
+    else element.before(space);
+    put[after ? "after" : "before"] = space;
+  }
+  return put;
+}

package/browser/shared/layers.mjs

@@ -0,0 +1,42 @@
+// The z-order of everything the editor and the preview draw over a report, written once, lowest
+// first. Each name is one level; a level's number is a step below TOP, near the largest z-index a
+// page can have, so no report's own content covers them. Add a level where it belongs in the list;
+// nothing else in src/ writes a number that big (tests/unit/editor-look.mjs holds it to that).
+//
+// Levels that used to share a number now stand one above the other: the resize guide was level with
+// the panels (format bar, conflicts) and the size label with the toast and the hint; they follow the
+// order below (the format bar is hidden while a picture is resized, so nothing shows the difference).
+//
+//   checks     the preview's note of failing checks (render/preview-checks.mjs)
+//   outline    the outline at the page's right (page/outline/: its list or its strip; the strip's card is a menu)
+//   layer      the overlay layers (page/overlay-layer.mjs): fills, frames, the handle, drop lines
+//   marquee    the box a box selection draws
+//   affordance a button that appears by the text it adds to (添加图标)
+//   note       批注 in the margin: the markers, the cards, a block anchor's bar (editor/page/annotate/)
+//   preview    the copies of the blocks being dragged
+//   mark       the text a link card is about, marked
+//   spin       a link's spinner
+//   guide      the line a resize drags
+//   label      its size label
+//   panel      the format bar, the conflicts, the lost texts
+//   toast      the page's own notice
+//   hint       the bubble that says why a block cannot be edited
+//   menu       the menus (block types, commands, the icon picker)
+//   card       a card over the text it belongs to (a formula, a link)
+//   viewer     a window over the whole page (a picture viewed, an embed full screen, the crop)
+//   tooltip    the tooltip, over everything
+const LEVELS = ["checks", "outline", "layer", "marquee", "affordance", "note", "preview", "mark", "spin", "guide", "label", "panel", "toast", "hint", "menu", "card", "viewer", "tooltip"];
+const TOP = 2147483010;
+
+/** name -> z-index. */
+export const Z = Object.freeze(Object.fromEntries(LEVELS.map((name, index) => [name, TOP - (LEVELS.length - 1 - index)])));
+
+/**
+ * What stands inside one overlay layer (a stacking context of its own), lowest first: a drop's tint,
+ * a selected block's fill, the frames, the handle and a section's bar, a button standing on a block's
+ * edge (a flowchart node's "+", centred on its right border: over the bar of the section it is in,
+ * whose right side it may reach) or beside it (the 批注 button, over that bar too), a drop's line.
+ */
+export const IN_LAYER = Object.freeze({ tint: 1, halo: 2, frame: 3, handle: 4, button: 5, drop: 6 });
+
+export const LEVEL_NAMES = LEVELS;

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/media.mjs

@@ -0,0 +1,162 @@
+// The media of a report, one place for what every system asks about it: the files its media
+// blocks, its page icon and any other reference of its markup keep in the report's folder
+// (assets/<file>), where the preview serves them, and what the editor may upload. Shared by the
+// render (the preview's and an export's pictures, files and frames: src/render/media-ref.mjs, and
+// every other reference: asset-references.mjs), the server (its routes: src/server/media-route.mjs,
+// the upload: src/editor/media-store.mjs), the editor's page and the shared component descriptions.
+// A new media kind is a row in these tables. Which blocks are media blocks is the descriptions' `media`
+// (components/index.mjs MEDIA_BLOCKS).
+
+// ---------- the files of a report's folder ----------
+
+// assets/<file>: the file's name of letters, digits, dots, dashes and underscores (the page editor's
+// uploads name each <kind>-<hash>.<extension>: editor/media-store.mjs). Flat and ASCII on purpose
+// (a name any shell, URL and zip writes as it is); what breaks it is said by assetProblem.
+const ASSET = /^assets\/[a-z0-9][a-z0-9._-]{0,80}$/i;
+
+/** Each extension's media type: what a build and an export embed a file with, what the server serves it as. */
+export const MEDIA_TYPES = {
+  png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp", avif: "image/avif", svg: "image/svg+xml", ico: "image/x-icon",
+  pdf: "application/pdf", csv: "text/csv", tsv: "text/tab-separated-values", txt: "text/plain", md: "text/markdown", json: "application/json",
+  xml: "application/xml", html: "text/html", htm: "text/html", zip: "application/zip", gz: "application/gzip", tar: "application/x-tar", "7z": "application/x-7z-compressed",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", xls: "application/vnd.ms-excel",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document", doc: "application/msword",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation", ppt: "application/vnd.ms-powerpoint",
+  mp3: "audio/mpeg", wav: "audio/wav", mp4: "video/mp4", webm: "video/webm", mov: "video/quicktime", vtt: "text/vtt",
+  woff: "font/woff", woff2: "font/woff2", ttf: "font/ttf", otf: "font/otf",
+};
+
+/** A name's extension, lowercase ("" when it has none). */
+export const extensionOf = (value) => /\.([a-z0-9]{1,10})$/i.exec(value)?.[1]?.toLowerCase() ?? "";
+
+/** The media type of a file by its extension (any file: application/octet-stream when the table lacks it). */
+export const mediaTypeOf = (value) => MEDIA_TYPES[extensionOf(value)] ?? "application/octet-stream";
+
+/** The extension an image's media type is kept under (png for image/png, jpg for image/jpeg). */
+export const imageExtension = (type) => (type.startsWith("image/") ? Object.keys(MEDIA_TYPES).find((extension) => MEDIA_TYPES[extension] === type) ?? null : null);
+
+/** Whether a value names a file of the report's folder (assets/<file>). */
+export const assetFile = (value) => typeof value === "string" && ASSET.test(value) && !value.includes("..");
+
+/** Whether a value names a picture of the report's folder (a file of an image type). */
+export const imageFile = (value) => assetFile(value) && mediaTypeOf(value).startsWith("image/");
+
+// The picture formats a page shows, as a failure names them.
+const PICTURE_FORMATS = "png, jpg, gif, webp, avif, svg or ico";
+// The rule of a file's name in assets/ (ASSET), as a failure says it.
+const NAME_RULE = "a name is 1 to 81 characters, each a letter a-z or A-Z, a digit, a dot, a dash or an underscore, the first a letter or a digit";
+
+/**
+ * A name of a file in assets/ that ASSET takes, made of one that it does not (an example a failure
+ * gives): its runs of ASCII letters and digits in lowercase, a dash between them, its extension kept
+ * (B263_古文孝経__NDL1288405.png → b263-ndl1288405.png); `fallback` when no letter or digit is left
+ * (古文孝経.png → picture.png).
+ */
+export function assetName(name, fallback = "file") {
+  const dot = name.lastIndexOf(".");
+  const extension = dot > 0 ? name.slice(dot + 1).toLowerCase().replace(/[^a-z0-9]/g, "").slice(0, 10) : "";
+  const stem = (dot > 0 ? name.slice(0, dot) : name).match(/[a-z0-9]+/gi)?.join("-").toLowerCase() || fallback;
+  return extension ? `${stem.slice(0, 80 - extension.length)}.${extension}` : stem.slice(0, 81);
+}
+
+/**
+ * Why a value names no file of the report's folder as the preview serves one (assetFile, and with
+ * `picture` imageFile), as a failure says it after the value and a colon, or null when it names one:
+ * each reason apart, with what to write instead: not in assets/ (a web address, another folder,
+ * ./assets/, ASSETS/ in capitals, one leaving it by ".."), in a folder of assets/, a name of
+ * characters ASSET does not take (each named, an example of a name it takes: assets/b263-kobun.png),
+ * too long or starting with neither a letter nor a digit; with `picture`, a file of no picture format
+ * too. The rule stays ASSET's: an Agent copies a file in under such a name (the uploads name theirs so).
+ */
+export function assetProblem(value, { picture = false } = {}) {
+  if (typeof value !== "string" || !value.trim()) return `it names no file: write assets/<file>, a file of the document's assets/ folder`;
+  const written = value.trim();
+  const format = (name) => (picture && !mediaTypeOf(name).startsWith("image/") ? `${extensionOf(name) ? `.${extensionOf(name)}` : "a file with no extension"} is no picture format a page shows (${PICTURE_FORMATS}): convert it to one` : "");
+  if (/^[a-z][a-z0-9+.-]*:/i.test(written)) return `it is no file of the document's folder (an export holds the document's own files alone): save it into the document's assets/ folder and write assets/<file>`;
+  const relative = /^\.\/(?=assets\/)/i.test(written) ? written.slice(2) : written;
+  if (!/^assets\//i.test(relative)) return `it is not in the document's assets/ folder: copy the file into it and write assets/<file>`;
+  const name = relative.slice("assets/".length);
+  if (!relative.startsWith("assets/")) return `the folder is assets/, in lowercase: write it so (assets/${name})`;
+  if (relative !== written) return `write it without "./" (${relative})`;
+  if (name.split(/[\\/]/).includes("..")) return `it leaves assets/ by "..": the files are right in assets/`;
+  const base = name.split(/[\\/]/).at(-1);
+  const proper = /^[a-z0-9][a-z0-9._-]{0,80}$/i.test(base) && !base.includes("..") ? base : assetName(base, picture ? "picture" : "file");
+  const converted = format(base);
+  if (/[\\/]/.test(name)) return `the preview serves the files right in assets/, none in a folder of it (${relative.slice(0, relative.length - base.length)}): move the file into assets/, as assets/${proper}${converted ? `; and ${converted}` : ""}`;
+  if (!base) return `it names no file: write assets/<file>, a file of the document's assets/ folder`;
+  const foreign = [...new Set(base.match(/[^a-z0-9._-]/gi) ?? [])];
+  const why = foreign.length ? `its name holds ${foreign.slice(0, 6).map((char) => (/\s/.test(char) ? "a space" : char)).join(", ")}${foreign.length > 6 ? "…" : ""}`
+    : base.length > 81 ? `its name is ${base.length} characters`
+    : !/^[a-z0-9]/i.test(base) ? `its name starts with "${base[0]}"`
+    : base.includes("..") ? `its name holds ".."`
+    : "";
+  if (why) return `${why}, which the preview serves no file by (${NAME_RULE}): copy the file in under such a name, as assets/${proper}${converted ? `; and ${converted}` : ""}`;
+  return converted || null;
+}
+
+/** Whether a value names an embed block's file of the report's folder (an HTML or PDF file). */
+export const embedFile = (value) => assetFile(value) && /\.(html?|pdf)$/i.test(value);
+
+/** Whether a value names a picture a page's icon may be (an image of the report's folder, but no .ico). */
+export const iconImageFile = (value) => imageFile(value) && extensionOf(value) !== "ico";
+
+/**
+ * The file of the report's folder a reference names, wherever it stands (render/asset-references.mjs):
+ * the value written assets/… or ./assets/… (in any case), without its query and fragment, its
+ * %-escapes read; or null when it names none (another address, or one leaving the folder by "..").
+ * Whether the preview can serve that file is assetFile's to say, as for any file of the folder.
+ */
+export function referencedFile(value) {
+  if (typeof value !== "string" || !/^\s*(?:\.\/)?assets\//i.test(value)) return null;
+  let file = value.trim().replace(/^\.\//, "").replace(/[?#].*$/, "");
+  try {
+    file = decodeURIComponent(file);
+  } catch {
+    // written with a stray "%": the name as it is
+  }
+  return file.split(/[\\/]/).includes("..") ? null : file;
+}
+
+// ---------- where the preview serves them ----------
+
+/**
+ * What each route of the preview server serves of a report's folder (/__gallery/edit/<route>/<slug>/assets/<file>):
+ * `asset` its pictures (the editor works with them as they are), `file` any file, handed out for saving
+ * only, `embed` an embed block's HTML or PDF file, shown in its frame. Each says what it takes.
+ */
+export const MEDIA_ROUTES = { asset: imageFile, file: assetFile, embed: embedFile };
+
+/** The address the preview serves a file of a report's folder at (`value`: assets/<file>). */
+export const mediaUrl = (route, slug, value) => `/__gallery/edit/${route}/${slug}/${value}`;
+
+// ---------- what may be uploaded ----------
+
+const MB = 1024 * 1024;
+/** The most bytes of each upload kind: an icon's picture, an image block's, a file block's, an embed block's file. */
+export const UPLOAD_LIMITS = { icon: 2 * MB, image: 10 * MB, file: 20 * MB, embed: 20 * MB };
+/** The limit of an upload kind as the page says it ("10 MB"). */
+export const sizeLimit = (kind) => `${UPLOAD_LIMITS[kind] / 1024 / 1024} MB`;
+
+/** A size as Notion writes one: 1024 a step, one decimal at most (12.1 KiB). */
+export function formatSize(bytes) {
+  const units = ["B", "KiB", "MiB", "GiB"];
+  let value = bytes;
+  let at = 0;
+  while (value >= 1024 && at < units.length - 1) {
+    value /= 1024;
+    at++;
+  }
+  return `${parseFloat(value.toFixed(at ? 1 : 0))} ${units[at]}`;
+}
+/** The most the upload request holds: the biggest file as base64, and a megabyte for the rest of it. */
+export const UPLOAD_REQUEST_LIMIT = Math.ceil((Math.max(...Object.values(UPLOAD_LIMITS)) * 4) / 3 / MB + 1) * MB;
+
+// ---------- the width a sized media block takes ----------
+
+/** The property of a media block's width, as a share of the width it stands in (a picture's: of the reading width, at most where it stands), and the shares it may take. */
+export const SPAN = "--doc-span";
+export const SPAN_SIZE = { min: 0.1, max: 1 };
+/** The reading width, px (the kit's --doc-content-max-width, styles/tokens.css): what a picture's width in pixels is a share of. */
+export const READING_WIDTH = 712;
+/** The gap between the columns of a row, px (the kit's --doc-column-gap, styles/tokens.css): what a column's width is less. */
+export const COLUMN_GAP = 20;

package/browser/shared/new-names.mjs

@@ -0,0 +1,67 @@
+import { parse } from "parse5";
+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
+// a text through this). Apart from old-names.mjs, which the page's code imports too: this one
+// parses the text (parse5), as only the tools on the server do.
+
+// The kit's tags (data-report-kit, data-report-vendor) and an export's inline copies of them: the
+// kit's own text, of its own time, whose attributes alone are the page's.
+const KIT_TAG = /^data-(?:report|doc)-(?:kit|vendor)$/;
+
+/**
+ * An HTML document's (or fragment's) text with the format's old names new: its attributes' names
+ * (data-report-* → data-doc-*), its classes, a meta's name, an id spelled as an old name and what
+ * points to it (for, aria-*, href="#…"), custom properties in any attribute (a style, an SVG's
+ * fill), the code of on* attributes and javascript: addresses, and the text of its
+ * own <style> and <script> elements (a JSON script is data: left as written, as is every text a
+ * reader reads, a comment and a code sample). An instance of a component package is passed by whole:
+ * no name in it is the format's. Lines stay where they are (a name changes in its line);
+ * a text holding none is given back as it is, and the new names are none of the old ones, so a
+ * second pass changes nothing.
+ */
+export function newNames(html) {
+  if (typeof html !== "string" || !mayHoldOldNames(html)) return html;
+  const document = parse(html, { sourceCodeLocationInfo: true });
+  const edits = []; // { start, end, text }
+  const put = (start, end, next) => {
+    if (html.slice(start, end) !== next) edits.push({ start, end, text: next });
+  };
+  function element(node) {
+    const places = node.sourceCodeLocation?.attrs ?? {};
+    for (const { name, value } of node.attrs) {
+      const place = places[name];
+      if (!place) continue;
+      const written = html.slice(place.startOffset, place.endOffset);
+      const equals = written.indexOf("=");
+      const head = equals < 0 ? written : written.slice(0, equals);
+      const tail = equals < 0 ? "" : written.slice(equals);
+      const newValue = /^on/i.test(name) || /^\s*javascript:/i.test(value) ? newScriptNames(tail) : newAttributeValue(name, tail, node.tagName);
+      put(place.startOffset, place.endOffset, newAttributeName(head) + newValue);
+    }
+    if (node.attrs.some(({ name }) => KIT_TAG.test(name)) || !["style", "script"].includes(node.tagName)) return;
+    const at = node.childNodes?.[0]?.sourceCodeLocation;
+    if (!at) return;
+    const type = (node.attrs.find(({ name }) => name === "type")?.value ?? "").trim().toLowerCase();
+    if (node.tagName === "script" && /json/.test(type)) return; // data: a chart's, a diff's lines
+    const source = html.slice(at.startOffset, at.endOffset);
+    put(at.startOffset, at.endOffset, node.tagName === "style" ? newStyleNames(source) : newScriptNames(source));
+  }
+  const visit = (node) => {
+    for (const child of node.childNodes ?? []) {
+      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);
+    }
+  };
+  visit(document);
+  if (!edits.length) return html;
+  edits.sort((a, b) => b.start - a.start);
+  let result = html;
+  for (const { start, end, text } of edits) result = result.slice(0, start) + text + result.slice(end);
+  return result;
+}