@pilates/core 1.0.0-rc.1 → 1.0.0

package/dist/algorithm/round.js

@@ -20,6 +20,44 @@ export function roundLayout(root) {
     collectAbsolutes(root, 0, 0, absolutes);
     applyRounding(root, absolutes, 0, 0);
 }
+/**
+ * Round the layout of a subtree that sits at a known absolute position.
+ *
+ * Used by the Phase 3 relayout-boundary path: when a boundary node is
+ * re-laid out under a cache-hit root, its children's positions are in
+ * floating-point space. We round them in isolation using the boundary
+ * node's already-rounded absolute position as the origin.
+ *
+ * The boundary node's own `width`/`height` are explicit integers (that is
+ * the boundary invariant) and its `left`/`top` were restored from the
+ * parent's rounded cache, so they are already integers. We therefore do
+ * NOT re-round the boundary node itself — only its children. The parent
+ * absolute corner is `(parentAbsX + node.left, parentAbsY + node.top)`.
+ *
+ * @internal
+ */
+export function roundLayoutSubtree(node, parentAbsX, parentAbsY) {
+    // Use the pre-rounding float left/top (node._floatLeft/Top) rather than the
+    // rounded integer _layout.left/top. The boundary node's _layout.left/top were
+    // restored from the parent's rounded cache (integers), but the true float
+    // position is stored in _floatLeft/Top (also restored from cache). Using the
+    // float position ensures that absolute coordinates of the boundary's children
+    // are computed in the same floating-point space as the full-tree roundLayout pass.
+    const nodeAbsX = parentAbsX + node._floatLeft;
+    const nodeAbsY = parentAbsY + node._floatTop;
+    const absolutes = new Map();
+    // Collect children relative to the node's absolute corner.
+    for (let i = 0; i < node.getChildCount(); i++) {
+        collectAbsolutes(node.getChild(i), nodeAbsX, nodeAbsY, absolutes);
+    }
+    // Round children (their positions are relative to `node`, so
+    // parentRoundedX/Y for each child is node's absolute corner rounded).
+    const roundedNodeX = Math.round(nodeAbsX);
+    const roundedNodeY = Math.round(nodeAbsY);
+    for (let i = 0; i < node.getChildCount(); i++) {
+        applyRounding(node.getChild(i), absolutes, roundedNodeX, roundedNodeY);
+    }
+}
 function collectAbsolutes(node, parentX, parentY, out) {
     const x = parentX + node.layout.left;
     const y = parentY + node.layout.top;
@@ -34,10 +72,10 @@ function applyRounding(node, abs, parentRoundedX, parentRoundedY) {
     const roundedY = Math.round(my.y);
     const roundedR = Math.round(my.x + my.w);
     const roundedB = Math.round(my.y + my.h);
-    node.layout.left = roundedX - parentRoundedX;
-    node.layout.top = roundedY - parentRoundedY;
-    node.layout.width = Math.max(0, roundedR - roundedX);
-    node.layout.height = Math.max(0, roundedB - roundedY);
+    node._layout.left = roundedX - parentRoundedX;
+    node._layout.top = roundedY - parentRoundedY;
+    node._layout.width = Math.max(0, roundedR - roundedX);
+    node._layout.height = Math.max(0, roundedB - roundedY);
     for (let i = 0; i < node.getChildCount(); i++) {
         applyRounding(node.getChild(i), abs, roundedX, roundedY);
     }

package/dist/algorithm/round.js.map

@@ -1 +1 @@
-{"version":3,"file":"round.js","sourceRoot":"","sources":["../../src/algorithm/round.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAWH,MAAM,UAAU,WAAW,CAAC,IAAU;IACpC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAmB,CAAC;IAC7C,gBAAgB,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC;IACxC,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AACvC,CAAC;AAED,SAAS,gBAAgB,CACvB,IAAU,EACV,OAAe,EACf,OAAe,EACf,GAAyB;IAEzB,MAAM,CAAC,GAAG,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IACrC,MAAM,CAAC,GAAG,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC;IACpC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACrE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAE,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;IACjD,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CACpB,IAAU,EACV,GAAyB,EACzB,cAAsB,EACtB,cAAsB;IAEtB,MAAM,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC;IAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IAEzC,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,QAAQ,GAAG,cAAc,CAAC;IAC7C,IAAI,CAAC,MAAM,CAAC,GAAG,GAAG,QAAQ,GAAG,cAAc,CAAC;IAC5C,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC;IACrD,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC;IAEtD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC5D,CAAC;AACH,CAAC"}
+{"version":3,"file":"round.js","sourceRoot":"","sources":["../../src/algorithm/round.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export declare const VERSION = "1.0.0-rc.1";
 export { Node } from './node.js';
 export { Edge } from './edge.js';
-export type { Align, Display, FlexDirection, FlexWrap, Justify, Length, PositionType, Style, } from './style.js';
+export type { Align, Display, FlexDirection, FlexWrap, Justify, Length, Overflow, PositionType, Style, } from './style.js';
 export { MeasureMode } from './measure-func.js';
 export type { MeasureFunc, MeasureSize } from './measure-func.js';
 export type { ComputedLayout } from './layout.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,eAAe,CAAC;AAGpC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,YAAY,EACV,KAAK,EACL,OAAO,EACP,aAAa,EACb,QAAQ,EACR,OAAO,EACP,MAAM,EACN,YAAY,EACZ,KAAK,GACN,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGlE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,eAAe,CAAC;AAGpC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,YAAY,EACV,KAAK,EACL,OAAO,EACP,aAAa,EACb,QAAQ,EACR,OAAO,EACP,MAAM,EACN,QAAQ,EACR,YAAY,EACZ,KAAK,GACN,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGlE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,YAAY,CAAC;AAEpC,OAAO;AACP,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,eAAe;AACf,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAYjC,mBAAmB;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAMhD,yEAAyE;AACzE,uDAAuD;AACvD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAiB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,YAAY,CAAC;AAEpC,OAAO;AACP,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,eAAe;AACf,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAajC,mBAAmB;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAMhD,yEAAyE;AACzE,uDAAuD;AACvD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAiB,MAAM,oBAAoB,CAAC"}

package/dist/layout.d.ts

@@ -10,6 +10,14 @@ export interface ComputedLayout {
     top: number;
     width: number;
     height: number;
+    /**
+     * Natural content width. For nodes with `overflow !== 'visible'`, this
+     * is the bounding box of children unbounded by the parent's content
+     * width. For non-overflow nodes, equals the node's own `width`.
+     */
+    scrollWidth: number;
+    /** See {@link scrollWidth}. */
+    scrollHeight: number;
 }
 export declare function defaultLayout(): ComputedLayout;
 //# sourceMappingURL=layout.d.ts.map

package/dist/layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,aAAa,IAAI,cAAc,CAE9C"}
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,aAAa,IAAI,cAAc,CAE9C"}

package/dist/layout.js

@@ -1,4 +1,4 @@
 export function defaultLayout() {
-    return { left: 0, top: 0, width: 0, height: 0 };
+    return { left: 0, top: 0, width: 0, height: 0, scrollWidth: 0, scrollHeight: 0 };
 }
 //# sourceMappingURL=layout.js.map

package/dist/layout.js.map

@@ -1 +1 @@
-{"version":3,"file":"layout.js","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAcA,MAAM,UAAU,aAAa;IAC3B,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;AAClD,CAAC"}
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAsBA,MAAM,UAAU,aAAa;IAC3B,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;AACnF,CAAC"}

package/dist/node.d.ts

@@ -15,19 +15,109 @@
  *   - `measure`   — optional measure function for leaf intrinsic sizing.
  *   - `dirty`     — set on style/tree mutation; consumed by the algorithm.
  */
+import { type LayoutCache, MeasureCache } from './algorithm/cache.js';
 import { Edge } from './edge.js';
 import { type ComputedLayout } from './layout.js';
 import type { MeasureFunc } from './measure-func.js';
-import { type Align, type Display, type FlexDirection, type FlexWrap, type Justify, type Length, type PositionType, type Style } from './style.js';
+import { type Align, type Display, type FlexDirection, type FlexWrap, type Justify, type Length, type Overflow, type PositionType, type Style } from './style.js';
 export declare class Node {
-    /** Public-but-internal: read by the layout algorithm and by `getComputedLayout`. */
-    readonly style: Style;
-    readonly layout: ComputedLayout;
+    /**
+     * Backing storage for `style`. Mutated by this class's setters and read
+     * by the algorithm via the public `style` getter. The leading `_` and
+     * `@internal` mark this as algorithm-only — consumers must use the
+     * `setX()` methods.
+     *
+     * @internal
+     */
+    readonly _style: Style;
+    /**
+     * Backing storage for `layout`. Written by the algorithm in this package
+     * (see `algorithm/`); read externally via the public `layout` getter or
+     * the safer `getComputedLayout()` snapshot.
+     *
+     * @internal
+     */
+    readonly _layout: ComputedLayout;
+    /**
+     * Horizontal scroll offset. Mutable; defaults to 0. Read by the renderer
+     * when painting children of an `overflow !== 'visible'` node — children's
+     * paint origin is translated by `(-scrollLeft, -scrollTop)`. NOT clamped
+     * by this class — bounds clamping is the consumer's job (`<ScrollView>`
+     * clamps before writing). Direct mutation does not mark the node dirty
+     * because scroll offset is a paint-time concern, not layout.
+     */
+    scrollLeft: number;
+    /** See {@link scrollLeft}. */
+    scrollTop: number;
+    /** Read-only view of `_layout.scrollWidth`. See {@link scrollLeft}. */
+    get scrollWidth(): number;
+    /** Read-only view of `_layout.scrollHeight`. */
+    get scrollHeight(): number;
+    /**
+     * Read-only view of this node's style. Mutating the returned object is
+     * blocked at the type level — call `setX()` methods to change style so
+     * `markDirty()` runs.
+     */
+    get style(): Readonly<Style>;
+    /**
+     * Read-only view of this node's most recently computed layout. Use
+     * `getComputedLayout()` for a stable copy if you need to retain it past
+     * the next `calculateLayout()` call.
+     */
+    get layout(): Readonly<ComputedLayout>;
     private readonly _children;
     private _parent;
     private _measure;
     /** True if style or tree has changed since the last `calculateLayout()`. */
     private _dirty;
+    /**
+     * True if any descendant has been marked dirty (even if dirty propagation
+     * was stopped by a relayout boundary before reaching this node). Used by
+     * the root cache-hit path to skip `layoutChildren` for subtrees that have
+     * no mutations at all — not just subtrees where this node itself is clean.
+     *
+     * Invariant: `_dirty` implies `_hasDirtyDescendant` on the parent (if any).
+     * Cleared by `clearDirty()` after each `calculateLayout()`.
+     */
+    _hasDirtyDescendant: boolean;
+    /**
+     * Lazy-allocated measure-func result cache. Created the first time
+     * `setMeasureFunc()` installs a measurer. Cleared by `markDirty()`
+     * (which fires on every style/tree mutation) and by re-installing
+     * the measure function. Read by `callMeasureFunc()` in
+     * `algorithm/main-axis.ts`.
+     *
+     * @internal
+     */
+    _measureCache?: MeasureCache;
+    /**
+     * Lazy-allocated layout-cache. Created the first time `layoutChildren`
+     * (or `calculateLayout` at the root) stores a result. Cleared by
+     * `markDirty()`. Read by `layoutChildren` and the root
+     * `calculateLayout` path in `algorithm/`.
+     *
+     * @internal
+     */
+    _layoutCache?: LayoutCache;
+    /**
+     * Pre-rounding (float) left/top position of this node within its parent,
+     * as computed by the flex algorithm BEFORE `roundLayout` converts positions
+     * to integers.
+     *
+     * Written by the position-write helpers in `algorithm/main-axis.ts` at the
+     * same time as `_layout.left/top`. After `roundLayout` runs, `_layout.left/top`
+     * become integers but `_floatLeft/Top` retain the float values. These are
+     * captured by `snapshotForCache` and restored by `restoreFromCache` so that
+     * `roundLayoutSubtree` can compute the correct absolute float coordinate for
+     * a re-laid-out boundary node's children.
+     *
+     * Initialized to 0 (same as `_layout.left/top`).
+     *
+     * @internal
+     */
+    _floatLeft: number;
+    /** See {@link _floatLeft}. @internal */
+    _floatTop: number;
     /** Construct via `Node.create()` to mirror Yoga's factory style. */
     static create(): Node;
     insertChild(child: Node, index: number): void;
@@ -42,7 +132,16 @@ export declare class Node {
     getMeasureFunc(): MeasureFunc | null;
     setFlexDirection(value: FlexDirection): void;
     setFlexWrap(value: FlexWrap): void;
-    /** CSS `flex` shorthand: grow=value, shrink=1, basis=0 (when value > 0). */
+    /**
+     * CSS `flex` shorthand: grow=value, shrink=1, basis=0 (when value > 0).
+     *
+     * Note that the implied `shrink: 1` follows CSS, not Yoga: Yoga's
+     * default `flexShrink` is 0, and `setFlex(N)` in Yoga also leaves
+     * shrink at 0. Pilates intentionally tracks CSS here so consumers
+     * who think in CSS terms get the result they expect; consumers
+     * porting from Ink (which wraps Yoga) should call `setFlexShrink(0)`
+     * after `setFlex` if they need the Yoga behaviour.
+     */
     setFlex(value: number): void;
     setFlexGrow(value: number): void;
     setFlexShrink(value: number): void;
@@ -55,6 +154,11 @@ export declare class Node {
     setMaxWidth(value: number | undefined): void;
     /** Pass `undefined` to remove an upper bound. */
     setMaxHeight(value: number | undefined): void;
+    /**
+     * Pass `undefined` to clear the constraint. Must be a positive finite
+     * number when set. See `style.ts` for the full derivation rules.
+     */
+    setAspectRatio(value: number | undefined): void;
     setPadding(edge: Edge, value: number): void;
     setMargin(edge: Edge, value: number): void;
     setGap(axis: 'row' | 'column', value: number): void;
@@ -66,6 +170,9 @@ export declare class Node {
     /** Pass `undefined` to leave that edge unconstrained. */
     setPosition(edge: Edge, value: number | undefined): void;
     setDisplay(value: Display): void;
+    setOverflow(overflow: Overflow): void;
+    setOverflowX(overflow: Overflow): void;
+    setOverflowY(overflow: Overflow): void;
     /**
      * Compute layout for this node and its descendants.
      *
@@ -84,13 +191,79 @@ export declare class Node {
      * Before `calculateLayout()` has run, all values are 0.
      */
     getComputedLayout(): ComputedLayout;
+    /**
+     * A node is a relayout boundary iff its layout size is fully
+     * independent of both parent flex distribution and descendant changes:
+     *
+     *   1. `width` AND `height` are explicit numbers (not `'auto'`) — pins
+     *      the node's own preferred size on both axes.
+     *   2. `flexGrow <= 0` — the node won't be grown by parent free space.
+     *   3. `flexShrink <= 0` — the node won't be shrunk by parent overflow.
+     *
+     * The early spec draft argued (1) alone was sufficient ("flex grow/shrink
+     * adjust size based on parent state, not descendant state"). The fuzzer
+     * disproved this: with `flexGrow > 0`, the parent's flex distribution
+     * gives the boundary a post-grow width different from style.width. After
+     * a descendant mutation dirties the boundary but not its ancestors, the
+     * cached parent layout reuses the post-grow width, but the cold
+     * recompute may produce a different post-grow width if any sibling
+     * changed (or even due to micro-rounding interactions). The fuzzer
+     * surfaced this with a `setFlexGrow(1)` boundary producing
+     * `cached=17 vs cold=16` width drift.
+     *
+     * Conditions (2) + (3) ensure the boundary's actual size equals its
+     * style values exactly, so the cached parent layout stays valid no
+     * matter what siblings do.
+     *
+     * Boundaries stop the upward dirty propagation in `markDirtyFromChild()`
+     * so descendant mutations don't invalidate ancestor layout caches.
+     *
+     * See `docs/superpowers/specs/2026-05-09-relayout-boundaries-design.md`
+     * for the full rationale and edge-case analysis.
+     */
+    private isLayoutBoundary;
     /**
      * Walk up the tree marking every ancestor dirty too. The algorithm uses
      * this hint to short-circuit work in subtrees that did not change.
      */
     markDirty(): void;
+    /**
+     * Called when a child (or descendant via recursion) is mutated. Marks
+     * this node dirty and propagates upward — but stops here if this node
+     * is a relayout boundary. The boundary semantics apply only when the
+     * mutation originates in a descendant, not when this node's own setters
+     * call `markDirty()` directly.
+     *
+     * See `isLayoutBoundary()` for the boundary definition and rationale.
+     */
+    private markDirtyFromChild;
+    /**
+     * Propagate the "has a dirty descendant somewhere below" signal upward
+     * without marking ancestors `_dirty`. Called when a relayout boundary
+     * stops the dirty propagation but still needs to let the root know that
+     * some subtree needs attention. Stops if the parent is already dirty
+     * (in which case the root will recompute everything anyway) or already
+     * has a dirty descendant flag set.
+     */
+    private markHasDirtyDescendant;
+    /**
+     * Set dirty + clear caches + propagate up unconditionally, bypassing
+     * the layout-boundary short-circuit in `markDirty()`. Used only by
+     * `markDirtyDeep` in `algorithm/cache.ts` for differential-mode and
+     * fuzzer validation that need to force the full tree onto the cold
+     * path regardless of boundary semantics.
+     *
+     * @internal
+     */
+    _forceDirty(): void;
     isDirty(): boolean;
-    /** Internal: called by the algorithm once layout is fresh. */
+    /**
+     * Called by the algorithm once layout is fresh. Not part of the public
+     * API — consumers should treat layout cleanliness as derived state and
+     * never reach in to clear the flag themselves.
+     *
+     * @internal
+     */
     clearDirty(): void;
 }
 //# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"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"}