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

package/dist/canvas/viewport.js

@@ -1,112 +1,112 @@
-// Pure px (client/viewport) <-> pt (page/model) bridge for the canvas
-// interaction layer (ADR-0018 §9/Karar 9, §9.1).
-//
-// The renderer never computes a scale factor of its own — `syncPages`
-// (src/render/renderer.js) writes raw `pt` CSS strings and lets the browser
-// do px conversion (measured, not assumed: no ptToPx/getBoundingClientRect
-// call exists anywhere in src/ today). This module is the FIRST place that
-// conversion is named, and it takes an already-measured `PageRect` as
-// input rather than measuring the DOM itself — invariant #7 ("the
-// browser's DOM is not the data model") applied to geometry: the real
-// `getBoundingClientRect()` call is a controller-level concern (a later
-// phase's `readPageMetrics()`), enjected in, never called from here.
-//
-// No src/, DOM, or history import — this module is pure data in, data out.
-
-/**
- * @typedef {object} PageRect
- * @property {number} left    client px
- * @property {number} top     client px
- * @property {number} width   client px
- * @property {number} height  client px
- * @property {number} scale   client px per pt
- */
-
-/**
- * @param {PageRect} pageRect
- * @returns {number}
- */
-export function pageScale(pageRect) {
-  return pageRect.scale;
-}
-
-/**
- * A client-space point, converted to page-space pt relative to the page's
- * own top-left corner. The only place a pointer event's clientX/clientY
- * becomes a pt coordinate hit-test.js can use.
- *
- * @param {PageRect} pageRect
- * @param {number} clientX
- * @param {number} clientY
- * @returns {{x: number, y: number}}
- */
-export function clientToPagePoint(pageRect, clientX, clientY) {
-  return {
-    x: (clientX - pageRect.left) / pageRect.scale,
-    y: (clientY - pageRect.top) / pageRect.scale,
-  };
-}
-
-/**
- * A page-space pt rect (BoxLayout/geometry.js's `Rect` shape), converted to
- * a client-space px rect — the inverse of `clientToPagePoint`, for drawing
- * a tutamak/overlay (a later phase) over a real box.
- *
- * @param {PageRect} pageRect
- * @param {import("./geometry.js").Rect} rect
- * @returns {{left: number, top: number, width: number, height: number}}
- */
-export function pageToClientRect(pageRect, rect) {
-  return {
-    left: pageRect.left + rect.x * pageRect.scale,
-    top: pageRect.top + rect.y * pageRect.scale,
-    width: rect.cx * pageRect.scale,
-    height: rect.cy * pageRect.scale,
-  };
-}
-
-/**
- * Which page (1-based, matching `BoxLayout.page`'s convention) a client
- * point falls on, or null if it lands on none of them — the space between
- * pages, or above/below the whole stack. `pageRects[0]` is page 1,
- * `pageRects[1]` is page 2, and so on: `PageRect` itself carries no page
- * number (it is exactly the five numbers a controller measures for ONE
- * page), so the array's own order carries that instead.
- *
- * @param {PageRect[]} pageRects
- * @param {number} clientX
- * @param {number} clientY
- * @returns {number | null}
- */
-export function pageAtClientPoint(pageRects, clientX, clientY) {
-  for (let i = 0; i < pageRects.length; i += 1) {
-    const rect = pageRects[i];
-    if (
-      clientX >= rect.left &&
-      clientX <= rect.left + rect.width &&
-      clientY >= rect.top &&
-      clientY <= rect.top + rect.height
-    ) {
-      return i + 1;
-    }
-  }
-  return null;
-}
-
-/**
- * Observation only, not a rule (ADR-0018 §10.2): whether a page's measured
- * client-px footprint scales its width and height by the SAME factor
- * relative to the page's own pt size. `PageRect.scale` is a single number
- * because every other function here assumes uniform scaling; this is the
- * one place that assumption gets checked rather than silently trusted.
- * Zero means no skew. No consumer reads this value for real behavior, and
- * no mutation is registered for it — see the file header of
- * `test/canvas/viewport.test.js`.
- *
- * @param {{width: number, height: number}} pageRectPx  raw client px measurement
- * @param {{width: number, height: number}} pagePt      the page's own pt size (Doc.page)
- * @returns {number}
- */
-export function pageScaleSkew(pageRectPx, pagePt) {
-  return pageRectPx.width / pagePt.width - pageRectPx.height / pagePt.height;
-}
+// Pure px (client/viewport) <-> pt (page/model) bridge for the canvas
+// interaction layer (ADR-0018 §9/Karar 9, §9.1).
+//
+// The renderer never computes a scale factor of its own — `syncPages`
+// (src/render/renderer.js) writes raw `pt` CSS strings and lets the browser
+// do px conversion (measured, not assumed: no ptToPx/getBoundingClientRect
+// call exists anywhere in src/ today). This module is the FIRST place that
+// conversion is named, and it takes an already-measured `PageRect` as
+// input rather than measuring the DOM itself — invariant #7 ("the
+// browser's DOM is not the data model") applied to geometry: the real
+// `getBoundingClientRect()` call is a controller-level concern (a later
+// phase's `readPageMetrics()`), enjected in, never called from here.
+//
+// No src/, DOM, or history import — this module is pure data in, data out.
+
+/**
+ * @typedef {object} PageRect
+ * @property {number} left    client px
+ * @property {number} top     client px
+ * @property {number} width   client px
+ * @property {number} height  client px
+ * @property {number} scale   client px per pt
+ */
+
+/**
+ * @param {PageRect} pageRect
+ * @returns {number}
+ */
+export function pageScale(pageRect) {
+  return pageRect.scale;
+}
+
+/**
+ * A client-space point, converted to page-space pt relative to the page's
+ * own top-left corner. The only place a pointer event's clientX/clientY
+ * becomes a pt coordinate hit-test.js can use.
+ *
+ * @param {PageRect} pageRect
+ * @param {number} clientX
+ * @param {number} clientY
+ * @returns {{x: number, y: number}}
+ */
+export function clientToPagePoint(pageRect, clientX, clientY) {
+  return {
+    x: (clientX - pageRect.left) / pageRect.scale,
+    y: (clientY - pageRect.top) / pageRect.scale,
+  };
+}
+
+/**
+ * A page-space pt rect (BoxLayout/geometry.js's `Rect` shape), converted to
+ * a client-space px rect — the inverse of `clientToPagePoint`, for drawing
+ * a tutamak/overlay (a later phase) over a real box.
+ *
+ * @param {PageRect} pageRect
+ * @param {import("./geometry.js").Rect} rect
+ * @returns {{left: number, top: number, width: number, height: number}}
+ */
+export function pageToClientRect(pageRect, rect) {
+  return {
+    left: pageRect.left + rect.x * pageRect.scale,
+    top: pageRect.top + rect.y * pageRect.scale,
+    width: rect.cx * pageRect.scale,
+    height: rect.cy * pageRect.scale,
+  };
+}
+
+/**
+ * Which page (1-based, matching `BoxLayout.page`'s convention) a client
+ * point falls on, or null if it lands on none of them — the space between
+ * pages, or above/below the whole stack. `pageRects[0]` is page 1,
+ * `pageRects[1]` is page 2, and so on: `PageRect` itself carries no page
+ * number (it is exactly the five numbers a controller measures for ONE
+ * page), so the array's own order carries that instead.
+ *
+ * @param {PageRect[]} pageRects
+ * @param {number} clientX
+ * @param {number} clientY
+ * @returns {number | null}
+ */
+export function pageAtClientPoint(pageRects, clientX, clientY) {
+  for (let i = 0; i < pageRects.length; i += 1) {
+    const rect = pageRects[i];
+    if (
+      clientX >= rect.left &&
+      clientX <= rect.left + rect.width &&
+      clientY >= rect.top &&
+      clientY <= rect.top + rect.height
+    ) {
+      return i + 1;
+    }
+  }
+  return null;
+}
+
+/**
+ * Observation only, not a rule (ADR-0018 §10.2): whether a page's measured
+ * client-px footprint scales its width and height by the SAME factor
+ * relative to the page's own pt size. `PageRect.scale` is a single number
+ * because every other function here assumes uniform scaling; this is the
+ * one place that assumption gets checked rather than silently trusted.
+ * Zero means no skew. No consumer reads this value for real behavior, and
+ * no mutation is registered for it — see the file header of
+ * `test/canvas/viewport.test.js`.
+ *
+ * @param {{width: number, height: number}} pageRectPx  raw client px measurement
+ * @param {{width: number, height: number}} pagePt      the page's own pt size (Doc.page)
+ * @returns {number}
+ */
+export function pageScaleSkew(pageRectPx, pagePt) {
+  return pageRectPx.width / pagePt.width - pageRectPx.height / pagePt.height;
+}

package/dist/canvas/z-order.js

@@ -1,171 +1,171 @@
-// Which z values a "bring to front / send to back / step forward / step
-// backward" command should write (ADR-0018 §8, §9/Karar 9). Pure planning —
-// the caller feeds the returned entries straight to `setBoxZOrder`
-// (src/commands/box.js). No src/, DOM, or history import.
-//
-// Reference set is CLOSED (§8, measured): boxes UNION decorations.
-// `Renderer.writeLayout`/`syncDecorations` write `zIndex` onto the SAME
-// page element's children, so a "bring to front" that ignored decorations
-// could leave a box BEHIND a decoration that is already above it.
-// `pageOccupants` is called with no `kind` filter for the same reason
-// snap.js does not filter it — the "is this a box or a decoration"
-// question stays in ONE file (page.js).
-//
-// z is a SPARSE integer, never renumbered: reassigning every occupant on a
-// page for a single "bring to front" would turn one user gesture into a
-// step touching every box on the page. Decorations' own z never appears in
-// the returned entries (ADR-0015: it never changes) — they are read here
-// only as part of the max/min reference set.
-//
-// `selectedIds` is assumed to name only boxes, never decorations — a
-// decoration cannot be selected in the first place (ADR-0015: not a
-// hit-test target), so this is a caller invariant, not something this file
-// re-validates.
-
-import { pageOccupants } from "./page.js";
-import { stackOrder } from "./hit-test.js";
-
-/**
- * @typedef {"front" | "back" | "forward" | "backward"} ZOrderOp
- */
-
-/**
- * @param {number} minZ
- * @returns {void}
- */
-export function requireMinZ(minZ) {
-  if (typeof minZ !== "number" || !Number.isFinite(minZ)) {
-    throw new TypeError(`zOrderPlan: minZ must be a finite number, got ${JSON.stringify(minZ)}`);
-  }
-}
-
-/**
- * `front`/`back` for a WHOLE selection at once: every selected occupant
- * gets its OWN new z, consecutive, positioned entirely above (front) or
- * below (back) the current max/min — never a single shared value. A shared
- * value would leave the group's mutual order to whichever occupant happens
- * to have the smaller `index` (its unrelated `doc.content` position),
- * silently discarding the group's actual prior stacking. Values are
- * assigned in the group's own current bottom-to-top order, so the occupant
- * that was already highest among the selection is still the highest once
- * the whole group lands above (or below) everything else.
- *
- * @param {import("./page.js").PageOccupant[]} occupants  the WHOLE page's reference set (boxes + decorations)
- * @param {import("./page.js").PageOccupant[]} ordered  `occupants`, `stackOrder`'d (top-to-bottom)
- * @param {Set<import("../model/node.js").NodeId>} selected
- * @param {"front" | "back"} end
- * @param {number} minZ
- * @returns {import("../commands/box.js").BoxZOrderEntry[]}
- */
-function edgePlan(occupants, ordered, selected, end, minZ) {
-  const selectedBottomToTop = ordered.filter((occupant) => selected.has(occupant.id)).reverse();
-  const k = selectedBottomToTop.length;
-  if (k === 0) {
-    return [];
-  }
-
-  const zs = occupants.map((occupant) => occupant.z);
-  if (end === "front") {
-    const base = Math.max(...zs) + 1;
-    return selectedBottomToTop.map((occupant, i) => ({ containerId: occupant.id, z: base + i }));
-  }
-
-  // back — the group's lowest member would land at min(zs) - k; ADR-0018
-  // §4.3b's floor-clamp pattern (CANV14) applied to z instead of cx/cy:
-  // never let that go below minZ, shifting the WHOLE group up together so
-  // it stays a contiguous, distinct block instead of several members
-  // collapsing onto the same clamped value.
-  const base = Math.max(minZ, Math.min(...zs) - k);
-  return selectedBottomToTop.map((occupant, i) => ({ containerId: occupant.id, z: base + i }));
-}
-
-/**
- * `forward`/`backward` for a WHOLE selection: each selected occupant swaps
- * z with its immediate neighbor in the CURRENT stacking order — `step: -1`
- * moves toward the front (swap with the occupant just above), `step: +1`
- * moves toward the back (swap with the occupant just below). An occupant
- * already at that edge of the page has no neighbor to swap with and is
- * left out of the result entirely.
- *
- * When two selected occupants are immediately adjacent to EACH OTHER, the
- * one further from the edge sits out this step rather than swapping with
- * its selected neighbor — trading two selected occupants' z values would
- * not change their relative order at all, and a swap needs a genuine
- * (non-selected) neighbor to make progress against. A block of N
- * consecutive selected occupants therefore advances one member per call
- * rather than shifting as a unit. Two DIFFERENT selected occupants can
- * never target the same neighbor position in one call (each position has a
- * unique -1/+1 partner), so this never produces two conflicting entries
- * for the same id.
- *
- * A DECORATION never becomes a swap partner: its own z must never appear
- * in the returned entries (ADR-0015 — no step ever targets one; `box.js`'s
- * `setBoxZOrder` would in fact silently no-op the WHOLE batch if it did,
- * since a decoration has no `doc.layout` entry). When the immediate
- * neighbor in `step`'s direction is a decoration, the search keeps walking
- * past it to the nearest actual BOX — decorations are fixed scenery a box
- * steps over, not something a step swaps with. A box's z crossing a
- * decoration's is itself enough to change their relative order; the
- * decoration's own z does not need to (and must not) move for that.
- *
- * @param {import("./page.js").PageOccupant[]} ordered  `stackOrder`'d, top-to-bottom
- * @param {Set<import("../model/node.js").NodeId>} selected
- * @param {-1 | 1} step
- * @returns {import("../commands/box.js").BoxZOrderEntry[]}
- */
-function swapPlan(ordered, selected, step) {
-  /** @type {import("../commands/box.js").BoxZOrderEntry[]} */
-  const entries = [];
-  for (let position = 0; position < ordered.length; position += 1) {
-    const occupant = ordered[position];
-    if (!selected.has(occupant.id)) {
-      continue;
-    }
-    let partnerPosition = position + step;
-    while (partnerPosition >= 0 && partnerPosition < ordered.length && ordered[partnerPosition].kind === "decoration") {
-      partnerPosition += step;
-    }
-    if (partnerPosition < 0 || partnerPosition >= ordered.length) {
-      continue;
-    }
-    const partner = ordered[partnerPosition];
-    if (selected.has(partner.id)) {
-      continue;
-    }
-    entries.push({ containerId: occupant.id, z: partner.z });
-    entries.push({ containerId: partner.id, z: occupant.z });
-  }
-  return entries;
-}
-
-/**
- * The `BoxZOrderEntry[]` a z-order command should write, ready for
- * `setBoxZOrder` (`src/commands/box.js`) — never renumbers an occupant this
- * op did not target.
- *
- * @param {import("../model/node.js").Doc} doc
- * @param {number} page
- * @param {import("../model/node.js").NodeId[]} selectedIds
- * @param {ZOrderOp} op
- * @param {number} minZ  pt — injected, no default (ADR-0018 §8, unmeasured: only `back`'s floor is decided open; front/forward/backward do not consult it)
- * @returns {import("../commands/box.js").BoxZOrderEntry[]}
- */
-export function zOrderPlan(doc, page, selectedIds, op, minZ) {
-  requireMinZ(minZ);
-  const occupants = pageOccupants(doc, page);
-  const selected = new Set(selectedIds);
-  const ordered = stackOrder(occupants);
-
-  switch (op) {
-    case "front":
-      return edgePlan(occupants, ordered, selected, "front", minZ);
-    case "back":
-      return edgePlan(occupants, ordered, selected, "back", minZ);
-    case "forward":
-      return swapPlan(ordered, selected, -1);
-    case "backward":
-      return swapPlan(ordered, selected, 1);
-    default:
-      throw new TypeError(`zOrderPlan: unknown op ${JSON.stringify(op)}`);
-  }
-}
+// Which z values a "bring to front / send to back / step forward / step
+// backward" command should write (ADR-0018 §8, §9/Karar 9). Pure planning —
+// the caller feeds the returned entries straight to `setBoxZOrder`
+// (src/commands/box.js). No src/, DOM, or history import.
+//
+// Reference set is CLOSED (§8, measured): boxes UNION decorations.
+// `Renderer.writeLayout`/`syncDecorations` write `zIndex` onto the SAME
+// page element's children, so a "bring to front" that ignored decorations
+// could leave a box BEHIND a decoration that is already above it.
+// `pageOccupants` is called with no `kind` filter for the same reason
+// snap.js does not filter it — the "is this a box or a decoration"
+// question stays in ONE file (page.js).
+//
+// z is a SPARSE integer, never renumbered: reassigning every occupant on a
+// page for a single "bring to front" would turn one user gesture into a
+// step touching every box on the page. Decorations' own z never appears in
+// the returned entries (ADR-0015: it never changes) — they are read here
+// only as part of the max/min reference set.
+//
+// `selectedIds` is assumed to name only boxes, never decorations — a
+// decoration cannot be selected in the first place (ADR-0015: not a
+// hit-test target), so this is a caller invariant, not something this file
+// re-validates.
+
+import { pageOccupants } from "./page.js";
+import { stackOrder } from "./hit-test.js";
+
+/**
+ * @typedef {"front" | "back" | "forward" | "backward"} ZOrderOp
+ */
+
+/**
+ * @param {number} minZ
+ * @returns {void}
+ */
+export function requireMinZ(minZ) {
+  if (typeof minZ !== "number" || !Number.isFinite(minZ)) {
+    throw new TypeError(`zOrderPlan: minZ must be a finite number, got ${JSON.stringify(minZ)}`);
+  }
+}
+
+/**
+ * `front`/`back` for a WHOLE selection at once: every selected occupant
+ * gets its OWN new z, consecutive, positioned entirely above (front) or
+ * below (back) the current max/min — never a single shared value. A shared
+ * value would leave the group's mutual order to whichever occupant happens
+ * to have the smaller `index` (its unrelated `doc.content` position),
+ * silently discarding the group's actual prior stacking. Values are
+ * assigned in the group's own current bottom-to-top order, so the occupant
+ * that was already highest among the selection is still the highest once
+ * the whole group lands above (or below) everything else.
+ *
+ * @param {import("./page.js").PageOccupant[]} occupants  the WHOLE page's reference set (boxes + decorations)
+ * @param {import("./page.js").PageOccupant[]} ordered  `occupants`, `stackOrder`'d (top-to-bottom)
+ * @param {Set<import("../model/node.js").NodeId>} selected
+ * @param {"front" | "back"} end
+ * @param {number} minZ
+ * @returns {import("../commands/box.js").BoxZOrderEntry[]}
+ */
+function edgePlan(occupants, ordered, selected, end, minZ) {
+  const selectedBottomToTop = ordered.filter((occupant) => selected.has(occupant.id)).reverse();
+  const k = selectedBottomToTop.length;
+  if (k === 0) {
+    return [];
+  }
+
+  const zs = occupants.map((occupant) => occupant.z);
+  if (end === "front") {
+    const base = Math.max(...zs) + 1;
+    return selectedBottomToTop.map((occupant, i) => ({ containerId: occupant.id, z: base + i }));
+  }
+
+  // back — the group's lowest member would land at min(zs) - k; ADR-0018
+  // §4.3b's floor-clamp pattern (CANV14) applied to z instead of cx/cy:
+  // never let that go below minZ, shifting the WHOLE group up together so
+  // it stays a contiguous, distinct block instead of several members
+  // collapsing onto the same clamped value.
+  const base = Math.max(minZ, Math.min(...zs) - k);
+  return selectedBottomToTop.map((occupant, i) => ({ containerId: occupant.id, z: base + i }));
+}
+
+/**
+ * `forward`/`backward` for a WHOLE selection: each selected occupant swaps
+ * z with its immediate neighbor in the CURRENT stacking order — `step: -1`
+ * moves toward the front (swap with the occupant just above), `step: +1`
+ * moves toward the back (swap with the occupant just below). An occupant
+ * already at that edge of the page has no neighbor to swap with and is
+ * left out of the result entirely.
+ *
+ * When two selected occupants are immediately adjacent to EACH OTHER, the
+ * one further from the edge sits out this step rather than swapping with
+ * its selected neighbor — trading two selected occupants' z values would
+ * not change their relative order at all, and a swap needs a genuine
+ * (non-selected) neighbor to make progress against. A block of N
+ * consecutive selected occupants therefore advances one member per call
+ * rather than shifting as a unit. Two DIFFERENT selected occupants can
+ * never target the same neighbor position in one call (each position has a
+ * unique -1/+1 partner), so this never produces two conflicting entries
+ * for the same id.
+ *
+ * A DECORATION never becomes a swap partner: its own z must never appear
+ * in the returned entries (ADR-0015 — no step ever targets one; `box.js`'s
+ * `setBoxZOrder` would in fact silently no-op the WHOLE batch if it did,
+ * since a decoration has no `doc.layout` entry). When the immediate
+ * neighbor in `step`'s direction is a decoration, the search keeps walking
+ * past it to the nearest actual BOX — decorations are fixed scenery a box
+ * steps over, not something a step swaps with. A box's z crossing a
+ * decoration's is itself enough to change their relative order; the
+ * decoration's own z does not need to (and must not) move for that.
+ *
+ * @param {import("./page.js").PageOccupant[]} ordered  `stackOrder`'d, top-to-bottom
+ * @param {Set<import("../model/node.js").NodeId>} selected
+ * @param {-1 | 1} step
+ * @returns {import("../commands/box.js").BoxZOrderEntry[]}
+ */
+function swapPlan(ordered, selected, step) {
+  /** @type {import("../commands/box.js").BoxZOrderEntry[]} */
+  const entries = [];
+  for (let position = 0; position < ordered.length; position += 1) {
+    const occupant = ordered[position];
+    if (!selected.has(occupant.id)) {
+      continue;
+    }
+    let partnerPosition = position + step;
+    while (partnerPosition >= 0 && partnerPosition < ordered.length && ordered[partnerPosition].kind === "decoration") {
+      partnerPosition += step;
+    }
+    if (partnerPosition < 0 || partnerPosition >= ordered.length) {
+      continue;
+    }
+    const partner = ordered[partnerPosition];
+    if (selected.has(partner.id)) {
+      continue;
+    }
+    entries.push({ containerId: occupant.id, z: partner.z });
+    entries.push({ containerId: partner.id, z: occupant.z });
+  }
+  return entries;
+}
+
+/**
+ * The `BoxZOrderEntry[]` a z-order command should write, ready for
+ * `setBoxZOrder` (`src/commands/box.js`) — never renumbers an occupant this
+ * op did not target.
+ *
+ * @param {import("../model/node.js").Doc} doc
+ * @param {number} page
+ * @param {import("../model/node.js").NodeId[]} selectedIds
+ * @param {ZOrderOp} op
+ * @param {number} minZ  pt — injected, no default (ADR-0018 §8, unmeasured: only `back`'s floor is decided open; front/forward/backward do not consult it)
+ * @returns {import("../commands/box.js").BoxZOrderEntry[]}
+ */
+export function zOrderPlan(doc, page, selectedIds, op, minZ) {
+  requireMinZ(minZ);
+  const occupants = pageOccupants(doc, page);
+  const selected = new Set(selectedIds);
+  const ordered = stackOrder(occupants);
+
+  switch (op) {
+    case "front":
+      return edgePlan(occupants, ordered, selected, "front", minZ);
+    case "back":
+      return edgePlan(occupants, ordered, selected, "back", minZ);
+    case "forward":
+      return swapPlan(ordered, selected, -1);
+    case "backward":
+      return swapPlan(ordered, selected, 1);
+    default:
+      throw new TypeError(`zOrderPlan: unknown op ${JSON.stringify(op)}`);
+  }
+}