@pilates/core 1.0.0-rc.1 → 1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 pilates contributors
+Copyright (c) 2026 Pilates contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,13 +1,18 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pilatesjs/pilates/main/assets/logo-dark.svg">
+  <img src="https://raw.githubusercontent.com/pilatesjs/pilates/main/assets/logo.svg" alt="pilates" width="48">
+</picture>
+
 # @pilates/core
 
 > Headless flex layout engine for terminal UIs. Imperative `Node` API, integer cell
 > coordinates, terminal-correct text measurement. **Pure TypeScript, zero runtime
 > dependencies.**
 
-`@pilates/core` is what you get when you take Yoga's flex algorithm, rebuild it for
-the terminal (integer cells, CJK / emoji / wide-char awareness, ANSI escape
-passthrough), and *unbundle* it from any UI framework. Use it directly, or wrap it
-in React, Vue, Svelte, or anything else.
+`@pilates/core` is the engine of **Pilates** — a flex layout algorithm built
+for the terminal (integer cells, CJK / emoji / wide-char awareness, ANSI
+escape passthrough), unbundled from any UI framework. Use it directly, or wrap
+it in React, Vue, Svelte, or anything else.
 
 ## Install
 
@@ -42,12 +47,12 @@ sidebar.getComputedLayout(); // { left:58, top:1, width:20, height:22 }
 
 ## Style API
 
-Setters mirror Yoga / CSS Flexbox semantics. All values are in terminal cells.
+Setters mirror CSS Flexbox semantics. All values are in terminal cells.
 
 | Category | Setters |
 |---|---|
 | Direction | `setFlexDirection`, `setFlexWrap` |
-| Sizing | `setWidth`, `setHeight`, `setMinWidth`, `setMinHeight`, `setMaxWidth`, `setMaxHeight` |
+| Sizing | `setWidth`, `setHeight`, `setMinWidth`, `setMinHeight`, `setMaxWidth`, `setMaxHeight`, `setAspectRatio` |
 | Flex | `setFlex` (shorthand), `setFlexGrow`, `setFlexShrink`, `setFlexBasis` |
 | Spacing | `setPadding(edge, n)`, `setMargin(edge, n)`, `setGap('row' \| 'column', n)` |
 | Alignment | `setJustifyContent`, `setAlignItems`, `setAlignSelf`, `setAlignContent` |
@@ -88,9 +93,10 @@ text.setMeasureFunc((width, widthMode, height, heightMode) => {
 ## Status
 
 Release candidate (`1.0.0-rc.1`). The full v1 surface is implemented and
-verified cell-for-cell against `yoga-layout` (Meta's reference WASM build).
+validated cell-for-cell against a reference WASM flexbox implementation
+across 30 oracle fixtures.
 
-**Out of v1:** `aspectRatio`, RTL/LTR direction inheritance, baseline alignment.
+**Out of v1:** RTL/LTR direction inheritance, baseline alignment.
 
 ## License
 

package/dist/algorithm/axis.d.ts

@@ -34,6 +34,19 @@ export declare function readEnd(box: readonly number[], axis: Axis): number;
 export declare function gapAlong(style: Style, axis: Axis): number;
 /** The style's preferred size along an axis (`width` for row, `height` for column). */
 export declare function preferredSize(style: Style, axis: Axis): number | 'auto';
+/**
+ * Like `preferredSize`, but additionally derives the size from `aspectRatio`
+ * when this axis is `'auto'` and the perpendicular axis is an explicit number:
+ *   width = height * aspectRatio  (axis === 'row')
+ *   height = width  / aspectRatio (axis === 'column')
+ *
+ * If both axes are explicit, the explicit value on this axis wins (the ratio
+ * is treated as a hint, per the CSS aspect-ratio spec). If both are `'auto'`,
+ * we have nothing to derive from and return `'auto'`. The result is NOT
+ * clamped — callers are expected to feed it through `clampSize` so min/max
+ * still bind on each axis.
+ */
+export declare function effectivePreferredSize(style: Style, axis: Axis): number | 'auto';
 export declare function minSize(style: Style, axis: Axis): number;
 export declare function maxSize(style: Style, axis: Axis): number | undefined;
 /** Clamp a candidate size to the [minSize, maxSize] range for the given axis. */

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

@@ -1 +1 @@
-{"version":3,"file":"axis.d.ts","sourceRoot":"","sources":["../../src/algorithm/axis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,MAAM,IAAI,GAAG,KAAK,GAAG,QAAQ,CAAC;AAOpC,wBAAgB,QAAQ,CAAC,CAAC,EAAE,aAAa,GAAG,IAAI,CAE/C;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,aAAa,GAAG,IAAI,CAEhD;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,aAAa,GAAG,OAAO,CAEnD;AAED,qDAAqD;AACrD,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE5C;AAED,mDAAmD;AACnD,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE1C;AAED,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,CAEpE;AAED,+DAA+D;AAC/D,wBAAgB,OAAO,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,CAElE;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,CAEzD;AAED,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAEvE;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,CAExD;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAEpE;AAED,iFAAiF;AACjF,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMzE"}
+{"version":3,"file":"axis.d.ts","sourceRoot":"","sources":["../../src/algorithm/axis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,MAAM,IAAI,GAAG,KAAK,GAAG,QAAQ,CAAC;AAOpC,wBAAgB,QAAQ,CAAC,CAAC,EAAE,aAAa,GAAG,IAAI,CAE/C;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,aAAa,GAAG,IAAI,CAEhD;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,aAAa,GAAG,OAAO,CAEnD;AAED,qDAAqD;AACrD,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE5C;AAED,mDAAmD;AACnD,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE1C;AAED,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,CAEpE;AAED,+DAA+D;AAC/D,wBAAgB,OAAO,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,CAElE;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,CAEzD;AAED,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAEvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAQhF;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,CAExD;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAEpE;AAED,iFAAiF;AACjF,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMzE"}

package/dist/algorithm/axis.js

@@ -54,6 +54,30 @@ export function gapAlong(style, axis) {
 export function preferredSize(style, axis) {
     return axis === 'row' ? style.width : style.height;
 }
+/**
+ * Like `preferredSize`, but additionally derives the size from `aspectRatio`
+ * when this axis is `'auto'` and the perpendicular axis is an explicit number:
+ *   width = height * aspectRatio  (axis === 'row')
+ *   height = width  / aspectRatio (axis === 'column')
+ *
+ * If both axes are explicit, the explicit value on this axis wins (the ratio
+ * is treated as a hint, per the CSS aspect-ratio spec). If both are `'auto'`,
+ * we have nothing to derive from and return `'auto'`. The result is NOT
+ * clamped — callers are expected to feed it through `clampSize` so min/max
+ * still bind on each axis.
+ */
+export function effectivePreferredSize(style, axis) {
+    const s = preferredSize(style, axis);
+    if (typeof s === 'number')
+        return s;
+    const ratio = style.aspectRatio;
+    if (ratio === undefined)
+        return 'auto';
+    const other = preferredSize(style, axis === 'row' ? 'column' : 'row');
+    if (typeof other !== 'number')
+        return 'auto';
+    return axis === 'row' ? other * ratio : other / ratio;
+}
 export function minSize(style, axis) {
     return axis === 'row' ? style.minWidth : style.minHeight;
 }

package/dist/algorithm/axis.js.map

@@ -1 +1 @@
-{"version":3,"file":"axis.js","sourceRoot":"","sources":["../../src/algorithm/axis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,MAAM,GAAG,GAAG,CAAC,CAAC;AACd,MAAM,KAAK,GAAG,CAAC,CAAC;AAChB,MAAM,MAAM,GAAG,CAAC,CAAC;AACjB,MAAM,IAAI,GAAG,CAAC,CAAC;AAEf,MAAM,UAAU,QAAQ,CAAC,CAAgB;IACvC,OAAO,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,CAAgB;IACxC,OAAO,QAAQ,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,CAAgB;IACxC,OAAO,CAAC,KAAK,aAAa,IAAI,CAAC,KAAK,gBAAgB,CAAC;AACvD,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,SAAS,CAAC,IAAU;IAClC,OAAO,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;AACrC,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,OAAO,CAAC,IAAU;IAChC,OAAO,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;AACzC,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,SAAS,CAAC,GAAsB,EAAE,IAAU;IAC1D,OAAO,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,OAAO,CAAC,GAAsB,EAAE,IAAU;IACxD,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAY,EAAE,IAAU;IAC/C,OAAO,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;AACzD,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,aAAa,CAAC,KAAY,EAAE,IAAU;IACpD,OAAO,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAY,EAAE,IAAU;IAC9C,OAAO,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAY,EAAE,IAAU;IAC9C,OAAO,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC;AAC3D,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,SAAS,CAAC,KAAY,EAAE,IAAU,EAAE,KAAa;IAC/D,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACjC,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACjC,IAAI,CAAC,GAAG,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;IAClC,IAAI,GAAG,KAAK,SAAS,IAAI,CAAC,GAAG,GAAG;QAAE,CAAC,GAAG,GAAG,CAAC;IAC1C,OAAO,CAAC,CAAC;AACX,CAAC"}
+{"version":3,"file":"axis.js","sourceRoot":"","sources":["../../src/algorithm/axis.ts"],"names":[],"mappings":"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"}

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