silvery 0.19.2 → 0.21.1

package/dist/layout-signals-Dch2EiCy.mjs

@@ -0,0 +1,1111 @@
+import { i as signal } from "./src-WeA_J4BV.mjs";
+//#region packages/ag/src/types.ts
+/**
+* Check if two rects are equal (same position and size).
+*/
+function rectEqual$1(a, b) {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+}
+//#endregion
+//#region packages/ag/src/wrap-measurer.ts
+let _measurer = null;
+/**
+* Register the active wrap measurer. Pass `null` to clear (test teardown,
+* or a Term disposing its runtime).
+*
+* Idempotent: setting the same reference twice is a no-op. Setting a new
+* reference replaces the previous one — there's no stack. v1 assumes a
+* single Term-per-process consumer; multi-Term setups need a different
+* dispatch (see file header).
+*/
+function setWrapMeasurer(m) {
+	_measurer = m;
+}
+/**
+* Read the active wrap measurer, or `null` if none is registered.
+*
+* Geometry helpers (`computeSelectionFragments` is the v1 consumer) call
+* this at compute-time — not at module-load — so the registration order
+* doesn't matter. The fragment helper falls back to `\n`-split when this
+* returns null.
+*/
+function getWrapMeasurer() {
+	return _measurer;
+}
+//#endregion
+//#region packages/ag/src/place-floating.ts
+function splitPlacement(placement) {
+	const dashIdx = placement.indexOf("-");
+	return {
+		side: placement.slice(0, dashIdx),
+		align: placement.slice(dashIdx + 1)
+	};
+}
+function oppositePlacement(placement) {
+	const { side, align } = splitPlacement(placement);
+	return `${{
+		top: "bottom",
+		bottom: "top",
+		left: "right",
+		right: "left"
+	}[side]}-${align}`;
+}
+function rectFitsWithin(rect, boundary) {
+	return rect.x >= boundary.x && rect.y >= boundary.y && rect.x + rect.width <= boundary.x + boundary.width && rect.y + rect.height <= boundary.y + boundary.height;
+}
+function clampAxis(value, min, max) {
+	if (max < min) return min;
+	return Math.min(max, Math.max(min, value));
+}
+function shiftIntoBoundary(rect, boundary) {
+	return {
+		x: clampAxis(rect.x, boundary.x, boundary.x + boundary.width - rect.width),
+		y: clampAxis(rect.y, boundary.y, boundary.y + boundary.height - rect.height),
+		width: rect.width,
+		height: rect.height
+	};
+}
+function rectEqual(a, b) {
+	return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+}
+function sideOverflow(rect, boundary, side) {
+	switch (side) {
+		case "top": return Math.max(0, boundary.y - rect.y);
+		case "bottom": return Math.max(0, rect.y + rect.height - (boundary.y + boundary.height));
+		case "left": return Math.max(0, boundary.x - rect.x);
+		case "right": return Math.max(0, rect.x + rect.width - (boundary.x + boundary.width));
+	}
+}
+/**
+* Compute the absolute rect at which a floating decoration should be painted
+* relative to its anchor.
+*
+* Inputs:
+*   - `anchor`: the anchor's rect (typically `findAnchor(root, id)` →
+*     `contentRect`). Origin in the same absolute terminal cell space as
+*     other rect signals.
+*   - `target.{width, height}`: intrinsic size of the floating decoration.
+*     Both must be `>= 0` — this function does not enforce minimums; callers
+*     pass through what their renderer asked for.
+*   - `placement`: 12-placement vocabulary. See module docstring for the
+*     visual reference.
+*
+* Output: `Rect` in the same coordinate space as `anchor`. Width/height equal
+* `target.width`/`target.height` exactly (no clamping, no shifting).
+*
+* **Pure**: no allocation other than the result rect, no I/O, no logging.
+* Suitable for property tests and SILVERY_STRICT cross-checks.
+*/
+function placeFloating(anchor, target, placement, options = {}) {
+	const { x: ax, y: ay, width: aw, height: ah } = anchor;
+	const tw = target.width;
+	const th = target.height;
+	const { side, align } = splitPlacement(placement);
+	let x = 0;
+	let y = 0;
+	if (side === "top" || side === "bottom") {
+		y = side === "top" ? ay - th : ay + ah;
+		if (align === "start") x = ax;
+		else if (align === "end") x = ax + aw - tw;
+		else x = ax + Math.round((aw - tw) / 2);
+	} else {
+		x = side === "left" ? ax - tw : ax + aw;
+		if (align === "start") y = ay;
+		else if (align === "end") y = ay + ah - th;
+		else y = ay + Math.round((ah - th) / 2);
+	}
+	const offset = options.offset ?? 0;
+	const alignOffset = options.alignOffset ?? 0;
+	if (side === "top") y -= offset;
+	else if (side === "bottom") y += offset;
+	else if (side === "left") x -= offset;
+	else x += offset;
+	if (side === "top" || side === "bottom") x += alignOffset;
+	else y += alignOffset;
+	return {
+		x,
+		y,
+		width: tw,
+		height: th
+	};
+}
+/**
+* Resolve a floating rect with optional viewport collision handling.
+*
+* This is the collision-aware peer of `placeFloating`. The fixed-placement
+* helper remains intentionally simple and deterministic; this function adds
+* the behavior needed by declarative popovers/tooltips: gap offsets, alignment
+* nudges, side flipping, viewport shifting, and hide-on-overflow.
+*/
+function resolveFloatingPlacement(anchor, target, placement, options = {}) {
+	const boundary = options.boundary ?? null;
+	const strategy = options.collisionStrategy ?? "none";
+	const requested = placeFloating(anchor, target, placement, options);
+	if (!boundary || strategy === "none") return {
+		rect: requested,
+		placement,
+		flipped: false,
+		shifted: false
+	};
+	if (strategy === "hide") return rectFitsWithin(requested, boundary) ? {
+		rect: requested,
+		placement,
+		flipped: false,
+		shifted: false
+	} : null;
+	let finalPlacement = placement;
+	let rect = requested;
+	let flipped = false;
+	if (strategy === "flip" || strategy === "flip-then-shift") {
+		const side = splitPlacement(placement).side;
+		const requestedSideOverflow = sideOverflow(requested, boundary, side);
+		if (requestedSideOverflow > 0) {
+			const candidatePlacement = oppositePlacement(placement);
+			const candidate = placeFloating(anchor, target, candidatePlacement, options);
+			const candidateSide = splitPlacement(candidatePlacement).side;
+			if (sideOverflow(candidate, boundary, candidateSide) < requestedSideOverflow) {
+				finalPlacement = candidatePlacement;
+				rect = candidate;
+				flipped = true;
+			}
+		}
+	}
+	let shifted = false;
+	if (strategy === "shift" || strategy === "flip-then-shift") {
+		const shiftedRect = shiftIntoBoundary(rect, boundary);
+		shifted = !rectEqual(shiftedRect, rect);
+		rect = shiftedRect;
+	}
+	return {
+		rect,
+		placement: finalPlacement,
+		flipped,
+		shifted
+	};
+}
+//#endregion
+//#region packages/ag/src/layout-signals.ts
+/**
+* withLayoutSignals — reactive signal layer for AgNode layout outputs.
+*
+* Composable plugin that wraps an AgNode with reactive signals for layout
+* rects, text content, and focus state. Engine-agnostic — works with
+* Flexily, Yoga, or any future layout engine.
+*
+* Signals are WeakMap-backed and lazily created. Nodes without subscribers
+* pay zero cost. After layout completes, the pipeline calls `syncSignals()`
+* to propagate imperative state into signals.
+*
+* ## Usage
+*
+* ```ts
+* import { getLayoutSignals, syncSignals } from "@silvery/ag/layout-signals"
+*
+* // Get (or create) signals for a node
+* const signals = getLayoutSignals(node)
+* signals.boxRect()       // read current rect
+* signals.textContent()   // read current text
+*
+* // After layout/reconciler mutations, sync imperative → reactive
+* syncSignals(node)
+* ```
+*
+* ## Three-layer stack
+*
+* Layer 0: alien-signals (signal, computed, effect)
+* Layer 1: getLayoutSignals() — this module (@silvery/ag, framework-agnostic)
+* Layer 2: useSignal(signal) — @silvery/ag-react (React bridge)
+* Layer 3: useBoxRect(), useAgNode() — semantic convenience hooks
+*/
+const permanentlyObservedLayoutSignals = /* @__PURE__ */ new WeakMap();
+const observedLayoutSignals = /* @__PURE__ */ new WeakMap();
+const retainedLayoutSignals = /* @__PURE__ */ new WeakMap();
+function addObservedLayoutSignal(node, key) {
+	let observed = observedLayoutSignals.get(node);
+	if (!observed) {
+		observed = /* @__PURE__ */ new Set();
+		observedLayoutSignals.set(node, observed);
+	}
+	observed.add(key);
+}
+function markObservedLayoutSignal(node, key) {
+	addObservedLayoutSignal(node, key);
+	let permanent = permanentlyObservedLayoutSignals.get(node);
+	if (!permanent) {
+		permanent = /* @__PURE__ */ new Set();
+		permanentlyObservedLayoutSignals.set(node, permanent);
+	}
+	permanent.add(key);
+}
+function observeLayoutSignal(node, key) {
+	addObservedLayoutSignal(node, key);
+	let retained = retainedLayoutSignals.get(node);
+	if (!retained) {
+		retained = /* @__PURE__ */ new Map();
+		retainedLayoutSignals.set(node, retained);
+	}
+	retained.set(key, (retained.get(key) ?? 0) + 1);
+	let released = false;
+	return () => {
+		if (released) return;
+		released = true;
+		const current = retainedLayoutSignals.get(node);
+		if (!current) return;
+		const next = (current.get(key) ?? 0) - 1;
+		if (next > 0) {
+			current.set(key, next);
+			return;
+		}
+		current.delete(key);
+		if (current.size === 0) retainedLayoutSignals.delete(node);
+		if (!permanentlyObservedLayoutSignals.get(node)?.has(key)) observedLayoutSignals.get(node)?.delete(key);
+	};
+}
+function cursorRectEqual(a, b) {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	return a.x === b.x && a.y === b.y && a.visible === b.visible && a.shape === b.shape;
+}
+/**
+* Per-field equality on a list of rects. Used to skip selection-fragment
+* signal writes when nothing changed — mirrors the rect-tuple equality
+* pattern used for boxRect/scrollRect/screenRect/contentRect/cursorRect.
+*
+* Reference equality is checked first (the common no-op path); only when
+* lengths match do we walk the entries. An empty array is the canonical
+* "no fragments" state — the equality path treats `[]` and `[]` as equal
+* by length-zero, so collapsed/no-selection nodes don't churn the signal.
+*/
+function selectionFragmentsEqual(a, b) {
+	if (a === b) return true;
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (!rectEqual$1(a[i] ?? null, b[i] ?? null)) return false;
+	return true;
+}
+/**
+* Stable empty-rects sentinel — `selectionFragments` defaults to this when a
+* node has no `selectionIntent` declared. Reusing the same array reference
+* means subscribers see reference-stable "no selection" frames and can skip
+* downstream re-computation. The array is frozen so accidental mutation
+* never corrupts the sentinel.
+*/
+const EMPTY_FRAGMENTS = Object.freeze([]);
+/**
+* Stable empty-decorations sentinel — `decorationRects` defaults to this when
+* a node has no `decorations` BoxProp. Same reference-stability story as
+* `EMPTY_FRAGMENTS`.
+*/
+const EMPTY_DECORATION_RECTS = Object.freeze([]);
+const signalMap = /* @__PURE__ */ new WeakMap();
+/**
+* Get or create layout signals for a node.
+*
+* Lazily created on first access. Automatically garbage-collected
+* when the node is removed from the tree (WeakMap semantics).
+*/
+function getLayoutSignals(node) {
+	let s = signalMap.get(node);
+	if (!s) {
+		s = {
+			boxRect: signal(node.boxRect),
+			scrollRect: signal(node.scrollRect),
+			screenRect: signal(node.screenRect),
+			boxRectCommitted: signal(node.boxRect),
+			scrollRectCommitted: signal(node.scrollRect),
+			screenRectCommitted: signal(node.screenRect),
+			contentRect: signal(computeContentRect(node)),
+			cursorRect: signal(computeCursorRect(node)),
+			focusedNodeId: signal(computeFocusedNodeId(node)),
+			selectionFragments: signal(computeSelectionFragments(node)),
+			scrollState: signal(snapshotScrollState(node)),
+			anchorRect: signal(computeAnchorRect(node)),
+			parkRect: signal(computeParkRect(node)),
+			decorationRects: signal(EMPTY_DECORATION_RECTS),
+			textContent: signal(node.textContent),
+			focused: signal(node.interactiveState?.focused ?? false)
+		};
+		signalMap.set(node, s);
+	}
+	return s;
+}
+/**
+* Compute the content-box rect for a node — `scrollRect` minus border and
+* padding (CSS content area in absolute terminal coordinates).
+*
+* Returns null when `scrollRect` is not yet populated (pre-layout) or when
+* border + padding would shrink the area to zero/negative width or height
+* (clipped/empty content area).
+*
+* The math is the canonical "border + padding" calculation that the layout
+* engine uses internally. Lifted here so consumers (cursor positioning,
+* popover anchors, selection overlays) read one signal instead of re-deriving
+* the offsets at every call site.
+*/
+function computeContentRect(node) {
+	const props = node.props;
+	const scroll = node.scrollRect;
+	if (!scroll) return null;
+	const padLeft = props?.paddingLeft ?? props?.paddingX ?? props?.padding ?? 0;
+	const padRight = props?.paddingRight ?? props?.paddingX ?? props?.padding ?? 0;
+	const padTop = props?.paddingTop ?? props?.paddingY ?? props?.padding ?? 0;
+	const padBottom = props?.paddingBottom ?? props?.paddingY ?? props?.padding ?? 0;
+	const borderLeft = props?.borderStyle ? 1 : 0;
+	const borderRight = props?.borderStyle ? 1 : 0;
+	const borderTop = props?.borderStyle ? 1 : 0;
+	const borderBottom = props?.borderStyle ? 1 : 0;
+	const x = scroll.x + borderLeft + padLeft;
+	const y = scroll.y + borderTop + padTop;
+	const width = scroll.width - borderLeft - borderRight - padLeft - padRight;
+	const height = scroll.height - borderTop - borderBottom - padTop - padBottom;
+	if (width <= 0 || height <= 0) return null;
+	return {
+		x,
+		y,
+		width,
+		height
+	};
+}
+/**
+* Compute the absolute caret rect for a node based on its `cursorOffset`
+* prop and current `contentRect`. Caret coordinates are content-area-relative
+* (inside border + padding), so this delegates to `computeContentRect` for
+* the origin instead of redoing the border/padding math here.
+*
+* Returns null when:
+* - the node has no `cursorOffset` prop, OR
+* - `scrollRect` is not yet populated (pre-layout), OR
+* - the content box collapsed to zero/negative size (no place to draw).
+*
+* `computeContentRect` keeps cursor positioning and overlay anchoring on the
+* same origin — Phase 4 / overlay-anchor consumers read `contentRect`
+* directly and won't drift from where the caret lands. See bead
+* `km-silvery.cursor-invariants` invariant 3.
+*/
+function computeCursorRect(node) {
+	const offset = node.props?.cursorOffset;
+	if (!offset) return null;
+	const content = computeContentRect(node);
+	if (!content) return null;
+	return {
+		x: content.x + offset.col,
+		y: content.y + offset.row,
+		visible: offset.visible !== false,
+		shape: offset.shape
+	};
+}
+/**
+* Compute the focused-node id for a node based on its `focused` BoxProp.
+*
+* Returns the node's `id` (preferred) or `testID` when `props.focused === true`,
+* else `null`. This is the per-node value carried in
+* `LayoutSignals.focusedNodeId` — the tree-walk lookup
+* `findActiveFocusedNodeId(root)` picks the deepest non-null among all
+* declarers (Phase 4a precedence rule).
+*
+* Identity priority: `id` > `testID`. Apps that want stable focus identity
+* should set one of those props alongside `focused={true}`. When neither is
+* set but `focused === true`, an opaque sentinel (`"__focused__"`) is
+* returned so the signal is still observable as "something is focused" —
+* downstream consumers should not depend on the sentinel value beyond
+* non-null/null.
+*/
+function computeFocusedNodeId(node) {
+	const props = node.props;
+	if (!props?.focused) return null;
+	if (typeof props.id === "string" && props.id.length > 0) return props.id;
+	if (typeof props.testID === "string" && props.testID.length > 0) return props.testID;
+	return "__focused__";
+}
+/**
+* Resolve the `anchorRef` BoxProp into a string id. Accepts the shorthand
+* `anchorRef="my-id"` and the structured `anchorRef={{ id: "my-id" }}` form.
+*
+* Returns `null` when no anchorRef is present, or when the prop is malformed
+* (empty id string). Apps that need stable anchor identity should always pass
+* a non-empty string.
+*/
+function resolveAnchorId(node) {
+	const ref = node.props?.anchorRef;
+	if (!ref) return null;
+	if (typeof ref === "string") return ref.length > 0 ? ref : null;
+	const ar = ref;
+	if (typeof ar.id === "string" && ar.id.length > 0) return ar.id;
+	return null;
+}
+/**
+* Compute the anchor rect for a Box that declares `anchorRef`. The registered
+* rect is the Box's `contentRect` — the inner area inside border + padding
+* — which is the canonical origin for placement math. Edge-specific rects
+* (top/bottom/left/right) are derived by `placeFloating` at consumption time
+* rather than baked into the registry.
+*
+* Returns `null` when:
+*   - the node has no `anchorRef` BoxProp (or it's empty), OR
+*   - `contentRect` is unavailable (pre-layout / clipped to zero size).
+*
+* Phase 4c of `km-silvery.view-as-layout-output` (overlay-anchor v1).
+*/
+function computeAnchorRect(node) {
+	if (resolveAnchorId(node) === null) return null;
+	return computeContentRect(node);
+}
+/**
+* Compute the absolute HARDWARE-PARK rect for a node from its `parkOffset` prop
+* and current `contentRect`. The park rect is the 1×1 cell where a managed
+* terminal frame parks (then hides) the hardware cursor when this node owns the
+* frame — position-only (the visible caret is `cursorOffset`/`computeCursorRect`'s
+* job, so `visible`/`shape` on the offset are ignored here).
+*
+* UNLIKE `computeCursorRect`, this is consumed **non-focus-gated** (see
+* `findActiveParkRect`): an editable declares its input cell whether or not it
+* is focused, so a managed frame ALWAYS has a benign park cell and never falls
+* back to the box origin or home (@km/code/v0.2/19702). Mirrors
+* `computeAnchorRect`'s content-origin delegation.
+*
+* Returns null when the node has no `parkOffset` prop or `contentRect` is
+* unavailable (pre-layout / clipped to zero size).
+*/
+function computeParkRect(node) {
+	const offset = node.props?.parkOffset;
+	if (!offset) return null;
+	const content = computeContentRect(node);
+	if (!content) return null;
+	return {
+		x: content.x + offset.col,
+		y: content.y + offset.row,
+		width: 1,
+		height: 1
+	};
+}
+/**
+* Walk the tree and return the deepest declared hardware-park rect, or null when
+* no node declares `parkOffset`. Post-order deepest-wins (mirrors `findAnchor`),
+* and deliberately **non-focus-gated and non-visibility-gated** — the park
+* target exists regardless of focus so `managedCursorSuffix` always has a benign
+* cell to park the hardware cursor at, never the box origin / `home(0,0)`
+* (@km/code/v0.2/19702). Signal-or-compute per node so it works before signals
+* are allocated (first frame after mount).
+*/
+function findActiveParkRect(root) {
+	let result = null;
+	function walk(node) {
+		for (const child of node.children) walk(child);
+		if (!node.props?.parkOffset) return;
+		const s = signalMap.get(node);
+		const rect = s ? s.parkRect() : computeParkRect(node);
+		if (rect) result = rect;
+	}
+	walk(root);
+	return result;
+}
+/**
+* Walk the tree and find the rect for an anchor by id. Returns `null` when
+* no Box declares `anchorRef` with a matching id, or when the matching Box's
+* `contentRect` is unavailable this frame (pre-layout / clipped).
+*
+* **Optional `edge` parameter** — when supplied, returns a 1-cell-thick rect
+* along the requested edge of the anchor (`top`, `bottom`, `left`, `right`).
+* Convenience for callers that want to draw against a specific edge without
+* threading the full content rect through `placeFloating`. Without `edge`,
+* returns the full content rect.
+*
+* **Walk order**: post-order (deepest-first). If two anchors share an id —
+* the contract says they shouldn't, but the substrate doesn't enforce
+* uniqueness — the deeper / later-rendered one wins. This matches the
+* deepest-wins precedence used by cursor and focus walks.
+*
+* Per-node cost: one `props.anchorRef` check + one signal lookup (or one
+* direct compute when no signal is allocated). Trees with no anchors return
+* `null` after a single traversal.
+*
+* Phase 4c of `km-silvery.view-as-layout-output` (overlay-anchor v1).
+*/
+function findAnchor(root, id, edge) {
+	let result = null;
+	function walk(node) {
+		for (const child of node.children) walk(child);
+		if (resolveAnchorId(node) !== id) return;
+		const s = signalMap.get(node);
+		const rect = s ? s.anchorRect() : computeAnchorRect(node);
+		if (rect) result = rect;
+	}
+	walk(root);
+	if (result === null || edge === void 0) return result;
+	const r = result;
+	switch (edge) {
+		case "top": return {
+			x: r.x,
+			y: r.y,
+			width: r.width,
+			height: 1
+		};
+		case "bottom": return {
+			x: r.x,
+			y: r.y + Math.max(0, r.height - 1),
+			width: r.width,
+			height: 1
+		};
+		case "left": return {
+			x: r.x,
+			y: r.y,
+			width: 1,
+			height: r.height
+		};
+		case "right": return {
+			x: r.x + Math.max(0, r.width - 1),
+			y: r.y,
+			width: 1,
+			height: r.height
+		};
+	}
+}
+/**
+* Compute the resolved decoration rects for a node based on its `decorations`
+* BoxProp. Each entry produces one `DecorationRect` whose `rects` may be empty
+* when an anchor lookup fails.
+*
+* **Behavior by kind**:
+*   - `popover` / `tooltip`: requires `anchorId` + `placement` + `size`. The
+*     anchor rect is looked up via `findAnchor(root, anchorId)`; if found and
+*     all required fields are present, `placeFloating` produces the placed
+*     rect. Missing anchor or missing required fields → empty rect list.
+*   - `highlight`: the `rect` field, if present, is translated from
+*     content-relative coordinates into absolute terminal coordinates by
+*     adding the owning Box's `contentRect.{x, y}`. Missing rect or no
+*     contentRect → empty rect list.
+*
+* **Per-frame**: this runs in the layout-phase notify pass, so anchor rects
+* are populated for the same frame. Anchors declared deeper in the tree
+* resolve correctly because the function takes the root tree as input rather
+* than relying on a separately-built map.
+*
+* Phase 4c of `km-silvery.view-as-layout-output` (overlay-anchor v1).
+*/
+function computeDecorationRects(node, root) {
+	const decos = node.props?.decorations;
+	if (!decos || decos.length === 0) return EMPTY_DECORATION_RECTS;
+	const out = [];
+	const content = computeContentRect(node);
+	for (const d of decos) if (d.kind === "popover" || d.kind === "tooltip") {
+		if (!d.anchorId || !d.placement || !d.size) {
+			out.push({
+				kind: d.kind,
+				id: d.id,
+				rects: []
+			});
+			continue;
+		}
+		const anchor = findAnchor(root, d.anchorId);
+		if (!anchor) {
+			out.push({
+				kind: d.kind,
+				id: d.id,
+				rects: []
+			});
+			continue;
+		}
+		const placed = resolveFloatingPlacement(anchor, d.size, d.placement, {
+			offset: d.offset,
+			alignOffset: d.alignOffset,
+			collisionStrategy: d.collisionStrategy,
+			boundary: root.boxRect
+		});
+		out.push({
+			kind: d.kind,
+			id: d.id,
+			rects: placed ? [placed.rect] : []
+		});
+	} else if (d.kind === "highlight") {
+		if (!d.rect || !content) {
+			out.push({
+				kind: d.kind,
+				id: d.id,
+				rects: []
+			});
+			continue;
+		}
+		out.push({
+			kind: d.kind,
+			id: d.id,
+			rects: [{
+				x: content.x + d.rect.x,
+				y: content.y + d.rect.y,
+				width: d.rect.width,
+				height: d.rect.height
+			}]
+		});
+	}
+	return out.length === 0 ? EMPTY_DECORATION_RECTS : out;
+}
+/**
+* Per-field equality on a list of `DecorationRect`. Used to skip
+* `decorationRects` signal writes when nothing changed — mirrors the
+* `selectionFragmentsEqual` pattern.
+*/
+function decorationRectsEqual(a, b) {
+	if (a === b) return true;
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) {
+		const ai = a[i];
+		const bi = b[i];
+		if (ai.kind !== bi.kind) return false;
+		if (ai.id !== bi.id) return false;
+		if (ai.rects.length !== bi.rects.length) return false;
+		for (let j = 0; j < ai.rects.length; j++) if (!rectEqual$1(ai.rects[j] ?? null, bi.rects[j] ?? null)) return false;
+	}
+	return true;
+}
+/**
+* Collect the textual content of a selection-declaring Box.
+*
+* The selection-fragment math operates on the rendered text content of the
+* owning Box — `selectionIntent.{from,to}` are character offsets into this
+* string. For Box nodes, the canonical content is the concatenation of
+* descendant `silvery-text` nodes' `textContent` (in tree order), with `\n`
+* separators between adjacent Text/Box children that introduce visual line
+* breaks.
+*
+* v1 behaviour (kept intentionally minimal):
+* - A Box with `silvery-text` children: concatenates `textContent` strings
+*   from those children. Two adjacent text children produce one logical
+*   line; if you want a line break, embed `\n` in the text.
+* - A Box with mixed children: same — only `silvery-text` descendants
+*   contribute. Nested Box children don't add line breaks (they're treated
+*   as transparent for content purposes).
+* - A `silvery-text` node directly carrying the prop: its own `textContent`
+*   is the content.
+*
+* This keeps the v1 model honest: declare `selectionIntent` on a Box (or
+* Text) whose text content is the source of truth for the selection. Apps
+* that want per-line semantics can split the selection across multiple
+* intent declarations.
+*/
+function collectSelectionText(node) {
+	if (node.type === "silvery-text") return node.textContent ?? "";
+	let out = "";
+	const stack = [node];
+	while (stack.length) {
+		const cur = stack.pop();
+		for (let i = cur.children.length - 1; i >= 0; i--) {
+			const child = cur.children[i];
+			if (child) stack.push(child);
+		}
+		if (cur === node) continue;
+		if (cur.type === "silvery-text" && cur.textContent !== void 0) out += cur.textContent;
+	}
+	return out;
+}
+/**
+* Compute the geometric fragments for a node's `selectionIntent` — the list
+* of rectangles (one per visual line spanned) that the selection renderer
+* should paint with highlight bg this frame.
+*
+* Returns:
+* - `[]` when the node has no `selectionIntent` prop, or when the intent is
+*   collapsed (`from === to`), or when the content rect is unavailable
+*   (pre-layout / clipped to zero size).
+* - `[Rect]` for a single-visual-line selection.
+* - `[Rect, Rect, ...]` for multi-line selections (split per visual line).
+*
+* **Geometry** (mirrors text-editor / ProseMirror conventions):
+* - First line: from `(content.x + fromCol, content.y + fromLine)` to the
+*   end of the line. If single-line, runs to `toCol`.
+* - Middle lines: full content-rect width, one row each.
+* - Last line: from `(content.x, content.y + toLine)` to `toCol` chars.
+*
+* Coordinates are absolute terminal cells, matching `cursorRect`'s
+* coordinate space. Width is in cells (one rect per visual line).
+*
+* **Soft-wrap awareness (Option B)**: when a wrap measurer is registered
+* via `setWrapMeasurer({ wrapText })` AND the content rect width is known,
+* this function splits on the measurer's per-visual-line slices — a
+* 60-char paragraph wrapped at width 20 produces 3 fragments rather than
+* one wide rectangle. The terminal runtime (`@silvery/ag-term`) registers
+* its grapheme-aware `wrapText` at startup; pure `@silvery/ag` consumers
+* (no terminal) fall back to `\n`-only splitting which preserves the
+* pre-Option-B behavior bit-for-bit. See `wrap-measurer.ts` for the
+* registry contract. Closes Phase 4b deferred wrap-spanning (bead
+* `km-silvery.softwrap-selection-fragments`).
+*/
+function computeSelectionFragments(node) {
+	const intent = node.props?.selectionIntent;
+	if (!intent) return EMPTY_FRAGMENTS;
+	if (intent.from >= intent.to) return EMPTY_FRAGMENTS;
+	const content = computeContentRect(node);
+	if (!content) return EMPTY_FRAGMENTS;
+	const text = collectSelectionText(node);
+	if (text.length === 0) return EMPTY_FRAGMENTS;
+	const measurer = getWrapMeasurer();
+	const visualLines = measurer !== null && content.width > 0 ? buildVisualLinesWithMeasurer(text, content.width, measurer.wrapText) : buildVisualLinesNewlineOnly(text);
+	const fragments = [];
+	for (let i = 0; i < visualLines.length; i++) {
+		const line = visualLines[i];
+		if (line.endOffset <= intent.from) continue;
+		if (line.startOffset >= intent.to) break;
+		const localFrom = Math.max(0, intent.from - line.startOffset);
+		const localTo = Math.min(line.text.length, intent.to - line.startOffset);
+		const width = Math.max(0, localTo - localFrom);
+		if (width === 0) continue;
+		fragments.push({
+			x: content.x + localFrom,
+			y: content.y + i,
+			width,
+			height: 1
+		});
+	}
+	return fragments.length === 0 ? EMPTY_FRAGMENTS : fragments;
+}
+/**
+* Walk paragraphs (split on `\n`) through the registered wrap measurer to
+* produce per-visual-line slices. When a paragraph fits within the width
+* unchanged, the measurer returns `[]` — we synthesize a single-slice
+* passthrough so the downstream loop sees uniform input.
+*
+* Maintains the invariant that visual-line offsets are monotone and cover
+* the full input (including the `\n` terminator counted as a zero-width
+* boundary so cross-paragraph selections stay aligned).
+*/
+function buildVisualLinesWithMeasurer(text, width, wrapText) {
+	const out = [];
+	let paraStart = 0;
+	for (let i = 0; i <= text.length; i++) {
+		const isEnd = i === text.length;
+		const isNewline = !isEnd && text.charCodeAt(i) === 10;
+		if (!isEnd && !isNewline) continue;
+		const para = text.slice(paraStart, i);
+		const slices = wrapText(para, width);
+		if (slices.length === 0) out.push({
+			text: para,
+			startOffset: paraStart,
+			endOffset: paraStart + para.length
+		});
+		else for (const slice of slices) out.push({
+			text: slice.text,
+			startOffset: paraStart + slice.startOffset,
+			endOffset: paraStart + slice.endOffset
+		});
+		paraStart = i + 1;
+	}
+	return out;
+}
+/**
+* Fallback: split on `\n` only. Preserves pre-Option-B geometry exactly so
+* unit tests that exercise the framework-only layer (no terminal Term
+* registered) keep passing without changes.
+*
+* The `endOffset` of each line is the position of the `\n` (or `text.length`
+* for the trailing line) — this matches the convention used by
+* `buildVisualLinesWithMeasurer`, where the newline is a zero-width
+* paragraph boundary rather than a visual line of its own.
+*/
+function buildVisualLinesNewlineOnly(text) {
+	const out = [];
+	let lineStart = 0;
+	for (let i = 0; i <= text.length; i++) if (i === text.length || text.charCodeAt(i) === 10) {
+		out.push({
+			text: text.slice(lineStart, i),
+			startOffset: lineStart,
+			endOffset: i
+		});
+		lineStart = i + 1;
+	}
+	return out;
+}
+/**
+* Project AgNode.scrollState → ScrollStateSnapshot (the subset the virtualizer
+* needs). Returns null if the node has no scroll state yet (non-scroll
+* containers or fresh scroll containers pre-layout).
+*
+* Keeping this projection tight means callers can compare snapshots by
+* per-field equality without pulling the mutable underlying object into
+* consumer code.
+*/
+function snapshotScrollState(node) {
+	const ss = node.scrollState;
+	if (!ss) return null;
+	return {
+		offset: ss.offset,
+		contentHeight: ss.contentHeight,
+		viewportHeight: ss.viewportHeight,
+		firstVisibleChild: ss.firstVisibleChild,
+		lastVisibleChild: ss.lastVisibleChild,
+		hiddenAbove: ss.hiddenAbove,
+		hiddenBelow: ss.hiddenBelow
+	};
+}
+/** Per-field equality check for ScrollStateSnapshot (skips allocation). */
+function scrollStateEqual(a, b) {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	return a.offset === b.offset && a.contentHeight === b.contentHeight && a.viewportHeight === b.viewportHeight && a.firstVisibleChild === b.firstVisibleChild && a.lastVisibleChild === b.lastVisibleChild && a.hiddenAbove === b.hiddenAbove && a.hiddenBelow === b.hiddenBelow;
+}
+/** Check whether a node has signals allocated (for testing). */
+function hasLayoutSignals(node) {
+	return signalMap.has(node);
+}
+function hasObservedLayoutSignal(node, key) {
+	return observedLayoutSignals.get(node)?.has(key) ?? false;
+}
+/**
+* Sync all rect signals from the node's current values.
+*
+* Called from notifyLayoutSubscribers after layout + scroll + sticky
+* phases complete. Only syncs nodes that have signals allocated.
+* Reference-equality check prevents unnecessary downstream updates.
+*/
+function syncRectSignals(node) {
+	const props = node.props ?? void 0;
+	const hasCursorOffset = !!props?.cursorOffset;
+	const hasFocused = !!props?.focused;
+	const hasSelectionIntent = !!props?.selectionIntent;
+	const hasAnchorRef = !!props?.anchorRef;
+	const hasDecorations = !!(props?.decorations && props.decorations.length > 0);
+	const s = hasCursorOffset || hasFocused || hasSelectionIntent || hasAnchorRef || hasDecorations ? getLayoutSignals(node) : signalMap.get(node);
+	if (!s) return;
+	if (node.boxRect !== s.boxRect()) s.boxRect(node.boxRect);
+	if (node.scrollRect !== s.scrollRect()) s.scrollRect(node.scrollRect);
+	if (node.screenRect !== s.screenRect()) s.screenRect(node.screenRect);
+	const nextContentRect = computeContentRect(node);
+	if (!rectEqual$1(nextContentRect, s.contentRect())) s.contentRect(nextContentRect);
+	const nextCursorRect = computeCursorRect(node);
+	if (!cursorRectEqual(nextCursorRect, s.cursorRect())) s.cursorRect(nextCursorRect);
+	const nextFocusedId = computeFocusedNodeId(node);
+	if (nextFocusedId !== s.focusedNodeId()) s.focusedNodeId(nextFocusedId);
+	const nextFragments = computeSelectionFragments(node);
+	if (!selectionFragmentsEqual(nextFragments, s.selectionFragments())) s.selectionFragments(nextFragments);
+	const nextAnchorRect = computeAnchorRect(node);
+	if (!rectEqual$1(nextAnchorRect, s.anchorRect())) s.anchorRect(nextAnchorRect);
+	const nextParkRect = computeParkRect(node);
+	if (!rectEqual$1(nextParkRect, s.parkRect())) s.parkRect(nextParkRect);
+	const nextScrollState = snapshotScrollState(node);
+	if (!scrollStateEqual(nextScrollState, s.scrollState())) s.scrollState(nextScrollState);
+}
+/**
+* Second-pass sync for `decorationRects` — must run AFTER `syncRectSignals`
+* has populated every anchor rect this frame, because decoration resolution
+* calls `findAnchor(root, id)` and needs the freshest anchor rects.
+*
+* Walks the tree, recomputes per-node decoration rects, and writes the signal
+* only when the result differs (per-field equality via `decorationRectsEqual`).
+*
+* Phase 4c of `km-silvery.view-as-layout-output` (overlay-anchor v1).
+*
+* Per-node cost: one `props.decorations` length check (zero-allocation
+* short-circuit) + one signal lookup + one decoration recompute when present.
+* Trees without decorations pay only the prop check at every node.
+*/
+function syncDecorationRects(root) {
+	function walk(node) {
+		const props = node.props;
+		if (!!(props?.decorations && props.decorations.length > 0)) {
+			const s = getLayoutSignals(node);
+			const next = computeDecorationRects(node, root);
+			if (!decorationRectsEqual(next, s.decorationRects())) s.decorationRects(next);
+		} else {
+			const s = signalMap.get(node);
+			if (s && s.decorationRects().length > 0) s.decorationRects(EMPTY_DECORATION_RECTS);
+		}
+		for (const child of node.children) walk(child);
+	}
+	walk(root);
+}
+/**
+* Promote the in-flight rect signals (`boxRect` / `scrollRect` / `screenRect`)
+* to their committed counterparts (`boxRectCommitted` / etc.). Reactive
+* `useBoxRect()` / `useScrollRect()` / `useScreenRect()` consumers subscribe
+* to the committed signals — calling this advances them by one frame.
+*
+* Called by the runtime ONCE per event-batch commit, after the convergence
+* loop has fully drained. Within a single batch, multiple convergence passes
+* may write the in-flight signals (callback-form observers fire each time),
+* but the committed signals advance only here. That's what lets a render
+* which both READS `useBoxRect()` and WRITES a layout-affecting prop converge
+* in one pass: the read returns the same value across every pass in the
+* batch, so the write is idempotent.
+*
+* Reference equality on the underlying alien-signal write means a no-op
+* commit (same rect as last frame) does not fire any subscribers — steady
+* state pays no cost.
+*
+* The walker visits only nodes that already have allocated `LayoutSignals`
+* (i.e. nodes with at least one consumer); a tree with no rect subscribers
+* pays only the WeakMap probe per node.
+*
+* **Return value**: `true` when the commit promoted at least one committed
+* rect signal — i.e. it fired at least one reactive subscriber's forceUpdate.
+* Those forceUpdates are React-scheduled (deferred-lane) updates that do NOT
+* surface as the runtime's `pendingRerender` flag and are NOT drained by
+* `reconciler.flushSyncWork()`; only a subsequent `doRender()`
+* (`updateContainerSync`) processes them. The runtime's post-commit drain uses
+* this return so it can run the documented "exactly one additional pass" that
+* paints the subscriber update WITHIN the same event — instead of leaking a
+* stale frame to a later macrotask (the @si/render/19436 boxSize signature).
+*
+* See bead `@km/silvery/use-deferred-box-rect-and-post-commit-observers`.
+*/
+function commitLayoutSnapshot(root) {
+	let promoted = false;
+	function walk(node) {
+		const s = signalMap.get(node);
+		if (s) {
+			const nextBox = s.boxRect();
+			if (!rectEqual$1(nextBox, s.boxRectCommitted())) {
+				s.boxRectCommitted(nextBox);
+				if (hasObservedLayoutSignal(node, "boxRect") || hasObservedLayoutSignal(node, "boxSize")) promoted = true;
+			}
+			const nextScroll = s.scrollRect();
+			if (!rectEqual$1(nextScroll, s.scrollRectCommitted())) {
+				s.scrollRectCommitted(nextScroll);
+				if (hasObservedLayoutSignal(node, "scrollRect")) promoted = true;
+			}
+			const nextScreen = s.screenRect();
+			if (!rectEqual$1(nextScreen, s.screenRectCommitted())) {
+				s.screenRectCommitted(nextScreen);
+				if (hasObservedLayoutSignal(node, "screenRect")) promoted = true;
+			}
+		}
+		for (const child of node.children) walk(child);
+	}
+	walk(root);
+	return promoted;
+}
+/**
+* Walk the tree and find the active caret rect — the caret to render this
+* frame, applying the precedence + clipping rules locked by bead
+* `km-silvery.cursor-invariants`. Returns null when no cursor owner is
+* present; focused hidden owners return a rect with `visible: false`.
+*
+* **Precedence (invariant 1)**:
+*   1. **Focused cursor owner wins**: a Box with `cursorOffset` AND either
+*      `focused === true` or `interactiveState.focused === true` wins even
+*      when `cursorOffset.visible === false`. If the rect is visible,
+*      renderers show it; if it is hidden, renderers move there and hide the
+*      hardware cursor. Either way it suppresses non-focused fallback cursors.
+*   2. **Otherwise deepest visible in paint order**: if no node is a focused
+*      cursor owner, fall back to the deepest visible declarer (post-order
+*      tree walk). This covers Ink-compat consumers and `useCursor` callers
+*      that don't participate in the focus tree.
+*   3. **Otherwise null**: no visible cursor owner is present.
+*
+* **Clipping (invariant 4)**: at each scroll/clip ancestor (a Box with
+* `overflow="scroll"` / `"hidden"` / `overflowY="hidden"`), the caret's
+* position is checked against the ancestor's `scrollRect`. If the caret
+* falls outside the visible region, the caret is treated as not-present.
+* Default behavior is **hide** (no caret ANSI emitted) — never clamp. A
+* caret rect at the exact clip edge is treated as visible.
+*
+* Visited in tree order (depth-first, post-order). Per-node cost is one
+* `props.cursorOffset` check + one signal lookup; trees without any cursor
+* declarer return null after a single traversal.
+*/
+function findActiveCursorRect(root) {
+	return findActiveCursorRectWithProvenance(root)?.rect ?? null;
+}
+/**
+* Walk the tree once and return the active cursor rect WITH its provenance.
+* `findActiveCursorRect` is the value-only projection of this. See
+* `CursorProvenance` for the source categories and why the terminal layer needs
+* them (one walk, no parallel island-blind re-derivation in the compositing
+* gate). Precedence and clipping match `findActiveCursorRect`'s documented
+* invariants exactly — this IS that walk.
+*/
+function findActiveCursorRectWithProvenance(root) {
+	let focusedResult = null;
+	let focusedSuppressesFallback = false;
+	let fallbackResult = null;
+	let fallbackProvenance = "declarative-fallback";
+	const clipStack = [];
+	function isClipped(rect) {
+		for (let i = clipStack.length - 1; i >= 0; i--) {
+			const clip = clipStack[i];
+			if (!clip) continue;
+			if (rect.x < clip.x || rect.y < clip.y || rect.x >= clip.x + clip.width || rect.y >= clip.y + clip.height) return true;
+		}
+		return false;
+	}
+	function isClipAncestor(node) {
+		const props = node.props;
+		if (!props) return false;
+		if (props.overflow === "scroll" || props.overflow === "hidden") return true;
+		if (props.overflowY === "hidden") return true;
+		return false;
+	}
+	function walk(node) {
+		const isClip = isClipAncestor(node);
+		if (isClip) clipStack.push(node.scrollRect ?? null);
+		for (const child of node.children) walk(child);
+		const props = node.props;
+		if (props?.cursorOffset) {
+			const s = signalMap.get(node);
+			const rect = s ? s.cursorRect() : computeCursorRect(node);
+			const isFocusedCursorOwner = props.focused === true || node.interactiveState?.focused === true;
+			if (rect) {
+				const clipped = isClipped(rect);
+				if (isFocusedCursorOwner) {
+					focusedSuppressesFallback = true;
+					if (!clipped) focusedResult = rect;
+				}
+				if (!clipped) {
+					if (rect.visible) {
+						fallbackResult = rect;
+						fallbackProvenance = "declarative-fallback";
+					}
+				}
+			} else if (isFocusedCursorOwner) focusedSuppressesFallback = true;
+		}
+		if (node.type === "silvery-island" && node.islandState?.cursorActive) {
+			const out = node.islandState.handle?.output;
+			const cur = out?.cursor;
+			const base = node.screenRect ?? node.boxRect;
+			if (cur && out?.cursorVisible && base) {
+				const rect = {
+					x: base.x + cur.col,
+					y: base.y + cur.row,
+					visible: true,
+					shape: cur.style
+				};
+				if (!focusedSuppressesFallback && !isClipped(rect)) {
+					fallbackResult = rect;
+					fallbackProvenance = "island";
+				}
+			}
+		}
+		if (isClip) clipStack.pop();
+	}
+	walk(root);
+	if (focusedResult) return {
+		rect: focusedResult,
+		provenance: "focused-declarative"
+	};
+	if (focusedSuppressesFallback || !fallbackResult) return null;
+	return {
+		rect: fallbackResult,
+		provenance: fallbackProvenance
+	};
+}
+/**
+* Sync textContent signal from the node's current value.
+*
+* Called from commitTextUpdate in the reconciler.
+*/
+function syncTextContentSignal(node) {
+	const s = signalMap.get(node);
+	if (!s) return;
+	if (node.textContent !== s.textContent()) s.textContent(node.textContent);
+}
+/**
+* Sync focused signal for a node.
+*
+* Called from FocusManager when focus changes.
+*/
+function syncFocusedSignal(node, focused) {
+	const s = signalMap.get(node);
+	if (!s) return;
+	if (focused !== s.focused()) s.focused(focused);
+}
+//#endregion
+export { rectEqual$1 as _, findActiveParkRect as a, hasObservedLayoutSignal as c, syncDecorationRects as d, syncFocusedSignal as f, setWrapMeasurer as g, getWrapMeasurer as h, findActiveCursorRectWithProvenance as i, markObservedLayoutSignal as l, syncTextContentSignal as m, computeContentRect as n, getLayoutSignals as o, syncRectSignals as p, findActiveCursorRect as r, hasLayoutSignals as s, commitLayoutSnapshot as t, observeLayoutSignal as u };
+
+//# sourceMappingURL=layout-signals-Dch2EiCy.mjs.map