@wardic/dom 0.0.0-stage → 1.0.0-rc.2

package/dist/internal/projection.d.ts

@@ -0,0 +1,529 @@
+/**
+ * The box-based Projection system (ADR-0009), the reusable DOM half of
+ * layout animation. It holds the projection nodes, the trigger sources, and the
+ * Clock-driven coordinator that derives each node's transform every frame.
+ *
+ * It has NO framework reactivity: it reaches its host binding through two seams
+ * only — a {@link ProjectionSink} (`write` per-element projection values into the
+ * binding's flush gate + `flushPass` a Measure pass, applying its writes at once) and a
+ * `ManagedRuntime` providing the Environment's {@link FrameLoop} (the coordinator is one
+ * run on it, ADR-0027).
+ * So it lives here in `@wardic/dom`, next to `ClockDomLive`/the Renderer, and any
+ * binding (Solid today; React/vanilla later) wires it with its own gate + runtime.
+ *
+ * Pipeline (the locked design):
+ *   - REGISTER a node (its gate `id`, `element`, and a `transition` accessor, ADR-0009 *Amendment (#171)*).
+ *   - TRIGGER (registration / a shared `ResizeObserver` size change /
+ *     `layoutDependency` via `notify`) -> ONE **Measure pass** per task, run by the
+ *     engine in a microtask at the end of that task (ADR-0018).
+ *   - MEASURE pass (through `sink.flushPass`, which applies what it wrote before
+ *     returning): re-measure EVERY node's untransformed box (Q5); compute the
+ *     projection TREE by DOM ancestry (each node's parent = the nearest ancestor
+ *     ELEMENT that is a registered node); for each node that moved, set up an
+ *     animation (origin + target) and seed the progress-0 frame; start the
+ *     coordinator. A running node whose box didn't change is left alone. A trigger
+ *     during the pass's own flush repeats it (at most 5 rounds). Every node the pass
+ *     seeded takes its first step at the Frame loop's next tick, whose end flushes the
+ *     gate, so it moves in that Refresh frame whatever the Clock's state (ADR-0033).
+ *   - COORDINATOR (one run on the Environment's Frame loop while >=1 node animates,
+ *     Q4; ADR-0027, #75): each tick steps every active node's progress spring, then
+ *     `deriveAll()` walks the active nodes TOP-DOWN (ancestors first) computing
+ *     each node's `projectionDelta` + `treeScale` via `applyTreeDeltas` over its
+ *     animating ancestors' deltas, and writes the `@projection` value (the renderer
+ *     assembles the transform). On settle it drops the node; when none remain the
+ *     run settles and leaves the loop (idle = zero cost).
+ *
+ * DRAG (ADR-0016 and its *Amendment (#26)*): a dragged node follows the pointer through
+ * its target (`grabBox + dragDelta`), and it and its subtree are drag-blocked: a
+ * Measure pass updates their slots but starts no animation there, the dragged node is
+ * its subtree's relative parent, and a resting descendant is left to ride the drag
+ * through CSS. A pointer move re-derives the dragged group. The drag is a layer on top of
+ * the node's layout animation, which a grab leaves running; the release is a **Release
+ * offset**, the drag target's distance from where the layout puts the node, springing to
+ * zero per axis on top of it from the loop's next tick (ADR-0016, *Amendment (velocity
+ * family)*).
+ *
+ * Nesting: parent links come from a DOM-ancestry WALK (CSS composes by DOM
+ * nesting, so that is exactly what projection must follow), and a child's box is
+ * corrected for its ancestors' transforms via `applyTreeDeltas` (+ `treeScale`)
+ * for nested SCALE. For nested layout, an animating child with a pure-translate
+ * animating ancestor uses RELATIVE projection (`relativeParentOf` + `derive`): it
+ * re-anchors to its `relativeParent`'s CURRENT target each frame, so it stays
+ * glued even when parent and child run DIFFERENT transitions ("not left behind").
+ *
+ * DOM ACCESS (#16, parked until a second Environment): the engine is meant to move into
+ * `@wardic/core` behind a port its Environment implements, once a non-DOM Environment (canvas,
+ * native) gives that port a second implementation to be shaped against. Until then, NEW DOM
+ * access goes through a named read function in `measure.ts`, never inline here (no new
+ * `getComputedStyle`, `getBoundingClientRect`, `parentElement` walk or `contains` in this file):
+ * `measure.ts` is the port's surface, and #16 maps what this file still does inline.
+ */
+import * as Box from "@wardic/core/Box";
+import * as FrameLoop from "@wardic/core/FrameLoop";
+import type * as Arc from "@wardic/core/Arc";
+import type * as Point from "@wardic/core/Point";
+import * as Probe from "@wardic/core/Probe";
+import * as Projection from "@wardic/core/Projection";
+import * as Renderer from "@wardic/core/Renderer";
+import * as Effect from "effect/Effect";
+import type * as Fiber from "effect/Fiber";
+import * as Inspectable from "effect/Inspectable";
+import * as Option from "effect/Option";
+import * as Scope from "effect/Scope";
+import { AtomRegistry } from "effect/reactivity";
+import { type DragTransition, type LayoutTransition } from "./projection-defaults.ts";
+import { type ScaleCorrectorEntry } from "./scale-correction.ts";
+/**
+ * What the engine writes each node's projection through: a `FlushGate` is one, so the engine never
+ * imports a framework. `write` merges an element's projection into what it draws at the next frame;
+ * `flushPass` runs a measure now, and draws what it wrote before it returns, so a new layout never paints
+ * without its projection.
+ */
+export interface ProjectionSink {
+    /** Merges `partial` into element `id`'s values, drawn at the next frame. */
+    readonly write: (id: string, partial: Record<string, unknown>) => void;
+    /** Runs `pass`, a measure, now, and draws what it wrote before it returns. */
+    readonly flushPass: (pass: () => void) => void;
+}
+/**
+ * What the engine needs from its Environment: the Frame loop it runs on, the renderer, which draws a
+ * leaving follower whose gate is gone, and the Probe's viewport, read through the Environment's
+ * `AtomRegistry`, so it lands rather than animates through a resize.
+ */
+export type ProjectionServices = FrameLoop.FrameLoop | Renderer.Renderer | Probe.Probe | AtomRegistry.AtomRegistry;
+/**
+ * How the engine runs its Effects: synchronously, and forked. `DomProjectionSystem.make` builds one
+ * from its Layer's context, forking into its Scope (#132, ADR-0041); a test's `ManagedRuntime`
+ * is one too.
+ */
+export interface ProjectionRuntime {
+    readonly runSync: <A, E>(effect: Effect.Effect<A, E, ProjectionServices>) => A;
+    readonly runFork: <A, E>(effect: Effect.Effect<A, E, ProjectionServices>) => Fiber.Fiber<A, E>;
+    /** The Scope it was built in: its own fibers live there, ended as it closes (#618). */
+    readonly scope: Scope.Scope;
+}
+/**
+ * Whether `a` and `b` draw the same (#27, ADR-0009 *Amendment (#27)*): every field the renderer reads,
+ * each axis's translate and scale, the tree scale, the opacities, the rotation, the raise and the
+ * pointer pass-through, and each axis's origin. Not `originPoint`, the engine's own, which moves with
+ * a translating parent while nothing drawn changes. Per frame: statement `if`s, no allocation. Exported
+ * for its test, not from the package.
+ */
+export declare const drawsSame: (a: Projection.Value, b: Projection.Value) => boolean;
+/** Options to register a layout element as a projection node. */
+export interface RegisterNodeOptions {
+    /** The element's id in the flush gate: the engine writes its projection there, beside its animated values. */
+    readonly id: string;
+    /** The live DOM element to measure + project. */
+    readonly element: HTMLElement;
+    /**
+     * The node's layout transition, read at each layout animation's (re)start: a spring or a tween, or
+     * `None` for Motion's default, {@link DEFAULT_LAYOUT_TRANSITION}.
+     */
+    readonly transition: () => Option.Option<LayoutTransition>;
+    /**
+     * The element's Path, read at each layout animation's start: a flight of 20 px or more curves its
+     * centre along it, from where it starts to its box, its size still mixed straight, as Motion's
+     * `interpolateProjection`. None, or left out, and every flight is straight.
+     */
+    readonly path?: (() => Option.Option<Arc.Path>) | undefined;
+    /**
+     * The app's `onLayoutAnimationStart`, read when it fires: at the frame where a layout animation of
+     * this node takes its first step, once per animation (restarts in one task are one). Not for a node
+     * that is a **Follower**: a handover is its Lead's. `None` when the app has none.
+     */
+    readonly onLayoutAnimationStart?: () => Option.Option<() => void>;
+    /**
+     * The app's `onLayoutAnimationComplete`, read when it fires: at the frame where a layout animation of
+     * this node lands on its own. Not for one interrupted by a restart, finished early by a window resize,
+     * or cut off by an unmount; not for a Follower. `None` when the app has none.
+     */
+    readonly onLayoutAnimationComplete?: () => Option.Option<() => void>;
+    /**
+     * The app's `onDragTransitionEnd` (Motion's), read when it fires: once a drag's release (its **Release
+     * offset**) comes to rest on its own, after that frame's flush; for a drag released in place at rest,
+     * which starts none, from a microtask after the release. Not for one a grab stopped and a drag took
+     * over, nor one an unmount or a resize ended. `None` when the app has none.
+     */
+    readonly onReleaseEnd?: () => Option.Option<() => void>;
+    /**
+     * The node's drag transition, read at each release: what its Release offset runs on, or `None` for
+     * Motion's, {@link DEFAULT_DRAG_TRANSITION}.
+     */
+    readonly dragTransition?: () => Option.Option<DragTransition>;
+    /**
+     * Whether the node's layout animations honour reduced motion, read at each (re)start: `false` animates
+     * them whatever the system's `reducedMotion` says (a binding's per-transition opt-out). Default
+     * `true`.
+     */
+    readonly respectReducedMotion?: () => boolean;
+    /**
+     * Whether reduced motion applies to the node now, read at each layout animation's (re)start: a
+     * binding's setting for its subtree with the user's preference (Wardic's `WardicConfig`). Default: the
+     * system's `reducedMotion`.
+     */
+    readonly reducedMotion?: () => boolean;
+    /**
+     * Whether the node's animations are skipped now (a binding's `skipAnimations`), read at each layout
+     * animation's (re)start and each drag release: it lands at once, whatever reduced motion says, and a
+     * release lands on its slot. Default: never.
+     */
+    readonly skipAnimations?: () => boolean;
+    /**
+     * The node's **Layout mode**, read at each layout animation's start: which parts of a layout change it
+     * animates. Default `true`, position and size.
+     */
+    readonly layoutMode?: () => Projection.LayoutMode;
+    /**
+     * The element's own scale per axis: its `scale` times its `scaleX` or `scaleY`, which the renderer
+     * draws on top of its projection (`ownScaleOf`). Read at each handover, and each frame a Follower is
+     * derived. Default `{ x: 1, y: 1 }`.
+     */
+    readonly ownScale?: () => Point.Point;
+    /**
+     * The element's own translate: its `x` plus `translateX` and `y` plus `translateY`, in page pixels,
+     * which the renderer adds to its projection's (`ownTranslateOf`). Read where its own scale is. Default
+     * `{ x: 0, y: 0 }`.
+     */
+    readonly ownTranslate?: () => Point.Point;
+    /**
+     * The element's own `rotate` in degrees, which the renderer weaves into its projection
+     * (`ownRotateOf`): what a handover blends a twin's rotation into, read each frame of one. Default 0.
+     */
+    readonly ownRotate?: () => number;
+    /**
+     * The element's own opacity (`ownOpacityOf`): what a Switch blends the leaver's opacity into, read
+     * each frame of one, and a leaver's when it's already off the page. Default 1.
+     */
+    readonly ownOpacity?: () => number;
+    /**
+     * The transform a Measure pass holds the element at (Motion's `transformTemplate(values, "")`): its
+     * **Transform template**'s with no transform of Wardic's, so a static part of it, such as centring, is
+     * in the boxes it flies between. Read at each pass. Without one, the pass clears it.
+     */
+    readonly heldTransform?: () => string;
+    /**
+     * Called as each Measure pass that measures the node begins (Motion's `onBeforeLayoutMeasure`): in its
+     * write phase, before its transform is held for the read, blocked passes included. A throw is
+     * reported, and the pass goes on.
+     */
+    readonly onBeforeMeasure?: () => void;
+    /**
+     * Called with the node's box each Measure pass measures it (Motion's `onLayoutMeasure`), after the
+     * read: in its Scroll-stable frame, Motion's page layout box, and the box before it, none at its
+     * first. Blocked passes included. A throw is reported, and the pass goes on.
+     */
+    readonly onMeasure?: (box: Box.Box, prev: Option.Option<Box.Box>) => void;
+    /**
+     * Its shared-element key: nodes with the same `layoutId` are twins, and one flies into the other, the
+     * newest leading and the others following, crossfading. A twin removed in the same task as its twin
+     * arrives hands it where it was. Left out for a plain layout node.
+     */
+    readonly layoutId?: string;
+    /**
+     * Marks the element a scroll container, as Motion's `layoutScroll`: its scroll is read at each measure
+     * and taken out of its descendants' boxes, so a scroll between two layout changes doesn't animate them;
+     * as a `position: fixed` scroll root, its style is read at every measure. Every other ancestor that can
+     * scroll is taken out too, unmarked.
+     */
+    readonly layoutScroll?: boolean;
+    /**
+     * Marks the element a layout root, as Motion's `layoutRoot`: it never animates its own layout change,
+     * landing on it at once, and its subtree's projections stop at it, so a change outside it doesn't move
+     * what's inside.
+     */
+    readonly layoutRoot?: boolean;
+    /**
+     * Where in its parent the node is anchored, as Motion's `layoutAnchor`, from 0 to 1 on each axis: its
+     * top-left, `{ x: 0, y: 0 }`, by default. Its box is kept relative to that point while its parent
+     * animates. `false` keeps it absolute.
+     */
+    readonly layoutAnchor?: Point.Point | false;
+    /**
+     * Whether a handover onto this node crossfades (Motion's `layoutCrossfade`), read as each begins:
+     * `false` hides its Followers as it starts, and it moves at its own opacity. A Switch blends as ever.
+     * Left out, every handover crossfades.
+     */
+    readonly crossfade?: (() => boolean) | undefined;
+    /**
+     * Raises the node while it's dragged: from the drag's start until its release settles, at once for a
+     * release in place, its projection carries a raise the renderer draws as `z-index`, so it paints above
+     * its siblings, as Motion's Reorder items do; then one last write drops it. It's `2` while dragged and
+     * `1` once released, so the item under the pointer paints above one flying back. A Reorder item sets it.
+     */
+    readonly raiseWhileDragged?: boolean;
+    /**
+     * Where a presence child taking over from its leaver starts: the leaver's box in the **Root frame**,
+     * as it painted ({@link ProjectionSystem.rootBoxOf}). The node's first measure moves it from there to
+     * its own box, as a layout change, with no handover. A live twin to crossfade from comes first; this
+     * comes before a Switch seed.
+     */
+    readonly enteredFrom?: Box.Box;
+    /**
+     * Where the handover its first measure begins starts its fade: a keyed twin back while its leaver
+     * crossfades out goes on from the factor that leaver had faded to ({@link
+     * ProjectionSystem.dropLeaver}). Omitted, 0.
+     */
+    readonly fadeFrom?: number;
+}
+/**
+ * How a draggable layout node is dragged: through its projection, not its own `x` and `y`, which stay its
+ * animations', drawn on top. A binding's drag calls these, so the element follows the pointer and flies to
+ * its place at the release. Part of `ProjectionNodeHandle`.
+ */
+export interface DragProjectionHandle {
+    /**
+     * Begin a drag: capture the grab-time slot box as the pointer anchor, from where a stopped
+     * release left the node; hold the node active. A layout animation running at the grab runs
+     * on under the drag.
+     */
+    readonly dragStart: () => void;
+    /**
+     * The live pointer translate from the grab point — the node tracks `grabBox + delta`.
+     * Re-derives the dragged group into the sink at once, so the gate's next flush paints it.
+     */
+    readonly dragMove: (delta: Point.Point) => void;
+    /**
+     * End the drag: from the loop's next tick, the drag target's distance from where the layout
+     * puts the node springs to zero on each axis (a **Release offset**), starting at `velocity`
+     * (px/s; at rest when omitted) on top of the node's layout animation.
+     */
+    readonly dragEnd: (velocity?: Point.Point) => void;
+    /**
+     * A grab (a press on the element): stop a running release where it is, as Motion's drag
+     * stops its offset at the press. A drag that follows continues from there.
+     */
+    readonly stopRelease: () => void;
+    /** A press that ends with no drag: start a stopped release again, from rest. */
+    readonly resumeRelease: () => void;
+}
+/** Handle returned from {@link ProjectionSystem.register}. */
+export interface ProjectionNodeHandle extends DragProjectionHandle {
+    /** Asks for a measure at the end of the task, however many ask: this node's `layoutDependency` changed, say. */
+    readonly notify: () => void;
+    /**
+     * The node's slot (its layout box) in the Scroll-stable frame, as of its last Measure pass; none
+     * before the first. A plain read: no layout read.
+     */
+    readonly layoutBox: () => Option.Option<Box.Box>;
+    /**
+     * How far the node paints from its slot while dragged (the drag target minus the
+     * slot, per axis, leaving out a layout animation the grab left running); `{ x: 0, y: 0 }`
+     * otherwise, the release included.
+     */
+    readonly dragOffset: () => Point.Point;
+    /**
+     * A count that rises with every Measure pass round that measures the node (a
+     * blocked one included); 0 before the first. A **Reorder group** waits on it after
+     * a reorder, as on Motion's former `layoutVersion` counter (removed in motion-dom
+     * 13.4.5).
+     */
+    readonly layoutVersion: () => number;
+    /**
+     * A **Keyboard reorder**'s lift: `true` raises the node as a drag does (`2`) while it's lifted,
+     * through the layout animations its steps start; `false` (its drop or cancel) leaves it raised (`1`)
+     * until its last one lands, as a drag's release does, or drops the raise now at rest.
+     */
+    readonly setLifted: (on: boolean) => void;
+    /** Unregisters the node, ending an animation in flight. */
+    readonly dispose: () => void;
+}
+/** The Projection system: what a binding registers its layout elements with, one per provider. */
+export interface ProjectionSystem extends Inspectable.Inspectable {
+    /**
+     * Registers a layout element: its node, from then on measured at each layout change and animated from
+     * where it was. The handle tells the engine what changed, and its `dispose` removes the node.
+     */
+    readonly register: (opts: RegisterNodeOptions) => ProjectionNodeHandle;
+    /**
+     * Asks for a measure of the whole tree at the end of the task, however many ask: for a change a group
+     * declares, as a layout group's `layoutDependency` does, so every node its change moves animates.
+     */
+    readonly notify: () => void;
+    /**
+     * A **Declared layout change**: run `fn`, and animate the layout change it makes from where every node
+     * is at the call, even where no trigger sees the change or a node's last Measurement is out of date.
+     * Returns `fn`'s result; its error throws to the caller.
+     *
+     * - **The Measurements.** The first call in a task measures every node before `fn` runs. A Measure
+     *   pass already due in the task runs then instead, so what triggered it animates as before, and its
+     *   reads are the Measurements. Later calls in the task share them, so a node one call's change pushes
+     *   animates from before the first change (Motion's `parallel-calls-intersecting`).
+     * - **The pass.** The Measure pass at the end of the task animates every node that moved from those
+     *   Measurements. A running animation `fn` moves restarts from where it paints; one it doesn't move
+     *   carries on.
+     * - **What stays as in any pass.** A **Resize block** wins: `fn` runs and nothing animates. A dragged
+     *   subtree takes its slot-only update. A call from inside a pass's own flush uses the reads that pass
+     *   just made.
+     * - **Synchronous only.** A promise `fn` returns isn't awaited: a change after an `await` is in a
+     *   later task. Such a call logs a warning.
+     * - **`onSettled`** is called once the change has settled: every layout animation the end-of-task pass
+     *   started has ended, however each ended (landed, cut short by a resize or an unmount, or restarted
+     *   by a later change), or at the end of that pass if it started none. Calls in one task share that
+     *   pass, so they settle together.
+     */
+    readonly animateLayout: <A>(fn: () => A, options?: AnimateLayoutOptions) => A;
+    /**
+     * An **Instant change** (Motion's `useInstantLayoutTransition`): run `fn`, and the Measure pass at the
+     * end of the task gives every node its new box and starts nothing, as a Resize block's does. Every
+     * running layout animation but a dragged node's ends on its slot as that pass begins.
+     */
+    readonly instant: (fn?: () => void) => void;
+    /**
+     * A **Projection reset** (Motion's `useResetProjection`): every running layout animation and Release
+     * offset ends on its slot, every leaver and Switch seed goes (each `layoutId` stack keeps its live
+     * nodes), and the next Measure pass measures every box afresh, animating none.
+     */
+    readonly reset: () => void;
+    /**
+     * A leaving `layoutId` element its exit keeps in the document: `true` when there's a live twin, the
+     * lead, to crossfade toward. The engine then draws `el` as a leaving follower, on the lead's box and
+     * fading out, through the renderer since its gate is gone, and calls `onDone` once the crossfade settles,
+     * so the exit removes it. `false` for one with no twin: its own exit runs as usual.
+     */
+    readonly handleLeave: (el: HTMLElement, onDone: () => void) => boolean;
+    /**
+     * Hand back the twins inside a leaving element that isn't a twin, for a presence child {@link
+     * handleLeave} declined: each crossfades onto its other twin, following the leaver's own exit.
+     * `onDone` once every handover has ended; the returned call drops them at once. `None` when it held
+     * none, so presence runs its exit alone.
+     */
+    readonly handBackWithin: (el: HTMLElement, onDone: () => void) => Option.Option<() => void>;
+    /**
+     * A presence child leaving with nobody to take its twins over: the twins it held as it went, inside it
+     * or it a twin itself, stay a later twin's to take over while it's on the page, until the returned
+     * call: the presence removing it, which ends their records at once (a held leaver otherwise lasts
+     * until a task ends with it off the page). A twin that registers meanwhile brings one back as its
+     * leaving Follower, as if it were live in its stack, and tells the presence through `taken` ({@link
+     * LateTaken}), which holds the child for that handover.
+     *
+     * Its layout nodes with no `layoutId`, it included, come back as nodes it carries: corrected for an
+     * ancestor's layout animation while it exits, its exit's own values drawn on the correction, and gone
+     * with the returned call.
+     */
+    readonly keepLeaving: (el: HTMLElement, taken: LateTaken) => () => void;
+    /**
+     * Whether a twin that `el` is, or holds, left in this task with no live twin in its stack yet: a twin
+     * arriving later in the same update takes it over, so a presence decides on `el`'s leave at the task's
+     * end, when {@link handleLeave} or {@link handBackWithin} finds that twin.
+     */
+    readonly awaitsTwin: (el: HTMLElement) => boolean;
+    /**
+     * A leaver its presence popped out of the flow: at the first frame after, if the page scrolled since
+     * (a router's scroll to the top at a navigation), `move` takes it by that scroll, so it stays where it
+     * was seen, and the leaving nodes inside it go with it. Once: scrolling after moves it with the page.
+     */
+    readonly keepSeen: (el: HTMLElement, move: (by: Point.Point) => void) => void;
+    /**
+     * Register an element's values: a binding hands every element's, read from what it last wrote, so a
+     * `layoutId` twin's flight follows the translate and scale Wardic animates on its ancestors each
+     * frame, an element that isn't a projection node included. A presence registers a leaver's drawn
+     * values in their place, its Transform template among them, so it's drawn through it as it leaves.
+     * Returns the unregistration, for the element's dispose.
+     */
+    readonly registerValues: (el: Element, read: () => Readonly<Record<string, unknown>>) => () => void;
+    /**
+     * An element's box in the **Root frame** as it paints now, its transforms included: where a presence
+     * child taking over from it starts ({@link RegisterNodeOptions.enteredFrom}). `None` for one off the
+     * page.
+     */
+    readonly rootBoxOf: (el: HTMLElement) => Option.Option<Box.Box>;
+    /**
+     * End a leaving Follower at once: a keyed presence child is back while its twin crossfades out, and
+     * takes over. Its `onDone` is called, as at its handover's end. Returns the crossfade factor it had
+     * faded to, for the child's new node to go on from ({@link RegisterNodeOptions.fadeFrom}); `None` for
+     * an element that isn't one.
+     */
+    readonly dropLeaver: (el: HTMLElement) => Option.Option<number>;
+    /** Stops the engine: its run, its observers and its listeners. The Layer's Scope calls it. */
+    readonly dispose: () => void;
+    /**
+     * Run `listener` at the end of every Measure pass; returns the unsubscribe. The engine's Layer hands
+     * it out as the internal `PassEnds` service, beside the engine, not on it (internal/pass-ends.ts).
+     */
+    readonly onPassEnd: (listener: () => void) => () => void;
+    /**
+     * The tree as plain data, for a diagnostic read: every node now, in the order it was registered.
+     * `console.log(system)` shows it (Effect's `Inspectable`). Parent links are the last Measure pass's,
+     * as the engine reads them.
+     */
+    readonly toJSON: () => Tree;
+}
+/** {@link ProjectionSystem.toJSON}'s tree. */
+export interface Tree {
+    /** What it is, as Effect's `Inspectable` names it. */
+    readonly _id: "ProjectionSystem";
+    /** Every node, in the order it was registered. */
+    readonly nodes: ReadonlyArray<TreeNode>;
+}
+/** One node in a {@link Tree}. */
+export interface TreeNode {
+    /** The id its binding registered it with. */
+    readonly id: string;
+    /** Its element's tag, lower-case. */
+    readonly tag: string;
+    /** Its `layoutId`, if it has one. */
+    readonly layoutId: string | undefined;
+    /** Its parent's id, as the last Measure pass found it by DOM ancestry; `undefined` for a root. */
+    readonly parent: string | undefined;
+    /** Whether it's a layout root. */
+    readonly layoutRoot: boolean;
+    /** A `layoutId` twin's part: the Lead, the newest live one, or a Follower; `undefined` for none. */
+    readonly twin: "lead" | "follower" | undefined;
+    /** A Follower's Lead's id. */
+    readonly lead: string | undefined;
+    /** A layout animation in flight. */
+    readonly animating: boolean;
+    /** A drag in progress. */
+    readonly dragging: boolean;
+    /** A drag's release, running on its Release offset. */
+    readonly releasing: boolean;
+    /** Kept by a presence while it leaves. */
+    readonly leaving: boolean;
+}
+/** `animateLayout`'s options. */
+export interface AnimateLayoutOptions {
+    /** Called once the change has settled: every layout animation it started has ended, however; at once after its pass if it started none. */
+    readonly onSettled?: () => void;
+    /**
+     * Where the change animates from: the boxes at the call (`"call"`, the default), or the last Measure
+     * pass's (`"lastPass"`), for a change a framework applied after the call, such as a write Solid 2
+     * held, which no pass has seen yet. With `"lastPass"` the call takes no Measurements of its own: the
+     * pass it asks for compares with the boxes the last one kept.
+     */
+    readonly from?: "call" | "lastPass" | undefined;
+}
+/**
+ * A late take-over of a twin inside a leaving presence child, told to its presence, with `drop` to end
+ * the handover at once. Returns what ends it as one of the child's parts.
+ */
+export type LateTaken = (drop: () => void) => () => void;
+/** What a binding hands its engine. */
+export interface ProjectionSystemOptions {
+    /**
+     * Whether reduced motion applies now, read when a layout animation starts: the binding's
+     * `ReducedMotion.applies` of its app's setting and the user's preference. Under it, a layout animation
+     * lands on its new box at once, and a crossfade switches at once; a drag's release still returns to
+     * its slot, since it continues the gesture (as Motion's does). By default, never.
+     */
+    readonly reducedMotion?: () => boolean;
+    /**
+     * The app's own scale correctors (Motion's `addScaleCorrector` entries), by the value key each
+     * corrects, for this system's nodes alone. Each is handed the element's own value for its key each
+     * frame (from its `style` or an animation), else its computed value read at its first Measurement, and
+     * writes nothing while the projection doesn't scale it, putting the value back once. One keyed
+     * `borderRadius` or `boxShadow` replaces the built-in one, and a replaced radius isn't blended across
+     * a handover.
+     */
+    readonly scaleCorrectors?: Readonly<Record<string, ScaleCorrectorEntry>> | undefined;
+}
+/**
+ * Build a projection system against a binding's `runtime` (providing its
+ * {@link FrameLoop}) and its {@link ProjectionSink} (its flush gate).
+ *
+ * Runs the coordinator on `runtime`'s Frame loop; the binding disposes the system in
+ * its own teardown (e.g. the provider's `onCleanup`).
+ */
+export declare const makeProjectionSystem: (runtime: ProjectionRuntime, sink: ProjectionSink, options?: ProjectionSystemOptions) => ProjectionSystem;
+export { DEFAULT_DRAG_TRANSITION, DEFAULT_LAYOUT_TRANSITION, type DragTransition, type LayoutTransition } from "./projection-defaults.ts";
+//# sourceMappingURL=projection.d.ts.map

package/dist/internal/projection.d.ts.map

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