@sametalmdr/word-editor 0.2.0-alpha → 0.3.0-alpha

package/dist/canvas/box-clipboard.js

@@ -1,238 +1,238 @@
-// The box clipboard: what a copy/cut writes, and what a paste rebuilds
-// (ADR-0018 Karar 7, §9/Karar 9). No src/, DOM, or history import — this
-// file only produces plain data (a payload, and fresh Container/BoxLayout
-// values); it never builds a Transaction or touches HistoryEngine. The
-// (future) CanvasController turns this data into steps, the same
-// boundary `src/commands/box.js`'s functions sit on the other side of.
-//
-// NO SPECIAL MIME TYPE (§7.1 — present in an earlier draft, WITHDRAWN):
-// how well a custom `setData` type survives the synchronous `copy` event
-// versus the asynchronous Clipboard API is UNMEASURED in this repo, and
-// `src/input/clipboard.js` is `text/plain` in both directions today.
-// Depending on that unmeasured behavior is the same call Karar 1 already
-// made rejecting `elementFromPoint`. Honest consequence: cross-document
-// paste of boxes does not work in P3b-a — `payloadToText` is the
-// `text/plain` mirror written to the system clipboard alongside the real
-// `BoxPayload`, which lives only in the (future) CanvasController's own
-// instance.
-//
-// INVARIANT #13: `serializeBoxes` reuses `toJSON`'s field-by-field copying
-// discipline (document-json.js:63-77) for `layout`, never `{ ...entry }`
-// let alone `layout: entry`. That comment documents a production bug: a
-// shallow spread still aliases every BoxLayout entry to the live
-// document, and `devFreeze` is dev-only, so the alias goes undetected in
-// production until something writes through it.
-
-import { containerById, createContainer, createParagraph, createRun, layoutOf, LAYOUT_KEYS } from "../model/node.js";
-import { anchorBounds } from "./box-selection.js";
-
-/** Bumped when the shape changes incompatibly — mirrors document-json.js's own field. */
-export const BOX_PAYLOAD_VERSION = 1;
-
-/**
- * @typedef {object} BoxPayloadParagraph
- * @property {import("../model/node.js").NodeId} id
- * @property {import("../model/node.js").PropRef} [pPrRef]
- * @property {{text: string, marks: import("../model/node.js").Marks}[]} runs
- */
-
-/**
- * @typedef {object} BoxPayloadEntry
- * @property {Partial<import("../model/node.js").BoxLayout>} layout  a fresh, field-by-field copy — never a live reference
- * @property {BoxPayloadParagraph[]} paragraphs
- */
-
-/**
- * @typedef {object} BoxPayload
- * @property {number} version
- * @property {{x: number, y: number}} origin  the copied selection's own bounding-rect top-left (ADR-0018 §7.3's "grubun sol-üstü")
- * @property {BoxPayloadEntry[]} boxes
- */
-
-/**
- * A fresh, field-by-field copy of one container's paragraphs — the SAME
- * per-paragraph shape `document-json.js`'s `toJSON` builds, reused rather
- * than re-invented.
- * @param {import("../model/node.js").Container} container
- * @returns {BoxPayloadParagraph[]}
- */
-function copyParagraphs(container) {
-  return container.content.map((para) => ({
-    id: para.id,
-    ...(para.pPrRef !== undefined ? { pPrRef: para.pPrRef } : {}),
-    runs: para.content.map((run) => ({ text: run.text, marks: { ...run.marks } })),
-  }));
-}
-
-/**
- * A fresh, field-by-field copy of one `BoxLayout` entry, built from
- * `LAYOUT_KEYS` (model/node.js's single source) — never `{ ...entry }`,
- * which would only copy the top-level object and leave every field an
- * alias if this were ever mutated by reference instead of replaced
- * (invariant #13, CANV11's own target).
- * @param {import("../model/node.js").BoxLayout} entry
- * @returns {Partial<import("../model/node.js").BoxLayout>}
- */
-function copyLayout(entry) {
-  /** @type {any} */
-  const copy = {};
-  for (const key of LAYOUT_KEYS) {
-    if (entry[key] !== undefined) {
-      copy[key] = entry[key];
-    }
-  }
-  return copy;
-}
-
-/**
- * The clipboard payload for a set of boxes — `null` if the selection is
- * empty or any id no longer names a real box (a stale selection copying
- * nothing meaningful is a no-op, not a partial copy).
- *
- * @param {import("../model/node.js").Doc} doc
- * @param {import("../model/node.js").NodeId[]} containerIds
- * @returns {BoxPayload | null}
- */
-export function serializeBoxes(doc, containerIds) {
-  const bounds = anchorBounds(doc, containerIds);
-  if (bounds === null) {
-    return null;
-  }
-
-  const boxes = [];
-  for (const id of containerIds) {
-    const layout = layoutOf(doc, id);
-    const container = containerById(doc, id);
-    if (layout === null || container === null) {
-      return null;
-    }
-    boxes.push({ layout: copyLayout(layout), paragraphs: copyParagraphs(container) });
-  }
-
-  return { version: BOX_PAYLOAD_VERSION, origin: { x: bounds.x, y: bounds.y }, boxes };
-}
-
-/**
- * The plain-text mirror written to the system clipboard's `text/plain`
- * slot alongside the real payload (§7.1) — every paragraph of every box,
- * in payload order, joined the same way `serializeToText` joins a text
- * selection's paragraphs.
- * @param {BoxPayload} payload
- * @returns {string}
- */
-export function payloadToText(payload) {
-  return payload.boxes
-    .flatMap((box) => box.paragraphs.map((para) => para.runs.map((run) => run.text).join("")))
-    .join("\n");
-}
-
-/**
- * @typedef {object} MintedBoxIds
- * @property {import("../model/node.js").NodeId} containerId
- * @property {import("../model/node.js").NodeId[]} paragraphIds  same length and order as `box.paragraphs`
- */
-
-/**
- * Fresh ids for one payload box, minted from `ids` — NEVER the ids the
- * payload itself carries (those are the ORIGINAL box's, and reusing them
- * would collide the moment the original still exists, CANV12's own
- * target). Minted before any step exists (ADR-0003: `apply()` never mints
- * an id) — the same ordering `commands/clipboard.js`'s `pasteText` already
- * uses for a pasted paragraph's id, generalized to a whole box.
- *
- * @param {BoxPayloadEntry} box
- * @param {import("../model/ids.js").IdFactory} ids
- * @returns {MintedBoxIds}
- */
-export function mintBoxIds(box, ids) {
-  return {
-    containerId: ids.next(),
-    paragraphIds: box.paragraphs.map(() => ids.next()),
-  };
-}
-
-/**
- * @typedef {object} PastePage
- * @property {number} page  1-based, the ACTIVE page paste targets — never the page the boxes were copied from (§7.2)
- * @property {number} width
- * @property {number} height
- */
-
-/**
- * @typedef {object} PastedBox
- * @property {import("../model/node.js").Container} container  fresh ids throughout
- * @property {import("../model/node.js").BoxLayout} layout
- */
-
-/**
- * Rebuilds `payload` as fresh containers + layouts, ready for the (future)
- * caller to turn into `insertContainerStep`s — one transaction, so the
- * whole paste is one undo entry.
- *
- * Relative geometry is preserved EXACTLY (§7.4): the offset from
- * `payload.origin` to its post-paste position is computed ONCE, from the
- * group's own bounding rect, and applied IDENTICALLY to every box's own
- * absolute `{x,y}` — never computed per box. A per-box offset (e.g. each
- * box separately clamped against the page) would let two boxes drift
- * apart or together depending on which one needed clamping (CANV9's own
- * target): two boxes 40pt apart must land 40pt apart, whether or not the
- * paste needed to shift for the page edge.
- *
- * Falling outside the target page CLIPS the whole group's bounding rect
- * into it (§7.2) — smart placement is not attempted; ARCHITECTURE.md:357
- * already calls "no overlap" an unrealistic goal, and clipping the whole
- * group keeps that same "don't pretend to solve overlap" stance instead
- * of inventing a different unsolved problem (per-box collision avoidance).
- *
- * @param {BoxPayload} payload
- * @param {import("../model/ids.js").IdFactory} ids
- * @param {PastePage} targetPage
- * @param {number} pasteOffsetPt  pt — injected, no default (an unmeasured UI constant, CanvasMetrics' `pasteOffsetPt`)
- * @returns {PastedBox[]}
- */
-export function pasteBoxes(payload, ids, targetPage, pasteOffsetPt) {
-  if (payload.boxes.length === 0) {
-    return [];
-  }
-
-  const groupLeft = Math.min(...payload.boxes.map((box) => /** @type {number} */ (box.layout.x)));
-  const groupTop = Math.min(...payload.boxes.map((box) => /** @type {number} */ (box.layout.y)));
-  const groupRight = Math.max(
-    ...payload.boxes.map((box) => /** @type {number} */ (box.layout.x) + /** @type {number} */ (box.layout.cx)),
-  );
-  const groupBottom = Math.max(
-    ...payload.boxes.map((box) => /** @type {number} */ (box.layout.y) + /** @type {number} */ (box.layout.cy)),
-  );
-  const groupWidth = groupRight - groupLeft;
-  const groupHeight = groupBottom - groupTop;
-
-  const desiredLeft = payload.origin.x + pasteOffsetPt;
-  const desiredTop = payload.origin.y + pasteOffsetPt;
-
-  const clampedLeft = Math.min(Math.max(desiredLeft, 0), Math.max(0, targetPage.width - groupWidth));
-  const clampedTop = Math.min(Math.max(desiredTop, 0), Math.max(0, targetPage.height - groupHeight));
-
-  const dx = clampedLeft - groupLeft;
-  const dy = clampedTop - groupTop;
-
-  return payload.boxes.map((box) => {
-    const minted = mintBoxIds(box, ids);
-    const container = createContainer(
-      minted.containerId,
-      box.paragraphs.map((para, i) =>
-        createParagraph(
-          minted.paragraphIds[i],
-          para.runs.map((run) => createRun(run.text, { ...run.marks })),
-          { pPrRef: para.pPrRef },
-        ),
-      ),
-    );
-    const layout = /** @type {import("../model/node.js").BoxLayout} */ ({
-      ...box.layout,
-      page: targetPage.page,
-      x: /** @type {number} */ (box.layout.x) + dx,
-      y: /** @type {number} */ (box.layout.y) + dy,
-    });
-    return { container, layout };
-  });
-}
+// The box clipboard: what a copy/cut writes, and what a paste rebuilds
+// (ADR-0018 Karar 7, §9/Karar 9). No src/, DOM, or history import — this
+// file only produces plain data (a payload, and fresh Container/BoxLayout
+// values); it never builds a Transaction or touches HistoryEngine. The
+// (future) CanvasController turns this data into steps, the same
+// boundary `src/commands/box.js`'s functions sit on the other side of.
+//
+// NO SPECIAL MIME TYPE (§7.1 — present in an earlier draft, WITHDRAWN):
+// how well a custom `setData` type survives the synchronous `copy` event
+// versus the asynchronous Clipboard API is UNMEASURED in this repo, and
+// `src/input/clipboard.js` is `text/plain` in both directions today.
+// Depending on that unmeasured behavior is the same call Karar 1 already
+// made rejecting `elementFromPoint`. Honest consequence: cross-document
+// paste of boxes does not work in P3b-a — `payloadToText` is the
+// `text/plain` mirror written to the system clipboard alongside the real
+// `BoxPayload`, which lives only in the (future) CanvasController's own
+// instance.
+//
+// INVARIANT #13: `serializeBoxes` reuses `toJSON`'s field-by-field copying
+// discipline (document-json.js:63-77) for `layout`, never `{ ...entry }`
+// let alone `layout: entry`. That comment documents a production bug: a
+// shallow spread still aliases every BoxLayout entry to the live
+// document, and `devFreeze` is dev-only, so the alias goes undetected in
+// production until something writes through it.
+
+import { containerById, createContainer, createParagraph, createRun, layoutOf, LAYOUT_KEYS } from "../model/node.js";
+import { anchorBounds } from "./box-selection.js";
+
+/** Bumped when the shape changes incompatibly — mirrors document-json.js's own field. */
+export const BOX_PAYLOAD_VERSION = 1;
+
+/**
+ * @typedef {object} BoxPayloadParagraph
+ * @property {import("../model/node.js").NodeId} id
+ * @property {import("../model/node.js").PropRef} [pPrRef]
+ * @property {{text: string, marks: import("../model/node.js").Marks}[]} runs
+ */
+
+/**
+ * @typedef {object} BoxPayloadEntry
+ * @property {Partial<import("../model/node.js").BoxLayout>} layout  a fresh, field-by-field copy — never a live reference
+ * @property {BoxPayloadParagraph[]} paragraphs
+ */
+
+/**
+ * @typedef {object} BoxPayload
+ * @property {number} version
+ * @property {{x: number, y: number}} origin  the copied selection's own bounding-rect top-left (ADR-0018 §7.3's "grubun sol-üstü")
+ * @property {BoxPayloadEntry[]} boxes
+ */
+
+/**
+ * A fresh, field-by-field copy of one container's paragraphs — the SAME
+ * per-paragraph shape `document-json.js`'s `toJSON` builds, reused rather
+ * than re-invented.
+ * @param {import("../model/node.js").Container} container
+ * @returns {BoxPayloadParagraph[]}
+ */
+function copyParagraphs(container) {
+  return container.content.map((para) => ({
+    id: para.id,
+    ...(para.pPrRef !== undefined ? { pPrRef: para.pPrRef } : {}),
+    runs: para.content.map((run) => ({ text: run.text, marks: { ...run.marks } })),
+  }));
+}
+
+/**
+ * A fresh, field-by-field copy of one `BoxLayout` entry, built from
+ * `LAYOUT_KEYS` (model/node.js's single source) — never `{ ...entry }`,
+ * which would only copy the top-level object and leave every field an
+ * alias if this were ever mutated by reference instead of replaced
+ * (invariant #13, CANV11's own target).
+ * @param {import("../model/node.js").BoxLayout} entry
+ * @returns {Partial<import("../model/node.js").BoxLayout>}
+ */
+function copyLayout(entry) {
+  /** @type {any} */
+  const copy = {};
+  for (const key of LAYOUT_KEYS) {
+    if (entry[key] !== undefined) {
+      copy[key] = entry[key];
+    }
+  }
+  return copy;
+}
+
+/**
+ * The clipboard payload for a set of boxes — `null` if the selection is
+ * empty or any id no longer names a real box (a stale selection copying
+ * nothing meaningful is a no-op, not a partial copy).
+ *
+ * @param {import("../model/node.js").Doc} doc
+ * @param {import("../model/node.js").NodeId[]} containerIds
+ * @returns {BoxPayload | null}
+ */
+export function serializeBoxes(doc, containerIds) {
+  const bounds = anchorBounds(doc, containerIds);
+  if (bounds === null) {
+    return null;
+  }
+
+  const boxes = [];
+  for (const id of containerIds) {
+    const layout = layoutOf(doc, id);
+    const container = containerById(doc, id);
+    if (layout === null || container === null) {
+      return null;
+    }
+    boxes.push({ layout: copyLayout(layout), paragraphs: copyParagraphs(container) });
+  }
+
+  return { version: BOX_PAYLOAD_VERSION, origin: { x: bounds.x, y: bounds.y }, boxes };
+}
+
+/**
+ * The plain-text mirror written to the system clipboard's `text/plain`
+ * slot alongside the real payload (§7.1) — every paragraph of every box,
+ * in payload order, joined the same way `serializeToText` joins a text
+ * selection's paragraphs.
+ * @param {BoxPayload} payload
+ * @returns {string}
+ */
+export function payloadToText(payload) {
+  return payload.boxes
+    .flatMap((box) => box.paragraphs.map((para) => para.runs.map((run) => run.text).join("")))
+    .join("\n");
+}
+
+/**
+ * @typedef {object} MintedBoxIds
+ * @property {import("../model/node.js").NodeId} containerId
+ * @property {import("../model/node.js").NodeId[]} paragraphIds  same length and order as `box.paragraphs`
+ */
+
+/**
+ * Fresh ids for one payload box, minted from `ids` — NEVER the ids the
+ * payload itself carries (those are the ORIGINAL box's, and reusing them
+ * would collide the moment the original still exists, CANV12's own
+ * target). Minted before any step exists (ADR-0003: `apply()` never mints
+ * an id) — the same ordering `commands/clipboard.js`'s `pasteText` already
+ * uses for a pasted paragraph's id, generalized to a whole box.
+ *
+ * @param {BoxPayloadEntry} box
+ * @param {import("../model/ids.js").IdFactory} ids
+ * @returns {MintedBoxIds}
+ */
+export function mintBoxIds(box, ids) {
+  return {
+    containerId: ids.next(),
+    paragraphIds: box.paragraphs.map(() => ids.next()),
+  };
+}
+
+/**
+ * @typedef {object} PastePage
+ * @property {number} page  1-based, the ACTIVE page paste targets — never the page the boxes were copied from (§7.2)
+ * @property {number} width
+ * @property {number} height
+ */
+
+/**
+ * @typedef {object} PastedBox
+ * @property {import("../model/node.js").Container} container  fresh ids throughout
+ * @property {import("../model/node.js").BoxLayout} layout
+ */
+
+/**
+ * Rebuilds `payload` as fresh containers + layouts, ready for the (future)
+ * caller to turn into `insertContainerStep`s — one transaction, so the
+ * whole paste is one undo entry.
+ *
+ * Relative geometry is preserved EXACTLY (§7.4): the offset from
+ * `payload.origin` to its post-paste position is computed ONCE, from the
+ * group's own bounding rect, and applied IDENTICALLY to every box's own
+ * absolute `{x,y}` — never computed per box. A per-box offset (e.g. each
+ * box separately clamped against the page) would let two boxes drift
+ * apart or together depending on which one needed clamping (CANV9's own
+ * target): two boxes 40pt apart must land 40pt apart, whether or not the
+ * paste needed to shift for the page edge.
+ *
+ * Falling outside the target page CLIPS the whole group's bounding rect
+ * into it (§7.2) — smart placement is not attempted; ARCHITECTURE.md:357
+ * already calls "no overlap" an unrealistic goal, and clipping the whole
+ * group keeps that same "don't pretend to solve overlap" stance instead
+ * of inventing a different unsolved problem (per-box collision avoidance).
+ *
+ * @param {BoxPayload} payload
+ * @param {import("../model/ids.js").IdFactory} ids
+ * @param {PastePage} targetPage
+ * @param {number} pasteOffsetPt  pt — injected, no default (an unmeasured UI constant, CanvasMetrics' `pasteOffsetPt`)
+ * @returns {PastedBox[]}
+ */
+export function pasteBoxes(payload, ids, targetPage, pasteOffsetPt) {
+  if (payload.boxes.length === 0) {
+    return [];
+  }
+
+  const groupLeft = Math.min(...payload.boxes.map((box) => /** @type {number} */ (box.layout.x)));
+  const groupTop = Math.min(...payload.boxes.map((box) => /** @type {number} */ (box.layout.y)));
+  const groupRight = Math.max(
+    ...payload.boxes.map((box) => /** @type {number} */ (box.layout.x) + /** @type {number} */ (box.layout.cx)),
+  );
+  const groupBottom = Math.max(
+    ...payload.boxes.map((box) => /** @type {number} */ (box.layout.y) + /** @type {number} */ (box.layout.cy)),
+  );
+  const groupWidth = groupRight - groupLeft;
+  const groupHeight = groupBottom - groupTop;
+
+  const desiredLeft = payload.origin.x + pasteOffsetPt;
+  const desiredTop = payload.origin.y + pasteOffsetPt;
+
+  const clampedLeft = Math.min(Math.max(desiredLeft, 0), Math.max(0, targetPage.width - groupWidth));
+  const clampedTop = Math.min(Math.max(desiredTop, 0), Math.max(0, targetPage.height - groupHeight));
+
+  const dx = clampedLeft - groupLeft;
+  const dy = clampedTop - groupTop;
+
+  return payload.boxes.map((box) => {
+    const minted = mintBoxIds(box, ids);
+    const container = createContainer(
+      minted.containerId,
+      box.paragraphs.map((para, i) =>
+        createParagraph(
+          minted.paragraphIds[i],
+          para.runs.map((run) => createRun(run.text, { ...run.marks })),
+          { pPrRef: para.pPrRef },
+        ),
+      ),
+    );
+    const layout = /** @type {import("../model/node.js").BoxLayout} */ ({
+      ...box.layout,
+      page: targetPage.page,
+      x: /** @type {number} */ (box.layout.x) + dx,
+      y: /** @type {number} */ (box.layout.y) + dy,
+    });
+    return { container, layout };
+  });
+}

package/dist/canvas/box-selection.js

@@ -1,80 +1,80 @@
-// How a set of selected box ids changes under shift+click and the marquee
-// (ADR-0018 Karar 5, §9/Karar 9). No src/, DOM, or history import — pure
-// data in, data out.
-//
-// The marquee rule is CONTAINMENT, not intersection (§5.1, measured):
-// overlap exists in 46/46 corpus documents at 3-36% density
-// (corpus-inventory.md:390). An intersection rule would let one small
-// marquee over a dense document scoop up dozens of unrelated boxes sitting
-// under a full-page background shape; containment is what the ADR settled
-// on instead.
-//
-// `rectContains`/`unionRect`/`normalizeRect` (geometry.js) are the ONLY
-// place this arithmetic is defined — this file never recomputes them.
-// `boxesOnPage` (hit-test.js) is the ONLY place "is this a decoration"
-// is decided — a decoration can never be selected (ADR-0015), so the
-// marquee reuses that filter rather than re-checking `kind` itself.
-
-import { boxesOnPage } from "./hit-test.js";
-import { normalizeRect, rectContains, rectOfLayout, unionRect } from "./geometry.js";
-import { layoutOf } from "../model/node.js";
-
-/**
- * Shift+click: add `id` if it is not selected, remove it if it is. Order is
- * append-on-add — the array is a set with a stable iteration order, not
- * re-sorted on every toggle.
- *
- * @param {import("../model/node.js").NodeId[]} selected
- * @param {import("../model/node.js").NodeId} id
- * @returns {import("../model/node.js").NodeId[]}
- */
-export function toggleSelection(selected, id) {
-  return selected.includes(id) ? selected.filter((existing) => existing !== id) : [...selected, id];
-}
-
-/**
- * Every box on `page` ENTIRELY inside `rect` — never a decoration
- * (`boxesOnPage` already excludes them, ADR-0015: not selectable). `rect`
- * is normalized first: a real marquee drag can go in any direction and
- * `rectContains` assumes non-negative size (`geometry.js`'s own reason
- * `normalizeRect` exists).
- *
- * @param {import("../model/node.js").Doc} doc
- * @param {number} page
- * @param {import("./geometry.js").Rect} rect  the dragged marquee, any direction
- * @returns {import("../model/node.js").NodeId[]}
- */
-export function boxesInMarquee(doc, page, rect) {
-  const normalized = normalizeRect(rect);
-  return boxesOnPage(doc, page)
-    .filter((occupant) => rectContains(normalized, occupant.rect))
-    .map((occupant) => occupant.id);
-}
-
-/**
- * The union of every selected box's own rect — the single bounding
- * rectangle a multi-select's move handle is drawn around, and the
- * reference corner `box-clipboard.js`'s copy/paste offset math uses.
- * `null` for an empty selection, or if any id no longer names a real box
- * (deleted out from under a stale selection) — a caller must not draw a
- * bounds rect for a selection it cannot fully resolve.
- *
- * @param {import("../model/node.js").Doc} doc
- * @param {import("../model/node.js").NodeId[]} containerIds
- * @returns {import("./geometry.js").Rect | null}
- */
-export function anchorBounds(doc, containerIds) {
-  if (containerIds.length === 0) {
-    return null;
-  }
-  /** @type {import("./geometry.js").Rect[]} */
-  const rects = [];
-  for (const id of containerIds) {
-    const layout = layoutOf(doc, id);
-    if (layout === null) {
-      return null;
-    }
-    rects.push(rectOfLayout(layout));
-  }
-  return rects.reduce((acc, rect) => unionRect(acc, rect));
-}
+// How a set of selected box ids changes under shift+click and the marquee
+// (ADR-0018 Karar 5, §9/Karar 9). No src/, DOM, or history import — pure
+// data in, data out.
+//
+// The marquee rule is CONTAINMENT, not intersection (§5.1, measured):
+// overlap exists in 46/46 corpus documents at 3-36% density
+// (corpus-inventory.md:390). An intersection rule would let one small
+// marquee over a dense document scoop up dozens of unrelated boxes sitting
+// under a full-page background shape; containment is what the ADR settled
+// on instead.
+//
+// `rectContains`/`unionRect`/`normalizeRect` (geometry.js) are the ONLY
+// place this arithmetic is defined — this file never recomputes them.
+// `boxesOnPage` (hit-test.js) is the ONLY place "is this a decoration"
+// is decided — a decoration can never be selected (ADR-0015), so the
+// marquee reuses that filter rather than re-checking `kind` itself.
+
+import { boxesOnPage } from "./hit-test.js";
+import { normalizeRect, rectContains, rectOfLayout, unionRect } from "./geometry.js";
+import { layoutOf } from "../model/node.js";
+
+/**
+ * Shift+click: add `id` if it is not selected, remove it if it is. Order is
+ * append-on-add — the array is a set with a stable iteration order, not
+ * re-sorted on every toggle.
+ *
+ * @param {import("../model/node.js").NodeId[]} selected
+ * @param {import("../model/node.js").NodeId} id
+ * @returns {import("../model/node.js").NodeId[]}
+ */
+export function toggleSelection(selected, id) {
+  return selected.includes(id) ? selected.filter((existing) => existing !== id) : [...selected, id];
+}
+
+/**
+ * Every box on `page` ENTIRELY inside `rect` — never a decoration
+ * (`boxesOnPage` already excludes them, ADR-0015: not selectable). `rect`
+ * is normalized first: a real marquee drag can go in any direction and
+ * `rectContains` assumes non-negative size (`geometry.js`'s own reason
+ * `normalizeRect` exists).
+ *
+ * @param {import("../model/node.js").Doc} doc
+ * @param {number} page
+ * @param {import("./geometry.js").Rect} rect  the dragged marquee, any direction
+ * @returns {import("../model/node.js").NodeId[]}
+ */
+export function boxesInMarquee(doc, page, rect) {
+  const normalized = normalizeRect(rect);
+  return boxesOnPage(doc, page)
+    .filter((occupant) => rectContains(normalized, occupant.rect))
+    .map((occupant) => occupant.id);
+}
+
+/**
+ * The union of every selected box's own rect — the single bounding
+ * rectangle a multi-select's move handle is drawn around, and the
+ * reference corner `box-clipboard.js`'s copy/paste offset math uses.
+ * `null` for an empty selection, or if any id no longer names a real box
+ * (deleted out from under a stale selection) — a caller must not draw a
+ * bounds rect for a selection it cannot fully resolve.
+ *
+ * @param {import("../model/node.js").Doc} doc
+ * @param {import("../model/node.js").NodeId[]} containerIds
+ * @returns {import("./geometry.js").Rect | null}
+ */
+export function anchorBounds(doc, containerIds) {
+  if (containerIds.length === 0) {
+    return null;
+  }
+  /** @type {import("./geometry.js").Rect[]} */
+  const rects = [];
+  for (const id of containerIds) {
+    const layout = layoutOf(doc, id);
+    if (layout === null) {
+      return null;
+    }
+    rects.push(rectOfLayout(layout));
+  }
+  return rects.reduce((acc, rect) => unionRect(acc, rect));
+}