@heycys/gallery 0.0.0-stage → 0.1.0

package/browser/editor/page/frames.mjs

@@ -0,0 +1,196 @@
+import { audit, note, provide, report } from "./overlays.mjs";
+
+// The editor's one animation-frame loop (docs/editor.md, "Overlays"). What the editor draws over the
+// page follows it through tasks of this loop, never through loops of their own: the block tools
+// (fills, the handle, a drag), the dashed frame of the text being edited, a box selection scrolling
+// the page. One frame is requested at a time, however often tasks ask, from inside the loop too. A
+// task runs on the next frame after wake(), and what its run() returns says when it runs again:
+// true, on the next frame (a gesture under way: a drag, a box selection scrolling the page by the
+// window's edge); FOLLOW, when something may have moved what it drew over (it stands over blocks: the
+// handle, the fills, the frame of the text being edited, the flags); anything else, at its next
+// wake(). One that throws takes down what it draws (fail()), the error is said (overlays.mjs report:
+// not on every frame), and it waits for the next wake(): no stale picture stays. After the tasks,
+// the overlays are audited (overlays.mjs): none may stand for nothing. An event that may show a
+// stray (a scroll, a press, a key) asks for an audit too.
+//
+// The loop rests while nothing moves. Run on every frame while anything was drawn, it measured and
+// drew the same things again and again with the pointer resting on a paragraph (its handle shown) or
+// blocks selected: 60–160ms of the main thread a second, 115 frames a second, for a picture that did
+// not change. What may move a block, and so runs the followers again: the page changed (a mutation
+// anywhere but in the editor's own layers, overlay-layer.mjs, whose drawings move nothing), anything
+// scrolled (a box of the page that scrolls by itself, the page under what sticks to the window), the
+// window or the page resized, a transition or an animation under way (on every frame until it ends,
+// LONGEST at most when its end never comes), a picture or a frame loaded (or failing), fonts loaded, the pointer
+// onto another element (what :hover styles) or the focus moving (:focus-within), and any task woken
+// (the pointer moved, the selection changed). After each, the followers run on SETTLE frames more: a
+// layout the page's own frame callbacks change after the editor's (the kit's tables lay themselves
+// out in a frame), one the next frame finishes.
+
+/** What run() returns to run again whenever what it drew over may have moved (not on every frame). */
+export const FOLLOW = "follow";
+
+const SETTLE = 3; // frames the followers run on after the last thing that may have moved their blocks
+const LONGEST = 5000; // ms: a transition or animation whose end never comes (one that repeats for good) stops counting as moving
+
+const tasks = new Map(); // name -> { run, fail, wanted, follows }
+let frame = 0;
+let requested = 0; // frames requested and not yet run: never more than one
+let epoch = 0; // frames run
+let lastRun = 0;
+let auditWanted = false;
+let running = false; // a frame is being run
+let settling = 0; // frames the followers still run on without a new reason
+const moving = new Map(); // element -> { names: Set of transitions and animations under way on it, since }
+
+const follows = () => {
+  for (const task of tasks.values()) if (task.follows) return true;
+  return false;
+};
+
+function request() {
+  if (frame) return;
+  requested++;
+  frame = requestAnimationFrame(editorFrame);
+}
+
+// Transitions and animations under way, their elements still on the page and begun not too long ago.
+function stillMoving() {
+  if (moving.size === 0) return false;
+  const now = performance.now();
+  for (const [element, entry] of moving) if (!element.isConnected || now - entry.since > LONGEST) moving.delete(element);
+  return moving.size > 0;
+}
+
+function editorFrame() {
+  frame = 0;
+  requested--;
+  epoch++;
+  lastRun = performance.now();
+  // Something may have moved the blocks lately: the followers run on this frame.
+  if (settling > 0 || stillMoving()) {
+    settling = Math.max(0, settling - 1);
+    for (const task of tasks.values()) if (task.follows) task.wanted = true;
+  }
+  running = true;
+  let ran = false;
+  for (const [name, task] of tasks) {
+    if (!task.wanted) continue;
+    task.wanted = false;
+    ran = true;
+    try {
+      const next = task.run();
+      task.wanted = next === true;
+      task.follows = next === FOLLOW;
+    } catch (error) {
+      task.wanted = false;
+      task.follows = false;
+      try {
+        task.fail?.();
+      } catch (cleanup) {
+        report(`${name} (taking it down)`, cleanup);
+      }
+      report(name, error);
+    }
+  }
+  running = false;
+  if (auditWanted || ran) {
+    auditWanted = false;
+    try {
+      audit();
+    } catch (error) {
+      report("audit", error);
+    }
+  }
+  const following = follows();
+  watch(following);
+  if ([...tasks.values()].some((task) => task.wanted) || (following && (settling > 0 || moving.size > 0))) request();
+}
+
+/**
+ * A task of the loop: run() draws (returns true to run again on the next frame, FOLLOW to run again
+ * when what it drew over may have moved), fail() takes down what it draws. Returns { wake }: run it
+ * on the next frame.
+ */
+export function task(name, { run, fail }) {
+  const entry = { run, fail, wanted: false, follows: false };
+  tasks.set(name, entry);
+  return {
+    wake() {
+      entry.wanted = true;
+      settling = SETTLE;
+      request();
+    },
+  };
+}
+
+/** Audit the overlays on the next frame (an event that may have shown a stray). */
+function auditSoon() {
+  auditWanted = true;
+  request();
+}
+
+// Something that may have moved the blocks happened: the followers run on the next frames.
+function moved() {
+  settling = SETTLE;
+  if (follows()) request();
+}
+
+// The page's mutations, watched only while a task follows (none to pay for while the reader types
+// with nothing drawn): those inside the editor's layers are its own drawings, which move no block.
+const mutations = new MutationObserver((records) => {
+  for (const record of records) {
+    const node = record.target.nodeType === 1 ? record.target : record.target.parentElement;
+    if (!node?.closest(".ge-layer")) return moved();
+  }
+});
+let watching = false;
+function watch(on) {
+  if (on === watching) return;
+  watching = on;
+  if (on) mutations.observe(document.documentElement, { childList: true, subtree: true, attributes: true, characterData: true });
+  else mutations.disconnect();
+}
+const resizes = new ResizeObserver(() => moved());
+resizes.observe(document.documentElement);
+const main = document.querySelector("main");
+if (main) resizes.observe(main);
+for (const type of ["scroll", "resize", "pointerover", "focusin", "focusout"]) addEventListener(type, moved, { capture: true, passive: true });
+// A picture's or a frame's load never reaches the window (a load event's path ends at the document).
+for (const type of ["load", "error"]) document.addEventListener(type, moved, { capture: true, passive: true });
+document.fonts?.addEventListener("loadingdone", moved);
+// A transition or an animation begun goes on moving what it moves until it ends (or is cancelled).
+const began = (event) => {
+  if (!(event.target instanceof Element)) return;
+  let entry = moving.get(event.target);
+  if (!entry) moving.set(event.target, (entry = { names: new Set(), since: 0 }));
+  entry.names.add(event.propertyName ?? event.animationName);
+  entry.since = performance.now();
+  moved();
+};
+const ended = (event) => {
+  const entry = moving.get(event.target);
+  entry?.names.delete(event.propertyName ?? event.animationName);
+  if (entry?.names.size === 0) moving.delete(event.target);
+  moved();
+};
+for (const type of ["transitionrun", "animationstart"]) addEventListener(type, began, { capture: true, passive: true });
+for (const type of ["transitionend", "transitioncancel", "animationend", "animationcancel"]) addEventListener(type, ended, { capture: true, passive: true });
+
+/** Frames run so far: a measurement taken in one frame is good for that frame only. */
+export const frameNumber = () => epoch;
+
+/** Whether a frame is being run now (outside one, what is measured is measured afresh). */
+export const inFrame = () => running;
+
+provide("frames", () => ({
+  requested,
+  epoch,
+  sinceLastRun: lastRun ? Math.round(performance.now() - lastRun) : null,
+  settling,
+  moving: moving.size,
+  watching,
+  tasks: [...tasks].map(([name, entry]) => ({ name, wanted: entry.wanted, follows: entry.follows })),
+}));
+
+for (const type of ["scroll", "pointerdown", "keyup"]) addEventListener(type, auditSoon, { capture: true, passive: true });
+note("frames", "started");

package/browser/editor/page/geometry.mjs

@@ -0,0 +1,400 @@
+import { UNIT, isEmpty, isHost, nestedBlocks, withLeads } from "./core.mjs";
+import { boxRole, isBlock, isLead } from "../components/registry.mjs";
+
+// Where the blocks are on the screen (docs/editor.md, "Selecting blocks"). measure() reads the
+// page once into a tree of boxes and units with their rectangles. hoverAt, atHeight, measuredNode, pick,
+// endOf and gapScore are pure functions of that tree, so their rules are tested without a browser
+// (tests/unit/geometry.mjs); what reads the DOM is measure() and the readers of one element it and the
+// overlays use: extentOf, fillExtentOf, clipOf, markerRect, markerAt, blankTarget:
+//
+//   hoverAt      the block whose handle shows while the pointer is on empty space beside it (and,
+//                of text blocks, the one a click there puts the caret into)
+//   pick         the blocks a box selection takes: the ones it touches, lifted to one level
+//   endOf        what a click below the last block of a box does: a new paragraph there, or the
+//                caret into the empty paragraph already at the end
+//   innerBox     the innermost box at a click's height, whose blocks are those beside it
+//
+// Where dragged blocks would go (resolveDrop) is drag/drop.mjs, from the same tree.
+//
+// Geometry proposes, the page's structure (boxes, units) decides the level, and accepts() and the
+// block rules decide what may happen; nothing here changes the page.
+//
+// A box: { type: "box", el, kind, role, rect, content, row, children: [unit | box] }, its units and the
+// boxes standing loose in it (the report's header in the page); `content`: its rect inside its
+// padding and border (where an empty box takes a block); `row`: it lays its blocks side by side (a
+// tab row, a row of columns), "wrap" when in rows that wrap (a flowchart's nodes). A unit: { type: "unit", el, kind, rect, start, empty, text,
+// nestable, children: [box] }, the boxes it holds (itself when it is one: a section, a list); its
+// rect is where it shows (extentOf: a list item with its marker), `start` where its own content
+// starts (a list item's text, right of the marker; its left otherwise); `text`: it is a text block
+// itself, `nestable`: a list item that may take lists. Rects are { left, top, right, bottom } in
+// page coordinates (scrolling does not change them); what is not shown (a hidden Sheet panel, a
+// closed disclosure) is not in the tree.
+
+const FLOWS = new Set(["root", "flow", "column"]);
+
+const RULE = 12; // a divider line shows as a band this far above and below it (as tall as the handle)
+
+/**
+ * Where a block shows (client coordinates), or null when it does not: its own box and those of its
+ * leads, a list item's marker left of it, out to its list's edge (the list's room for markers), and
+ * a divider line (an <hr>) as a band around the line, a line of text tall (the line alone is a
+ * pixel or two), as the reader sees the block. Its fill, its handle, where the pointer finds it and
+ * what a box selection touches go by this.
+ */
+export function extentOf(el) {
+  let rect = null;
+  for (const part of withLeads(el)) {
+    const next = part.getBoundingClientRect();
+    if (next.width === 0 && next.height === 0) continue;
+    rect = rect
+      ? { left: Math.min(rect.left, next.left), top: Math.min(rect.top, next.top), right: Math.max(rect.right, next.right), bottom: Math.max(rect.bottom, next.bottom) }
+      : { left: next.left, top: next.top, right: next.right, bottom: next.bottom };
+  }
+  const marker = rect ? markerLeft(el) : null;
+  if (marker !== null) rect.left = Math.min(rect.left, marker);
+  if (rect && el.localName === "hr") {
+    const middle = (rect.top + rect.bottom) / 2;
+    rect.top = Math.min(rect.top, middle - RULE);
+    rect.bottom = Math.max(rect.bottom, middle + RULE);
+  }
+  return rect;
+}
+
+const RULE_FILL = 7; // ...and as what the editor draws over it shows it: Notion's divider row (13px)
+
+/**
+ * Where what the editor draws over a block lies (a selected block's fill, the frame of what is
+ * edited): its extent (extentOf), a divider line's band as tall as Notion's divider row; the band
+ * the pointer finds it by stays taller (it once showed the fill 36px high around a 1px line).
+ */
+export function fillExtentOf(el) {
+  const rect = extentOf(el);
+  if (!rect || el.localName !== "hr") return rect;
+  const middle = (rect.top + rect.bottom) / 2;
+  return { ...rect, top: middle - RULE_FILL, bottom: middle + RULE_FILL };
+}
+
+/**
+ * The part of the window a block can show in (client coordinates): inside every element around it
+ * that cuts off what overflows it (a dialog's scrolling content, a Sheet's tab row), or null when
+ * none does. What the editor draws over a block (its fill, its frame) is cut to it, as the block is.
+ */
+export function clipOf(el) {
+  let clip = null;
+  for (let node = el.parentElement; node && node !== document.body; node = node.parentElement) {
+    const style = getComputedStyle(node);
+    if (style.overflowX === "visible" && style.overflowY === "visible") continue;
+    const rect = node.getBoundingClientRect();
+    const left = rect.left + node.clientLeft;
+    const top = rect.top + node.clientTop;
+    const inner = { left, top, right: left + node.clientWidth, bottom: top + node.clientHeight }; // inside its borders and scroll bars
+    clip = clip
+      ? { left: Math.max(clip.left, inner.left), top: Math.max(clip.top, inner.top), right: Math.min(clip.right, inner.right), bottom: Math.min(clip.bottom, inner.bottom) }
+      : inner;
+  }
+  return clip;
+}
+
+/**
+ * The kit's marker of a list item (its number, bullet or to-do box, drawn left of its text by the
+ * item's ::before: flow.css, todo.css) where the browser laid it out, or null when the item has
+ * none. The one reading of it: the handle's reach, a number's tooltip and menu, a to-do's box.
+ */
+export function markerRect(el) {
+  if (el.localName !== "li") return null;
+  const before = getComputedStyle(el, "::before");
+  if (before.position !== "absolute" || !before.content || before.content === "none" || before.content === "normal") return null;
+  // One drawn inside the item is none (a flowchart's step number, in its card: flowchart.css).
+  if (parseFloat(before.left) >= 0) return null;
+  const number = (value) => parseFloat(value) || 0;
+  const box = el.getBoundingClientRect();
+  const width = number(before.width) + (before.boxSizing === "border-box" ? 0 : number(before.paddingLeft) + number(before.paddingRight) + number(before.borderLeftWidth) + number(before.borderRightWidth));
+  const right = box.left - number(before.marginRight);
+  const top = box.top + number(before.top);
+  const height = number(before.height) || number(getComputedStyle(el).lineHeight) || 26;
+  return { left: right - width, right, top, bottom: top + height, width, height };
+}
+
+/**
+ * The marker of a list item when a point is on it: its width (2px more to either side) on the
+ * item's first line. Null when it is not, or the item has none.
+ */
+export function markerAt(el, x, y) {
+  const rect = markerRect(el);
+  if (!rect) return null;
+  const top = el.getBoundingClientRect().top;
+  const line = Math.max(rect.height, parseFloat(getComputedStyle(el).lineHeight) || 0);
+  return x >= rect.left - 2 && x <= rect.right + 2 && y >= top && y <= top + line ? rect : null;
+}
+
+// Where the marker of a list item standing outside its box starts (the browser's, in its list's
+// padding; the kit's, markerRect), or null when it has none there.
+function markerLeft(el) {
+  if (el.localName !== "li" || !el.parentElement?.matches("ul, ol")) return null;
+  const list = el.parentElement.getBoundingClientRect().left;
+  const style = getComputedStyle(el);
+  if (style.display.includes("list-item") && style.listStylePosition === "outside" && style.listStyleType !== "none") return list;
+  const marker = markerRect(el);
+  return marker && Math.min(list, marker.left);
+}
+
+/**
+ * Whether a press or the pointer is on empty space: the page around the report, or a box between
+ * its blocks. Never text: a list item is the box of its lists too, yet a press on it is in its text.
+ */
+export function blankTarget(target) {
+  if (!target?.closest || target.closest("[data-doc-dev]")) return false;
+  if (target === document.documentElement || target === document.body) return true;
+  if (!target.closest("main")) return false; // the report's own controls outside it
+  return target.localName === "main" || (target.hasAttribute("data-ge-box") && target.getAttribute("contenteditable") !== "true");
+}
+
+/**
+ * The tree of `root` (a box, the page's main by default). With `band` ({ top, bottom }, page
+ * coordinates) only the units reaching into it are measured, and what they hold (reaching it with
+ * a divider's band to spare: a divider at a section's top reaches past the section).
+ */
+export function measure(root = document.querySelector("main"), band = null) {
+  const dx = scrollX;
+  const dy = scrollY;
+  const onPage = (rect) => rect && { left: rect.left + dx, top: rect.top + dy, right: rect.right + dx, bottom: rect.bottom + dy };
+  const ownRect = (el) => {
+    const rect = el.getBoundingClientRect();
+    return rect.width === 0 && rect.height === 0 ? null : onPage(rect);
+  };
+  const reaches = (rect) => Boolean(rect) && (!band || (rect.bottom + RULE >= band.top && rect.top - RULE <= band.bottom));
+
+  function boxNode(el) {
+    const kind = el.getAttribute("data-ge-box-kind");
+    const style = getComputedStyle(el);
+    const rect = ownRect(el);
+    const node = { type: "box", el, kind, role: boxRole(kind), rect, content: rect && contentOf(rect, style), row: sideBySide(style), children: [] };
+    for (const child of el.children) {
+      if (child.matches(UNIT)) {
+        const unit = unitNode(child);
+        if (unit) node.children.push(unit);
+      } else if (child.hasAttribute("data-ge-box")) {
+        const box = boxNode(child);
+        if (reaches(box.rect)) node.children.push(box);
+      }
+    }
+    return node;
+  }
+
+  function unitNode(el) {
+    const rect = onPage(extentOf(el));
+    if (!reaches(rect)) return null;
+    const start = el.localName === "li" ? el.getBoundingClientRect().left + dx : rect.left;
+    const text = isHost(el);
+    const empty = text && el.localName === "p" && el.classList.length === 0 && isEmpty(el);
+    // An item takes lists when the file's has its box for them, or it was made on the page.
+    const nestable = el.localName === "li" && (el.getAttribute("data-ge-box-kind") === "nest" || (el.hasAttribute("data-ge-new") && !el.hasAttribute("data-ge-unit")));
+    // An item holding blocks: its own line, above them (a box selection touching it takes the item).
+    const lists = text ? nestedBlocks(el) : [];
+    const own = lists.length > 0 ? { ...rect, bottom: lists[0].getBoundingClientRect().top + dy } : null;
+    const node = { type: "unit", el, kind: el.getAttribute("data-ge-unit-kind"), rect, start, empty, text, nestable, own, children: [] };
+    for (const inner of boxesOf(el)) {
+      if (folded(inner)) continue;
+      const box = boxNode(inner);
+      if (box.rect) node.children.push(box);
+    }
+    return node;
+  }
+
+  return boxNode(root);
+}
+
+/**
+ * Whether a box is a closed disclosure's content: none of it is on the page. (The browser still
+ * places its blocks, under the title, over the blocks after the disclosure: a box selection or the
+ * pointer there would find them.)
+ */
+const folded = (box) => box.parentElement?.localName === "details" && !box.parentElement.open;
+
+// The boxes a unit holds: itself when it is one, otherwise those inside it with no unit or box between.
+function boxesOf(el) {
+  if (el.hasAttribute("data-ge-box")) return [el];
+  return [...el.querySelectorAll("[data-ge-box]")].filter((box) => box.parentElement.closest(`${UNIT}, [data-ge-box]`) === el);
+}
+
+// A box's rect inside its padding and border.
+function contentOf(rect, style) {
+  const inset = (side) => (parseFloat(style[`padding${side}`]) || 0) + (parseFloat(style[`border${side}Width`]) || 0);
+  return { left: rect.left + inset("Left"), top: rect.top + inset("Top"), right: rect.right - inset("Right"), bottom: rect.bottom - inset("Bottom") };
+}
+
+// A box laying its blocks side by side (a tab row, a grid of cards) rather than one below another:
+// true, or "wrap" when its rows wrap (a flowchart's nodes, as the kit lays them out: rows that fill
+// its width, a node alone in a row of its own where nothing goes beside it), false for none.
+export function sideBySide(style) {
+  if (style.display.includes("grid")) return style.gridTemplateColumns.trim().split(/\s+/).length > 1;
+  if (!style.display.includes("flex") || style.flexDirection.startsWith("column")) return false;
+  return style.flexWrap.startsWith("wrap") ? "wrap" : true;
+}
+
+/**
+ * The block beside the point (page coordinates) whose handle shows while the pointer is on empty
+ * space: of the units whose rectangle, widened by `reach` on both sides, holds the point, the one
+ * nested deepest (a list item rather than its list, a paragraph rather than its section), and of
+ * those side by side the nearest. `skip(unit)`: a unit with no handle of its own (a section, a
+ * Sheet area), whose blocks still count.
+ */
+export function hoverAt(tree, x, y, { reach = 150, skip = () => false } = {}) {
+  let best = null;
+  const visit = (box, depth) => {
+    for (const child of box.children) {
+      if (child.type === "box") {
+        visit(child, depth);
+        continue;
+      }
+      const { left, top, right, bottom } = child.rect;
+      const distance = Math.max(left - x, x - right, 0);
+      if (y >= top && y <= bottom && distance <= reach && !skip(child) && (!best || depth > best.depth || (depth === best.depth && distance < best.distance))) {
+        best = { unit: child, depth, distance };
+      }
+      // Looked into either way: what it holds may reach past it (a divider's band at its top).
+      for (const inner of child.children) visit(inner, depth + 1);
+    }
+  };
+  visit(tree, 0);
+  return best?.unit.el ?? null;
+}
+
+// The units a node holds, through its boxes; a skipped unit (one with no handle of its own: a row of
+// columns, a column) is looked into.
+function innerUnits(node, skip) {
+  const found = [];
+  const visit = (each) => {
+    for (const child of each.children) {
+      if (child.type === "box" || skip(child)) visit(child);
+      else found.push(child);
+    }
+  };
+  visit(node);
+  return found;
+}
+
+/**
+ * The block whose handle shows with the pointer at (x, y) (page coordinates) in a measured unit
+ * holding blocks (a list item and its lists, a quote, a disclosure): the handle follows the
+ * pointer's height, as Notion's and Feishu's do. The innermost block reaching that height; between
+ * blocks (their gaps), the nearest by height, then by width (blocks side by side). The unit's own
+ * head (a list item's own line, a title above what it holds) is one of them: there it is the unit
+ * itself. `skip(unit)`: a unit with no handle of its own, whose blocks count.
+ */
+export function atHeight(node, x, y, { skip = () => false } = {}) {
+  const score = (rect) => gapScore(rect, x, y);
+  for (;;) {
+    const inner = innerUnits(node, skip).filter((unit) => unit.rect);
+    if (inner.length === 0) return node;
+    const first = Math.min(...inner.map((unit) => unit.rect.top));
+    const head = node.own ?? (first - node.rect.top >= 8 ? { ...node.rect, bottom: first } : null);
+    let best = head ? { unit: null, score: score(head) } : null;
+    for (const unit of inner) {
+      const each = score(unit.rect);
+      if (!best || each[0] < best.score[0] || (each[0] === best.score[0] && each[1] < best.score[1])) best = { unit, score: each };
+    }
+    if (!best.unit) return node;
+    node = best.unit;
+  }
+}
+
+/** The measured node of an element in a tree, or null. */
+export function measuredNode(tree, el) {
+  if (tree.el === el && tree.type === "unit") return tree;
+  for (const child of tree.children) {
+    const found = measuredNode(child, el);
+    if (found) return found;
+  }
+  return null;
+}
+
+const meets = (a, b) => a.left <= b.right && a.right >= b.left && a.top <= b.bottom && a.bottom >= b.top;
+
+/**
+ * The blocks a box selection over `rect` (page coordinates) takes, in document order: the units it
+ * touches that hold no other unit it touches, each lifted to the child of the innermost box around
+ * all of them. Two paragraphs of a section give those paragraphs; a paragraph of each of two
+ * sections gives both sections; blocks in two columns of a row give those blocks (a column is no
+ * block of its own); items of a list give the items, an item and the paragraph before
+ * the list give that paragraph and the list; an item holding lists whose own line it touches is
+ * taken whole (below that line, the nested items it touches). What lifts to something that is no unit (the report's
+ * header, around its lines) is left out.
+ */
+export function pick(tree, rect) {
+  const hits = []; // [path from the tree down to the unit, the unit last]
+  // A box's lead (a highlight block's icon) is no block to pick (notion-lite's is none): it is the
+  // block's own, so a box touching only it, or only the block's padding, takes the whole highlight
+  // block, as a disclosure's title row takes the disclosure (notion-lite's box-select.js).
+  const visit = (node, path) => {
+    for (const child of node.children) {
+      const next = [...path, child];
+      if (child.type === "unit" && node.type === "box" && isLead(node.kind, child.kind)) continue;
+      if (child.type === "unit" && meets(child.rect, rect)) hits.push(next);
+      visit(child, next); // what it holds may reach past it (a divider's band at its top)
+    }
+  };
+  visit(tree, [tree]);
+  const outer = new Set(hits.flatMap((path) => path.slice(0, -1)));
+  // A list item whose own line it touches counts as one, the lists it holds with it.
+  const whole = (node) => node.type === "unit" && Boolean(node.own) && meets(node.own, rect);
+  const leaves = hits.filter((path) => (whole(path.at(-1)) || !outer.has(path.at(-1))) && !path.slice(0, -1).some(whole));
+  if (leaves.length === 0) return [];
+  // The innermost box on every leaf's path.
+  let common = 0;
+  while (leaves.every((path) => path.length > common + 1 && path[common + 1] === leaves[0][common + 1])) common++;
+  let level = common;
+  while (leaves[0][level].type !== "box") level--;
+  const picked = [];
+  for (const path of leaves) {
+    let lifted = path[level + 1];
+    // A column is no block of its own (as Feishu's): across columns, the blocks touched in each.
+    if (lifted.type === "unit" && !isBlock(lifted.kind)) lifted = path[level + 3];
+    if (lifted?.type === "unit" && !picked.includes(lifted)) picked.push(lifted);
+  }
+  return picked.map((unit) => unit.el);
+}
+
+/**
+ * A click on the empty space of `box` (measured) at height `y` (page coordinates): below its last
+ * block, a flow or the page takes a new paragraph at its end ({ box, after }: after its last
+ * block, or at its start); when the last block, followed down through the flows it holds (a
+ * section's, a panel's, a disclosure's), is an empty paragraph, the caret goes there instead
+ * ({ focus }), so clicking again does not pile them up. Anywhere else, null.
+ */
+export function endOf(box, y) {
+  if (!FLOWS.has(box.role)) return null;
+  const last = box.children.at(-1) ?? null;
+  if (last && y <= last.rect.bottom) return null;
+  let deepest = last;
+  while (deepest?.type === "unit") {
+    const next = deepest.children.filter((inner) => FLOWS.has(inner.role)).at(-1)?.children.at(-1);
+    if (!next) break;
+    deepest = next;
+  }
+  if (deepest?.type === "unit" && deepest.empty) return { focus: deepest.el };
+  return { box: box.el, after: last?.el ?? null };
+}
+
+/**
+ * The innermost box of `box` (measured) reaching height `y` (page coordinates), `box` itself when
+ * none does: a Sheet's panel, a section, a disclosure's content, a list; of those side by side (the
+ * columns of a row) the nearest to `x`. What stands beside a click on the page's margin goes by it,
+ * as the margin is no box's but the page's.
+ */
+export function innerBox(box, x, y) {
+  const inner = box.children.flatMap((child) => (child.type === "box" ? [child] : child.children)).filter(({ rect }) => y >= rect.top && y <= rect.bottom);
+  if (inner.length === 0) return box;
+  const gap = ({ rect }) => gapScore(rect, x, y)[1];
+  return innerBox(inner.reduce((a, b) => (gap(b) < gap(a) ? b : a)), x, y);
+}
+
+/**
+ * How far a rectangle is from the point (x, y): [the gap by height, the gap by width], 0 where the
+ * point is within it. The nearest block to a point goes by it, height first (then width: blocks
+ * side by side); how a tie goes is each caller's.
+ */
+export const gapScore = (rect, x, y) => [
+  y < rect.top ? rect.top - y : y > rect.bottom ? y - rect.bottom : 0,
+  x < rect.left ? rect.left - x : x > rect.right ? x - rect.right : 0,
+];

package/browser/editor/page/gesture.mjs

@@ -0,0 +1,45 @@
+// How a press gesture ends besides the pointer coming up (docs/editor.md, "Overlays"): resizing a
+// card, dragging a gap between columns, drawing a box selection and selecting text across blocks
+// all end the same ways, written once here. Each keeps its own state machine and what it does on
+// letting go; only the ways of giving up are shared, and every one of them is idempotent.
+
+/**
+ * The CSS that locks the page while a gesture is under way, the tool having set `attribute` (a
+ * name, or name="value") on the document element: the cursor it asks for (`cursor`) shows wherever
+ * the pointer goes, and, with `select`, nothing gets selected. The one place the editor's gesture
+ * styles are !important, and they must be: the elements under a pointer that a gesture holds (the
+ * tool captures it on the document element) have rules of their own for the cursor (a grip's grab,
+ * a table's resize bar) and for selecting, more specific than any rule about "everything while
+ * this happens".
+ */
+export function gestureLock(attribute, { cursor = null, select = false } = {}) {
+  const on = `html[${attribute}]`;
+  return `${on}, ${on} * { ${cursor ? `cursor: ${cursor} !important; ` : ""}${select ? "-webkit-user-select: none !important; user-select: none !important; " : ""}}`;
+}
+
+/**
+ * The gesture is over, cancelled (what it took is let go, nothing is written), when the browser
+ * cancels the pointer (a touch it took), the capture is lost any other way (after pointerup the
+ * gesture is over already), the window loses the focus, or the page is hidden. `active()`: whether
+ * the gesture is under way; `cancel()`: give it up. `owns(event)`: whether a lost capture is the
+ * gesture's, by default the document element's, where the tools hold the pointer.
+ */
+export function endsGesture({ active, cancel, owns = (event) => event.target === document.documentElement }) {
+  addEventListener("pointercancel", () => { if (active()) cancel(); }, true);
+  document.documentElement.addEventListener("lostpointercapture", (event) => { if (active() && owns(event)) cancel(); });
+  addEventListener("blur", () => { if (active()) cancel(); });
+  document.addEventListener("visibilitychange", () => { if (document.hidden && active()) cancel(); });
+}
+
+/**
+ * Esc while the gesture is under way gives it up, and nothing else sees the key (`cancel` may say
+ * so on the status line).
+ */
+export function cancelOnEscape({ active, cancel }) {
+  addEventListener("keydown", (event) => {
+    if (event.key !== "Escape" || !active()) return;
+    event.preventDefault();
+    event.stopPropagation();
+    cancel();
+  }, true);
+}