@heycys/gallery 0.0.0-stage → 0.1.1

package/browser/editor/page/overlay-layer.mjs

@@ -0,0 +1,227 @@
+import { Z } from "../../shared/layers.mjs";
+import { UNIT, unitElement, withLeads } from "./core.mjs";
+import { frameNumber, inFrame } from "./frames.mjs";
+import { clipOf, fillExtentOf } from "./geometry.mjs";
+import { provide } from "./overlays.mjs";
+import { addStyle, element } from "./ui.mjs";
+
+// Where the editor draws over the report's blocks (docs/editor.md, "Overlays"): a selected block's
+// fill, the dashed frame of the text being edited, the handle and a section's bar, a drag's line
+// and tint. Each goes into the layer of the coordinate system its block moves in:
+//
+//   page      the document's own scrolling (a block in the report's flow): a layer at the
+//             document's origin (absolute, in the body), so scrolling the page moves the drawing
+//             with its block natively, without waiting for a frame;
+//   viewport  the window (a block that is fixed or sticky, or inside one: a table's sticky header
+//             cell): a fixed layer;
+//   dialog    the open modal dialog holding the block (it is in the top layer, where nothing of
+//             the body shows): a fixed layer inside that dialog, never inside another one.
+//
+// Positions are measured against the layer's own rectangle, never worked out from scrollX/scrollY,
+// so they hold whatever the layer's containing block. A box of the page that scrolls by itself (a
+// dialog's content, a table wider than its frame, a code block's frame) moves its blocks without
+// the layer: the frames that keep the drawings on their blocks put them back (frames.mjs, the same
+// frame as the scroll). A block is measured once per frame (shapeOf): its fill, its frame and its
+// handle drawn in one frame use the same numbers, kept relative to the layer, which scrolling the
+// page leaves as they are; outside the frames (a selection made, a block converted) it is measured
+// afresh.
+
+const STYLE = `
+  .ge-layer { left: 0; top: 0; width: 0; height: 0; overflow: visible; pointer-events: none; z-index: ${Z.layer}; }
+  .ge-layer[data-context="page"] { position: absolute; }
+  .ge-layer[data-context="viewport"], .ge-layer[data-context="dialog"] { position: fixed; }
+  /* Whatever the tools put in a layer stands where they say; those that declared a position of their own (a relative box) would not, and the layer cannot know which rule a tool wrote them with: !important keeps it one rule. */
+  .ge-layer > * { position: absolute !important; }
+  .ge-layer > .ge-handle, .ge-layer > .ge-section-bar { pointer-events: auto; }
+`;
+
+// The coordinate system a block moves in, and the element its layer goes into.
+function contextOf(target) {
+  const dialog = target.closest("dialog[open]");
+  if (dialog?.matches(":modal")) return { kind: "dialog", host: dialog };
+  for (let node = target; node && node !== document.body && node !== document.documentElement; node = node.parentElement) {
+    const { position } = getComputedStyle(node);
+    if (position === "fixed" || position === "sticky") return { kind: "viewport", host: document.body };
+  }
+  return { kind: "page", host: document.body };
+}
+
+/** The layer the editor draws in over `target` (made when first needed). */
+export function layerOf(target) {
+  addStyle(STYLE);
+  const { kind, host } = contextOf(target);
+  let layer = [...host.children].find((child) => child.classList.contains("ge-layer") && child.dataset.context === kind);
+  if (!layer) {
+    layer = element("div", { class: "ge-layer", "data-context": kind, "data-doc-dev": "" });
+    host.append(layer);
+  }
+  return layer;
+}
+
+const shapes = new WeakMap(); // block -> { at: the frame measured in, shape }
+
+/**
+ * Where `target` shows, as the editor draws over it: { layer, origin: the layer's corner in the
+ * window, rect and clip relative to the layer, radius: its corners, reach: how far its fill reaches
+ * when it says so, room: how far it may reach above and below it (roomOf, measured when first read:
+ * only a selected block's fill and the frame of what is edited read it, so the handle, the flags and
+ * the others never measure the neighbours) }, or null when it does not show. Measured once per
+ * frame; outside the frames, afresh.
+ */
+export function shapeOf(target) {
+  const at = inFrame() ? frameNumber() : -1;
+  const cached = shapes.get(target);
+  if (at >= 0 && cached?.at === at) return cached.shape;
+  const box = fillExtentOf(target);
+  let shape = null;
+  if (box) {
+    const layer = layerOf(target);
+    const origin = layer.getBoundingClientRect();
+    const relative = (rect) => rect && { left: rect.left - origin.left, top: rect.top - origin.top, right: rect.right - origin.left, bottom: rect.bottom - origin.top };
+    let room = null;
+    shape = {
+      layer, origin: { left: origin.left, top: origin.top }, rect: relative(box), clip: relative(clipOf(target)), radius: boxRadius(target), reach: boxReach(target),
+      get room() { return (room ??= roomOf(target, box)); },
+    };
+  }
+  if (at >= 0) shapes.set(target, { at, shape });
+  return shape;
+}
+
+/**
+ * How far what the editor draws over a block reaches past it (a selected block's fill, the frame
+ * of what is being edited), as Notion's fill: a block of its own rounded box (a code block, a
+ * highlight block, a card) 6px, or what the block says (`reach`: a file's row 4px, as notion-lite's;
+ * a callout's square box 6px), its corners its own and that much more, so the two are concentric; a
+ * block of text 2px, 4px round. `radius`: the block's (boxRadius). Above and below it, never more
+ * than its `room` (roomOf): two neighbours' fills, however close the blocks stand (disclosures and
+ * code blocks 8px apart, list items 5px), never overlap; where the room is less, a block of its own
+ * box reaches that much less at its sides too and its corners are round by that much less (the fill
+ * as even around it as its box is: never wide at the sides and narrow above and below, never an
+ * ellipse); a block of text keeps its 2px at its sides. { x: at its sides, y: its own reach, top,
+ * bottom: above and below it, the same, radius, corners: null }.
+ */
+export const reachOf = (radius, reach = null, room = null) => {
+  const text = radius <= 0 && reach === null;
+  const out = text ? 2 : reach ?? 6;
+  // The same above and below, the smaller room of the two: a block's fill is even, so in a run of
+  // blocks the first and the last look as the ones between (not wider toward the text around them).
+  const top = Math.min(out, room?.above ?? out, room?.below ?? out);
+  const bottom = top;
+  if (text) return { x: out, y: out, top, bottom, radius: 4, corners: null };
+  // A box filled evenly on every side: where its room keeps the fill closer above and below, it is as
+  // close at the sides (3px all round for disclosures 8px apart, not 6 at the sides and 3 above), and its
+  // corners are the block's own and that reach (a circle, as the block's).
+  return { x: top, y: out, top, bottom, radius: Math.max(0, radius) + top, corners: null };
+};
+
+/**
+ * How far a block's fill may reach above and below it ({ above, below }, Infinity where nothing
+ * limits it; reachOf takes the smaller of the two for both sides), one rule for every kind of block: half the gap to the block next to it that way
+ * (neighbourOf) with a pixel left between them ((gap - 1) / 2, rounded down), or what that block's
+ * own reach leaves of the gap less a pixel when that is more (a disclosure 12px under a paragraph,
+ * whose fill reaches 2px, keeps its 6px), so two neighbours' fills never overlap: they keep a
+ * hairline apart, or just meet where the blocks touch. `box`: its fillExtentOf.
+ */
+export function roomOf(target, box = fillExtentOf(target)) {
+  if (!box) return null;
+  const room = (neighbour, gap) => {
+    if (!neighbour) return Infinity;
+    const { x: reach } = reachOf(boxRadius(neighbour.unit), boxReach(neighbour.unit)); // its own, on every side
+    return Math.max(0, Math.floor((gap - 1) / 2), Math.floor(gap - 1 - reach));
+  };
+  const above = neighbourOf(target, box, false);
+  const below = neighbourOf(target, box, true);
+  return { above: room(above, above && box.top - above.rect.bottom), below: room(below, below && below.rect.top - box.bottom) };
+}
+
+// The block next to `target` above it (`forward`: below it) and where it shows (fillExtentOf),
+// { unit, rect }, or null: the nearest unit of its container that way that shows and stands over or
+// under it (a column beside it, a step of a flowchart's row, does not); none, its container's (a
+// disclosure's first block: the block before the disclosure). Any of them may be filled with it (a
+// selection, the blocks a text selection takes whole), so its fill keeps clear of all of them.
+function neighbourOf(target, box, forward) {
+  for (let at = target; at; at = at.parentElement?.closest(UNIT) ?? null) {
+    for (let next = forward ? at.nextElementSibling : withLeads(at)[0].previousElementSibling; next; next = forward ? next.nextElementSibling : next.previousElementSibling) {
+      const unit = unitElement(next);
+      if (!unit || unit === at || unit.parentElement !== at.parentElement) continue;
+      const rect = fillExtentOf(unit);
+      if (rect && rect.right > box.left && rect.left < box.right) return { unit, rect };
+    }
+  }
+  return null;
+}
+
+/** Where a block's fill lies (client coordinates): its fillExtentOf and its reach past it (reachOf, roomOf), or null. */
+export function fillRectOf(target) {
+  const box = fillExtentOf(target);
+  if (!box) return null;
+  const { x, top, bottom } = reachOf(boxRadius(target), boxReach(target), roomOf(target, box));
+  return { left: box.left - x, top: box.top - top, right: box.right + x, bottom: box.bottom + bottom };
+}
+
+/** How far a boxed block's fill reaches past it when it says so (--doc-box-reach; a square box too, a callout's), else null. */
+export function boxReach(element) {
+  const declared = parseFloat(getComputedStyle(element).getPropertyValue("--doc-box-reach"));
+  return declared > 0 ? declared : null;
+}
+
+/**
+ * The corner radius of a block that shows a box of its own (a background or a border: a code
+ * block, a highlight block, a card), else 0 (text, however its element is rounded: a paragraph or
+ * heading given a background color too, whose fill the kit lays where a text block's selection is).
+ * The editor's own tints over a block (a formula block's under the pointer or while its box is open)
+ * are inset shadows, never its background, so they never count: a block's fill is the same
+ * whatever the pointer does.
+ */
+export function boxRadius(element) {
+  const style = getComputedStyle(element);
+  // A block whose box is drawn inside it (a file's row, a bookmark's card, an embed's frame), a list
+  // item drawn as a box (a flowchart's step) or a list drawn as its items' boxes (a flowchart, whose
+  // fill has its cards' corners: styles/flowchart.css), says so.
+  const declared = parseFloat(style.getPropertyValue("--doc-box-radius"));
+  if (declared > 0) return declared;
+  if (/^(P|H[1-4]|LI|HR)$/.test(element.tagName)) return 0; // a divider is a line, no box either
+  const radius = parseFloat(style.borderTopLeftRadius) || 0;
+  if (radius === 0) return 0;
+  const painted = !/^(transparent|rgba\(0, 0, 0, 0\))$/.test(style.backgroundColor) || style.backgroundImage !== "none";
+  const bordered = ["Top", "Right", "Bottom", "Left"].some((side) => parseFloat(style[`border${side}Width`]) > 0 && style[`border${side}Style`] !== "none");
+  return painted || bordered ? radius : 0;
+}
+
+/**
+ * Lay `node` over a block measured as `shape` (shapeOf): `x` past it at its sides, `above` and
+ * `below` it (`y` both, unless said), with corners of `radius` (or `corners`, a border-radius: reachOf's),
+ * cut where the block is cut. Each edge is rounded on its own, so two drawings kept apart stay apart.
+ */
+export function drawOver(node, { layer, rect, clip }, { x, y, top: above = y, bottom: below = y, radius, corners = null }) {
+  if (node.parentNode !== layer) layer.append(node);
+  const left = Math.round(rect.left - x);
+  const top = Math.round(rect.top - above);
+  const width = Math.round(rect.right + x) - left;
+  const height = Math.round(rect.bottom + below) - top;
+  const cut = clip && [clip.top - top, left + width - clip.right, top + height - clip.bottom, clip.left - left].map((side) => `${Math.max(0, Math.round(side))}px`).join(" ");
+  Object.assign(node.style, {
+    transform: `translate(${left}px, ${top}px)`, width: `${width}px`, height: `${height}px`, borderRadius: corners ?? `${radius}px`,
+    clipPath: cut && cut !== "0px 0px 0px 0px" ? `inset(${cut})` : "",
+  });
+}
+
+/** Put `node` in `layer` at `left`, `top` (relative to the layer). */
+export function drawAt(node, layer, left, top) {
+  if (node.parentNode !== layer) layer.append(node);
+  node.style.transform = `translate(${Math.round(left)}px, ${Math.round(top)}px)`;
+}
+
+/** Lay `node` in `layer` over `rect` (window coordinates), `outset` past it. */
+export function drawBox(node, layer, rect, outset = 0) {
+  if (node.parentNode !== layer) layer.append(node);
+  const origin = layer.getBoundingClientRect();
+  Object.assign(node.style, {
+    transform: `translate(${Math.round(rect.left - origin.left - outset)}px, ${Math.round(rect.top - origin.top - outset)}px)`,
+    width: `${Math.round(rect.right - rect.left + 2 * outset)}px`,
+    height: `${Math.round(rect.bottom - rect.top + 2 * outset)}px`,
+  });
+}
+
+provide("layers", () => [...document.querySelectorAll(".ge-layer")].map((layer) => ({ context: layer.dataset.context, in: layer.parentElement?.localName ?? null, drawings: layer.children.length })));

package/browser/editor/page/overlays.mjs

@@ -0,0 +1,205 @@
+// What the editor draws over the page (docs/editor.md, "Overlays"): a selected block's fill, the
+// handle and a section's bar, the dashed frame of the text being edited, a drag's line, tint and
+// the blocks' faded copy, a box selection, a resize's lines. Each such node is registered with what it stands for
+// (own: a block, or the gesture it belongs to) and a test of whether it still does (alive). The
+// editor's frames audit them against that: one standing for nothing (a block no longer selected or
+// on the page, a gesture over) is a bug, said once with what led to it, and the node goes, so no
+// overlay is ever left behind on the screen. window.__galleryOverlays() describes them all, with
+// their owners, where each is against where it should be, the frames and the recent events: what
+// to look at (and copy) when something drawn looks wrong.
+
+// own() marks each overlay node with this attribute: the audit and the snapshot go through the marked
+// nodes on the page, so whatever is registered is audited, whoever draws it. The audit keeps the
+// marked nodes it found (and those marked since) and goes through them: looking them up in the whole
+// page after every frame took 0.2ms a frame on a long report. It looks through the page again
+// whenever a node it does not hold may have come onto it (put in by anyone: a copy of an overlay, one
+// taken off and put back), which an observer of what is added says (`arrivals`).
+const MARK = "data-ge-overlay";
+
+const owners = new WeakMap(); // node -> { kind, owner, alive, expected }
+const owned = new Set(); // the marked nodes the audit goes through
+let unknown = true; // a node `owned` does not hold may be on the page: the next audit looks through it
+
+// Watched from an audit to the first node added that `owned` does not hold (or that holds a marked
+// node), then not until the next audit: nothing to pay for while the page is built or typed in. Made
+// at the first audit (this module is read without a page too: the unit tests).
+let arrivals = null;
+function arrived(records) {
+  for (const record of records) {
+    for (const node of record.addedNodes) {
+      if (node.nodeType === 1 && (!owned.has(node) || node.querySelector(`[${MARK}]`))) return true;
+    }
+  }
+  return false;
+}
+function stopWatching() {
+  unknown = true;
+  arrivals?.disconnect();
+}
+const settlers = new Set(); // what each part drops at once after a structural change
+const providers = new Map(); // name -> () => state, for the snapshot
+const events = []; // the last things that changed what is drawn: { t, type, detail }
+const said = new Map(); // scope -> { message, time }: errors said, not said again within 5s
+const errors = []; // the last errors said: { t, scope, message }
+let lastStray = "";
+
+/**
+ * Register `node` as an overlay of `kind` standing for `owner` (a block, or null for a gesture);
+ * alive(): whether it still stands for something (the block selected and on the page, the gesture
+ * under way); expected(): where it should be now (client coordinates), when that can be told.
+ */
+export function own(node, kind, { owner = null, alive = () => true, expected = null } = {}) {
+  owners.set(node, { kind, owner, alive, expected });
+  if (node.getAttribute(MARK) !== kind) node.setAttribute(MARK, kind); // the block tools own theirs again on every frame they draw
+  owned.add(node);
+  return node;
+}
+
+/**
+ * settle(): after a structural change (history.mjs: a change, undo, redo), at once, not on a later
+ * frame, each part drops what stands for something no longer on the page (the selection its gone
+ * blocks, the handle the block it stood beside, the frame the text it framed). onSettle(fn): a part's.
+ */
+export function onSettle(fn) {
+  settlers.add(fn);
+}
+
+export function settle() {
+  for (const fn of settlers) {
+    try {
+      fn();
+    } catch (error) {
+      report("settling after a change", error);
+    }
+  }
+}
+
+/** Something that changes what is drawn happened (selection, history, a gesture). */
+export function note(type, detail = "") {
+  events.push({ t: Math.round(performance.now()), type, detail: String(detail).slice(0, 160) });
+  if (events.length > 30) events.shift();
+}
+
+/** A part of the editor's state for the snapshot (the frames, the block tools). */
+export function provide(name, state) {
+  providers.set(name, state);
+}
+
+/**
+ * An error in drawing or in a gesture: said on the console (the same one at most every 5 seconds
+ * per scope, never on every frame) and kept for the snapshot.
+ */
+export function report(scope, error) {
+  const message = error?.message ?? String(error);
+  const now = performance.now();
+  const last = said.get(scope);
+  if (last && last.message === message && now - last.time < 5000) return;
+  said.set(scope, { message, time: now });
+  errors.push({ t: Math.round(now), scope, message });
+  if (errors.length > 10) errors.shift();
+  note("error", `${scope}: ${message}`);
+  console.error(`[gallery] ${scope} failed:`, error);
+}
+
+// A short description of a block or node: tag, id, the start of its text.
+export function describe(node) {
+  if (!node) return null;
+  if (!node.localName) return String(node);
+  const id = node.getAttribute?.("data-block-id");
+  const text = (node.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, 24);
+  return `${node.localName}${id ? `#${id}` : ""}${text ? ` "${text}"` : ""}`;
+}
+
+const rounded = (rect) => rect && { left: Math.round(rect.left), top: Math.round(rect.top), right: Math.round(rect.right), bottom: Math.round(rect.bottom) };
+
+// How far a node's rectangle is from where it should be (the largest difference of an edge), or null.
+function offBy(rect, expected) {
+  if (!rect || !expected) return null;
+  return Math.max(...["left", "top", "right", "bottom"].map((side) => Math.abs(rect[side] - expected[side])));
+}
+
+/** Everything drawn and what it stands for, the frames and the recent events (plain data). */
+export function snapshot() {
+  const overlays = [];
+  for (const node of document.querySelectorAll(`[${MARK}]`)) {
+    const entry = owners.get(node);
+    const rect = node.getBoundingClientRect();
+    const shown = !node.hidden && rect.width > 0 && rect.height > 0;
+    let expected = null;
+    try {
+      expected = entry?.expected?.() ?? null;
+    } catch {}
+    let alive = null;
+    try {
+      alive = entry ? Boolean(entry.alive()) : null;
+    } catch {}
+    overlays.push({
+      class: node.className,
+      kind: entry?.kind ?? null,
+      shown,
+      rect: rounded(rect),
+      owner: describe(entry?.owner),
+      ownerOnPage: entry?.owner ? Boolean(entry.owner.isConnected) : null,
+      alive,
+      expected: rounded(expected),
+      offBy: shown ? offBy(rect, expected) : null,
+    });
+  }
+  const state = {};
+  for (const [name, provider] of providers) {
+    try {
+      state[name] = provider();
+    } catch (error) {
+      state[name] = `unavailable: ${error.message}`;
+    }
+  }
+  return { time: Math.round(performance.now()), scroll: { x: Math.round(scrollX), y: Math.round(scrollY) }, overlays, ...state, errors: [...errors], events: [...events] };
+}
+
+/**
+ * The overlays standing for nothing, removed (a bug: said once, with the snapshot). Returns how
+ * many there were.
+ */
+export function audit() {
+  if (!unknown && arrived(arrivals.takeRecords())) stopWatching();
+  if (unknown) {
+    owned.clear();
+    for (const node of document.querySelectorAll(`[${MARK}]`)) owned.add(node);
+    unknown = false;
+    arrivals ??= new MutationObserver((records) => {
+      if (arrived(records)) stopWatching();
+    });
+    arrivals.observe(document.documentElement, { childList: true, subtree: true });
+  }
+  const strays = [...owned].filter((node) => {
+    // Off the page (what puts it back is an arrival), or no longer marked (annotate/ unmarks its
+    // markers as they fade out, standing for nothing): not the audit's.
+    if (!node.isConnected || !node.hasAttribute(MARK)) {
+      owned.delete(node);
+      return false;
+    }
+    const entry = owners.get(node);
+    try {
+      return !entry || !entry.alive();
+    } catch {
+      return true;
+    }
+  });
+  if (strays.length === 0) {
+    lastStray = "";
+    return 0;
+  }
+  const key = strays.map((node) => `${node.className}:${describe(owners.get(node)?.owner)}`).join(" | ");
+  if (key !== lastStray) {
+    lastStray = key;
+    note("stray", key);
+    console.error("[gallery] overlay standing for nothing (removed):", key, snapshot());
+  }
+  strays.forEach((node) => {
+    node.remove();
+    owned.delete(node);
+  });
+  return strays.length;
+}
+
+globalThis.__galleryOverlays = snapshot;

package/browser/editor/page/own.mjs

@@ -0,0 +1,28 @@
+import { isInkClass } from "./marks.mjs";
+import { TAB } from "../components/paragraph/index.mjs";
+
+// Inline elements of the report's own (docs/editor.md, "In-place text editing"): a phrasing element
+// the editor has no format for (a span with a class, style or attribute of the report's own: a
+// number badge in a heading, a citation in a cell; a cite, a small, an abbr…), and a format bar's tag
+// that carries attributes of its own and holds no words (a drawn arrow, <i class="arr-r"></i>). In a
+// text block it is an atom, as an inline formula is: shown and written back as the file has it, its
+// words not edited, the words around it editable. Judged from an element's tag, its attributes as the
+// file writes them and whether it holds words, so that the scanner's parse5 nodes (source/blocks.mjs)
+// and the page's elements (core.mjs) are judged alike. Not the editor's own: a text color or
+// highlight (the kit's classes alone), small text's end part, a formula, a link.
+
+const PHRASING = new Set([
+  "span", "abbr", "cite", "dfn", "small", "mark", "q", "time", "data", "bdi", "bdo", "kbd", "samp", "var",
+  "ins", "del", "strike", "font", "big", "tt", "nobr", "acronym",
+]);
+const FORMATS = new Set(["strong", "em", "b", "i", "u", "s", "code", "sup", "sub"]);
+
+/** `attributes`: [{ name, value }] as the file writes them; `words`: whether it holds any. */
+export function ownInline(tag, attributes, words) {
+  if (FORMATS.has(tag)) return attributes.length > 0 && !words;
+  if (!PHRASING.has(tag)) return false;
+  if (tag !== "span") return true;
+  const classes = attributes.length === 1 && attributes[0].name === "class" ? attributes[0].value.trim().split(/\s+/).filter(Boolean) : null;
+  if (classes?.length > 0 && (classes.every(isInkClass) || classes.join(" ") === TAB)) return false;
+  return !attributes.some(({ name, value }) => name === "class" && value.split(/\s+/).includes("doc-math-inline"));
+}

package/browser/editor/page/pads.mjs

@@ -0,0 +1,71 @@
+import { select } from "./caret.mjs";
+import { holdsNothing } from "./marks.mjs";
+import { ZWSP } from "../../shared/inline-spacing.mjs";
+
+// Zero-width pads: a text node holding nothing but a zero-width space where the browser would not
+// keep the caret, so that what is typed there lands on the side the reader chose: after a mark a
+// Markdown shortcut made (typed text would go into it, markdown/), outside after inline code or
+// inside at its start (typing/code-edges.mjs). Text typed into a pad stays there and the space
+// goes (settlePads); a pad the caret left empty goes. A text node holding nothing but the space is
+// never saved (core.mjs serializeNode).
+
+const pads = new Set();
+
+/** Whether `node` is a text node holding nothing but the zero-width space. */
+export const isPad = (node) => node?.nodeType === 3 && node.data === ZWSP;
+
+/**
+ * The caret in a pad `where` `node` is ("after" or "before" it, or "start": inside it, first),
+ * after its space; one already there is used again.
+ */
+export function padCaret(node, where) {
+  let pad = where === "start" ? node.firstChild : where === "after" ? node.nextSibling : node.previousSibling;
+  if (!isPad(pad)) {
+    pad = node.ownerDocument.createTextNode(ZWSP);
+    if (where === "start") node.prepend(pad);
+    else if (where === "after") node.after(pad);
+    else node.before(pad);
+  }
+  pads.add(pad);
+  const caret = node.ownerDocument.createRange();
+  caret.setStart(pad, 1);
+  caret.collapse(true);
+  select(caret);
+  return pad;
+}
+
+/**
+ * Text arrived in a pad: the space goes, the caret staying after the text. `left` (the selection
+ * moved): a pad still empty goes unless the caret is in it.
+ */
+export function settlePads(left = false) {
+  const selection = getSelection();
+  for (const pad of [...pads]) {
+    if (!pad.isConnected) {
+      pads.delete(pad);
+      continue;
+    }
+    const inside = selection.rangeCount > 0 && selection.anchorNode === pad;
+    if (pad.data === ZWSP) {
+      if (left && !inside) {
+        pads.delete(pad);
+        const parent = pad.parentElement;
+        pad.remove();
+        // Inline code that held nothing but the pad (its text deleted, the caret gone) goes too: it
+        // would stay drawn as an empty box.
+        if (parent?.tagName === "CODE" && holdsNothing(parent)) parent.remove();
+      }
+      continue;
+    }
+    pads.delete(pad);
+    const at = pad.data.indexOf(ZWSP);
+    if (at < 0) continue;
+    const offset = inside ? selection.anchorOffset : null;
+    pad.deleteData(at, 1);
+    if (offset !== null) {
+      const caret = pad.ownerDocument.createRange();
+      caret.setStart(pad, Math.max(0, offset - (offset > at ? 1 : 0)));
+      select(caret);
+    }
+  }
+}

package/browser/editor/page/page-objects.mjs

@@ -0,0 +1,105 @@
+import { HOST_COMPONENT, TYPE_COMPONENT, TYPE_INFO, UNIT_COMPONENT, canHaveChildren, ownerOf, textFilters } from "../components/registry.mjs";
+
+// The components' page objects (components/pages.mjs) for the engines that are handed no `ctx` of
+// their own: the editor gives them here once it has made them, and what a type needs of the page is
+// asked of its component.
+let pages = {};
+
+/** Hand the engines the page objects. */
+export function connectPages(given) {
+  pages = given;
+}
+
+/** Whether what happens on `node` is a component's own, the editor letting go of it (`keepsKeys`: its keys, the clipboard, a press that would draw a selection). `event`: the key, where one is asked about. */
+export const keptByComponent = (node, event = null) => pageObjects().some((page) => page.keepsKeys?.(node, event));
+
+/** The page object of the component a block type is of, if it has one. */
+export const pageOfType = (type) => pages[TYPE_COMPONENT[type]];
+
+/**
+ * A key of a menu of blocks (notion-lite's menuEntry): a type, or "type:variant", another entry of the
+ * type a page object says (`menuVariants`: { label, icon, words, preview?, sample?, create(what) },
+ * `sample` where the words a new one holds are there to be typed over): { type, variant (null when it
+ * names none, or none there is), named }.
+ */
+export function menuEntry(key) {
+  const [type, ...rest] = String(key).split(":");
+  const name = rest.join(":");
+  return { type, variant: name ? pageOfType(type)?.menuVariants?.()[name] ?? null : null, named: Boolean(name) };
+}
+
+/** The row of a key of a menu of blocks: its type's, or its variant's; null for neither. */
+export const menuRow = (key) => TYPE_INFO[key] ?? menuEntry(key).variant;
+
+/** The keys of every variant there is now. */
+export const variantKeys = () => Object.keys(TYPE_COMPONENT).flatMap((type) => Object.keys(pageOfType(type)?.menuVariants?.() ?? {}).map((name) => `${type}:${name}`));
+
+/** The page objects, in the order they are made. */
+export const pageObjects = () => Object.values(pages);
+
+/** The page object with an editor open over the page (`panel`), if any. */
+export const panelOpen = () => pageObjects().find((page) => page.panel) ?? null;
+
+/** The text field outside the page's text blocks being edited (`field`: a tab's name), or null. */
+export const fieldOpen = () => pageObjects().map((page) => page.field).find(Boolean) ?? null;
+
+/** What the block tools do with rows of columns (`columnOps`, notion-lite's), of whichever page object says, or null. */
+export const columnOps = () => pageObjects().find((page) => page.columnOps)?.columnOps ?? null;
+
+/** What the block tools do with sections (`sectionOps`), of whichever page object says, or null. */
+export const sectionOps = () => pageObjects().find((page) => page.sectionOps)?.sectionOps ?? null;
+
+/** What the gaps between blocks in a row resize (`rowOps`), of whichever page object says, or null. */
+export const rowOps = () => pageObjects().find((page) => page.rowOps)?.rowOps ?? null;
+
+// With no component that says `modalOps`, nothing stands over the page.
+const NO_MODALS = { open: () => [], listen() {}, closeTop: () => false, show: () => null, kept: () => [], reopen() {} };
+
+/** What stands open over the page as a modal (`modalOps`), of whichever page object says. */
+export const modalOps = () => pageObjects().find((page) => page.modalOps)?.modalOps ?? NO_MODALS;
+
+/** The page's own icon, as the page shows it (`pageIcon`), or null. */
+export const pageIcon = () => pageObjects().map((page) => page.pageIcon?.()).find(Boolean) ?? null;
+
+/** The page object of the component that defines a kind of text block. */
+export const pageOfHost = (kind) => pages[HOST_COMPONENT[kind]];
+
+/** The page object of the component a kind of unit is of, if it has one. */
+export const pageOfKind = (kind) => pages[UNIT_COMPONENT[kind]];
+
+/** The page object of the component a block is of, by the kind of unit it is (`menuItems`, `menu`), if it has one. */
+export const pageOfUnit = (unit) => pageOfKind(unit.getAttribute("data-ge-unit-kind"));
+
+/** The row of the block menu a page object has for a block of another component (`rowBeside`), the first that has one, or null. */
+export const rowBeside = (target) => pageObjects().map((page) => page.rowBeside?.(target)).find(Boolean) ?? null;
+
+/** The page object of the component a text block is of, or none (`keys`). */
+export const pageOf = (host) => pages[ownerOf(host)];
+
+/**
+ * What stands around a text block, nearest first, each once and its own component none of them: the
+ * block before it where that says `canHaveChildren`, then what it stands in, from where it stands out.
+ */
+export function pagesAround(host) {
+  const before = host.previousElementSibling;
+  const around = before && canHaveChildren(before) ? [before] : [];
+  for (let node = host.parentElement; node; node = node.parentElement) around.push(node);
+  const own = pageOf(host);
+  return [...new Set(around.map(pageOf))].filter((page) => page && page !== own);
+}
+
+/** The page object of what a press or a click came down on: of the component of the nearest element around it that is of one. */
+export function pageAt(target) {
+  for (let node = target; node?.nodeType === 1; node = node.parentElement) {
+    const owner = ownerOf(node);
+    if (owner) return pages[owner];
+  }
+  return undefined;
+}
+
+/** Text put in a text block that takes it as it is (`textFilters`), by its component's `type`. Whether it took it. */
+export function typedAsIs(host, text) {
+  const page = textFilters(host) ? null : pageOf(host);
+  page?.type?.(host, text);
+  return Boolean(page?.type);
+}