@pilates/core 1.0.1 → 2.0.0

package/dist/algorithm/spineless/runtime.d.ts

@@ -0,0 +1,292 @@
+/**
+ * Spineless Traversal runtime — incremental driver for an attribute
+ * grammar (Kirisame, Wang, Panchekha — PLDI 2025).
+ *
+ * Combines the three foundational primitives:
+ *   - `BenderOrderMaintenance` (OM) — assigns a stable, totally-
+ *     ordered timestamp to every field at first computation. Topo
+ *     order at init time => OM order forever, even after relabel.
+ *   - `OmPriorityQueue<Field>` — keyed on the field's OM node.
+ *     Popping the minimum returns the next field to recompute in
+ *     topological order, without any explicit DAG walks.
+ *   - `Grammar` — declarative `field -> rule(deps, compute)` map.
+ *     The runtime queries it on every recompute.
+ *
+ * ## Phases
+ *
+ * **Init** (`init()`): one full pass over the grammar from the
+ * supplied root fields. DFS in topological order; for each field,
+ * allocate an OM node (`om.insertAfter(prev)`), record the
+ * reverse-deps edges so dependents can be scheduled later, then run
+ * the field's compute and cache the value. After init, every
+ * reachable field has a (timestamp, value, dependents-list) triple
+ * in the runtime's storage.
+ *
+ * **Recompute** (`markDirty(field)` + `recompute()`): callers mark
+ * the fields whose inputs changed. Each dirty field is enqueued
+ * (`pq.push(field, omNode)`). `recompute()` loops: pop the
+ * OM-minimum field, re-run its rule. If the new value differs from
+ * the cached one, persist it and push every dependent. Process
+ * stops when the queue is empty.
+ *
+ * **Termination** rests on the dependency graph being acyclic: each
+ * field's value is a function of finitely many others, so the
+ * worklist reaches the DAG's unique fixpoint in finitely many
+ * steps. When the OM order is a true topological order — as it is
+ * after `init` and pure-additive `graft` — every field recomputes
+ * exactly once (a dependent always pops after its deps), giving the
+ * O(affected) Spineless bound. After a `rebindRule` an existing
+ * field may gain a dependency on a later-OM field; recompute stays
+ * correct and terminating, but such a field may recompute a bounded
+ * number of extra times. OM order is thus a performance property,
+ * not a correctness one.
+ *
+ * **Value preservation under no-op recompute:** if a field's rule
+ * produces the same value as before, its dependents are NOT
+ * scheduled. This is the key "skip work" property of Spineless.
+ *
+ * **Graft** (`graft(additions, newRoots)`): incremental structural
+ * growth (phase 5c). New fields whose topological position is at the
+ * tail — they may read existing fields, but no existing field reads
+ * them and no existing rule changes — are spliced in without a
+ * rebuild: each gets an OM node appended after the current tail, its
+ * reverse-dependency edges recorded, and its value computed once.
+ * This is exactly the shape of appending a child to a parent in the
+ * "simple" regime.
+ *
+ * **Detach** (`detach(fields)`): the inverse of `graft` — drops a
+ * removed subtree's fields, freeing their OM nodes and pruning the
+ * reverse-dependency edges into surviving fields. Valid when the
+ * removed set is closed under "is read by" (nothing outside reads
+ * in), which holds for removing a last child in the simple regime.
+ * Surviving leaf-input fields the removed set was the sole reader of
+ * are dropped too — the caller passes only the subtree's own fields.
+ *
+ * **Rebind** (`rebindRule(field, newRule)`): replace an existing
+ * field's rule — used when a structural change rewrites a surviving
+ * field (e.g. appending into a flex-distributing parent grows every
+ * sibling's flex-distribution dependency set). The reverse-
+ * dependency edges are updated to the new dep set and the field is
+ * marked dirty. New deps may have a later OM than the field — see
+ * the termination note above.
+ *
+ * ## What this runtime does NOT cover
+ *
+ * - Regime-changing structural mutation. `graft` only adds pure
+ *   topological-tail fields; appending into a flex-distributing /
+ *   justified / wrapping parent also rewrites existing siblings'
+ *   rules, and removal / direction flips re-key subtrees — later
+ *   phase-5c slices.
+ * - Differential mode against the imperative algorithm. The
+ *   correctness oracle for the runtime is the `TopoInterpreter`
+ *   running over the same grammar — once both agree, the grammar's
+ *   existing differential coverage carries through.
+ *
+ * @internal
+ */
+import type { Field, FieldRule, Grammar } from './grammar.js';
+import { type OrderMaintenance } from './order-maintenance.js';
+/**
+ * @internal
+ */
+export declare class SpinelessRuntime {
+    private readonly rootFields;
+    private readonly om;
+    private readonly pq;
+    /**
+     * External Grammar map reference — kept so that callers holding the
+     * same map reference (e.g. layout.ts's `output.grammar`) see mutations
+     * made by `graft` / `rebindRule` / `detach`. All internal HOT-PATH
+     * reads use `rulesArr` (O(1) array index) instead.
+     */
+    private readonly grammar;
+    /**
+     * Field rules indexed by field.id — the fast-path mirror of `grammar`.
+     * Updated in lockstep with every `grammar.set` / `grammar.delete`.
+     * Plain array; auto-grows on out-of-range assignment (JS semantics).
+     */
+    private rulesArr;
+    /**
+     * Fast path: numeric field values indexed by field.id.
+     * valuePresent[id] === 1 means the value is stored here as a number.
+     */
+    private valuesArr;
+    /**
+     * Presence / storage-kind bitset, indexed by field.id:
+     *   0 = absent (not yet computed or detached)
+     *   1 = computed, value is a number stored in valuesArr[id]
+     *   2 = computed, value is a non-number object stored in valuesMap
+     */
+    private valuePresent;
+    /**
+     * Fallback for non-number field values (e.g. Field<MainAxisDistribution>).
+     * Only populated when valuePresent[id] === 2.
+     */
+    private readonly valuesMap;
+    /**
+     * OM nodes indexed by field.id — replaces the former `omNodes: Map<Field, OMNode>`.
+     * Plain array; auto-grows on out-of-range assignment (JS semantics).
+     * undefined slot = field not integrated (or detached).
+     */
+    private omNodesArr;
+    /**
+     * Authoritative list of all fields ever registered with this runtime
+     * (in integration order). Used for iteration in `markAllDirty` — slots
+     * whose `omNodesArr[field.id]` is `undefined` (detached) are skipped.
+     * Dead entries are never removed; the skip is O(1) per slot.
+     */
+    private readonly fieldRoster;
+    /**
+     * Reverse-dependency lists indexed by field.id — replaces the former
+     * `dependents: Map<Field, Field[]>`. `dependentsArr[id]` is the array
+     * of fields that read field-id. undefined = no dependents recorded yet
+     * (or field detached). Plain array; auto-grows on assignment.
+     */
+    private dependentsArr;
+    /** The OM node at the topological tail — where `graft` appends. */
+    private lastOm;
+    private initDone;
+    /**
+     * Recompute counters — for observability (phase 9). Plain integer
+     * fields, bumped on the existing `integrate` / `recompute` loops,
+     * so they cost nothing measurable and need no enable flag.
+     */
+    readonly stats: {
+        /** Fields integrated so far — the `init` pass plus every `graft`. */
+        initFields: number;
+        /** Fields popped from the PQ by the most recent `recompute()`. */
+        recomputeVisited: number;
+        /** Of those, Fields whose value actually changed. */
+        recomputeChanged: number;
+        /** Cumulative Fields visited across every `recompute()` since init. */
+        totalVisited: number;
+    };
+    constructor(grammar: Grammar, rootFields: ReadonlyArray<Field<unknown>>, om?: OrderMaintenance);
+    /**
+     * Grow `valuesArr` and `valuePresent` so that `id` is a valid index.
+     * Doubles capacity until sufficient, copying forward (LayoutPool pattern).
+     */
+    private ensureFieldCapacity;
+    /**
+     * Walk the grammar in topological order, allocate an OM node per
+     * field, cache initial values, and record reverse-dependents. Must
+     * be called once before any `evaluate` / `markDirty` / `recompute`.
+     */
+    init(): void;
+    /**
+     * Integrate new fields into an already-`init`ed runtime without a
+     * rebuild (phase 5c). `additions` holds the rules for the new
+     * fields only — it throws if any field is already present, since
+     * redefining an existing field is a rule *change*, not a graft.
+     * `newRoots` are the new fields to start the topological DFS from
+     * (their existing-field dependencies are reached as boundaries).
+     *
+     * Correct **iff** the new fields are pure topological-tail
+     * additions: no existing field reads a new field, and no existing
+     * rule needed to change. The caller guarantees this — it holds by
+     * construction when appending a last child to a parent in the
+     * simple regime (no flex distribution, default `justify`, no
+     * wrap). The new fields are computed with correct inputs during
+     * the graft, so no `markDirty` / `recompute` is needed afterward.
+     */
+    graft(additions: Grammar, newRoots: ReadonlyArray<Field<unknown>>): void;
+    /**
+     * Remove fields from an already-`init`ed runtime without a rebuild
+     * (phase 5c) — the inverse of `graft`. `fields` is the exact set
+     * to drop (a removed subtree's fields). For each: its OM node is
+     * freed, its cached value and reverse-dependency list dropped, its
+     * rule deleted from the grammar, and it is pruned from the
+     * reverse-dependency list of every field it read.
+     *
+     * Throws if any removed field still has a dependent *outside* the
+     * removed set — detaching it would dangle that edge. The caller
+     * guarantees a clean cut: it holds by construction when removing a
+     * last child from a parent in the simple regime (nothing outside
+     * that subtree reads into it). No `recompute` is needed afterward —
+     * removing a topological-tail subtree changes no surviving field.
+     *
+     * After the cut, any surviving leaf-input field the removed set was
+     * the sole reader of is **orphaned** — nothing reads it and the
+     * grammar cannot re-read it without a fresh build. Such orphans are
+     * dropped too (a leaf has no dependencies, so this cannot cascade).
+     * That makes the caller's removed set just the subtree's own
+     * fields — orphan input fields, e.g. the previous last child's
+     * now-unread main-end margin, need not be enumerated.
+     *
+     * @returns The set of every field actually removed — both the
+     * explicit `fields` argument AND any orphan-cleaned surviving deps.
+     * Callers can use this to maintain a `Set<Field>` index in O(|dropped|)
+     * rather than scanning all tracked fields.
+     */
+    detach(fields: Iterable<Field<unknown>>): Set<Field<unknown>>;
+    /**
+     * Replace the rule of an already-integrated field (phase 5c) — for
+     * a structural change that rewrites a *surviving* field rather than
+     * adding or removing one. Appending a child into a flex-distributing
+     * parent, for instance, grows every existing sibling's
+     * flex-distribution dependency set.
+     *
+     * The reverse-dependency edges are repaired to match the new dep
+     * set (the field is dropped from the lists of deps it no longer
+     * reads and added to the lists of deps it now reads), the new rule
+     * is installed, and the field is marked dirty so the next
+     * `recompute()` re-runs it. Every new dependency must already be
+     * integrated. The field keeps its OM node; if a new dependency has
+     * a later OM, recompute stays correct (see the termination note on
+     * the class) at the cost of a bounded number of extra recomputes.
+     */
+    rebindRule(field: Field<unknown>, newRule: FieldRule<unknown>): void;
+    /**
+     * Topological DFS shared by `init` and `graft`. For every
+     * not-yet-integrated field reachable from `roots`: recurse into
+     * deps, record reverse-dependency edges, allocate an OM node after
+     * the current tail, run the rule, and cache the value. Fields that
+     * already have an OM node are boundaries — visited, edge recorded,
+     * not re-walked.
+     */
+    private integrate;
+    /**
+     * Read the current cached value of a field. Throws if the field
+     * wasn't reachable from any root during `init` (so no cache entry
+     * exists).
+     */
+    evaluate<T>(field: Field<T>): T;
+    /**
+     * Whether `field` is currently tracked by the runtime — integrated
+     * and not since detached. A caller holding a possibly-stale field
+     * reference (e.g. an input field orphaned by a `detach`) can check
+     * this before `markDirty`.
+     */
+    isTracked(field: Field<unknown>): boolean;
+    /**
+     * Mark every field tracked by this runtime as dirty. Useful as an
+     * escape hatch when callers don't have fine-grained style-mutation
+     * wiring yet: mutate styles, call `markAllDirty()`, then
+     * `recompute()`. Each field re-runs its rule once, but the "skip
+     * dependents when value unchanged" property still applies — so
+     * cost is one compute per field plus propagation only along
+     * actually-changed values, rather than a full re-init.
+     */
+    markAllDirty(): void;
+    /**
+     * Mark a field as dirty. Its rule will be re-run on the next
+     * `recompute()`. If the new value differs from the cached one,
+     * dependents are scheduled in turn.
+     *
+     * Duplicate calls are a no-op (the priority queue dedupes via its
+     * internal membership set).
+     */
+    markDirty(field: Field<unknown>): void;
+    /**
+     * Process all dirty fields. Pops in OM (= topological) order; runs
+     * each field's rule. If the result differs from the cached value,
+     * persists it and pushes every dependent so it gets re-run later in
+     * this same pass.
+     *
+     * Returns every field whose value actually changed — the caller
+     * uses it to scope an incremental write-back to the moved nodes.
+     */
+    recompute(): Array<Field<unknown>>;
+    private runCompute;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/algorithm/spineless/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/algorithm/spineless/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAU,MAAM,cAAc,CAAC;AACtE,OAAO,EAAuC,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAsBpG;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgC;IAC3D,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAmB;IACtC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAkC;IAErD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAElC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAA0C;IAE1D;;;OAGG;IACH,OAAO,CAAC,SAAS,CAAe;IAChC;;;;;OAKG;IACH,OAAO,CAAC,YAAY,CAAa;IACjC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2C;IACrE;;;;OAIG;IACH,OAAO,CAAC,UAAU,CAA8B;IAChD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwB;IACpD;;;;;OAKG;IACH,OAAO,CAAC,aAAa,CAAwC;IAE7D,mEAAmE;IACnE,OAAO,CAAC,MAAM,CAAuB;IAErC,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;OAIG;IACH,QAAQ,CAAC,KAAK;QACZ,qEAAqE;;QAErE,kEAAkE;;QAElE,qDAAqD;;QAErD,uEAAuE;;MAEvE;gBAGA,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EACzC,EAAE,GAAE,gBAA+C;IAkBrD;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAKZ;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI;IAgBxE;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAoF7D;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI;IA2CpE;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS;IAyDjB;;;;OAIG;IACH,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;IAY/B;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,OAAO;IAIzC;;;;;;;;OAQG;IACH,YAAY,IAAI,IAAI;IAWpB;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI;IAatC;;;;;;;;OAQG;IACH,SAAS,IAAI,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAuClC,OAAO,CAAC,UAAU;CA6BnB"}