@quario/editor 0.1.0

package/lib/document.js

@@ -0,0 +1,674 @@
+/**
+ * The editor's document model — one pure module, no DOM, the seam the Node
+ * suite pins. The document is exactly the schema: plain JSON, no injected ids,
+ * addressed by the engine's own path grammar. Every operation takes a schema
+ * and returns a new one (the history is a capped snapshot stack, so an op
+ * produces a document rather than mutating one), and legality is derived from
+ * the schema's closed key sets plus the engine's per-node anchor sets — a drop
+ * is legal only when every anchor the item reads is bound in the destination
+ * band. (The safety suite greps every source file for the forbidden
+ * string-to-code constructs, so they must not appear even in a comment.)
+ *
+ * Two rules hold everywhere:
+ *
+ * - Never normalize absent to empty, or back. `"empty": []` suppresses the
+ *   body while an absent `empty` keeps the default, so tidying a key away when
+ *   its last item leaves would silently change the report. Removing the last
+ *   item leaves `[]`; removing a band is a separate explicit verb.
+ * - Touch only the key you edited. Style declaration order survives a
+ *   write-back, clearing an optional key removes it while a required key
+ *   writes `""`, and a column header widens for style but never narrows.
+ */
+
+// --- paths ----------------------------------------------------------------
+
+/** @type {(path: string) => ({ key: string } | { index: number })[] | null} */
+let segments = (path) => {
+  let out = [];
+  for (let part of path.split(".")) {
+    let m = part.match(/^([^[]+)((\[\d+\])*)$/);
+    if (!m) return null;
+    out.push({ key: m[1] });
+    for (let idx of m[2].matchAll(/\[(\d+)\]/g)) out.push({ index: Number(idx[1]) });
+  }
+  return out;
+};
+
+/** One resolution step: follow the segment, or stay undefined off the end. */
+/** @type {(node: any, seg: { key: string } | { index: number }) => any} */
+let step = (node, seg) =>
+  node == null ? undefined : "key" in seg ? node[seg.key] : node[seg.index];
+
+/** Resolve a schema path to the node behind it, or undefined. */
+/** @type {(schema: any, path: string) => any} */
+export let resolve = (schema, path) => {
+  let segs = segments(path);
+  if (!segs) return undefined;
+  let node = schema;
+  for (let seg of segs) node = step(node, seg);
+  return node;
+};
+
+/** `groups[0].header[2]` -> `groups[0].header`; `header[0]` -> `header`. */
+/** @type {(path: string) => string} */
+export let bandOfItem = (path) => path.replace(/\[\d+\]$/, "");
+
+/** The item index a path ends with, or -1. */
+/** @type {(path: string) => number} */
+export let indexOfItem = (path) => Number(path.match(/\[(\d+)\]$/)?.[1] ?? -1);
+
+// --- bands and the slot model ---------------------------------------------
+
+/** `$` is bound everywhere; the rest is positional. */
+let ALWAYS = ["$"];
+
+/** The report's groups, outermost first, or [] when it declares none. */
+/** @type {(schema: any) => any[]} */
+let groupsOf = (schema) => (Array.isArray(schema?.groups) ? schema.groups : []);
+
+/** @type {(schema: any) => string[]} */
+let groupNamesOf = (schema) =>
+  groupsOf(schema)
+    .map((/** @type {any} */ group) => group?.name)
+    .filter((/** @type {any} */ name) => typeof name === "string");
+
+/** Whether the detail band is a table rather than a stack of items. */
+/** @type {(schema: any) => boolean} */
+let isTable = (schema) => schema?.detail != null && !Array.isArray(schema.detail);
+
+/** The anchors a band inside group `i` binds: `$` plus every enclosing handle. */
+/** @type {(groups: any[], i: number) => string[]} */
+let bindsAt = (groups, i) => [...ALWAYS, ...groupNamesOf({ groups: groups.slice(0, i + 1) })];
+
+/** One group instance's own header or footer band. */
+/** @type {(group: any, i: number, which: "header" | "footer", binds: string[]) => any} */
+let groupBand = (group, i, which, binds) => ({
+  path: "groups[" + i + "]." + which,
+  role: "group-" + which,
+  label: group?.name + " " + which,
+  binds,
+});
+
+/**
+ * The bands of a report, in render order, each with the anchors it binds.
+ * `page.header`/`page.footer` and `empty` are deliberately absent: outside
+ * v0.1's editable surface (they are invisible in an html-rendered preview).
+ *
+ * @type {(schema: any) => { path: string, role: string, label: string,
+ *   binds: string[], table?: boolean }[]}
+ */
+export let bands = (schema) => {
+  let groups = groupsOf(schema);
+  /** @type {ReturnType<typeof bands>} */
+  let out = [{ path: "header", role: "report-header", label: "Report header", binds: [...ALWAYS] }];
+  groups.forEach((/** @type {any} */ group, /** @type {number} */ i) =>
+    out.push(groupBand(group, i, "header", bindsAt(groups, i))),
+  );
+  // The detail band is the only place `@` and `run` are bound, and every
+  // group handle is still in scope there.
+  out.push({
+    path: "detail",
+    role: "detail",
+    label: "Detail",
+    binds: [...ALWAYS, ...groupNamesOf(schema), "@", "run"],
+    table: isTable(schema),
+  });
+  for (let i = groups.length - 1; i >= 0; i--)
+    out.push(groupBand(groups[i], i, "footer", bindsAt(groups, i)));
+  out.push({ path: "footer", role: "report-footer", label: "Report footer", binds: [...ALWAYS] });
+  return out;
+};
+
+/** The items a band holds, or [] for a band that is absent or a table. */
+/** @type {(schema: any, bandPath: string) => any[]} */
+export let itemsIn = (schema, bandPath) => {
+  let value = resolve(schema, bandPath);
+  return Array.isArray(value) ? value : [];
+};
+
+/** Whether a compiled source's path is the node's own or sits under it. */
+/** @type {(at: string, path: string) => boolean} */
+let under = (at, path) => at === path || at.startsWith(path + ".");
+
+/**
+ * The anchors a node reads, unioned from the engine plan's per-source sets —
+ * `anchors` is `plan().anchors`, keyed by compiled-source path, so the node's
+ * own set is every entry at or under its path. The engine's answer, never a
+ * source scan: it compiled the cell, so it knows.
+ *
+ * @type {(anchors: Record<string, readonly string[]>, path: string) => Set<string>}
+ */
+export let anchorsReadBy = (anchors, path) => {
+  let out = new Set();
+  for (let [at, names] of Object.entries(anchors))
+    if (under(at, path)) for (let name of names) out.add(name);
+  return out;
+};
+
+/** The two slots an item already occupies — offering them reads as a no-op. */
+/** @type {(band: any, index: number, held: { band: string, at: number }) => boolean} */
+let ownSlot = (band, index, held) =>
+  band.path === held.band && (index === held.at || index === held.at + 1);
+
+/** Every insertion point one band offers the item, with its verdict. */
+/** @type {(schema: any, band: any, reads: Set<string>,
+ *   held: { band: string, at: number }) => ReturnType<typeof legalSlots>} */
+let slotsOf = (schema, band, reads, held) => {
+  let blocked = [...reads].filter((anchor) => !band.binds.includes(anchor));
+  let count = itemsIn(schema, band.path).length;
+  /** @type {ReturnType<typeof legalSlots>} */
+  let out = [];
+  for (let index = 0; index <= count; index++)
+    if (!ownSlot(band, index, held))
+      out.push({ band: band.path, label: band.label, index, legal: !blocked.length, blocked });
+  return out;
+};
+
+/**
+ * Every slot the item at `path` may be dropped into, as insertion points:
+ * index 0 is before the band's first item, index n after its last. The item's
+ * own two adjacent slots are excluded — they are where it already is. A slot
+ * is refused (`legal: false`, with the anchors that block it) when the band
+ * does not bind everything the item reads; a table takes columns, never items.
+ *
+ * @type {(schema: any, anchors: Record<string, readonly string[]>, path: string)
+ *   => { band: string, label: string, index: number, legal: boolean, blocked: string[] }[]}
+ */
+export let legalSlots = (schema, anchors, path) => {
+  let reads = anchorsReadBy(anchors, path);
+  let held = { band: bandOfItem(path), at: indexOfItem(path) };
+  /** @type {ReturnType<typeof legalSlots>} */
+  let out = [];
+  for (let band of bands(schema)) if (!band.table) out.push(...slotsOf(schema, band, reads, held));
+  return out;
+};
+
+// --- item operations -------------------------------------------------------
+
+/** @type {(schema: any, bandPath: string) => any[]} */
+let bandArray = (next, bandPath) => {
+  // A drop or insert into an absent band is a creation, so the key appears;
+  // nothing else ever conjures or removes a band key.
+  let m = bandPath.match(/^groups\[(\d+)\]\.(header|footer)$/);
+  if (m) {
+    let group = next.groups[+m[1]];
+    group[m[2]] = Array.isArray(group[m[2]]) ? group[m[2]] : [];
+    return group[m[2]];
+  }
+  next[bandPath] = Array.isArray(next[bandPath]) ? next[bandPath] : [];
+  return next[bandPath];
+};
+
+/** Move the item at `path` into `slot` (`{ band, index }`). */
+/** @type {(schema: any, path: string, slot: { band: string, index: number }) => any} */
+export let moveItem = (schema, path, slot) => {
+  let next = structuredClone(schema);
+  let from = bandOfItem(path);
+  let at = indexOfItem(path);
+  let src = bandArray(next, from);
+  let [node] = src.splice(at, 1);
+  let dst = bandArray(next, slot.band);
+  // Removing from an earlier position in the same band shifts the target left.
+  let index = from === slot.band && at < slot.index ? slot.index - 1 : slot.index;
+  dst.splice(index, 0, node);
+  return next;
+};
+
+/**
+ * Insert a new text item — the one item kind whose required keys all have
+ * neutral defaults, which is the insertable-with-defaults rule that keeps
+ * images (expression-only source) out of the catalogue.
+ */
+/** @type {(schema: any, band: string, index: number) => any} */
+export let insertItem = (schema, band, index) => {
+  let next = structuredClone(schema);
+  bandArray(next, band).splice(index, 0, { type: "text", value: "" });
+  return next;
+};
+
+/** Remove the item at `path`. Removing the last item leaves `[]`. */
+/** @type {(schema: any, path: string) => any} */
+export let removeItem = (schema, path) => {
+  let next = structuredClone(schema);
+  bandArray(next, bandOfItem(path)).splice(indexOfItem(path), 1);
+  return next;
+};
+
+/** Duplicate the item at `path`, the copy landing right after it. */
+/** @type {(schema: any, path: string) => any} */
+export let duplicateItem = (schema, path) => {
+  let next = structuredClone(schema);
+  let list = bandArray(next, bandOfItem(path));
+  let at = indexOfItem(path);
+  list.splice(at + 1, 0, structuredClone(list[at]));
+  return next;
+};
+
+// --- column operations ------------------------------------------------------
+//
+// Every column operation mirrors `detail.total` silently: it is index-aligned
+// to `columns`, so a move, insert, remove or duplicate that touched one and
+// not the other would silently misalign the totals row.
+
+/** @type {(next: any, run: (list: any[]) => void) => void} */
+let mirrorTotal = (next, run) => {
+  run(next.detail.columns);
+  if (Array.isArray(next.detail.total)) run(next.detail.total);
+};
+
+// The engine's own invariant (SCHEMA.md, "Table detail"): sized widths total
+// at most 100 when every column is sized, and strictly under 100 otherwise,
+// leaving the width-less columns room. `LIMIT` is what breaks it; `TARGET` is
+// what a rescale aims at — an equal average share for the columns that have
+// no width. They differ on purpose: widths that are already legal are never
+// touched, which is the whole of "only when that breaks the sum invariant".
+/** @type {(sized: number, columns: number) => number} */
+let limit = (sized, columns) => (sized === columns ? 100 : 100 - WIDTH_EPS);
+/** @type {(sized: number, columns: number) => number} */
+let target = (sized, columns) => (sized === columns ? 100 : (100 * sized) / columns);
+
+/** The engine's own tolerance, restated: widths an author wrote as thirds
+ * must not fail on IEEE 754 alone. */
+let WIDTH_EPS = 1e-9;
+
+/**
+ * Scale authored widths down proportionally when an added column breaks the
+ * sum invariant — the one operation where the editor edits nodes the author
+ * did not touch. The invariant is the engine's: sized widths total at most
+ * 100 when every column is sized, and under 100 (leaving room) otherwise.
+ * The allowance leaves each width-less column an equal average share.
+ */
+/** @type {(columns: any[]) => void} */
+let fitWidths = (columns) => {
+  let sized = columns.filter((column) => column.width != null);
+  let total = sized.reduce((all, column) => all + column.width, 0);
+  if (total <= limit(sized.length, columns.length)) return;
+  let allowed = target(sized.length, columns.length);
+  for (let column of sized) column.width = (column.width * allowed) / total;
+};
+
+/** Move the column at index `at` to insertion point `to`. */
+/** @type {(schema: any, at: number, to: number) => any} */
+export let moveColumn = (schema, at, to) => {
+  let next = structuredClone(schema);
+  let index = at < to ? to - 1 : to;
+  mirrorTotal(next, (list) => list.splice(index, 0, list.splice(at, 1)[0]));
+  return next;
+};
+
+/** Insert a new column (and its empty total cell) at insertion point `index`. */
+/** @type {(schema: any, index: number) => any} */
+export let insertColumn = (schema, index) => {
+  let next = structuredClone(schema);
+  next.detail.columns.splice(index, 0, { header: "", value: "" });
+  if (Array.isArray(next.detail.total)) next.detail.total.splice(index, 0, { value: "" });
+  fitWidths(next.detail.columns);
+  return next;
+};
+
+/** Remove the column at `index` — never the last: `columns` is non-empty. */
+/** @type {(schema: any, index: number) => any} */
+export let removeColumn = (schema, index) => {
+  if (schema.detail.columns.length <= 1) return schema;
+  let next = structuredClone(schema);
+  mirrorTotal(next, (list) => list.splice(index, 1));
+  return next;
+};
+
+/** Duplicate the column at `index` (and its total cell), landing after it. */
+/** @type {(schema: any, index: number) => any} */
+export let duplicateColumn = (schema, index) => {
+  let next = structuredClone(schema);
+  mirrorTotal(next, (list) => list.splice(index + 1, 0, structuredClone(list[index])));
+  fitWidths(next.detail.columns);
+  return next;
+};
+
+// --- group operations -------------------------------------------------------
+
+/** Move the group at index `at` to insertion point `to` — renesting. */
+/** @type {(schema: any, at: number, to: number) => any} */
+export let moveGroup = (schema, at, to) => {
+  let next = structuredClone(schema);
+  let index = at < to ? to - 1 : to;
+  next.groups.splice(index, 0, next.groups.splice(at, 1)[0]);
+  return next;
+};
+
+/** Items worth keeping — an absent or empty band splices nothing. */
+/** @type {(band: any) => boolean} */
+let carries = (band) => Array.isArray(band) && band.length > 0;
+
+/** Lift a removed group's items into the enclosing bands: its header items
+ * append to that header, its footer items prepend to that footer. */
+/** @type {(next: any, group: any, parent: string) => void} */
+let splice = (next, group, parent) => {
+  if (carries(group.header)) bandArray(next, parent + "header").push(...group.header);
+  if (carries(group.footer)) bandArray(next, parent + "footer").unshift(...group.footer);
+};
+
+/**
+ * Remove the group at `index`. `"discard"` takes its bands with it;
+ * `"splice"` keeps their items — the header items append to the enclosing
+ * band's header (the next-outer group's, or the report's), the footer items
+ * prepend to the enclosing footer — so flattening a level loses nothing.
+ */
+/** @type {(schema: any, index: number, mode: "discard" | "splice") => any} */
+export let removeGroup = (schema, index, mode) => {
+  let next = structuredClone(schema);
+  let [group] = next.groups.splice(index, 1);
+  // The enclosing band is the next-outer group's, or the report's own.
+  if (mode === "splice") splice(next, group, index > 0 ? "groups[" + (index - 1) + "]." : "");
+  return next;
+};
+
+/** Add the group's header or footer band, empty. A no-op when it exists. */
+/** @type {(schema: any, index: number, which: "header" | "footer") => any} */
+export let addGroupBand = (schema, index, which) => {
+  if (schema.groups[index][which] != null) return schema;
+  let next = structuredClone(schema);
+  next.groups[index][which] = [];
+  return next;
+};
+
+/** Remove the group's header or footer band, contents and all — explicit. */
+/** @type {(schema: any, index: number, which: "header" | "footer") => any} */
+export let removeGroupBand = (schema, index, which) => {
+  let next = structuredClone(schema);
+  delete next.groups[index][which];
+  return next;
+};
+
+// --- what a path names -------------------------------------------------------
+
+/**
+ * The kind of node a selectable path names, deciding which properties panel
+ * it gets: a band item (`text` / `image` by its type), a table `column`, a
+ * `total` cell, a `group`, or the `table` itself.
+ */
+// The path shapes that name a kind outright, tried in order.
+let SHAPES = /** @type {[RegExp, string][]} */ ([
+  [/^groups\[\d+\]$/, "group"],
+  [/^detail\.columns\[\d+\]$/, "column"],
+  [/^detail\.total\[\d+\]$/, "total"],
+]);
+
+/** @type {(path: string) => string | null} */
+let shapeKind = (path) => {
+  for (let [shape, kind] of SHAPES) if (shape.test(path)) return kind;
+  return null;
+};
+
+/** A band item, by the `type` it declares. */
+/** @type {(schema: any, path: string) => string | null} */
+let itemKind = (schema, path) => {
+  let node = resolve(schema, path);
+  if (!node || !/\[\d+\]$/.test(path)) return null;
+  return node.type === "image" ? "image" : "text";
+};
+
+/** @type {(schema: any, path: string) => string | null} */
+export let nodeKindAt = (schema, path) => {
+  if (path === "detail") return isTable(schema) ? "table" : null;
+  return shapeKind(path) ?? itemKind(schema, path);
+};
+
+/** The group a path sits inside, when the path is not that group itself. */
+/** @type {(path: string) => string | null} */
+let enclosingGroup = (path) => {
+  let group = path.match(/^(groups\[\d+\])/);
+  return group && group[1] !== path ? group[1] : null;
+};
+
+/**
+ * The selectable ancestors of a path, outermost first, self last — the
+ * breadcrumb, which is how a container the pointer cannot hit is reached.
+ */
+/** @type {(schema: any, path: string) => string[]} */
+export let crumbsOf = (schema, path) => {
+  let out = [];
+  let group = enclosingGroup(path);
+  if (group) out.push(group);
+  if (path.startsWith("detail.") && isTable(schema)) out.push("detail");
+  out.push(path);
+  return out;
+};
+
+// --- the properties panel's field policy ------------------------------------
+
+// Four kinds decide every control: literal-only, always a template, always an
+// expression, and literal-or-expression — only the fourth gets the fx toggle,
+// because only it has a literal form to swap back to. `name` and `type` are
+// read-only (a group handle is read from arbitrary templates with no declared
+// back-references; a type change to image needs an expression-only source).
+let KINDS = /** @type {Record<string, string>} */ ({
+  value: "template",
+  header: "template",
+  alt: "template",
+  by: "expression",
+  source: "expression",
+  visible: "dual",
+  width: "literal",
+  fit: "literal",
+  take: "literal",
+  break: "literal",
+  reset: "literal",
+  columns: "literal",
+  name: "readonly",
+  type: "readonly",
+});
+
+/** @type {(key: string) => string} */
+export let fieldKind = (key) => KINDS[key] ?? "dual";
+
+/** The keys a node kind must keep: clearing one writes "" instead. A column
+ * requires its `header` as much as its `value` (SCHEMA.md, "Table detail"),
+ * and the shorthand string form is still that key. */
+let REQUIRED = new Set(["value", "by", "source", "type", "name", "header"]);
+
+/** @type {(node: any, key: string, value: any) => void} */
+let writeKey = (node, key, value) => {
+  if (value === undefined || value === "") {
+    // Touch only the key you edited: an optional key clears away, a required
+    // one writes "" — a forced `color: ""` would be a definition error, but
+    // an absent `value` is one too, and "" keeps the fault visible where the
+    // author is looking.
+    if (REQUIRED.has(key)) node[key] = "";
+    else delete node[key];
+    return;
+  }
+  node[key] = value;
+};
+
+/** Clear one style declaration, and the block itself once it holds nothing. */
+/** @type {(node: any, name: string) => void} */
+let clearStyle = (node, name) => {
+  if (!node.style) return;
+  delete node.style[name];
+  if (!Object.keys(node.style).length) delete node.style;
+};
+
+/** Write one style declaration; an existing one updates in place, so
+ * declaration order survives, and a new one appends. */
+/** @type {(node: any, name: string, value: any) => void} */
+let writeStyle = (node, name, value) => {
+  if (value === undefined || value === "") return clearStyle(node, name);
+  node.style = node.style ?? {};
+  node.style[name] = value;
+};
+
+/**
+ * Write one field of the node at `path`. `key` may be a plain key or
+ * `style.<name>`; style declaration order is never rewritten — an existing
+ * declaration updates in place, a new one appends.
+ */
+/** @type {(schema: any, path: string, key: string, value: any) => any} */
+export let writeField = (schema, path, key, value) => {
+  let next = structuredClone(schema);
+  let node = resolve(next, path);
+  let style = key.match(/^style\.(.+)$/);
+  // A column header widens for style and never narrows: `{ value: "Product" }`
+  // is a legal resting state, so a shorthand widens only when style arrives.
+  if (style) writeStyle(node, style[1], value);
+  else writeKey(node, key, value);
+  return next;
+};
+
+/** Widen a shorthand string column header to its object form, for style. */
+/** @type {(schema: any, columnPath: string) => any} */
+export let widenHeader = (schema, columnPath) => {
+  let next = structuredClone(schema);
+  let column = resolve(next, columnPath);
+  if (typeof column.header === "string") column.header = { value: column.header };
+  return next;
+};
+
+// --- placeholders: what the render leaves out --------------------------------
+
+/** What a hidden item's placeholder shows: the template the author wrote. */
+/** @type {(item: any) => string} */
+let sourceOf = (item) => (typeof item?.value === "string" ? item.value : "");
+
+/** One band's placeholders: its own when it is empty, else its hidden items. */
+/** @type {(band: any, items: any[], rendered: Set<string>, out: any[]) => void} */
+let bandPlaceholders = (band, items, rendered, out) => {
+  if (!items.length) return void out.push({ kind: "band", path: band.path });
+  items.forEach((/** @type {any} */ item, /** @type {number} */ i) => {
+    let path = band.path + "[" + i + "]";
+    if (!rendered.has(path)) out.push({ kind: "item", path, source: sourceOf(item) });
+  });
+};
+
+/**
+ * Given the schema and the set of paths that produced output (every
+ * `data-q-path` in the fragment), the placeholders in document order. Two
+ * meanings, one affordance: an empty band's placeholder is an insertion point
+ * and drop target, never a selection (a band has no keys); a hidden item's is
+ * a real selectable node carrying its template source, so several hidden
+ * items are distinguishable. Only v0.1's editable surface: `detail.row`,
+ * `empty` and the page bands are unaffected, and an absent band is not in the
+ * document, so it gets nothing.
+ *
+ * @type {(schema: any, rendered: Set<string>) => (
+ *   { kind: "band", path: string } |
+ *   { kind: "item", path: string, source: string })[]}
+ */
+export let placeholders = (schema, rendered) => {
+  /** @type {ReturnType<typeof placeholders>} */
+  let out = [];
+  for (let band of bands(schema)) {
+    let items = resolve(schema, band.path);
+    if (!band.table && Array.isArray(items)) bandPlaceholders(band, items, rendered, out);
+  }
+  return out;
+};
+
+// --- host mistakes -----------------------------------------------------------
+//
+// The check messages, folded into the pure surface rather than kept as a
+// separate check.js the way the viewer's is. Same discipline: every failure
+// names the property, and an invalid property keeps the last good values.
+
+/** @type {(message: string) => never} */
+let refuse = (message) => {
+  throw new TypeError("quario-editor: " + message);
+};
+
+/** @type {(value: any) => boolean} */
+let isObject = (value) => !!value && typeof value === "object";
+/** @type {(value: any) => boolean} */
+let record = (value) => isObject(value) && !Array.isArray(value);
+
+/** @type {(value: any) => any} */
+export let checkSchema = (value) => {
+  if (value !== undefined && !record(value)) refuse("schema: expected a report document object");
+  return value;
+};
+
+/** @type {(value: any) => any} */
+export let checkInstance = (value) => {
+  if (value !== undefined && !(record(value) && typeof value.plan === "function"))
+    refuse("instance: expected a quario instance (its plan() is the editor's loop)");
+  return value;
+};
+
+// Named, not duck-typed: a pdf target would compile happily and resolve bytes
+// the editor would then try to put in the DOM, failing far from the mistake —
+// so the wrong target is named here, where the mistake is.
+/** @type {(value: any) => void} */
+let checkHtml = (value) => {
+  if (!record(value) || typeof value.compile !== "function")
+    refuse("target: expected the html target from @quario/html");
+  if (value.name !== "html") refuse('target: expected the "html" target, got "' + value.name + '"');
+};
+
+/** @type {(value: any) => any} */
+export let checkTarget = (value) => {
+  if (value !== undefined) checkHtml(value);
+  return value;
+};
+
+/** @type {(value: any) => any} */
+export let checkFunctions = (value) => {
+  if (value !== undefined && !record(value)) refuse("functions: expected a record of functions");
+  return value;
+};
+
+// The same sheet vocabulary the viewer's `page` takes (the pdf target's page
+// sizes), purely visual: sheet width and padding. Restated rather than
+// imported, because the editor depends on no sibling package.
+let SIZES = /** @type {Record<string, [number, number]>} */ ({
+  A4: [595.28, 841.89],
+  letter: [612, 792],
+});
+
+/** The default margin, in points (0.75in) — the viewer's, restated. */
+let MARGIN = 54;
+
+/** A `[width, height]` pair the host wrote itself. */
+/** @type {(size: any) => boolean} */
+let isPair = (size) => Array.isArray(size) && size.length === 2 && size.every(Number.isFinite);
+/** One of the named sizes, from the closed set. */
+/** @type {(size: any) => boolean} */
+let isNamed = (size) => typeof size === "string" && Object.hasOwn(SIZES, size);
+
+/** @type {(size?: any) => [number, number] | null} */
+let sizeOf = (size = "A4") => {
+  if (isPair(size)) return /** @type {[number, number]} */ ([...size]);
+  return isNamed(size) ? SIZES[size] : null;
+};
+
+/** A margin has to leave the sheet room on both sides of its shorter edge. */
+/** @type {(margin: any, box: [number, number]) => boolean} */
+let fitsSheet = (margin, box) =>
+  Number.isFinite(margin) && margin >= 0 && margin * 2 < Math.min(box[0], box[1]);
+
+/** @type {(margin: any, box: [number, number]) => number} */
+let marginOf = (margin, box) => {
+  let used = margin === undefined ? MARGIN : margin;
+  if (!fitsSheet(used, box)) refuse("page.margin: expected a margin leaving room on the sheet");
+  return used;
+};
+
+/** @type {(value: any) => { width: number, height: number, margin: number }} */
+export let checkPage = (value) => {
+  if (value === undefined) return { width: SIZES.A4[0], height: SIZES.A4[1], margin: MARGIN };
+  if (!isObject(value)) refuse("page: expected a page geometry object");
+  let box = sizeOf(value.size);
+  if (!box) refuse('page.size: expected "A4", "letter", or [width, height] points');
+  return { width: box[0], height: box[1], margin: marginOf(value.margin, box) };
+};
+
+let SCHEME = /** @type {Record<string, string>} */ ({
+  light: "light",
+  dark: "dark",
+  auto: "light dark",
+});
+
+/** @type {(value: any) => string} */
+export let checkScheme = (value) => {
+  if (value === undefined) return "light";
+  if (typeof value !== "string" || !Object.hasOwn(SCHEME, value))
+    refuse('colorScheme: expected "light", "dark", or "auto"');
+  return SCHEME[value];
+};