@elytracms/studio 0.0.64 → 0.0.66

package/dist/components/builder/canvas-overlay-geometry.d.ts

@@ -0,0 +1,72 @@
+import type { ComponentNode } from '@elytracms/core/project-graph';
+import type { FlowAxis } from '@elytracms/studio/lib/dnd/drop-rules';
+import type { BuilderAction } from './builder-store.js';
+import type { Rect } from './canvas-rect-tracking.js';
+import type { InsertPosition } from './insert-context.js';
+/**
+ * Pure geometry + action-mapping for the canvas selection overlay (EC-404) —
+ * everything the overlay decides that does NOT touch the DOM or React, extracted
+ * so it is unit-testable in the node env: where the frame's chrome bar sits, and
+ * which tree actions its controls dispatch.
+ */
+/** Height reserved for the frame's chrome bar (the label + control cluster). */
+export declare const FRAME_BAR_HEIGHT = 24;
+/** Placement of the frame chrome bar in document coordinates. */
+export interface FrameBarPlacement {
+    top: number;
+    left: number;
+    /** `above` the frame's top edge, or `inside` its top when there's no room. */
+    placement: 'above' | 'inside';
+}
+/**
+ * Place the frame's chrome bar just above the frame's top edge, flipping to
+ * sit INSIDE the top when the edge is within a bar-height of the visible top
+ * (`docTop` = the current scroll offset, so the bar never floats above the
+ * viewport). Left-aligned to the frame.
+ */
+export declare function placeFrameBar(rect: Rect, opts: {
+    barHeight: number;
+    docTop: number;
+}): FrameBarPlacement;
+/** Which frame controls are available for a node (root has none; ends can't move further). */
+export interface FrameControls {
+    /** The composition root — no move/duplicate/delete affordances (mirrors the tree). */
+    isRoot: boolean;
+    canMoveUp: boolean;
+    canMoveDown: boolean;
+}
+/**
+ * Resolve a node's frame controls from the graph: the root gets none; a child's
+ * move affordances follow its position among its slot siblings — the identical
+ * enablement the page-tree row menu computes from `isFirst`/`isLast`.
+ */
+export declare function frameControlsFor(root: ComponentNode, nodeId: string): FrameControls;
+/** The four frame controls, in display order. */
+export type FrameControlKind = 'moveUp' | 'moveDown' | 'duplicate' | 'delete';
+/**
+ * Map a frame control to the EXISTING builder tree action it dispatches — the
+ * same `reorder`/`duplicate`/`remove` the page-tree "•••" menu fires (no new
+ * mutation path). One control, one dispatch, one undo step.
+ */
+export declare function frameControlAction(kind: FrameControlKind, nodeId: string): BuilderAction;
+/** The anchor point (document coords) a "+" affordance button centers on. */
+export interface AffordanceAnchor {
+    left: number;
+    top: number;
+}
+/**
+ * Place a "+" insertion affordance for `position` on a node's measured rect
+ * (EC-405). The returned point is the button's CENTER (the chrome CSS centers the
+ * button on it with a translate), so it sits ON the boundary:
+ *
+ *   - `before`/`after` ride the node's leading/trailing edge along the parent's
+ *     flow axis — top/bottom mid-points for a vertical flow, left/right mid-points
+ *     for a horizontal one (so the "+" always straddles the gap a drop `before`/
+ *     `after` would fill).
+ *   - `into` sits at the node's center — the affordance for dropping the first
+ *     child into an empty container.
+ *
+ * Pure over the rect + flow; no DOM, no clamping (the 16px body gutter keeps
+ * edge affordances on-canvas).
+ */
+export declare function placeAffordance(rect: Rect, position: InsertPosition, flow: FlowAxis): AffordanceAnchor;

package/dist/components/builder/canvas-overlay-geometry.js

@@ -0,0 +1,80 @@
+import { getParentInfo } from '@elytracms/core/project-graph';
+/**
+ * Pure geometry + action-mapping for the canvas selection overlay (EC-404) —
+ * everything the overlay decides that does NOT touch the DOM or React, extracted
+ * so it is unit-testable in the node env: where the frame's chrome bar sits, and
+ * which tree actions its controls dispatch.
+ */
+/** Height reserved for the frame's chrome bar (the label + control cluster). */
+export const FRAME_BAR_HEIGHT = 24;
+/**
+ * Place the frame's chrome bar just above the frame's top edge, flipping to
+ * sit INSIDE the top when the edge is within a bar-height of the visible top
+ * (`docTop` = the current scroll offset, so the bar never floats above the
+ * viewport). Left-aligned to the frame.
+ */
+export function placeFrameBar(rect, opts) {
+    const above = rect.top - opts.barHeight;
+    if (above >= opts.docTop)
+        return { top: above, left: rect.left, placement: 'above' };
+    return { top: rect.top, left: rect.left, placement: 'inside' };
+}
+/**
+ * Resolve a node's frame controls from the graph: the root gets none; a child's
+ * move affordances follow its position among its slot siblings — the identical
+ * enablement the page-tree row menu computes from `isFirst`/`isLast`.
+ */
+export function frameControlsFor(root, nodeId) {
+    const info = getParentInfo(root, nodeId);
+    if (!info)
+        return { isRoot: true, canMoveUp: false, canMoveDown: false };
+    const siblings = info.parent.slots?.[info.slot] ?? [];
+    return {
+        isRoot: false,
+        canMoveUp: info.index > 0,
+        canMoveDown: info.index < siblings.length - 1,
+    };
+}
+/**
+ * Map a frame control to the EXISTING builder tree action it dispatches — the
+ * same `reorder`/`duplicate`/`remove` the page-tree "•••" menu fires (no new
+ * mutation path). One control, one dispatch, one undo step.
+ */
+export function frameControlAction(kind, nodeId) {
+    switch (kind) {
+        case 'moveUp':
+            return { type: 'reorder', id: nodeId, delta: -1 };
+        case 'moveDown':
+            return { type: 'reorder', id: nodeId, delta: 1 };
+        case 'duplicate':
+            return { type: 'duplicate', id: nodeId };
+        case 'delete':
+            return { type: 'remove', id: nodeId };
+    }
+}
+/**
+ * Place a "+" insertion affordance for `position` on a node's measured rect
+ * (EC-405). The returned point is the button's CENTER (the chrome CSS centers the
+ * button on it with a translate), so it sits ON the boundary:
+ *
+ *   - `before`/`after` ride the node's leading/trailing edge along the parent's
+ *     flow axis — top/bottom mid-points for a vertical flow, left/right mid-points
+ *     for a horizontal one (so the "+" always straddles the gap a drop `before`/
+ *     `after` would fill).
+ *   - `into` sits at the node's center — the affordance for dropping the first
+ *     child into an empty container.
+ *
+ * Pure over the rect + flow; no DOM, no clamping (the 16px body gutter keeps
+ * edge affordances on-canvas).
+ */
+export function placeAffordance(rect, position, flow) {
+    const midX = rect.left + rect.width / 2;
+    const midY = rect.top + rect.height / 2;
+    if (position === 'into')
+        return { left: midX, top: midY };
+    if (flow === 'horizontal') {
+        return { left: position === 'before' ? rect.left : rect.left + rect.width, top: midY };
+    }
+    return { left: midX, top: position === 'before' ? rect.top : rect.top + rect.height };
+}
+//# sourceMappingURL=canvas-overlay-geometry.js.map

package/dist/components/builder/canvas-overlay-geometry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-overlay-geometry.js","sourceRoot":"","sources":["../../../src/components/builder/canvas-overlay-geometry.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ComponentNode } from '@elytracms/core/project-graph'\nimport { getParentInfo } from '@elytracms/core/project-graph'\nimport type { FlowAxis } from '@elytracms/studio/lib/dnd/drop-rules'\nimport type { BuilderAction } from './builder-store'\nimport type { Rect } from './canvas-rect-tracking'\nimport type { InsertPosition } from './insert-context'\n\n/**\n * Pure geometry + action-mapping for the canvas selection overlay (EC-404) —\n * everything the overlay decides that does NOT touch the DOM or React, extracted\n * so it is unit-testable in the node env: where the frame's chrome bar sits, and\n * which tree actions its controls dispatch.\n */\n\n/** Height reserved for the frame's chrome bar (the label + control cluster). */\nexport const FRAME_BAR_HEIGHT = 24\n\n/** Placement of the frame chrome bar in document coordinates. */\nexport interface FrameBarPlacement {\n  top: number\n  left: number\n  /** `above` the frame's top edge, or `inside` its top when there's no room. */\n  placement: 'above' | 'inside'\n}\n\n/**\n * Place the frame's chrome bar just above the frame's top edge, flipping to\n * sit INSIDE the top when the edge is within a bar-height of the visible top\n * (`docTop` = the current scroll offset, so the bar never floats above the\n * viewport). Left-aligned to the frame.\n */\nexport function placeFrameBar(rect: Rect, opts: { barHeight: number; docTop: number }): FrameBarPlacement {\n  const above = rect.top - opts.barHeight\n  if (above >= opts.docTop) return { top: above, left: rect.left, placement: 'above' }\n  return { top: rect.top, left: rect.left, placement: 'inside' }\n}\n\n/** Which frame controls are available for a node (root has none; ends can't move further). */\nexport interface FrameControls {\n  /** The composition root — no move/duplicate/delete affordances (mirrors the tree). */\n  isRoot: boolean\n  canMoveUp: boolean\n  canMoveDown: boolean\n}\n\n/**\n * Resolve a node's frame controls from the graph: the root gets none; a child's\n * move affordances follow its position among its slot siblings — the identical\n * enablement the page-tree row menu computes from `isFirst`/`isLast`.\n */\nexport function frameControlsFor(root: ComponentNode, nodeId: string): FrameControls {\n  const info = getParentInfo(root, nodeId)\n  if (!info) return { isRoot: true, canMoveUp: false, canMoveDown: false }\n  const siblings = info.parent.slots?.[info.slot] ?? []\n  return {\n    isRoot: false,\n    canMoveUp: info.index > 0,\n    canMoveDown: info.index < siblings.length - 1,\n  }\n}\n\n/** The four frame controls, in display order. */\nexport type FrameControlKind = 'moveUp' | 'moveDown' | 'duplicate' | 'delete'\n\n/**\n * Map a frame control to the EXISTING builder tree action it dispatches — the\n * same `reorder`/`duplicate`/`remove` the page-tree \"•••\" menu fires (no new\n * mutation path). One control, one dispatch, one undo step.\n */\nexport function frameControlAction(kind: FrameControlKind, nodeId: string): BuilderAction {\n  switch (kind) {\n    case 'moveUp':\n      return { type: 'reorder', id: nodeId, delta: -1 }\n    case 'moveDown':\n      return { type: 'reorder', id: nodeId, delta: 1 }\n    case 'duplicate':\n      return { type: 'duplicate', id: nodeId }\n    case 'delete':\n      return { type: 'remove', id: nodeId }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Insertion affordances (EC-405)\n// ---------------------------------------------------------------------------\n\n/** The anchor point (document coords) a \"+\" affordance button centers on. */\nexport interface AffordanceAnchor {\n  left: number\n  top: number\n}\n\n/**\n * Place a \"+\" insertion affordance for `position` on a node's measured rect\n * (EC-405). The returned point is the button's CENTER (the chrome CSS centers the\n * button on it with a translate), so it sits ON the boundary:\n *\n *   - `before`/`after` ride the node's leading/trailing edge along the parent's\n *     flow axis — top/bottom mid-points for a vertical flow, left/right mid-points\n *     for a horizontal one (so the \"+\" always straddles the gap a drop `before`/\n *     `after` would fill).\n *   - `into` sits at the node's center — the affordance for dropping the first\n *     child into an empty container.\n *\n * Pure over the rect + flow; no DOM, no clamping (the 16px body gutter keeps\n * edge affordances on-canvas).\n */\nexport function placeAffordance(rect: Rect, position: InsertPosition, flow: FlowAxis): AffordanceAnchor {\n  const midX = rect.left + rect.width / 2\n  const midY = rect.top + rect.height / 2\n  if (position === 'into') return { left: midX, top: midY }\n  if (flow === 'horizontal') {\n    return { left: position === 'before' ? rect.left : rect.left + rect.width, top: midY }\n  }\n  return { left: midX, top: position === 'before' ? rect.top : rect.top + rect.height }\n}\n"]}

package/dist/components/builder/canvas-rect-tracking.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The canvas overlay's rect-tracking core (EC-404) — the PURE, reusable half of
+ * the selection/hover overlay, kept free of React and of the DOM so the
+ * subscription + coalescing + change-detection bookkeeping is unit-testable with
+ * injected fakes (the `canvas-dnd`/`canvas-inline-editing` house pattern).
+ *
+ * The overlay draws its frames from measured node rects and must keep them glued
+ * to the page as async layout settles (images decode, fonts load, data resolves,
+ * the viewport resizes, the user scrolls). This module separates the two
+ * concerns EC-405 (insertion affordances) and EC-406 (spacing handles) will
+ * reuse:
+ *
+ *   - {@link createRectTracker} — generic bookkeeping: subscribe once, coalesce
+ *     invalidations into a single scheduled flush, re-measure, and emit ONLY when
+ *     the measured value actually changed (an injected `equals`). Pure over its
+ *     injected environment; no DOM, no React.
+ *   - {@link subscribeCanvasLayout} / {@link measureElementRect} — the thin DOM
+ *     glue that wires the real invalidation sources (scroll/resize/observers/
+ *     fonts) and reads a document-coordinate rect. Exercised live, not in jsdom.
+ */
+/** A document-coordinate rectangle (viewport rect + scroll offset). */
+export interface Rect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** Structural exact-equality of two rects (null-aware). */
+export declare function rectsEqual(a: Rect | null, b: Rect | null): boolean;
+/**
+ * The generic tracker: emits the CURRENT measured value on creation, then a new
+ * value whenever an invalidation resolves to a changed measurement. Coalescing
+ * is the injected `schedule`, which returns its OWN canceller (a compound
+ * rAF+timeout scheduler in production — see {@link scheduleFrame}); repeated
+ * invalidations before a flush collapse to one measure. `dispose` is idempotent
+ * and stops all further work.
+ */
+export interface RectTracker {
+    /** Request a coalesced re-measure (safe to call at any rate). */
+    invalidate(): void;
+    /** Unsubscribe + drop any pending flush; idempotent. */
+    dispose(): void;
+}
+export interface RectTrackerConfig<T> {
+    /** Read the current value (a rect, a geometry bundle, a set of slots …). */
+    measure(): T;
+    /** True when two measurements are equivalent — suppresses redundant emits. */
+    equals(a: T, b: T): boolean;
+    /** Receives the initial value and every subsequent CHANGED value. */
+    onChange(value: T): void;
+    /** Schedule a coalesced flush; return a canceller that unschedules it. */
+    schedule(flush: () => void): () => void;
+    /**
+     * Wire every invalidation source once, calling `invalidate` on each; return a
+     * teardown. Called exactly once during creation.
+     */
+    subscribe(invalidate: () => void): () => void;
+}
+export declare function createRectTracker<T>(config: RectTrackerConfig<T>): RectTracker;
+/** The window surface {@link scheduleFrame} needs (a real `Window` satisfies it). */
+export interface FrameScheduler {
+    requestAnimationFrame(cb: FrameRequestCallback): number;
+    cancelAnimationFrame(handle: number): void;
+    setTimeout(cb: () => void, ms: number): number;
+    clearTimeout(handle: number): void;
+}
+/**
+ * Schedule a coalesced flush on the next animation frame WITH a timeout
+ * backstop: rAF keeps the overlay paint-aligned while the canvas is on screen,
+ * and the timer guarantees the flush still runs when rAF is paused (a
+ * backgrounded/offscreen preview, or a non-painting automation environment) —
+ * otherwise a stranded rAF would freeze the tracker at its `cancelPending` gate.
+ * Whichever fires first cancels the other and runs the flush once. Returns a
+ * canceller that unschedules both.
+ */
+export declare function scheduleFrame(host: FrameScheduler, flush: () => void): () => void;
+/** The window surface the DOM glue reads (a real `Window` satisfies it). */
+interface LayoutWindow {
+    scrollX: number;
+    scrollY: number;
+    requestAnimationFrame(cb: FrameRequestCallback): number;
+    cancelAnimationFrame(handle: number): void;
+    addEventListener(type: string, listener: () => void, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: string, listener: () => void, options?: boolean | EventListenerOptions): void;
+    ResizeObserver?: typeof ResizeObserver;
+    MutationObserver?: typeof MutationObserver;
+}
+/**
+ * Measure an element's document-coordinate rect: viewport rect + scroll offset,
+ * so an absolutely-positioned overlay child in the iframe `body` stays glued to
+ * the element through scroll WITHOUT re-measuring (only layout changes move it in
+ * document space). Mirrors `SpacingHandles`' measurement convention exactly.
+ */
+export declare function measureElementRect(el: Element, win: Pick<LayoutWindow, 'scrollX' | 'scrollY'>): Rect;
+/** Locate a rendered node's editable wrapper and measure its document rect. */
+export declare function measureNodeRect(doc: Document, nodeId: string | null): Rect | null;
+/**
+ * Measure the `[data-ec-prop]` marker element for `propName` that belongs to
+ * node `nodeId` (EC-408 reverse highlight): the first matching marker inside the
+ * node's wrapper whose NEAREST node wrapper is that node — so a nested child
+ * node's same-named marker is never mistaken for the parent's. `null` when the
+ * node isn't rendered or carries no such marker (→ no highlight, silently).
+ */
+export declare function measurePropRect(doc: Document, nodeId: string | null, propName: string | null): Rect | null;
+/**
+ * Wire every invalidation source the canvas overlay needs and return a teardown:
+ *
+ *   - `scroll` (capture — inner scroll containers bubble nothing) + `resize` on
+ *     the iframe window;
+ *   - a `ResizeObserver` on the tracked target elements AND the body (a sibling
+ *     node growing pushes the target in document space — an image decoding, a
+ *     data list filling in);
+ *   - a `MutationObserver` on the body subtree (`childList` — nodes inserted or
+ *     removed by editing or async data), deliberately NOT observing attributes
+ *     so the overlay's own inline-style writes can't feed back a measure storm;
+ *   - `document.fonts.ready` — a one-shot re-measure once web fonts settle
+ *     (their metrics reflow text after first paint).
+ *
+ * Every source funnels through `invalidate`, which the tracker coalesces to one
+ * measure per frame. `targets` is read lazily so the caller can re-point the
+ * ResizeObserver on selection/hover changes by rebuilding the subscription.
+ */
+export declare function subscribeCanvasLayout(doc: Document, targets: () => Element[], invalidate: () => void): () => void;
+export {};

package/dist/components/builder/canvas-rect-tracking.js

@@ -0,0 +1,198 @@
+/**
+ * The canvas overlay's rect-tracking core (EC-404) — the PURE, reusable half of
+ * the selection/hover overlay, kept free of React and of the DOM so the
+ * subscription + coalescing + change-detection bookkeeping is unit-testable with
+ * injected fakes (the `canvas-dnd`/`canvas-inline-editing` house pattern).
+ *
+ * The overlay draws its frames from measured node rects and must keep them glued
+ * to the page as async layout settles (images decode, fonts load, data resolves,
+ * the viewport resizes, the user scrolls). This module separates the two
+ * concerns EC-405 (insertion affordances) and EC-406 (spacing handles) will
+ * reuse:
+ *
+ *   - {@link createRectTracker} — generic bookkeeping: subscribe once, coalesce
+ *     invalidations into a single scheduled flush, re-measure, and emit ONLY when
+ *     the measured value actually changed (an injected `equals`). Pure over its
+ *     injected environment; no DOM, no React.
+ *   - {@link subscribeCanvasLayout} / {@link measureElementRect} — the thin DOM
+ *     glue that wires the real invalidation sources (scroll/resize/observers/
+ *     fonts) and reads a document-coordinate rect. Exercised live, not in jsdom.
+ */
+/** Structural exact-equality of two rects (null-aware). */
+export function rectsEqual(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    return a.left === b.left && a.top === b.top && a.width === b.width && a.height === b.height;
+}
+export function createRectTracker(config) {
+    let last = config.measure();
+    let cancelPending = null;
+    let disposed = false;
+    const flush = () => {
+        cancelPending = null;
+        if (disposed)
+            return;
+        const next = config.measure();
+        if (!config.equals(last, next)) {
+            last = next;
+            config.onChange(next);
+        }
+    };
+    const invalidate = () => {
+        if (disposed || cancelPending !== null)
+            return;
+        cancelPending = config.schedule(flush);
+    };
+    // Emit the initial measurement, then subscribe. (Emitting first means a
+    // synchronous subscription that invalidates immediately still coalesces
+    // against a stable baseline.)
+    config.onChange(last);
+    const unsubscribe = config.subscribe(invalidate);
+    return {
+        invalidate,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            if (cancelPending !== null) {
+                cancelPending();
+                cancelPending = null;
+            }
+            unsubscribe();
+        },
+    };
+}
+/**
+ * Schedule a coalesced flush on the next animation frame WITH a timeout
+ * backstop: rAF keeps the overlay paint-aligned while the canvas is on screen,
+ * and the timer guarantees the flush still runs when rAF is paused (a
+ * backgrounded/offscreen preview, or a non-painting automation environment) —
+ * otherwise a stranded rAF would freeze the tracker at its `cancelPending` gate.
+ * Whichever fires first cancels the other and runs the flush once. Returns a
+ * canceller that unschedules both.
+ */
+export function scheduleFrame(host, flush) {
+    let raf = 0;
+    let timer = 0;
+    let done = false;
+    const fire = () => {
+        if (done)
+            return;
+        done = true;
+        host.cancelAnimationFrame(raf);
+        host.clearTimeout(timer);
+        flush();
+    };
+    raf = host.requestAnimationFrame(fire);
+    timer = host.setTimeout(fire, 100);
+    return () => {
+        if (done)
+            return;
+        done = true;
+        host.cancelAnimationFrame(raf);
+        host.clearTimeout(timer);
+    };
+}
+/**
+ * Measure an element's document-coordinate rect: viewport rect + scroll offset,
+ * so an absolutely-positioned overlay child in the iframe `body` stays glued to
+ * the element through scroll WITHOUT re-measuring (only layout changes move it in
+ * document space). Mirrors `SpacingHandles`' measurement convention exactly.
+ */
+export function measureElementRect(el, win) {
+    const r = el.getBoundingClientRect();
+    return { left: r.left + win.scrollX, top: r.top + win.scrollY, width: r.width, height: r.height };
+}
+/** Locate a rendered node's editable wrapper and measure its document rect. */
+export function measureNodeRect(doc, nodeId) {
+    if (!nodeId)
+        return null;
+    const win = doc.defaultView;
+    if (!win)
+        return null;
+    const el = doc.querySelector(`[data-ec-node-id="${nodeId}"]`);
+    return el ? measureElementRect(el, win) : null;
+}
+/**
+ * Measure the `[data-ec-prop]` marker element for `propName` that belongs to
+ * node `nodeId` (EC-408 reverse highlight): the first matching marker inside the
+ * node's wrapper whose NEAREST node wrapper is that node — so a nested child
+ * node's same-named marker is never mistaken for the parent's. `null` when the
+ * node isn't rendered or carries no such marker (→ no highlight, silently).
+ */
+export function measurePropRect(doc, nodeId, propName) {
+    if (!nodeId || !propName)
+        return null;
+    const win = doc.defaultView;
+    if (!win)
+        return null;
+    const wrapper = doc.querySelector(`[data-ec-node-id="${nodeId}"]`);
+    if (!wrapper)
+        return null;
+    // Prop names are plain manifest keys; escape defensively where CSS.escape exists.
+    const escaped = win.CSS?.escape?.(propName) ?? propName;
+    const markers = wrapper.querySelectorAll(`[data-ec-prop="${escaped}"]`);
+    for (const marker of markers) {
+        if (marker.closest('[data-ec-node-id]') === wrapper)
+            return measureElementRect(marker, win);
+    }
+    return null;
+}
+/**
+ * Wire every invalidation source the canvas overlay needs and return a teardown:
+ *
+ *   - `scroll` (capture — inner scroll containers bubble nothing) + `resize` on
+ *     the iframe window;
+ *   - a `ResizeObserver` on the tracked target elements AND the body (a sibling
+ *     node growing pushes the target in document space — an image decoding, a
+ *     data list filling in);
+ *   - a `MutationObserver` on the body subtree (`childList` — nodes inserted or
+ *     removed by editing or async data), deliberately NOT observing attributes
+ *     so the overlay's own inline-style writes can't feed back a measure storm;
+ *   - `document.fonts.ready` — a one-shot re-measure once web fonts settle
+ *     (their metrics reflow text after first paint).
+ *
+ * Every source funnels through `invalidate`, which the tracker coalesces to one
+ * measure per frame. `targets` is read lazily so the caller can re-point the
+ * ResizeObserver on selection/hover changes by rebuilding the subscription.
+ */
+export function subscribeCanvasLayout(doc, targets, invalidate) {
+    const win = doc.defaultView;
+    if (!win)
+        return () => { };
+    const teardowns = [];
+    win.addEventListener('scroll', invalidate, true);
+    win.addEventListener('resize', invalidate);
+    teardowns.push(() => {
+        win.removeEventListener('scroll', invalidate, true);
+        win.removeEventListener('resize', invalidate);
+    });
+    const RO = win.ResizeObserver;
+    if (RO) {
+        const ro = new RO(() => invalidate());
+        for (const el of targets())
+            ro.observe(el);
+        if (doc.body)
+            ro.observe(doc.body);
+        teardowns.push(() => ro.disconnect());
+    }
+    const MO = win.MutationObserver;
+    if (MO && doc.body) {
+        const mo = new MO(() => invalidate());
+        mo.observe(doc.body, { childList: true, subtree: true });
+        teardowns.push(() => mo.disconnect());
+    }
+    const fonts = doc.fonts;
+    if (fonts?.ready) {
+        let cancelled = false;
+        fonts.ready.then(() => !cancelled && invalidate()).catch(() => { });
+        teardowns.push(() => {
+            cancelled = true;
+        });
+    }
+    return () => {
+        for (const t of teardowns)
+            t();
+    };
+}
+//# sourceMappingURL=canvas-rect-tracking.js.map

package/dist/components/builder/canvas-rect-tracking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-rect-tracking.js","sourceRoot":"","sources":["../../../src/components/builder/canvas-rect-tracking.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The canvas overlay's rect-tracking core (EC-404) — the PURE, reusable half of\n * the selection/hover overlay, kept free of React and of the DOM so the\n * subscription + coalescing + change-detection bookkeeping is unit-testable with\n * injected fakes (the `canvas-dnd`/`canvas-inline-editing` house pattern).\n *\n * The overlay draws its frames from measured node rects and must keep them glued\n * to the page as async layout settles (images decode, fonts load, data resolves,\n * the viewport resizes, the user scrolls). This module separates the two\n * concerns EC-405 (insertion affordances) and EC-406 (spacing handles) will\n * reuse:\n *\n *   - {@link createRectTracker} — generic bookkeeping: subscribe once, coalesce\n *     invalidations into a single scheduled flush, re-measure, and emit ONLY when\n *     the measured value actually changed (an injected `equals`). Pure over its\n *     injected environment; no DOM, no React.\n *   - {@link subscribeCanvasLayout} / {@link measureElementRect} — the thin DOM\n *     glue that wires the real invalidation sources (scroll/resize/observers/\n *     fonts) and reads a document-coordinate rect. Exercised live, not in jsdom.\n */\n\n/** A document-coordinate rectangle (viewport rect + scroll offset). */\nexport interface Rect {\n  left: number\n  top: number\n  width: number\n  height: number\n}\n\n/** Structural exact-equality of two rects (null-aware). */\nexport function rectsEqual(a: Rect | null, b: Rect | null): boolean {\n  if (a === null || b === null) return a === b\n  return a.left === b.left && a.top === b.top && a.width === b.width && a.height === b.height\n}\n\n/**\n * The generic tracker: emits the CURRENT measured value on creation, then a new\n * value whenever an invalidation resolves to a changed measurement. Coalescing\n * is the injected `schedule`, which returns its OWN canceller (a compound\n * rAF+timeout scheduler in production — see {@link scheduleFrame}); repeated\n * invalidations before a flush collapse to one measure. `dispose` is idempotent\n * and stops all further work.\n */\nexport interface RectTracker {\n  /** Request a coalesced re-measure (safe to call at any rate). */\n  invalidate(): void\n  /** Unsubscribe + drop any pending flush; idempotent. */\n  dispose(): void\n}\n\nexport interface RectTrackerConfig<T> {\n  /** Read the current value (a rect, a geometry bundle, a set of slots …). */\n  measure(): T\n  /** True when two measurements are equivalent — suppresses redundant emits. */\n  equals(a: T, b: T): boolean\n  /** Receives the initial value and every subsequent CHANGED value. */\n  onChange(value: T): void\n  /** Schedule a coalesced flush; return a canceller that unschedules it. */\n  schedule(flush: () => void): () => void\n  /**\n   * Wire every invalidation source once, calling `invalidate` on each; return a\n   * teardown. Called exactly once during creation.\n   */\n  subscribe(invalidate: () => void): () => void\n}\n\nexport function createRectTracker<T>(config: RectTrackerConfig<T>): RectTracker {\n  let last = config.measure()\n  let cancelPending: (() => void) | null = null\n  let disposed = false\n\n  const flush = (): void => {\n    cancelPending = null\n    if (disposed) return\n    const next = config.measure()\n    if (!config.equals(last, next)) {\n      last = next\n      config.onChange(next)\n    }\n  }\n\n  const invalidate = (): void => {\n    if (disposed || cancelPending !== null) return\n    cancelPending = config.schedule(flush)\n  }\n\n  // Emit the initial measurement, then subscribe. (Emitting first means a\n  // synchronous subscription that invalidates immediately still coalesces\n  // against a stable baseline.)\n  config.onChange(last)\n  const unsubscribe = config.subscribe(invalidate)\n\n  return {\n    invalidate,\n    dispose(): void {\n      if (disposed) return\n      disposed = true\n      if (cancelPending !== null) {\n        cancelPending()\n        cancelPending = null\n      }\n      unsubscribe()\n    },\n  }\n}\n\n/** The window surface {@link scheduleFrame} needs (a real `Window` satisfies it). */\nexport interface FrameScheduler {\n  requestAnimationFrame(cb: FrameRequestCallback): number\n  cancelAnimationFrame(handle: number): void\n  // Browser `Window.setTimeout` returns a number (not the Node `Timeout` handle).\n  setTimeout(cb: () => void, ms: number): number\n  clearTimeout(handle: number): void\n}\n\n/**\n * Schedule a coalesced flush on the next animation frame WITH a timeout\n * backstop: rAF keeps the overlay paint-aligned while the canvas is on screen,\n * and the timer guarantees the flush still runs when rAF is paused (a\n * backgrounded/offscreen preview, or a non-painting automation environment) —\n * otherwise a stranded rAF would freeze the tracker at its `cancelPending` gate.\n * Whichever fires first cancels the other and runs the flush once. Returns a\n * canceller that unschedules both.\n */\nexport function scheduleFrame(host: FrameScheduler, flush: () => void): () => void {\n  let raf = 0\n  let timer = 0\n  let done = false\n  const fire = (): void => {\n    if (done) return\n    done = true\n    host.cancelAnimationFrame(raf)\n    host.clearTimeout(timer)\n    flush()\n  }\n  raf = host.requestAnimationFrame(fire)\n  timer = host.setTimeout(fire, 100)\n  return () => {\n    if (done) return\n    done = true\n    host.cancelAnimationFrame(raf)\n    host.clearTimeout(timer)\n  }\n}\n\n/** The window surface the DOM glue reads (a real `Window` satisfies it). */\ninterface LayoutWindow {\n  scrollX: number\n  scrollY: number\n  requestAnimationFrame(cb: FrameRequestCallback): number\n  cancelAnimationFrame(handle: number): void\n  addEventListener(type: string, listener: () => void, options?: boolean | AddEventListenerOptions): void\n  removeEventListener(type: string, listener: () => void, options?: boolean | EventListenerOptions): void\n  ResizeObserver?: typeof ResizeObserver\n  MutationObserver?: typeof MutationObserver\n}\n\n/**\n * Measure an element's document-coordinate rect: viewport rect + scroll offset,\n * so an absolutely-positioned overlay child in the iframe `body` stays glued to\n * the element through scroll WITHOUT re-measuring (only layout changes move it in\n * document space). Mirrors `SpacingHandles`' measurement convention exactly.\n */\nexport function measureElementRect(el: Element, win: Pick<LayoutWindow, 'scrollX' | 'scrollY'>): Rect {\n  const r = el.getBoundingClientRect()\n  return { left: r.left + win.scrollX, top: r.top + win.scrollY, width: r.width, height: r.height }\n}\n\n/** Locate a rendered node's editable wrapper and measure its document rect. */\nexport function measureNodeRect(doc: Document, nodeId: string | null): Rect | null {\n  if (!nodeId) return null\n  const win = doc.defaultView\n  if (!win) return null\n  const el = doc.querySelector(`[data-ec-node-id=\"${nodeId}\"]`)\n  return el ? measureElementRect(el, win) : null\n}\n\n/**\n * Measure the `[data-ec-prop]` marker element for `propName` that belongs to\n * node `nodeId` (EC-408 reverse highlight): the first matching marker inside the\n * node's wrapper whose NEAREST node wrapper is that node — so a nested child\n * node's same-named marker is never mistaken for the parent's. `null` when the\n * node isn't rendered or carries no such marker (→ no highlight, silently).\n */\nexport function measurePropRect(\n  doc: Document,\n  nodeId: string | null,\n  propName: string | null,\n): Rect | null {\n  if (!nodeId || !propName) return null\n  const win = doc.defaultView\n  if (!win) return null\n  const wrapper = doc.querySelector(`[data-ec-node-id=\"${nodeId}\"]`)\n  if (!wrapper) return null\n  // Prop names are plain manifest keys; escape defensively where CSS.escape exists.\n  const escaped = (win as Window & typeof globalThis).CSS?.escape?.(propName) ?? propName\n  const markers = wrapper.querySelectorAll(`[data-ec-prop=\"${escaped}\"]`)\n  for (const marker of markers) {\n    if (marker.closest('[data-ec-node-id]') === wrapper) return measureElementRect(marker, win)\n  }\n  return null\n}\n\n/**\n * Wire every invalidation source the canvas overlay needs and return a teardown:\n *\n *   - `scroll` (capture — inner scroll containers bubble nothing) + `resize` on\n *     the iframe window;\n *   - a `ResizeObserver` on the tracked target elements AND the body (a sibling\n *     node growing pushes the target in document space — an image decoding, a\n *     data list filling in);\n *   - a `MutationObserver` on the body subtree (`childList` — nodes inserted or\n *     removed by editing or async data), deliberately NOT observing attributes\n *     so the overlay's own inline-style writes can't feed back a measure storm;\n *   - `document.fonts.ready` — a one-shot re-measure once web fonts settle\n *     (their metrics reflow text after first paint).\n *\n * Every source funnels through `invalidate`, which the tracker coalesces to one\n * measure per frame. `targets` is read lazily so the caller can re-point the\n * ResizeObserver on selection/hover changes by rebuilding the subscription.\n */\nexport function subscribeCanvasLayout(\n  doc: Document,\n  targets: () => Element[],\n  invalidate: () => void,\n): () => void {\n  const win = doc.defaultView as LayoutWindow | null\n  if (!win) return () => {}\n  const teardowns: Array<() => void> = []\n\n  win.addEventListener('scroll', invalidate, true)\n  win.addEventListener('resize', invalidate)\n  teardowns.push(() => {\n    win.removeEventListener('scroll', invalidate, true)\n    win.removeEventListener('resize', invalidate)\n  })\n\n  const RO = win.ResizeObserver\n  if (RO) {\n    const ro = new RO(() => invalidate())\n    for (const el of targets()) ro.observe(el)\n    if (doc.body) ro.observe(doc.body)\n    teardowns.push(() => ro.disconnect())\n  }\n\n  const MO = win.MutationObserver\n  if (MO && doc.body) {\n    const mo = new MO(() => invalidate())\n    mo.observe(doc.body, { childList: true, subtree: true })\n    teardowns.push(() => mo.disconnect())\n  }\n\n  const fonts = (doc as Document & { fonts?: { ready?: Promise<unknown> } }).fonts\n  if (fonts?.ready) {\n    let cancelled = false\n    fonts.ready.then(() => !cancelled && invalidate()).catch(() => {})\n    teardowns.push(() => {\n      cancelled = true\n    })\n  }\n\n  return () => {\n    for (const t of teardowns) t()\n  }\n}\n"]}