@pilates/core 1.0.0-rc.2 → 1.0.1

package/dist/algorithm/cache.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Layout-engine caches.
+ *
+ * Phase 1: `MeasureCache` — caches the result of a leaf node's
+ * `MeasureFunc` so repeated calls with the same available-space
+ * inputs don't reinvoke the measurer. Wired into every measure-func
+ * call site in `main-axis.ts` via the `callMeasureFunc` helper.
+ *
+ * Caches are owned by `Node` (`_measureCache` field) and cleared
+ * automatically by `markDirty()`. Consumers never interact with the
+ * cache directly — it is `@internal`.
+ *
+ * Phase 2 added `LayoutCache` here (P2-T1).
+ *
+ * @internal
+ */
+import type { ComputedLayout } from '../layout.js';
+import type { MeasureMode } from '../measure-func.js';
+import type { Node } from '../node.js';
+/** @internal */
+export interface MeasureCacheKey {
+    availableWidth: number;
+    widthMode: MeasureMode;
+    availableHeight: number;
+    heightMode: MeasureMode;
+}
+/** @internal */
+export interface MeasureCacheValue {
+    width: number;
+    height: number;
+}
+/**
+ * Up to eight slots — matches Yoga's `LayoutResults::MaxCachedMeasurements`
+ * with the documented rationale "98% of analyzed layouts require less
+ * than 8 entries" (see facebook/yoga `node/LayoutResults.h`). Covers the
+ * hypothetical-vs-final pattern (single leaf measured twice per pass)
+ * plus broader reuse patterns where the same leaf is measured at multiple
+ * cross-axis sizes during line packing or across consecutive layout calls.
+ *
+ * Linear scan over 8 slots is a few-cycle hot-path cost; slots are
+ * lazy-allocated only on leaves with a `MeasureFunc` installed.
+ *
+ * @internal
+ */
+export declare class MeasureCache {
+    private static readonly MAX_ENTRIES;
+    private slots;
+    /**
+     * Hit/miss counters for diagnostics (bench output, debugging). Always
+     * on — the spec originally proposed `__DEV__`-gating these, but the
+     * project has no build-tooling `__DEV__` define and the counters cost
+     * two property writes per `lookup()` (negligible at any realistic
+     * call rate). Counts are incremented only by `lookup()`; `store()`
+     * assumes `lookup()` has already been called for the same key on the
+     * same call site, so it does not double-count.
+     *
+     * @internal
+     */
+    hits: number;
+    /** See {@link hits}. @internal */
+    misses: number;
+    lookup(key: MeasureCacheKey): MeasureCacheValue | undefined;
+    /**
+     * Store `value` for `key`. If `key` is already present, overwrite in
+     * place without growing the slot array; otherwise append, evicting
+     * the oldest slot when the array is at `MAX_ENTRIES` capacity.
+     *
+     * Callers should always invoke `lookup(key)` first and only call
+     * `store()` on a miss — the `misses` counter is incremented by
+     * `lookup()`, not here, so calling `store()` without a prior lookup
+     * would cause silent miss undercounting in diagnostics.
+     */
+    store(key: MeasureCacheKey, value: MeasureCacheValue): void;
+    /**
+     * Drop every cached entry. The `hits`/`misses` counters are
+     * deliberately preserved across `clear()` calls — they're lifetime
+     * diagnostics, not per-pass metrics, and zeroing them would mask the
+     * total-pressure picture during bench runs.
+     */
+    clear(): void;
+}
+/** @internal */
+export interface LayoutCacheKey {
+    availableWidth: number;
+    widthMode: MeasureMode;
+    availableHeight: number;
+    heightMode: MeasureMode;
+}
+/** @internal */
+export interface CachedChildLayout {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    scrollWidth: number;
+    scrollHeight: number;
+    /**
+     * Pre-rounding (float) left position of this child, captured before
+     * `roundLayout` converts positions to integers. Used by
+     * `roundLayoutSubtree` to compute the correct float absolute coordinate
+     * when re-laying out a dirty boundary node under a cache-hit root.
+     * See `Node._floatLeft` for the full explanation.
+     */
+    floatLeft: number;
+    /** See {@link floatLeft}. */
+    floatTop: number;
+}
+/** @internal */
+export interface LayoutCacheValue {
+    width: number;
+    height: number;
+    scrollWidth: number;
+    scrollHeight: number;
+    childLayouts: CachedChildLayout[];
+}
+/**
+ * Single-slot per-node layout cache. Matches Yoga's `cachedLayout`
+ * (single overwrite-on-write) and Taffy's 1-slot layout-cache. Internal
+ * nodes' final-pass keys converge to one stable input once the parent's
+ * flex distribution has settled, so additional slots would be dead memory.
+ *
+ * Lazy-allocated by the algorithm in `algorithm/main-axis.ts` and
+ * `algorithm/index.ts` only on nodes that actually go through the
+ * `layoutChildren` recursion. Cleared by `Node.markDirty()` (which fires
+ * on every style/tree mutation).
+ *
+ * Hit/miss counters are always-on (same rationale as `MeasureCache`).
+ *
+ * @internal
+ */
+export declare class LayoutCache {
+    private slot;
+    /** @internal */
+    hits: number;
+    /** @internal */
+    misses: number;
+    lookup(key: LayoutCacheKey): LayoutCacheValue | undefined;
+    /**
+     * Store `value` for `key`. Single-slot — replaces the previous entry
+     * unconditionally. Caller must construct a fresh `LayoutCacheValue` per
+     * store; this method does NOT deep-clone for performance, so any
+     * subsequent mutation of `value` is visible through `lookup`. The
+     * algorithm builds new values per layout pass so the contract holds.
+     */
+    store(key: LayoutCacheKey, value: LayoutCacheValue): void;
+    clear(): void;
+}
+/**
+ * Pre-order traversal returning a flat array of layout snapshots, one per
+ * node. Used by differential mode to capture and compare the entire tree's
+ * layout state cheaply.
+ *
+ * Captures only the six `ComputedLayout` fields. `_dirty` flags, cache
+ * contents, and other ancillary state are NOT in scope. Phase 2's
+ * layout-cache work should add `_dirty` validation to the harness if
+ * dirty-flag semantics ever become load-bearing for cache correctness.
+ *
+ * @internal
+ */
+export declare function snapshotTreeLayouts(root: Node): ComputedLayout[];
+/**
+ * Recursively clear `_measureCache` and `_layoutCache` on every node in
+ * the subtree. Used by differential mode and the fuzzer to force the cold
+ * path.
+ *
+ * @internal
+ */
+export declare function clearAllCaches(root: Node): void;
+/**
+ * Mark every node in the subtree dirty. Used after `clearAllCaches` to
+ * force `calculateLayout` down the full cold path.
+ *
+ * Uses `_forceDirty()` rather than `markDirty()` so the propagation
+ * walks through layout boundaries (Phase 3). Differential-mode and
+ * fuzzer validation rely on dirtying the entire tree to force the
+ * cold path; without this, boundaries would short-circuit the walk
+ * and leave clean ancestors that would never re-run the algorithm.
+ *
+ * Note: `Node._forceDirty()` also calls `_measureCache?.clear()` and
+ * `_layoutCache?.clear()` as a side-effect of dirtying. So calling
+ * `clearAllCaches(root)` then `markDirtyDeep(root)` clears each node's
+ * caches twice. The second clear is harmless (no-op on an empty
+ * structure), but differential-mode callers should know the
+ * redundancy is intentional — we want both invariants explicit at the
+ * call site.
+ *
+ * @internal
+ */
+export declare function markDirtyDeep(root: Node): void;
+/**
+ * Build a `LayoutCacheValue` from `node`'s current `_layout` + its direct
+ * children's `_layout`. Captures only direct children; deeper descendants
+ * are reconstituted via their own caches during `restoreFromCache`.
+ *
+ * Called by the algorithm AFTER `roundLayout` and `computeScrollSizes`
+ * have populated all `_layout` fields, so the captured values are
+ * already integer-rounded and scroll-aware.
+ *
+ * @internal
+ */
+export declare function snapshotForCache(node: Node): LayoutCacheValue;
+/**
+ * Restore `node`'s own size + scroll metrics, plus its direct children's
+ * left/top/width/height/scroll. The caller is responsible for handling
+ * the recursion into deeper descendants via per-child cache lookups (or
+ * a `layoutChildren` fallback on miss).
+ *
+ * Pre-conditions: `node`'s child list at this call must match the child
+ * list captured at cache-store time. The cache invalidation on
+ * `insertChild`/`removeChild` (via `markDirty`) guarantees this — a
+ * mismatch indicates a cache-correctness bug. We assert in differential
+ * mode.
+ *
+ * @internal
+ */
+export declare function restoreFromCache(node: Node, value: LayoutCacheValue): void;
+/**
+ * Produce a human-readable diff of two tree-layout snapshots. Returns
+ * an empty string if they match. Used by differential mode to surface
+ * cache bugs with enough context to debug them.
+ *
+ * @internal
+ */
+export declare function diffLayouts(a: ComputedLayout[], b: ComputedLayout[]): string;
+//# sourceMappingURL=cache.d.ts.map

package/dist/algorithm/cache.d.ts.map

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

package/dist/algorithm/cache.js

@@ -0,0 +1,312 @@
+/**
+ * Layout-engine caches.
+ *
+ * Phase 1: `MeasureCache` — caches the result of a leaf node's
+ * `MeasureFunc` so repeated calls with the same available-space
+ * inputs don't reinvoke the measurer. Wired into every measure-func
+ * call site in `main-axis.ts` via the `callMeasureFunc` helper.
+ *
+ * Caches are owned by `Node` (`_measureCache` field) and cleared
+ * automatically by `markDirty()`. Consumers never interact with the
+ * cache directly — it is `@internal`.
+ *
+ * Phase 2 added `LayoutCache` here (P2-T1).
+ *
+ * @internal
+ */
+/**
+ * Up to eight slots — matches Yoga's `LayoutResults::MaxCachedMeasurements`
+ * with the documented rationale "98% of analyzed layouts require less
+ * than 8 entries" (see facebook/yoga `node/LayoutResults.h`). Covers the
+ * hypothetical-vs-final pattern (single leaf measured twice per pass)
+ * plus broader reuse patterns where the same leaf is measured at multiple
+ * cross-axis sizes during line packing or across consecutive layout calls.
+ *
+ * Linear scan over 8 slots is a few-cycle hot-path cost; slots are
+ * lazy-allocated only on leaves with a `MeasureFunc` installed.
+ *
+ * @internal
+ */
+export class MeasureCache {
+    static MAX_ENTRIES = 8;
+    slots = [];
+    /**
+     * Hit/miss counters for diagnostics (bench output, debugging). Always
+     * on — the spec originally proposed `__DEV__`-gating these, but the
+     * project has no build-tooling `__DEV__` define and the counters cost
+     * two property writes per `lookup()` (negligible at any realistic
+     * call rate). Counts are incremented only by `lookup()`; `store()`
+     * assumes `lookup()` has already been called for the same key on the
+     * same call site, so it does not double-count.
+     *
+     * @internal
+     */
+    hits = 0;
+    /** See {@link hits}. @internal */
+    misses = 0;
+    lookup(key) {
+        for (const slot of this.slots) {
+            if (slot.availableWidth === key.availableWidth &&
+                slot.widthMode === key.widthMode &&
+                slot.availableHeight === key.availableHeight &&
+                slot.heightMode === key.heightMode) {
+                this.hits++;
+                return { width: slot.width, height: slot.height };
+            }
+        }
+        this.misses++;
+        return undefined;
+    }
+    /**
+     * Store `value` for `key`. If `key` is already present, overwrite in
+     * place without growing the slot array; otherwise append, evicting
+     * the oldest slot when the array is at `MAX_ENTRIES` capacity.
+     *
+     * Callers should always invoke `lookup(key)` first and only call
+     * `store()` on a miss — the `misses` counter is incremented by
+     * `lookup()`, not here, so calling `store()` without a prior lookup
+     * would cause silent miss undercounting in diagnostics.
+     */
+    store(key, value) {
+        for (const slot of this.slots) {
+            if (slot.availableWidth === key.availableWidth &&
+                slot.widthMode === key.widthMode &&
+                slot.availableHeight === key.availableHeight &&
+                slot.heightMode === key.heightMode) {
+                slot.width = value.width;
+                slot.height = value.height;
+                return;
+            }
+        }
+        if (this.slots.length < MeasureCache.MAX_ENTRIES) {
+            this.slots.push({ ...key, ...value });
+        }
+        else {
+            this.slots.shift();
+            this.slots.push({ ...key, ...value });
+        }
+    }
+    /**
+     * Drop every cached entry. The `hits`/`misses` counters are
+     * deliberately preserved across `clear()` calls — they're lifetime
+     * diagnostics, not per-pass metrics, and zeroing them would mask the
+     * total-pressure picture during bench runs.
+     */
+    clear() {
+        this.slots.length = 0;
+    }
+}
+/**
+ * Single-slot per-node layout cache. Matches Yoga's `cachedLayout`
+ * (single overwrite-on-write) and Taffy's 1-slot layout-cache. Internal
+ * nodes' final-pass keys converge to one stable input once the parent's
+ * flex distribution has settled, so additional slots would be dead memory.
+ *
+ * Lazy-allocated by the algorithm in `algorithm/main-axis.ts` and
+ * `algorithm/index.ts` only on nodes that actually go through the
+ * `layoutChildren` recursion. Cleared by `Node.markDirty()` (which fires
+ * on every style/tree mutation).
+ *
+ * Hit/miss counters are always-on (same rationale as `MeasureCache`).
+ *
+ * @internal
+ */
+export class LayoutCache {
+    slot = undefined;
+    /** @internal */
+    hits = 0;
+    /** @internal */
+    misses = 0;
+    lookup(key) {
+        const slot = this.slot;
+        if (slot !== undefined &&
+            slot.availableWidth === key.availableWidth &&
+            slot.widthMode === key.widthMode &&
+            slot.availableHeight === key.availableHeight &&
+            slot.heightMode === key.heightMode) {
+            this.hits++;
+            return slot.value;
+        }
+        this.misses++;
+        return undefined;
+    }
+    /**
+     * Store `value` for `key`. Single-slot — replaces the previous entry
+     * unconditionally. Caller must construct a fresh `LayoutCacheValue` per
+     * store; this method does NOT deep-clone for performance, so any
+     * subsequent mutation of `value` is visible through `lookup`. The
+     * algorithm builds new values per layout pass so the contract holds.
+     */
+    store(key, value) {
+        this.slot = { ...key, value };
+    }
+    clear() {
+        this.slot = undefined;
+    }
+}
+/**
+ * Pre-order traversal returning a flat array of layout snapshots, one per
+ * node. Used by differential mode to capture and compare the entire tree's
+ * layout state cheaply.
+ *
+ * Captures only the six `ComputedLayout` fields. `_dirty` flags, cache
+ * contents, and other ancillary state are NOT in scope. Phase 2's
+ * layout-cache work should add `_dirty` validation to the harness if
+ * dirty-flag semantics ever become load-bearing for cache correctness.
+ *
+ * @internal
+ */
+export function snapshotTreeLayouts(root) {
+    const out = [];
+    visit(root);
+    return out;
+    function visit(n) {
+        out.push({
+            left: n.layout.left,
+            top: n.layout.top,
+            width: n.layout.width,
+            height: n.layout.height,
+            scrollWidth: n.layout.scrollWidth,
+            scrollHeight: n.layout.scrollHeight,
+        });
+        for (let i = 0; i < n.getChildCount(); i++)
+            visit(n.getChild(i));
+    }
+}
+/**
+ * Recursively clear `_measureCache` and `_layoutCache` on every node in
+ * the subtree. Used by differential mode and the fuzzer to force the cold
+ * path.
+ *
+ * @internal
+ */
+export function clearAllCaches(root) {
+    root._measureCache?.clear();
+    root._layoutCache?.clear();
+    for (let i = 0; i < root.getChildCount(); i++)
+        clearAllCaches(root.getChild(i));
+}
+/**
+ * Mark every node in the subtree dirty. Used after `clearAllCaches` to
+ * force `calculateLayout` down the full cold path.
+ *
+ * Uses `_forceDirty()` rather than `markDirty()` so the propagation
+ * walks through layout boundaries (Phase 3). Differential-mode and
+ * fuzzer validation rely on dirtying the entire tree to force the
+ * cold path; without this, boundaries would short-circuit the walk
+ * and leave clean ancestors that would never re-run the algorithm.
+ *
+ * Note: `Node._forceDirty()` also calls `_measureCache?.clear()` and
+ * `_layoutCache?.clear()` as a side-effect of dirtying. So calling
+ * `clearAllCaches(root)` then `markDirtyDeep(root)` clears each node's
+ * caches twice. The second clear is harmless (no-op on an empty
+ * structure), but differential-mode callers should know the
+ * redundancy is intentional — we want both invariants explicit at the
+ * call site.
+ *
+ * @internal
+ */
+export function markDirtyDeep(root) {
+    root._forceDirty();
+    for (let i = 0; i < root.getChildCount(); i++)
+        markDirtyDeep(root.getChild(i));
+}
+/**
+ * Build a `LayoutCacheValue` from `node`'s current `_layout` + its direct
+ * children's `_layout`. Captures only direct children; deeper descendants
+ * are reconstituted via their own caches during `restoreFromCache`.
+ *
+ * Called by the algorithm AFTER `roundLayout` and `computeScrollSizes`
+ * have populated all `_layout` fields, so the captured values are
+ * already integer-rounded and scroll-aware.
+ *
+ * @internal
+ */
+export function snapshotForCache(node) {
+    const childLayouts = [];
+    const count = node.getChildCount();
+    for (let i = 0; i < count; i++) {
+        const c = node.getChild(i);
+        childLayouts.push({
+            left: c.layout.left,
+            top: c.layout.top,
+            width: c.layout.width,
+            height: c.layout.height,
+            scrollWidth: c.layout.scrollWidth,
+            scrollHeight: c.layout.scrollHeight,
+            floatLeft: c._floatLeft,
+            floatTop: c._floatTop,
+        });
+    }
+    return {
+        width: node.layout.width,
+        height: node.layout.height,
+        scrollWidth: node.layout.scrollWidth,
+        scrollHeight: node.layout.scrollHeight,
+        childLayouts,
+    };
+}
+/**
+ * Restore `node`'s own size + scroll metrics, plus its direct children's
+ * left/top/width/height/scroll. The caller is responsible for handling
+ * the recursion into deeper descendants via per-child cache lookups (or
+ * a `layoutChildren` fallback on miss).
+ *
+ * Pre-conditions: `node`'s child list at this call must match the child
+ * list captured at cache-store time. The cache invalidation on
+ * `insertChild`/`removeChild` (via `markDirty`) guarantees this — a
+ * mismatch indicates a cache-correctness bug. We assert in differential
+ * mode.
+ *
+ * @internal
+ */
+export function restoreFromCache(node, value) {
+    if (process.env.PILATES_DIFFERENTIAL_LAYOUT === '1') {
+        if (node.getChildCount() !== value.childLayouts.length) {
+            throw new Error(`[pilates layout cache] restored value has ${value.childLayouts.length} children but node has ${node.getChildCount()} — cache invalidation bug`);
+        }
+    }
+    node._layout.width = value.width;
+    node._layout.height = value.height;
+    node._layout.scrollWidth = value.scrollWidth;
+    node._layout.scrollHeight = value.scrollHeight;
+    // node._layout.left/top are set by the caller before recursion starts
+    // (root sets to 0; child positions come from this restore via the
+    // childLayouts array below).
+    for (let i = 0; i < node.getChildCount(); i++) {
+        const c = node.getChild(i);
+        const cl = value.childLayouts[i];
+        c._layout.left = cl.left;
+        c._layout.top = cl.top;
+        c._layout.width = cl.width;
+        c._layout.height = cl.height;
+        c._layout.scrollWidth = cl.scrollWidth;
+        c._layout.scrollHeight = cl.scrollHeight;
+        c._floatLeft = cl.floatLeft;
+        c._floatTop = cl.floatTop;
+    }
+}
+/**
+ * Produce a human-readable diff of two tree-layout snapshots. Returns
+ * an empty string if they match. Used by differential mode to surface
+ * cache bugs with enough context to debug them.
+ *
+ * @internal
+ */
+export function diffLayouts(a, b) {
+    if (a.length !== b.length) {
+        return `tree length mismatch: cached has ${a.length} nodes, cold has ${b.length}`;
+    }
+    const fields = ['left', 'top', 'width', 'height', 'scrollWidth', 'scrollHeight'];
+    for (let i = 0; i < a.length; i++) {
+        const av = a[i];
+        const bv = b[i];
+        for (const f of fields) {
+            if (av[f] !== bv[f]) {
+                return `node[${i}].${f}: cached=${av[f]} cold=${bv[f]}`;
+            }
+        }
+    }
+    return '';
+}
+//# sourceMappingURL=cache.js.map

package/dist/algorithm/cache.js.map

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

package/dist/algorithm/index.d.ts

@@ -6,6 +6,13 @@
  *   2. Recursively lay out children in floating-point coordinates.
  *   3. Round the whole tree to integer cells.
  *   4. Mark every node clean.
+ *
+ * When `PILATES_DIFFERENTIAL_LAYOUT=1` is set in the environment, the
+ * exported `calculateLayout` runs the algorithm twice — once normally
+ * (with caches active), then again with all caches cleared and every
+ * node forcibly re-dirtied — and asserts the two snapshots are byte
+ * identical. Used by the test suite (`pnpm test:differential`) to
+ * catch any cache-correctness regression as soon as it lands.
  */
 import type { Node } from '../node.js';
 export declare function calculateLayout(root: Node, availableWidth: number | undefined, availableHeight: number | undefined): void;

package/dist/algorithm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/algorithm/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAIvC,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,EACV,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,eAAe,EAAE,MAAM,GAAG,SAAS,GAClC,IAAI,CAUN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/algorithm/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAevC,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,EACV,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,eAAe,EAAE,MAAM,GAAG,SAAS,GAClC,IAAI,CAsBN"}