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

package/dist/internal/content-watch.js.map

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

package/dist/internal/default-transition.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The DOM Environment's Default transition (CONTEXT.md; ADR-0051, #357): Motion's, by value
+ * (`.reference/motion` at 16c6122, `motion-dom/src/animation/utils/default-transitions.ts`,
+ * `getDefaultTransition`):
+ * - a transform but a scale: a spring, 500 / 25, at rest under 10 px/s;
+ * - `scale`, `scaleX`, `scaleY`: a spring, 550, critically damped toward 0 (2·√550), else 30;
+ * - anything else (opacity, colours, a box's size, a filter): a 0.3 s tween on
+ *   `cubic-bezier(0.25, 0.1, 0.35, 1)`, "a slightly shallower version of the browser's default ease".
+ *
+ * - more than two keyframes (#429): Motion's `keyframesTransition`, a 0.8 s tween, each Interval on
+ *   `easeOut`, the `ease` Motion's `animateMotionValue` gives every value before its default.
+ *
+ * `DomLive` provides the Layer.
+ *
+ * @module
+ */
+import * as DefaultTransition from "@wardic/core/DefaultTransition";
+import * as Layer from "effect/Layer";
+/** The transition through more than two keyframes, as Motion's `keyframesTransition`: a 0.8 s tween, eased out. */
+export declare const keyframes: DefaultTransition.KeyframesTransition;
+/** The transition `key` runs on toward `target` when its own isn't defined, in the DOM: Motion's. */
+export declare const transitionFor: (key: string, target: number | string) => DefaultTransition.Transition;
+/** The DOM Environment's `DefaultTransition.DefaultTransition`. */
+export declare const DefaultTransitionDomLive: Layer.Layer<DefaultTransition.DefaultTransition>;
+//# sourceMappingURL=default-transition.d.ts.map

package/dist/internal/default-transition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-transition.d.ts","sourceRoot":"","sources":["../../src/internal/default-transition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,iBAAiB,MAAM,gCAAgC,CAAA;AAGnE,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAcrC,mHAAmH;AAEnH,eAAO,MAAM,SAAS,EAAE,iBAAiB,CAAC,mBAAuE,CAAA;AASjH,qGAAqG;AACrG,eAAO,MAAM,aAAa,QAAS,MAAM,UAAU,MAAM,GAAG,MAAM,KAAG,iBAAiB,CAAC,UACuB,CAAA;AAE9G,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,EAAE,KAAK,CAAC,KAAK,CAAC,iBAAiB,CAAC,iBAAiB,CAAoF,CAAA"}

package/dist/internal/default-transition.js

@@ -0,0 +1,41 @@
+/**
+ * The DOM Environment's Default transition (CONTEXT.md; ADR-0051, #357): Motion's, by value
+ * (`.reference/motion` at 16c6122, `motion-dom/src/animation/utils/default-transitions.ts`,
+ * `getDefaultTransition`):
+ * - a transform but a scale: a spring, 500 / 25, at rest under 10 px/s;
+ * - `scale`, `scaleX`, `scaleY`: a spring, 550, critically damped toward 0 (2·√550), else 30;
+ * - anything else (opacity, colours, a box's size, a filter): a 0.3 s tween on
+ *   `cubic-bezier(0.25, 0.1, 0.35, 1)`, "a slightly shallower version of the browser's default ease".
+ *
+ * - more than two keyframes (#429): Motion's `keyframesTransition`, a 0.8 s tween, each Interval on
+ *   `easeOut`, the `ease` Motion's `animateMotionValue` gives every value before its default.
+ *
+ * `DomLive` provides the Layer.
+ *
+ * @module
+ */
+import * as DefaultTransition from "@wardic/core/DefaultTransition";
+import * as ReducedMotion from "@wardic/core/ReducedMotion";
+import * as Bool from "effect/Boolean";
+import * as Layer from "effect/Layer";
+/** A transform's but a scale's: Motion's `underDampedSpring`. */
+const TRANSFORM = { type: "spring", stiffness: 500, damping: 25, restSpeed: 10 };
+/** A scale's toward 0: Motion's `criticallyDampedSpring`, critically damped, so it doesn't overshoot past 0. */
+const SCALE_TO_ZERO = { type: "spring", stiffness: 550, damping: 2 * Math.sqrt(550), restSpeed: 10 };
+/** A scale's toward anything else: Motion's `criticallyDampedSpring`, with its damping of 30. */
+const SCALE = { type: "spring", stiffness: 550, damping: 30, restSpeed: 10 };
+/** Every other key's: Motion's `ease`. */
+const EASE = { type: "tween", duration: 0.3, ease: [0.25, 0.1, 0.35, 1] };
+/** The transition through more than two keyframes, as Motion's `keyframesTransition`: a 0.8 s tween, eased out. */
+// #429: on its `animateMotionValue`'s `easeOut`.
+export const keyframes = { type: "tween", duration: 0.8, ease: "easeOut" };
+/** A transform's: a scale's, by its target, or the rest's. */
+const transformFor = (key, target) => Bool.match(key.startsWith("scale"), {
+    onTrue: () => Bool.match(target === 0, { onTrue: () => SCALE_TO_ZERO, onFalse: () => SCALE }),
+    onFalse: () => TRANSFORM,
+});
+/** The transition `key` runs on toward `target` when its own isn't defined, in the DOM: Motion's. */
+export const transitionFor = (key, target) => Bool.match(ReducedMotion.isTransform(key), { onTrue: () => transformFor(key, target), onFalse: () => EASE });
+/** The DOM Environment's `DefaultTransition.DefaultTransition`. */
+export const DefaultTransitionDomLive = Layer.succeed(DefaultTransition.DefaultTransition, { transitionFor, keyframes });
+//# sourceMappingURL=default-transition.js.map

package/dist/internal/default-transition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-transition.js","sourceRoot":"","sources":["../../src/internal/default-transition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,iBAAiB,MAAM,gCAAgC,CAAA;AACnE,OAAO,KAAK,aAAa,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,IAAI,MAAM,gBAAgB,CAAA;AACtC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC,iEAAiE;AACjE,MAAM,SAAS,GAAiC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,CAAA;AAE9G,gHAAgH;AAChH,MAAM,aAAa,GAAiC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAA;AAElI,iGAAiG;AACjG,MAAM,KAAK,GAAiC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,CAAA;AAE1G,0CAA0C;AAC1C,MAAM,IAAI,GAAiC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAA;AAEvG,mHAAmH;AACnH,iDAAiD;AACjD,MAAM,CAAC,MAAM,SAAS,GAA0C,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,CAAA;AAEjH,8DAA8D;AAC9D,MAAM,YAAY,GAAG,CAAC,GAAW,EAAE,MAAuB,EAAgC,EAAE,CAC1F,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE;IAClC,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,aAAa,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC;IAC7F,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS;CACzB,CAAC,CAAA;AAEJ,qGAAqG;AACrG,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,GAAW,EAAE,MAAuB,EAAgC,EAAE,CAClG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,CAAA;AAE9G,mEAAmE;AACnE,MAAM,CAAC,MAAM,wBAAwB,GAAqD,KAAK,CAAC,OAAO,CAAC,iBAAiB,CAAC,iBAAiB,EAAE,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC,CAAA"}

package/dist/internal/drag-defaults.d.ts

@@ -0,0 +1,18 @@
+/** A drag element's default style for its axis. */
+export type DragDefaultStyle = Readonly<Record<string, string>>;
+/**
+ * The default style of a drag element: `touch-action` `none` for a free drag, `pan-y`
+ * for an `x` drag and `pan-x` for a `y` drag, with no text selection or iOS callout.
+ * One frozen object per axis.
+ */
+export declare const dragDefaultStyle: (axis: boolean | "x" | "y") => DragDefaultStyle;
+/**
+ * A Reorder group item's `touch-action` for the group's axis: a `y` list keeps sideways panning, an `x`
+ * row vertical panning, and a grid none.
+ */
+export declare const reorderTouchAction: (axis: "x" | "y" | "xy") => string;
+/** The attribute every drag element gets: no native drag of the element or its content. */
+export declare const DRAG_DEFAULT_ATTRIBUTES: Readonly<{
+    readonly draggable: "false";
+}>;
+//# sourceMappingURL=drag-defaults.d.ts.map

package/dist/internal/drag-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drag-defaults.d.ts","sourceRoot":"","sources":["../../src/internal/drag-defaults.ts"],"names":[],"mappings":"AAcA,mDAAmD;AACnD,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AAe/D;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,CAAC,IAAI,EAAE,OAAO,GAAG,GAAG,GAAG,GAAG,KAAK,gBAI7D,CAAA;AAED;;;GAGG;AAEH,eAAO,MAAM,kBAAkB,EAAE,CAAC,IAAI,EAAE,GAAG,GAAG,GAAG,GAAG,IAAI,KAAK,MAI5D,CAAA;AAED,2FAA2F;AAC3F,eAAO,MAAM,uBAAuB;wBAA8B,OAAO;EAAY,CAAA"}

package/dist/internal/drag-defaults.js

@@ -0,0 +1,38 @@
+/**
+ * The defaults every drag element gets (ADR-0019, *Amendment (Reorder)*, #36), as
+ * Motion's draggables do (render/html/use-props.ts:57-73 at
+ * 16c61222c4166bbef5ff6ab0051192faa79fa8c8,
+ * https://github.com/motiondivision/motion/blob/16c61222c4166bbef5ff6ab0051192faa79fa8c8/packages/framer-motion/src/render/html/use-props.ts#L57-L73):
+ * no browser panning on the drag's axes (`touch-action`), so a touch drag isn't taken
+ * for a scroll and cancelled; no text selection or iOS callout, so a second drag
+ * starting on text the first one selected isn't a native drag; and `draggable="false"`,
+ * so an image or link inside doesn't start one. The style maps are kebab-case, for
+ * Solid's style objects and the Renderer's `setProperty`. Motion writes them over the
+ * user's style; a binding layers them under it, so an app can override one.
+ */
+import * as Match from "effect/Match";
+const styleFor = (touchAction) => Object.freeze({
+    "touch-action": touchAction,
+    "user-select": "none",
+    "-webkit-user-select": "none",
+    "-webkit-touch-callout": "none",
+});
+const FREE = styleFor("none");
+// An axis-locked drag keeps the browser's panning on the other axis.
+const X = styleFor("pan-y");
+const Y = styleFor("pan-x");
+/**
+ * The default style of a drag element: `touch-action` `none` for a free drag, `pan-y`
+ * for an `x` drag and `pan-x` for a `y` drag, with no text selection or iOS callout.
+ * One frozen object per axis.
+ */
+export const dragDefaultStyle = Match.type().pipe(Match.when("x", () => X), Match.when("y", () => Y), Match.orElse(() => FREE));
+/**
+ * A Reorder group item's `touch-action` for the group's axis: a `y` list keeps sideways panning, an `x`
+ * row vertical panning, and a grid none.
+ */
+// A **Reorder group**.
+export const reorderTouchAction = Match.type().pipe(Match.when("y", () => "pan-x"), Match.when("x", () => "pan-y"), Match.orElse(() => "none"));
+/** The attribute every drag element gets: no native drag of the element or its content. */
+export const DRAG_DEFAULT_ATTRIBUTES = Object.freeze({ draggable: "false" });
+//# sourceMappingURL=drag-defaults.js.map

package/dist/internal/drag-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drag-defaults.js","sourceRoot":"","sources":["../../src/internal/drag-defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAKrC,MAAM,QAAQ,GAAG,CAAC,WAAmB,EAAoB,EAAE,CACzD,MAAM,CAAC,MAAM,CAAC;IACZ,cAAc,EAAE,WAAW;IAC3B,aAAa,EAAE,MAAM;IACrB,qBAAqB,EAAE,MAAM;IAC7B,uBAAuB,EAAE,MAAM;CAChC,CAAC,CAAA;AAEJ,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAA;AAC7B,qEAAqE;AACrE,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAA;AAC3B,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAA;AAE3B;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAoD,KAAK,CAAC,IAAI,EAAuB,CAAC,IAAI,CACrH,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EACxB,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EACxB,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CACzB,CAAA;AAED;;;GAGG;AACH,uBAAuB;AACvB,MAAM,CAAC,MAAM,kBAAkB,GAAuC,KAAK,CAAC,IAAI,EAAoB,CAAC,IAAI,CACvG,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,EAC9B,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,EAC9B,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAC3B,CAAA;AAED,2FAA2F;AAC3F,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,OAAO,EAAW,CAAC,CAAA"}

package/dist/internal/gate.d.ts

@@ -0,0 +1,186 @@
+/**
+ * `makeFlushGate` — the deferred **Flush gate** (ADR-0006), framework-free here in `@wardic/dom`
+ * so every binding shares one (ADR-0031, decision 3). The binding hands in its `batch` and its
+ * sinks; the gate imports nothing from a framework.
+ *
+ * Per ADR-0006, per-frame writes never reach their element directly. Each source
+ * `write(id, partialValues)`s into a provider-owned gate that:
+ *
+ *   1. Accumulates *value-maps* (NOT already-projected Patches) per element,
+ *      merging partials by key — so multiple sources can feed one element
+ *      (e.g. a drag setting `x`/`y` while a spring drives `scale`, all
+ *      collapsing into one grouped `transform`). Projecting per source would
+ *      clobber the grouped transform.
+ *   2. Resolves the Renderer's PURE `project` ONCE at creation and uses it to
+ *      turn each dirty element's merged value-map into a `Patch` exactly once
+ *      per element per frame.
+ *   3. Commits each resulting Patch onto its element with the Renderer's `commit`, a plain
+ *      call (ADR-0034) — one DOM pass per frame, shared by every element: at the end of the
+ *      Frame loop's tick, in the Refresh frame that computed the values (ADR-0033). No
+ *      framework runs per frame: a binding's JSX carries an element's style only until its
+ *      first commit (ADR-0021, decision 6), and after it only the keys the gate doesn't hold.
+ *
+ * Three locked design decisions (this session's grills):
+ *   - FLUSHED at the end of the Frame loop's tick (ADR-0033): the gate registers a hook on
+ *     the Environment's loop (`afterTick`), so everything a tick writes is applied at the end
+ *     of that tick, inside the Clock's callback, and paints in that Refresh frame. A write
+ *     made outside a tick (a drag's move, a `release` from a task, an effect a sink's hook ran,
+ *     a Tier 2 `Stream` on `Clock.ticks` subscribed after the loop) still requests a
+ *     Refresh frame, only if one is not already pending, and the hook withdraws that request
+ *     when it flushes first. `flush` does NOT auto-reschedule, so an idle accumulator
+ *     requests no frames — the next `write` does. The frames come from the Environment's
+ *     `RefreshFrameSource` (ADR-0031): on the web, `requestAnimationFrame` itself. No binding
+ *     calls the browser's frame functions itself. A Tier 2 `Stream` that writes here paints in
+ *     the loop's frame or the next one, by its subscription order (ADR-0033): run it on the
+ *     loop (`Machine.run`) to paint with it.
+ *   - ONE flush per frame: all dirty elements flush together. The one exception
+ *     is `flushPass` (ADR-0018): a projection Measure pass's own writes are applied
+ *     at the end of its task, so a new layout never paints without its projection.
+ *   - ONE sink shape (ADR-0034): a sink is the element its patch is committed onto. The gate
+ *     also removes a key its last patch had and this one doesn't (a dragged node's `z-index`
+ *     once its raise is dropped, ADR-0016 *Amendment (Reorder)*), restoring the element's own
+ *     inline value, saved before the gate first wrote the key. Two hooks reach the binding,
+ *     outside the commits, each in the binding's `batch` (ADR-0034, *Amendment (#209)*): the
+ *     Starting-style switch before an element's first commit (`beforeFirstCommit`), and the keys
+ *     the gate holds on the element whenever they change (`onHeld`), so the binding's `style`
+ *     leaves them to Wardic.
+ *
+ * Observability (CONTEXT.md convention): the hot path (`write`/`flush`) is the
+ * per-frame work, so — exactly like core's per-frame writes and the Clock's
+ * `tick` — it stays quiet (no span, no per-call log, no metric). A flush that throws (a
+ * binding's hook, a commit) is reported (`reportFailure`) and the gate
+ * goes on, so it can't fail the Frame loop's tick it runs in (ADR-0033).
+ */
+import * as FrameLoop from "@wardic/core/FrameLoop";
+import * as RefreshFrameSource from "@wardic/core/RefreshFrameSource";
+import * as Renderer from "@wardic/core/Renderer";
+import { Atom, AtomRegistry } from "effect/reactivity";
+import * as Effect from "effect/Effect";
+import type * as Fiber from "effect/Fiber";
+import * as Scope from "effect/Scope";
+/**
+ * Where a flushed `Patch` is delivered: committed onto `target` with the Renderer's `commit`,
+ * at flush time.
+ */
+export interface FlushSink {
+    /** The element the patch is committed onto. */
+    readonly target: unknown;
+    /**
+     * Called once, just before the element's first commit in a frame flush (not a Measure
+     * pass's `flushPass`), inside the binding's `batch` with every other element's switch that
+     * flush: a binding drops its Starting style from its `style` prop here,
+     * so its framework removes those keys and the commit writes the first frame in the same
+     * Refresh frame, with no paint in between.
+     */
+    readonly beforeFirstCommit?: (() => void) | undefined;
+    /**
+     * Called with every key the gate now holds on the element, each time that set changes: after the
+     * gate restores a key it dropped, and before the commit that first
+     * writes a key. A binding whose `style` prop reaches the element leaves these keys out of it,
+     * so its framework never writes over Wardic's value (`style` is a key's fallback). Called in
+     * the binding's `batch`, with every other element's whose keys changed that flush, so what the
+     * binding changes reaches the element before the commit, a framework that applies an update later
+     * (Solid 2) included.
+     */
+    readonly onHeld?: ((keys: ReadonlyArray<string>) => void) | undefined;
+    /**
+     * Called once per frame in which the element's values were committed, after every commit of that
+     * frame (Motion's `onUpdate`), with its values before
+     * projection (`x` as a number). The object is the element's own, reused each call: valid during
+     * the call, copied to keep. A Measure pass's commits are told at the frame flush after them, so
+     * a frame tells each element once. A write it makes is the next frame's. A throw is reported,
+     * and the others are still told.
+     */
+    readonly onCommit?: ((values: Readonly<Record<string, unknown>>) => void) | undefined;
+}
+/** A Flush gate: what a binding registers its elements with and writes their values into, one per provider. */
+export interface FlushGate {
+    /**
+     * Register an element under `id` with its `sink`. Returns an unregister fn
+     * that removes the element from the accumulator (a subsequent `write` is a
+     * no-op). `values` start its value-map, unflushed: drawn with its first `write`, so they never
+     * commit alone.
+     */
+    readonly register: (id: string, sink: FlushSink, values?: Readonly<Record<string, unknown>>) => () => void;
+    /**
+     * Merge `partial` into the element's value-map by key, mark it dirty, and
+     * schedule a flush: the end of the Frame loop's tick, for a write made in one, or else the
+     * next Refresh frame. A `write` for an unregistered (or unregistered-since) id
+     * is a no-op.
+     */
+    readonly write: (id: string, partial: Record<string, unknown>) => void;
+    /**
+     * Run a projection **Measure pass** now and apply exactly what it wrote before
+     * returning. Only `write()`s made while
+     * `pass()` runs are recorded; each recorded entry is `project`ed and committed once, and
+     * marked clean. Everything else stays dirty for its flush. A write made by an effect a sink's
+     * hook runs (a Solid effect) takes the ordinary path. The Projection system calls it at the
+     * end of a task, so a new layout never paints without its projection.
+     */
+    readonly flushPass: (pass: () => void) => void;
+    /**
+     * Hand `keys` back to the element's own style: drop each from the element's
+     * value-map and schedule a flush, which writes `restore[key]` (CSS text) for a key it had
+     * written, or else the inline value it overwrote, and tells the sink (`onHeld`). A key the
+     * entry doesn't hold, or an unknown id, is a no-op. A binding releases a key back at its `style`
+     * value, so a later `style` change shows at rest. A later `write` brings the key back.
+     */
+    readonly release: (id: string, keys: ReadonlyArray<string>, restore?: Readonly<Record<string, string>>) => void;
+    /**
+     * The element's value for `id`'s `key`, live: an `Atom` set as each write that
+     * changes it lands, so it's the value the next commit draws, before the Renderer projects it
+     * (`x` as a number, not a `transform`). Set at the write, not the commit, so a value derived
+     * from it (another key following it through a binding) is written in the same frame and
+     * commits with it. `undefined` before the key's first write, and once it's released or the
+     * element unregisters. One Atom for an id and a key, made on first ask, so per frame only the
+     * keys asked for cost anything.
+     */
+    readonly valueOf: (id: string, key: string) => Atom.Atom<unknown>;
+    /**
+     * Call `fn` once, after the gate's next flush: the end of the Frame loop's tick, for a call
+     * made in one, else the next Refresh frame's, so what was written before it is on the elements.
+     * It schedules that flush if none is pending. A binding tells an animation's end here, as Motion's
+     * `onAnimationComplete` comes with the final value set. One that throws is reported, and the rest
+     * still run.
+     */
+    readonly afterFlush: (fn: () => void) => void;
+    /** Takes the gate off the Frame loop, cancels a pending frame and clears what it held. The Layer's Scope calls it. */
+    readonly dispose: () => void;
+}
+/** What a flush gate needs from its Environment: the `Renderer`, the Frame loop it flushes at the end of each tick of, and the `RefreshFrameSource`. */
+export type FlushGateServices = Renderer.Renderer | RefreshFrameSource.RefreshFrameSource | FrameLoop.FrameLoop | AtomRegistry.AtomRegistry;
+/**
+ * How the gate runs its Effects: synchronously, and forked. `FlushGate.make` builds one from its
+ * Layer's context, forking into its Scope (#132, ADR-0041); a test's `ManagedRuntime` is one too.
+ */
+export interface FlushGateRuntime {
+    readonly runSync: <A, E>(effect: Effect.Effect<A, E, FlushGateServices>) => A;
+    readonly runFork: <A, E>(effect: Effect.Effect<A, E, FlushGateServices>) => Fiber.Fiber<A, E>;
+    /** The Scope it was built in: its own fibers live there, ended as it closes (#618). */
+    readonly scope: Scope.Scope;
+}
+/** What a binding hands its flush gate. */
+export interface FlushGateOptions {
+    /**
+     * Runs a flush's hooks together: calls `apply`, and returns once every update inside it has reached
+     * the elements, before the gate commits. Solid 1 passes its `batch`, Solid 2 runs `apply` then
+     * `flush()`, and React would pass `flushSync`, untried; a binding with nothing to batch passes
+     * `(apply) => apply()`. Called at most twice a flush: once for the starting-style switches
+     * (`beforeFirstCommit`) of the elements committing for the first time, before anything is read off the
+     * elements; and once for the held keys (`onHeld`) of the elements whose held keys changed.
+     */
+    readonly batch: (apply: () => void) => void;
+}
+/**
+ * Build a flush gate against the provider's `runtime`, running each frame flush's Starting-style
+ * switches through the binding's `batch`.
+ *
+ * Resolves both ONCE here: `project` is pure and `commit` a plain call (both called directly at
+ * flush, ADR-0034), `requestFrame` /
+ * `cancelFrame` schedule and cancel the flush of a write made outside a tick, and the Frame
+ * loop's `afterTick` takes the gate's hook for its lifetime. All come from whichever env the
+ * provider was given (`DomLive` / `TestLive`), so the gate inherits that environment's
+ * grouping/unit logic, its Refresh frames and its loop with zero duplication.
+ */
+export declare const makeFlushGate: (runtime: FlushGateRuntime, options: FlushGateOptions) => FlushGate;
+//# sourceMappingURL=gate.d.ts.map

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

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