@pilates/core 1.0.1 → 2.0.0

package/dist/algorithm/spineless/classify.js

@@ -0,0 +1,109 @@
+/**
+ * Dirty-region classifier for the `calculateLayout` router (phase 14).
+ *
+ * Examines the dirty region of `root` against a snapshot map of the
+ * pre-mutation tree state. Returns a discriminated union telling the
+ * router which engine to use:
+ *
+ *   - `value`        — only value mutations on snapped nodes; Spineless wins
+ *   - `structural`   — one pivot node had its child list change; route to imperative
+ *   - `multi-pivot`  — two or more parents had children change; imperative for safety
+ *   - `sig-change`   — a snapped node had its signature or measure func change; imperative
+ *   - `no-snap`      — no snap map available (driver is cold or just invalidated)
+ *
+ * Pure function over `Node` reads + the snap map. No I/O, no
+ * side effects.
+ *
+ * @internal
+ */
+/**
+ * Build a structural signature for one node. Two nodes' sigs are equal
+ * iff their style-affecting-layout-shape fields are equal — see
+ * `SpinelessLayout`'s `nodeSig` for the inspiration.
+ */
+function nodeSig(node) {
+    const s = node.style;
+    return [
+        s.flexDirection,
+        s.flexWrap,
+        s.justifyContent,
+        s.alignItems,
+        s.alignContent,
+        s.alignSelf,
+        s.positionType,
+        s.display,
+        typeof s.width,
+        typeof s.height,
+        typeof s.flexBasis,
+        s.flexGrow > 0 ? 'g' : '_',
+        s.flexShrink > 0 ? 's' : '_',
+        s.aspectRatio === undefined ? 'n' : String(s.aspectRatio),
+        s.position.map((p) => (p === undefined ? '_' : String(p))).join(','),
+    ].join('|');
+}
+/** Snapshot one node's structural shape for later comparison. */
+export function snapNode(node) {
+    const children = [];
+    for (let i = 0; i < node.getChildCount(); i++)
+        children.push(node.getChild(i));
+    return { sig: nodeSig(node), measure: node.getMeasureFunc(), children };
+}
+/** True iff `node`'s current child list still matches `snap.children`. */
+function childrenUnchanged(snap, node) {
+    if (node.getChildCount() !== snap.children.length)
+        return false;
+    for (let i = 0; i < snap.children.length; i++) {
+        if (node.getChild(i) !== snap.children[i])
+            return false;
+    }
+    return true;
+}
+/** Walk dirty region, classify against the snap map. */
+export function classifyDirty(root, snaps) {
+    if (snaps === null)
+        return { kind: 'no-snap' };
+    let structuralPivot = null;
+    let multiPivot = false;
+    let sigChanged = false;
+    function visit(n) {
+        if (sigChanged || multiPivot)
+            return;
+        const dirty = n.isDirty();
+        const hasDirtyDescendant = n
+            ._hasDirtyDescendant;
+        const snap = snaps.get(n);
+        if (snap === undefined) {
+            // A node with no snap that's part of the dirty walk = newly
+            // introduced node (e.g. an appended child). Its parent's child-list
+            // change is already tracked via childrenUnchanged(); don't escalate
+            // to multi-pivot just because the new subtree contains unseen nodes.
+            return;
+        }
+        if (dirty) {
+            if (snap.sig !== nodeSig(n) || snap.measure !== n.getMeasureFunc()) {
+                sigChanged = true;
+                return;
+            }
+            if (!childrenUnchanged(snap, n)) {
+                if (structuralPivot !== null && structuralPivot !== n) {
+                    multiPivot = true;
+                    return;
+                }
+                structuralPivot = n;
+            }
+        }
+        if (dirty || hasDirtyDescendant) {
+            for (let i = 0; i < n.getChildCount(); i++)
+                visit(n.getChild(i));
+        }
+    }
+    visit(root);
+    if (sigChanged)
+        return { kind: 'sig-change' };
+    if (multiPivot)
+        return { kind: 'multi-pivot' };
+    if (structuralPivot !== null)
+        return { kind: 'structural', pivot: structuralPivot };
+    return { kind: 'value' };
+}
+//# sourceMappingURL=classify.js.map

package/dist/algorithm/spineless/classify.js.map

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

package/dist/algorithm/spineless/field-id-pool.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Monotonic integer ID allocator for Spineless `Field` objects.
+ * Phase 15I indexes the runtime's typed-array storage by field.id.
+ *
+ * IDs are never recycled — Fields are interned per (node, name) and
+ * live as long as their node. The max id is the live-field high-water
+ * mark, matching LayoutPool's accepted tradeoff.
+ *
+ * @internal
+ */
+/** Allocate a fresh unique integer id for a Field. */
+export declare function allocateFieldId(): number;
+/** Current id count — the exclusive upper bound of allocated ids.
+ *  Runtime typed arrays size to at least this. @internal */
+export declare function fieldIdCount(): number;
+/** Reset for tests. @internal
+ *
+ * WARNING: Only safe to call when no live `Field` objects exist
+ * anywhere — the `FIELD_REGISTRY` WeakMap in `grammar.ts` is NOT
+ * cleared, so any `Field` retained across this call still holds
+ * its old id. Newly-allocated fields will then collide with retained
+ * ids, aliasing entries in the runtime's typed-array storage. The
+ * standard test harness creates fresh `Node`s per test, so retained
+ * cross-test references are the only way to hit this; don't introduce
+ * them.
+ */
+export declare function _resetFieldIdsForTesting(): void;
+//# sourceMappingURL=field-id-pool.d.ts.map

package/dist/algorithm/spineless/field-id-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-id-pool.d.ts","sourceRoot":"","sources":["../../../src/algorithm/spineless/field-id-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,sDAAsD;AACtD,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;4DAC4D;AAC5D,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}

package/dist/algorithm/spineless/field-id-pool.js

@@ -0,0 +1,35 @@
+/**
+ * Monotonic integer ID allocator for Spineless `Field` objects.
+ * Phase 15I indexes the runtime's typed-array storage by field.id.
+ *
+ * IDs are never recycled — Fields are interned per (node, name) and
+ * live as long as their node. The max id is the live-field high-water
+ * mark, matching LayoutPool's accepted tradeoff.
+ *
+ * @internal
+ */
+let _nextFieldId = 0;
+/** Allocate a fresh unique integer id for a Field. */
+export function allocateFieldId() {
+    return _nextFieldId++;
+}
+/** Current id count — the exclusive upper bound of allocated ids.
+ *  Runtime typed arrays size to at least this. @internal */
+export function fieldIdCount() {
+    return _nextFieldId;
+}
+/** Reset for tests. @internal
+ *
+ * WARNING: Only safe to call when no live `Field` objects exist
+ * anywhere — the `FIELD_REGISTRY` WeakMap in `grammar.ts` is NOT
+ * cleared, so any `Field` retained across this call still holds
+ * its old id. Newly-allocated fields will then collide with retained
+ * ids, aliasing entries in the runtime's typed-array storage. The
+ * standard test harness creates fresh `Node`s per test, so retained
+ * cross-test references are the only way to hit this; don't introduce
+ * them.
+ */
+export function _resetFieldIdsForTesting() {
+    _nextFieldId = 0;
+}
+//# sourceMappingURL=field-id-pool.js.map

package/dist/algorithm/spineless/field-id-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-id-pool.js","sourceRoot":"","sources":["../../../src/algorithm/spineless/field-id-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,IAAI,YAAY,GAAG,CAAC,CAAC;AAErB,sDAAsD;AACtD,MAAM,UAAU,eAAe;IAC7B,OAAO,YAAY,EAAE,CAAC;AACxB,CAAC;AAED;4DAC4D;AAC5D,MAAM,UAAU,YAAY;IAC1B,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB;IACtC,YAAY,GAAG,CAAC,CAAC;AACnB,CAAC"}

package/dist/algorithm/spineless/flex-grammar.d.ts

@@ -0,0 +1,394 @@
+/**
+ * Flexbox layout expressed as an attribute grammar.
+ *
+ * Current slice (v16b) covers:
+ *
+ *   - flex-direction: `row`, `column`, `row-reverse`, `column-reverse`
+ *   - flex-grow / flex-shrink / flex-basis (v3-v4)
+ *   - padding / margin / gap (v5)
+ *   - justify-content + align-items / align-self (v6)
+ *   - flex-wrap (v7) — single-line wrap and multi-line packing,
+ *     each line independently distributed / justified / aligned
+ *   - positionType: `'absolute'` (v8) — out-of-flow children
+ *     positioned against the parent's OUTER box via `style.position`
+ *     and `style.margin`. Width / height resolve from explicit
+ *     style, from opposing edges (`left`+`right` or `top`+`bottom`),
+ *     or fall back to 0. Absolute children are filtered out of every
+ *     in-flow computation (flex distribution, justify leftover,
+ *     wrap line packing).
+ *   - align-content (v9) — for multi-line wrap containers, the cross-
+ *     axis leftover is distributed among / around the lines per
+ *     `flex-start` / `flex-end` / `center` / `space-between` /
+ *     `space-around` / `stretch`
+ *   - flex-wrap: `wrap-reverse` (v10) — the line stack is mirrored
+ *     on the cross axis
+ *   - flex-direction: `row-reverse` / `column-reverse` (v11) — the
+ *     main axis runs from the container's main END; each in-flow
+ *     child's main position is reflected across the inner-main box,
+ *     mirroring the imperative `flipMainAxis`
+ *   - min / max size clamping (v12) — every node's main size, cross
+ *     size, and an absolute child's width / height are clamped to
+ *     the node's own `[minWidth/Height, maxWidth/Height]`. v12a
+ *     covered the single-shot sites (non-distributed main size,
+ *     cross size, absolute children); v12b folds min/max into the
+ *     flex-distribution freeze loop and the wrap line packer — an
+ *     item whose proportional grow / shrink target breaches a clamp
+ *     is frozen at its bound and its share redistributed, iterating
+ *     to a fixpoint, exactly as the imperative `distributeGrow` /
+ *     `distributeShrink`.
+ *   - `'auto'` main size (v13) — a non-measured `'auto'` main-axis
+ *     size resolves to 0 (mirroring `resolveHypotheticalMainSize`);
+ *     the root's `'auto'` axis resolves from the caller-supplied
+ *     `available` size, modelled as a root input Field so a terminal
+ *     resize is incremental.
+ *   - `'auto'` cross size + `align-items: stretch` (v14) — an
+ *     `'auto'` cross-axis size is 0 under a non-stretch align, but
+ *     `stretch` (the default) resizes it to fill the line's inner
+ *     cross, mirroring the imperative `crossAlignItemsInLine`
+ *     stretch branch.
+ *   - `aspectRatio` (v15) — an `'auto'` axis whose perpendicular
+ *     axis is an explicit number derives `width = height × ratio` /
+ *     `height = width ÷ ratio`, mirroring `effectivePreferredSize`.
+ *     A derived axis is definite (not content-sized) — so it is not
+ *     stretched.
+ *   - measure-func leaves (v16) — a childless node with a measure
+ *     function resolves its `'auto'` axes by calling the measurer.
+ *     v16a covers the MAIN axis (main free, cross constrained,
+ *     mirroring `resolveHypotheticalMainSize`); v16b the CROSS axis
+ *     (cross constrained `AtMost` the parent inner cross, main free
+ *     with a hint, mirroring `naturalCrossSize`). A measured cross
+ *     feeds the wrap line cross-size aggregation and the non-stretch
+ *     cross size; `align-items: stretch` still overrides it.
+ *
+ * With v16 the grammar covers the full imperative `'auto'` /
+ * measure / `aspectRatio` resolution: the Spineless engine is a
+ * drop-in for `calculateLayout` on real content-sized trees.
+ *
+ * Fields emitted per node:
+ *
+ *   - `width`  — main-axis size when parent is `row`, cross-axis size
+ *                when parent is `column`. Cross axis reads
+ *                `style.width` verbatim. Main axis is the result of
+ *                flex distribution when the parent has any child with
+ *                grow > 0, shrink > 0, or numeric `flexBasis`;
+ *                otherwise it equals the basis.
+ *   - `height` — symmetric to `width`.
+ *   - `left`   — position relative to parent. For row-parent children
+ *                this is the main-axis cursor: `padLeft + myMarginLeft
+ *                + sum_priors(marginLeft + width + marginRight) +
+ *                i*gapColumn`. For column-parent children it's the
+ *                cross-axis position: `padLeft + myMarginLeft`. Root
+ *                is at 0.
+ *   - `top`    — symmetric to `left`.
+ *
+ * @internal
+ */
+import type { Node } from '../../node.js';
+import { type Field, type FieldRule, type Grammar } from './grammar.js';
+/**
+ * Per-node input Fields for the style props the grammar reads. Each
+ * is present only if the grammar actually reads that prop for the
+ * node — every in-flow node has all three sizes; a container that
+ * lays children out along an axis has the matching `gap*`; an
+ * absolute child has `width` / `height` only when its size is
+ * explicit.
+ *
+ * @internal
+ */
+export interface StyleInputs {
+    width?: Field<number>;
+    height?: Field<number>;
+    flexBasis?: Field<number>;
+    flexGrow?: Field<number>;
+    flexShrink?: Field<number>;
+    gapRow?: Field<number>;
+    gapColumn?: Field<number>;
+    /**
+     * Min / max size clamps. `min*` default to 0; `max*` carry
+     * `Infinity` when `style.max{Width,Height}` is `undefined` ("no
+     * upper bound"), so a single `clampMinMax` covers both.
+     */
+    minWidth?: Field<number>;
+    minHeight?: Field<number>;
+    maxWidth?: Field<number>;
+    maxHeight?: Field<number>;
+    /**
+     * Per-edge `padding` input Fields, indexed `[top, right, bottom,
+     * left]`. Entries are present only for edges the grammar reads
+     * (a container reads all four of its own padding edges).
+     */
+    padding?: Array<Field<number> | undefined>;
+    /**
+     * Per-edge `margin` input Fields, indexed `[top, right, bottom,
+     * left]`. Present for every non-root in-flow node and every
+     * absolute child (the grammar reads all four edges).
+     */
+    margin?: Array<Field<number> | undefined>;
+}
+/**
+ * Roots used by `buildFlexGrammar` to identify which (Node, name) pair
+ * is the canonical entry point. The Spineless runtime / interpreter
+ * starts evaluation from this set of fields and walks deps.
+ *
+ * @internal
+ */
+export interface FlexGrammarOutput {
+    grammar: Grammar;
+    /** Fields the caller typically wants computed on the root. */
+    rootFields: {
+        width: Field<number>;
+        height: Field<number>;
+        left: Field<number>;
+        top: Field<number>;
+    };
+    /** All emitted fields, in pre-order. Useful for differential tests. */
+    allFields: Array<{
+        node: Node;
+        width: Field<number>;
+        height: Field<number>;
+        left: Field<number>;
+        top: Field<number>;
+    }>;
+    /**
+     * Per-node input Fields for the style props the grammar models as
+     * graph inputs — currently the SIZE props (`width` / `height` /
+     * `flexBasis`), `gap` (`gapRow` / `gapColumn`), `padding` and
+     * `margin` (per-edge). Each is a leaf field whose value is the live
+     * `node.style` value; every layout field that reads one declares
+     * the matching input as a dependency. To drive a precise
+     * incremental relayout after a `setWidth` / `setHeight` /
+     * `setFlexBasis` / `setFlexGrow` / `setFlexShrink` / `setGap` /
+     * `setPadding` / `setMargin`, `markDirty` the input Field for the
+     * mutated `(node, prop)` and call `recompute()` — propagation then
+     * reaches exactly the affected layout fields, with no
+     * `markAllDirty`.
+     *
+     * Every numeric style prop the grammar reads is now an input
+     * field. What still needs a fresh `buildFlexGrammar()` is
+     * STRUCTURAL mutation — flex-direction, flex-wrap on/off, the
+     * justify / align category, `positionType`, and toggling a flex
+     * weight or `flexBasis` across the zero / numeric boundary (which
+     * flips whether the parent flex-distributes).
+     */
+    styleInputs: Map<Node, StyleInputs>;
+    /**
+     * Input Fields for the root's caller-supplied `available` size,
+     * present only for an axis where the root's style is `'auto'`
+     * (v13). `markDirty` one and `recompute()` to re-lay the tree
+     * after a terminal resize.
+     */
+    availableInputs: {
+        width?: Field<number>;
+        height?: Field<number>;
+    };
+    /**
+     * Per-parent intermediate Fields for the phase-12 flex-distribution
+     * grammar. Keyed by each flex-distributing single-line parent; value
+     * is the `mainDistribution` Field emitted for that parent. Fragment
+     * builders (append / remove / reorder) consult this to perform
+     * precise rebinds without a full grammar rebuild.
+     */
+    mainDistributionByParent: Map<Node, Field<MainAxisDistribution>>;
+}
+/** Caller-supplied availability for an `'auto'`-sized root. */
+export interface AvailableSize {
+    width?: number;
+    height?: number;
+}
+/**
+ * Walk the tree rooted at `root` and emit a `Grammar` that computes
+ * each node's `{width, height, left, top}`. See the module header
+ * for the field rules. A whole-tree build — `boundary` is `null`.
+ *
+ * `'auto'` width / height are supported (v13): a non-measured
+ * `'auto'` axis resolves to 0; the root's `'auto'` axis resolves
+ * from `available` (matching `calculateLayout`'s availability args).
+ *
+ * @internal
+ */
+export declare function buildFlexGrammar(root: Node, available?: AvailableSize): FlexGrammarOutput;
+/**
+ * The patch inputs for a fast-pathed child append — see
+ * `buildAppendFragment`.
+ *
+ * @internal
+ */
+export interface AppendFragment {
+    /** Rules for the newly-added subtree's fields, for `graft`. */
+    additions: Grammar;
+    /** The new fields to start `SpinelessRuntime.graft`'s DFS from. */
+    newRoots: Array<Field<unknown>>;
+    /**
+     * Existing fields whose rule the append rewrote, paired with the
+     * new rule — for `SpinelessRuntime.rebindRule`. Empty for a
+     * simple-regime append (`graft` alone suffices); non-empty when
+     * the parent flex-distributes / justifies / wraps, where appending
+     * a child also grows every existing sibling's dependency set.
+     * Apply these AFTER `graft` (the new rules reference the grafted
+     * fields), then call `recompute()`.
+     */
+    rebinds: Array<[Field<unknown>, FieldRule<unknown>]>;
+    /**
+     * A fresh full `FlexGrammarOutput` for the post-append tree. The
+     * caller should adopt it for subsequent operations — its
+     * `allFields` / `styleInputs` cover the new subtree (the runtime's
+     * own grammar is patched in place by `graft` + `rebindRule`).
+     */
+    next: FlexGrammarOutput;
+}
+/**
+ * Fast-path a child INSERT for the Spineless runtime. If adding
+ * `child` under `parent` can be absorbed without a fresh runtime,
+ * return the patch inputs; return `null` when a full rebuild is
+ * required — `child` is not a child of `parent`, or `parent` uses a
+ * reverse `flex-direction` (supported by the grammar since v11, but
+ * not by this structural fast-path — reflecting every sibling's
+ * position is a whole-subtree rewrite).
+ *
+ * The new subtree's fields are always topological-tail additions
+ * handled by `graft` (`additions` / `newRoots`). When `parent` is in
+ * the "simple" regime (no flex distribution, default `flex-start`
+ * justify, no wrap) AND `child` is its LAST child — or `child` is
+ * absolute — that is the whole patch and `rebinds` is empty, and the
+ * fragment is built in **O(subtree)**: `makeEmitter` emits just the
+ * appended subtree against the runtime's grammar as a boundary, no
+ * whole-tree rebuild. Otherwise the insert also rewrites existing
+ * in-flow siblings' rules — a flex-distributing / justified /
+ * wrapping parent reads every sibling, and a MID-LIST insert (v32)
+ * shifts every later in-flow sibling's main position — so the
+ * grammar is rebuilt O(tree) and `rebinds` carries those siblings'
+ * rewritten rules.
+ *
+ * `next.grammar` is always `prev.grammar` — the runtime's own Map,
+ * which `graft` / `rebindRule` patch in place; `next.allFields` /
+ * `next.styleInputs` are refreshed lookup tables the caller adopts.
+ *
+ * @internal
+ */
+export declare function buildAppendFragment(prev: FlexGrammarOutput, root: Node, parent: Node, child: Node, available?: AvailableSize): AppendFragment | null;
+/**
+ * The patch inputs for a fast-pathed child removal — see
+ * `buildRemoveFragment`.
+ *
+ * @internal
+ */
+export interface RemoveFragment {
+    /**
+     * Every field belonging to the removed subtree, for
+     * `SpinelessRuntime.detach`. Apply this AFTER the `rebinds` — a
+     * surviving sibling rebound off the removed child must drop its
+     * dependency on the child's fields before they can be detached.
+     */
+    removed: Array<Field<unknown>>;
+    /**
+     * Existing fields whose rule the removal rewrote, paired with the
+     * new rule — for `SpinelessRuntime.rebindRule`. Empty when removing
+     * a last child from a simple-regime parent (`detach` alone
+     * suffices); non-empty when the parent flex-distributes /
+     * justifies / wraps, or the child is interior — where removing it
+     * shrinks every surviving sibling's dependency set.
+     */
+    rebinds: Array<[Field<unknown>, FieldRule<unknown>]>;
+    /**
+     * A fresh full `FlexGrammarOutput` for the post-removal tree. The
+     * caller adopts it for subsequent operations.
+     */
+    next: FlexGrammarOutput;
+}
+/**
+ * Fast-path a child REMOVAL for the Spineless runtime — the mirror
+ * of `buildAppendFragment`. Call this **before** detaching `child`
+ * from `parent`: the simple-regime check needs `child` still in
+ * place. Returns the patch inputs, or `null` when a full rebuild is
+ * required (`child` is not `parent`'s child, or `parent` uses a
+ * reverse `flex-direction` — supported by the grammar since v11 but
+ * not by this fast-path).
+ *
+ * In the "simple" regime (no flex distribution, default `flex-start`
+ * justify, no wrap — or `child` is absolute) the patch is built in
+ * **O(subtree)**: `removed` is collected directly from `prev` by
+ * walking the removed subtree, with no whole-tree rebuild, and
+ * `rebinds` is empty. `SpinelessRuntime.detach` then drops those
+ * fields and auto-cleans any input field they orphaned (e.g. the new
+ * last child's now-unread main-end margin). Otherwise the removal
+ * shrinks every surviving in-flow sibling's dependency set, so the
+ * grammar is rebuilt O(tree) and `rebinds` carries those siblings'
+ * rewritten rules. The caller applies `rebindRule` for each rebind
+ * FIRST (so survivors stop depending on the removed fields), then
+ * `detach`, then `recompute()`.
+ *
+ * Does not mutate the tree. `next.grammar` is `prev.grammar` — the
+ * runtime's own Map, patched in place by `detach` / `rebindRule`.
+ *
+ * @internal
+ */
+export declare function buildRemoveFragment(prev: FlexGrammarOutput, root: Node, parent: Node, child: Node, available?: AvailableSize): RemoveFragment | null;
+/**
+ * The patch inputs for a fast-pathed child reorder — see
+ * `buildReorderFragment`.
+ *
+ * @internal
+ */
+export interface ReorderFragment {
+    /**
+     * Input fields the reorder newly needs — for `SpinelessRuntime.graft`.
+     * A reorder adds no node, but it can give a node a follower (or
+     * take one away), and a node's main-END margin is read only when it
+     * has a follower. So a node that gained a follower contributes a
+     * newly-read margin input.
+     */
+    additions: Grammar;
+    /** The new fields to start `graft`'s DFS from (every addition). */
+    newRoots: Array<Field<unknown>>;
+    /**
+     * Input fields the reorder no longer needs — for
+     * `SpinelessRuntime.detach`. The mirror of `additions`: a node that
+     * lost its follower (became the last child) no longer has its
+     * main-end margin read.
+     */
+    removed: Array<Field<unknown>>;
+    /**
+     * Existing fields whose rule the reorder rewrote, paired with the
+     * new rule — for `SpinelessRuntime.rebindRule`.
+     */
+    rebinds: Array<[Field<unknown>, FieldRule<unknown>]>;
+    /** A fresh full `FlexGrammarOutput` for the reordered tree. */
+    next: FlexGrammarOutput;
+}
+/**
+ * Fast-path a child REORDER for the Spineless runtime — `parent`'s
+ * children are a permutation of their former order (no node added or
+ * removed). The grammar is rebuilt O(tree) and the patch applied to
+ * the existing runtime without a fresh `init`.
+ *
+ * Reordering `parent`'s children can only change the rules of
+ * `parent` itself (its `'auto'` / wrap content size now packs the
+ * children in a new order) and of its in-flow children (their main
+ * positions, and — under wrap — their line-dependent sizes), so the
+ * rebind set is `parent` + its in-flow children's
+ * `width / height / left / top`. Descendants and ancestors recompute
+ * from the changed VALUES; their rules are untouched.
+ *
+ * A reorder also shifts the "has a follower" boundary, so a node's
+ * main-end margin input can become newly read (`additions`) or
+ * newly unread (`removed`) — the same diff `buildAppendFragment`'s
+ * non-simple branch takes. The caller applies `graft` then
+ * `rebindRule` then `detach`.
+ *
+ * `next.grammar` is `prev.grammar` — the runtime's own Map, patched
+ * in place.
+ *
+ * @internal
+ */
+export declare function buildReorderFragment(prev: FlexGrammarOutput, root: Node, parent: Node, available?: AvailableSize): ReorderFragment;
+/**
+ * The materialised result of a flex-distributing parent's main-axis
+ * pass — sizes plus folded positions. One per qualifying parent.
+ * Cells index into this instead of redoing the distribution each.
+ * @internal
+ */
+export interface MainAxisDistribution {
+    readonly sizes: readonly number[];
+    readonly positions: readonly number[];
+}
+//# sourceMappingURL=flex-grammar.d.ts.map

package/dist/algorithm/spineless/flex-grammar.d.ts.map

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