bireactive 0.3.0 → 0.3.1

package/dist/core/values/canvas.js

@@ -213,21 +213,20 @@ export class Canvas extends Cell {
             return c;
         };
         const self = this;
-        return Canvas.lens([self], {
-            init: ([s]) => chromaOf(s),
-            step: ([s], c, external) => (external ? chromaOf(s) : c),
-            fwd: ([s]) => {
+        return Canvas.lens(self, {
+            init: s => chromaOf(s),
+            fwd: s => {
                 const out = sf(s.w, s.h);
                 pass(LUMA, out, x => x.tex("u_s", 0, s.tex));
                 return stamp(out.tex, s.w, s.h);
             },
-            bwd: (target, [s], c) => {
+            bwd: (target, s, c) => {
                 const out = sb(s.w, s.h);
                 pass(RECOLOR, out, x => {
                     x.tex("u_t", 0, target.tex);
                     x.tex("u_c", 1, c.tex);
                 });
-                return { updates: [stamp(out.tex, s.w, s.h)], complement: c };
+                return { update: stamp(out.tex, s.w, s.h), complement: c };
             },
         });
     }
@@ -244,21 +243,20 @@ export class Canvas extends Cell {
             return c;
         };
         const self = this;
-        return Canvas.lens([self], {
-            init: ([s]) => lumaOf(s),
-            step: ([s], c, external) => (external ? lumaOf(s) : c),
-            fwd: ([s]) => {
+        return Canvas.lens(self, {
+            init: s => lumaOf(s),
+            fwd: s => {
                 const out = sf(s.w, s.h);
                 pass(CHROMA_VIEW, out, x => x.tex("u_s", 0, s.tex));
                 return stamp(out.tex, s.w, s.h);
             },
-            bwd: (target, [s], c) => {
+            bwd: (target, s, c) => {
                 const out = sb(s.w, s.h);
                 pass(DELUMA, out, x => {
                     x.tex("u_t", 0, target.tex);
                     x.tex("u_c", 1, c.tex);
                 });
-                return { updates: [stamp(out.tex, s.w, s.h)], complement: c };
+                return { update: stamp(out.tex, s.w, s.h), complement: c };
             },
         });
     }
@@ -332,14 +330,13 @@ export class Canvas extends Cell {
             return res;
         };
         const self = this;
-        return Canvas.lens([self], {
-            init: ([s]) => residualOf(s),
-            step: ([s], c, external) => (external ? residualOf(s) : c),
-            fwd: ([s]) => {
+        return Canvas.lens(self, {
+            init: s => residualOf(s),
+            fwd: s => {
                 const small = down(sdF, s.tex, s.w, s.h);
                 return stamp(small.tex, small.w, small.h);
             },
-            bwd: (target, [s], c) => {
+            bwd: (target, s, c) => {
                 const up = suB(s.w, s.h);
                 pass(UP, up, x => {
                     x.tex("u_small", 0, target.tex);
@@ -351,7 +348,7 @@ export class Canvas extends Cell {
                     x.tex("u_a", 0, up.tex);
                     x.tex("u_b", 1, c.tex);
                 });
-                return { updates: [stamp(out.tex, s.w, s.h)], complement: c };
+                return { update: stamp(out.tex, s.w, s.h), complement: c };
             },
         });
     }

package/dist/core/values/str.js

@@ -22,16 +22,16 @@ import { Cell } from "../cell.js";
 // The complement is state recorded forward from the source and consumed
 // on write-back. It persists across the lens's own writes (so `trim`
 // keeps its padding even when the view is emptied) and refreshes on
-// external source changes — the engine's `external` flag drives `step`.
+// external source changes — the engine re-runs `init` (the default `step`)
+// only when the source actually moves.
 /** Endo lens backed by a complement recorded from the source. `record`
- *  rebuilds the complement (kept on the lens's own writes), `project`
- *  is the forward view, `reconstruct` is the backward source. */
+ *  rebuilds the complement (kept on the lens's own writes; re-run on external
+ *  source changes), `project` is the forward view, `reconstruct` the source. */
 function complementLens(parent, record, project, reconstruct) {
-    return Str.lens([parent], {
-        init: ([s]) => record(s),
-        step: ([s], c, external) => (external ? record(s) : c),
-        fwd: ([s]) => project(s),
-        bwd: (target, _s, c) => ({ updates: [reconstruct(target, c)], complement: c }),
+    return Str.lens(parent, {
+        init: (s) => record(s),
+        fwd: (s) => project(s),
+        bwd: (target, _s, c) => ({ update: reconstruct(target, c), complement: c }),
     });
 }
 export const equals = (a, b) => a === b;

package/dist/formats/lens.js

@@ -36,19 +36,16 @@ export function valueHub(initial) {
  *  the error regions. */
 export function formatSpoke(hub, adapter) {
     return lens(hub, {
-        init: ([v]) => fromValue(adapter, v),
-        step: ([v], c) => (v === c.synced ? c : absorb(adapter, c, v)),
-        fwd: (_vals, c) => c.text,
-        bwd: (target, _vals, c) => {
+        init: v => fromValue(adapter, v),
+        step: (v, c) => (v === c.synced ? c : absorb(adapter, c, v)),
+        fwd: (_v, c) => c.text,
+        bwd: (target, _v, c) => {
             const { tree, errors } = adapter.parse(target);
             if (errors.length === 0) {
                 const v = valueOf(tree);
-                return { updates: [v], complement: { text: target, tree, errors, synced: v } };
+                return { update: v, complement: { text: target, tree, errors, synced: v } };
             }
-            return {
-                updates: [SKIP],
-                complement: { text: target, tree, errors, synced: c.synced },
-            };
+            return { update: SKIP, complement: { text: target, tree, errors, synced: c.synced } };
         },
     });
 }

package/dist/jsx-dev-runtime.d.ts

@@ -0,0 +1,2 @@
+export * from "./jsx-runtime.js";
+export { jsx as jsxDEV } from "./jsx-runtime.js";

package/dist/jsx-dev-runtime.js

@@ -0,0 +1,5 @@
+// Development entry for the automatic JSX runtime. esbuild/tsc import this when
+// `jsxDev` is enabled; the dev signature carries extra debug args we ignore, so
+// `jsxDEV` just forwards to `jsx`.
+export * from "./jsx-runtime.js";
+export { jsx as jsxDEV } from "./jsx-runtime.js";

package/dist/jsx-runtime.d.ts

@@ -0,0 +1,54 @@
+import { Cell } from "./core/cell.js";
+/** Marker for `<>…</>`; lowered to `jsx(Fragment, …)`. */
+export declare const Fragment: unique symbol;
+type Disposer = () => void;
+/** Register a teardown with the active scope (`mount` / `scope` / an `each`
+ *  item) — for raw `effect`s or listeners created in a component body, which
+ *  the JSX helpers otherwise track for you. No-op outside a scope. */
+export declare function onCleanup(fn: Disposer): void;
+type Props = Record<string, unknown> & {
+    children?: unknown;
+};
+type Component = (props: Props) => Node;
+/** Build a DOM node for one JSX element. */
+export declare function jsx(type: string | symbol | Component, props?: Props): Node;
+/** Static-children variant; behaviourally identical in a runtime builder. */
+export declare const jsxs: typeof jsx;
+/** Render `component` into `host`, collecting reactive teardowns. The returned
+ *  disposer releases them — call it on unmount (e.g. `disconnectedCallback`). */
+export declare function mount(component: () => Node, host: Node): Disposer;
+/** Run `fn` under a fresh reactive scope, returning its result and a disposer
+ *  for every effect created during it — `mount` without a host. `each` gives
+ *  each keyed item its own scope so its effects die when the item leaves. */
+export declare function scope<T>(fn: () => T): [T, Disposer];
+/** Keyed list rendering: keep `parent`'s children in sync with a reactive array,
+ *  reusing and reordering nodes by key, disposing those that leave. Each item is
+ *  rendered in its own `scope` (untracked from the list effect, so item-internal
+ *  reads don't retrigger the whole list). Attach via `ref`:
+ *  `<div ref={el => each(el, items, s => s.id, render)} />`. */
+export declare function each<T>(parent: Element, items: Cell<T[]> | (() => readonly T[]), key: (item: T, index: number) => string, render: (item: T, index: number) => Node): void;
+type Reactive<T> = T | Cell<T> | (() => T);
+export declare namespace JSX {
+    export type Element = Node;
+    export interface ElementChildrenAttribute {
+        children: unknown;
+    }
+    export interface IntrinsicAttributes {
+        children?: unknown;
+    }
+    export interface CommonProps {
+        class?: Reactive<string>;
+        style?: Reactive<string | Partial<CSSStyleDeclaration>>;
+        id?: Reactive<string>;
+        lens?: Cell<any>;
+        ref?: (el: Element) => void;
+        children?: unknown;
+        [attr: string]: any;
+    }
+    type Tag = keyof HTMLElementTagNameMap | keyof SVGElementTagNameMap;
+    export type IntrinsicElements = {
+        [K in Tag]: CommonProps;
+    };
+    export {};
+}
+export {};

package/dist/jsx-runtime.js

@@ -0,0 +1,219 @@
+// jsx-runtime.ts — minimal runtime JSX for bireactive (no compiler step).
+//
+// esbuild's automatic runtime (`jsxImportSource: "@bireactive"`) lowers JSX to
+// `jsx`/`jsxs`/`Fragment` calls; this module builds real DOM nodes and wires
+// reactive props and children through `effect`. The one binding with no React
+// analogue is the `lens` prop: a single bidirectional terminal — the dual of
+// the value-plus-onInput pair — that reads a writable cell forward into the
+// control and writes edits back, so a chain of lenses can be driven from the
+// leaf. Components are plain `props → Node`; reactive expressions are passed as
+// thunks (`{() => expr}`) or cells, since there is no compile step to wrap them.
+import { Cell, effect, untracked } from "./core/cell.js";
+/** Marker for `<>…</>`; lowered to `jsx(Fragment, …)`. */
+export const Fragment = Symbol.for("bireactive.jsx.Fragment");
+// The active mount scope: reactive teardowns created while building a tree are
+// collected here so `mount` can release them all on unmount. Non-reentrant —
+// `mount` saves/restores the previous owner around the render.
+let currentOwner = null;
+function track(d) {
+    currentOwner?.push(d);
+}
+/** Register a teardown with the active scope (`mount` / `scope` / an `each`
+ *  item) — for raw `effect`s or listeners created in a component body, which
+ *  the JSX helpers otherwise track for you. No-op outside a scope. */
+export function onCleanup(fn) {
+    track(fn);
+}
+/** Build a DOM node for one JSX element. */
+export function jsx(type, props) {
+    if (typeof type === "function")
+        return type(props ?? {});
+    if (type === Fragment) {
+        const frag = document.createDocumentFragment();
+        append(frag, props?.children);
+        return frag;
+    }
+    const el = document.createElement(type);
+    if (props)
+        for (const key in props)
+            applyProp(el, key, props[key]);
+    return el;
+}
+/** Static-children variant; behaviourally identical in a runtime builder. */
+export const jsxs = jsx;
+function applyProp(el, key, value) {
+    if (key === "children")
+        return append(el, value);
+    if (key === "ref") {
+        if (typeof value === "function")
+            value(el);
+        return;
+    }
+    if (key === "lens")
+        return bindLens(el, value);
+    if (key.startsWith("on") && typeof value === "function") {
+        el.addEventListener(key.slice(2).toLowerCase(), value);
+        return;
+    }
+    if (value instanceof Cell) {
+        track(effect(() => setProp(el, key, value.value)));
+        return;
+    }
+    if (typeof value === "function") {
+        track(effect(() => setProp(el, key, value())));
+        return;
+    }
+    setProp(el, key, value);
+}
+function setProp(el, key, value) {
+    if (key === "class" || key === "className") {
+        el.setAttribute("class", value == null ? "" : String(value));
+    }
+    else if (key === "style") {
+        if (value && typeof value === "object")
+            Object.assign(el.style, value);
+        else
+            el.setAttribute("style", value == null ? "" : String(value));
+    }
+    else if (key === "value") {
+        el.value = value == null ? "" : String(value);
+    }
+    else if (key === "checked" || key === "disabled" || key === "selected") {
+        // biome-ignore lint/suspicious/noExplicitAny: boolean DOM properties
+        el[key] = !!value;
+    }
+    else if (value == null || value === false) {
+        el.removeAttribute(key);
+    }
+    else {
+        el.setAttribute(key, value === true ? "" : String(value));
+    }
+}
+/** Append a child (array / Node / text / cell / thunk) to `parent`. */
+function append(parent, child) {
+    if (Array.isArray(child)) {
+        for (const c of child)
+            append(parent, c);
+    }
+    else if (child instanceof Node) {
+        parent.appendChild(child);
+    }
+    else if (child instanceof Cell) {
+        parent.appendChild(reactiveText(() => child.value));
+    }
+    else if (typeof child === "function") {
+        parent.appendChild(reactiveText(child));
+    }
+    else if (child != null && child !== false && child !== true) {
+        parent.appendChild(document.createTextNode(String(child)));
+    }
+}
+/** A text node whose content tracks `get()`. Primitive children only — the
+ *  minimal runtime does not reconcile dynamic element children. */
+function reactiveText(get) {
+    const node = document.createTextNode("");
+    track(effect(() => {
+        const v = get();
+        node.data = v == null ? "" : String(v);
+    }));
+    return node;
+}
+/** Two-way bind a form control to a writable cell: read forward into the
+ *  control, write back on input. The forward write is skipped while the
+ *  control is focused, so a live edit is never clobbered mid-drag (the
+ *  controlled-input focus guard, written once). */
+function bindLens(el, lens) {
+    const checkbox = el.type === "checkbox";
+    track(effect(() => {
+        const v = lens.value;
+        if (checkbox) {
+            el.checked = !!v;
+            return;
+        }
+        const next = v == null ? "" : String(v);
+        const root = el.getRootNode();
+        if (root.activeElement !== el && el.value !== next)
+            el.value = next;
+    }));
+    const evt = checkbox || el.tagName === "SELECT" ? "change" : "input";
+    el.addEventListener(evt, () => {
+        lens.value = checkbox
+            ? el.checked
+            : el.type === "range" || el.type === "number"
+                ? Number(el.value)
+                : el.value;
+    });
+}
+/** Render `component` into `host`, collecting reactive teardowns. The returned
+ *  disposer releases them — call it on unmount (e.g. `disconnectedCallback`). */
+export function mount(component, host) {
+    const [node, dispose] = scope(component);
+    host.appendChild(node);
+    return dispose;
+}
+/** Run `fn` under a fresh reactive scope, returning its result and a disposer
+ *  for every effect created during it — `mount` without a host. `each` gives
+ *  each keyed item its own scope so its effects die when the item leaves. */
+export function scope(fn) {
+    const prev = currentOwner;
+    const owner = [];
+    currentOwner = owner;
+    try {
+        return [
+            fn(),
+            () => {
+                for (const d of owner)
+                    d();
+                owner.length = 0;
+            },
+        ];
+    }
+    finally {
+        currentOwner = prev;
+    }
+}
+/** Keyed list rendering: keep `parent`'s children in sync with a reactive array,
+ *  reusing and reordering nodes by key, disposing those that leave. Each item is
+ *  rendered in its own `scope` (untracked from the list effect, so item-internal
+ *  reads don't retrigger the whole list). Attach via `ref`:
+ *  `<div ref={el => each(el, items, s => s.id, render)} />`. */
+export function each(parent, items, key, render) {
+    const read = typeof items === "function" ? items : () => items.value;
+    const cache = new Map();
+    const stop = effect(() => {
+        const arr = read();
+        const seen = new Set();
+        const nodes = [];
+        arr.forEach((item, i) => {
+            const k = key(item, i);
+            seen.add(k);
+            let entry = cache.get(k);
+            if (entry === undefined) {
+                const [node, dispose] = untracked(() => scope(() => render(item, i)));
+                entry = { node, dispose };
+                cache.set(k, entry);
+            }
+            nodes.push(entry.node);
+        });
+        for (const [k, entry] of cache) {
+            if (!seen.has(k)) {
+                entry.dispose();
+                cache.delete(k);
+            }
+        }
+        // Only touch the DOM when the ordered node set actually changed — re-inserting
+        // identical children mid-interaction would steal focus and reset clicks.
+        const cur = parent.childNodes;
+        let same = cur.length === nodes.length;
+        for (let i = 0; same && i < nodes.length; i++)
+            same = cur[i] === nodes[i];
+        if (!same)
+            parent.replaceChildren(...nodes);
+    });
+    track(() => {
+        stop();
+        for (const entry of cache.values())
+            entry.dispose();
+        cache.clear();
+    });
+}

package/dist/schema/lens.js

@@ -372,12 +372,12 @@ export function recurse(build) {
 /** Lift a value-lens onto a reactive cell. */
 export function toStep(vl) {
     return src => lens(src, {
-        init: ([v]) => vl.init(v),
-        step: ([v], c) => (vl.step ? vl.step(v, c) : c),
-        fwd: ([v], c) => vl.fwd(v, c),
-        bwd: (t, [v], c) => {
+        init: v => vl.init(v),
+        step: (v, c) => (vl.step ? vl.step(v, c) : c),
+        fwd: (v, c) => vl.fwd(v, c),
+        bwd: (t, v, c) => {
             const r = vl.bwd(t, v, c);
-            return { updates: [r.s], complement: r.c };
+            return { update: r.s, complement: r.c };
         },
     });
 }

package/dist/shapes/drag-behaviors.d.ts

@@ -0,0 +1,56 @@
+import { type Animator, type SpringOpts } from "../animation/index.js";
+import { type Cell, type Inner, type Read, Vec, type Writable } from "../core/index.js";
+import type { Drag } from "./drag-spec.js";
+import type { AnyShape } from "./shape.js";
+export interface FloatingResult {
+    /** True between pointerdown and release. Drive ghosting/elevation off this. */
+    dragging: Cell<boolean>;
+    /** Start this on the diagram's `Anim` (`this.anim.start(anim)`). */
+    anim: Animator<void>;
+    dispose: () => void;
+}
+export interface FloatingOpts extends SpringOpts<{
+    x: number;
+    y: number;
+}> {
+}
+/** Dragology's `withFloating`: while held, `pos` follows the pointer
+ *  directly (via the robust `drag` wiring — grab offset, touch, capture);
+ *  on release it springs to `home` (the resolved target, e.g. a `closest`
+ *  snap position or a layout slot). `pos` is the caller-owned display cell
+ *  the shape renders from.
+ *
+ *      const pos = vec(home.peek());
+ *      const dot = s(circle(pos, 10));
+ *      const { anim } = floating(dot, pos, home);
+ *      this.anim.start(anim);
+ *
+ *  While dragging, the settle spring is frozen (rate 0) so it never fights
+ *  the pointer; on release it re-engages and eases `pos` home. */
+export declare function floating(shape: AnyShape, pos: Writable<Vec>, home: Read<{
+    x: number;
+    y: number;
+}>, opts?: FloatingOpts): FloatingResult;
+/** Run `grab`/`drop` on the rising/falling edge of `active`. */
+export declare function onGesture(active: Read<boolean>, edges: {
+    grab?: () => void;
+    drop?: () => void;
+}): () => void;
+/** Re-append shapes to raise them above siblings (z-order). */
+export declare function raise(...shapes: readonly AnyShape[]): void;
+export interface DragModel<M, Id> {
+    /** Which element is being dragged (null when idle). */
+    active: Cell<Id | null>;
+    /** The free pointer for the active drag (bound by `grip`). */
+    pointer: Writable<Vec>;
+    /** Previewed model while dragging, else the committed model. */
+    preview: Read<M>;
+    /** Where the dragged handle sits this frame (float the dragged element here). */
+    at: Vec;
+    /** Wire a handle: seed + claim on press, commit `drop` on release. */
+    grip(handle: AnyShape, id: Id, seed: () => Inner<Vec>, onGrab?: () => void): () => void;
+}
+/** Bind a committed `model` cell to a `Drag<M>` spec built at grab time. Owns
+ *  the transient drag state (which element, the free pointer, the live preview)
+ *  and commits the spec's drop on release — the demo only renders `preview`/`at`. */
+export declare function dragModel<M, Id>(model: Writable<Cell<M>>, spec: (id: Id, pointer: Read<Inner<Vec>>) => Drag<M>): DragModel<M, Id>;

package/dist/shapes/drag-behaviors.js

@@ -0,0 +1,102 @@
+// drag-behaviors.ts — Dragology-style drag *modifiers* layered over the
+// scene graph. The model-driven cores (`closest`, `between`, `whenFar`)
+// live in `core/lenses/snap.ts`; these wire them to pointer input and the
+// animation clock.
+//
+// The key idea, and the answer to "drag-and-drop complicates state": the
+// floating offset and the spring-settle are TRANSIENT drag state, held in
+// the animator, never written to the model. The model only ever sees the
+// committed drop.
+import { spring } from "../animation/index.js";
+import { cell, derive, effect, Vec, vec, } from "../core/index.js";
+import { drag } from "./interaction.js";
+/** Dragology's `withFloating`: while held, `pos` follows the pointer
+ *  directly (via the robust `drag` wiring — grab offset, touch, capture);
+ *  on release it springs to `home` (the resolved target, e.g. a `closest`
+ *  snap position or a layout slot). `pos` is the caller-owned display cell
+ *  the shape renders from.
+ *
+ *      const pos = vec(home.peek());
+ *      const dot = s(circle(pos, 10));
+ *      const { anim } = floating(dot, pos, home);
+ *      this.anim.start(anim);
+ *
+ *  While dragging, the settle spring is frozen (rate 0) so it never fights
+ *  the pointer; on release it re-engages and eases `pos` home. */
+export function floating(shape, pos, home, opts = {}) {
+    const dragging = cell(false);
+    const dispose = drag(shape, pos, dragging);
+    const anim = spring(pos, home, {
+        omega: opts.omega ?? 24,
+        zeta: opts.zeta ?? 0.9,
+        ...opts,
+        // Never completes (re-engages every release) and yields to the pointer
+        // while held.
+        precision: 0,
+        rate: () => (dragging.value ? 0 : (opts.rate?.() ?? 1)),
+    });
+    return { dragging, anim, dispose };
+}
+// ── drag lifecycle ──────────────────────────────────────────────────
+// The `was`-flag edge and z-raise every demo hand-rolls, factored out, plus a
+// model-driven driver that ties a `Drag<M>` spec (drag-spec.ts) to the
+// grab→preview→commit lifecycle — the spec is built once per grab (like
+// Dragology's `dragologyOnDrag`), so candidate states are enumerated then.
+/** Run `grab`/`drop` on the rising/falling edge of `active`. */
+export function onGesture(active, edges) {
+    let was = false;
+    return effect(() => {
+        const now = active.value;
+        if (now && !was)
+            edges.grab?.();
+        else if (!now && was)
+            edges.drop?.();
+        was = now;
+    });
+}
+/** Re-append shapes to raise them above siblings (z-order). */
+export function raise(...shapes) {
+    for (const s of shapes)
+        s.el.parentElement?.appendChild(s.el);
+}
+/** Bind a committed `model` cell to a `Drag<M>` spec built at grab time. Owns
+ *  the transient drag state (which element, the free pointer, the live preview)
+ *  and commits the spec's drop on release — the demo only renders `preview`/`at`. */
+export function dragModel(model, spec) {
+    const active = cell(null);
+    const pointer = vec(0, 0);
+    const live = cell(null);
+    const preview = derive(() => {
+        const s = live.value;
+        return s ? s.preview.value : model.value;
+    });
+    const at = Vec.derive(() => {
+        const s = live.value;
+        return s ? s.at.value : pointer.value;
+    });
+    const grip = (handle, id, seed, onGrab) => {
+        const dragging = cell(false);
+        const offDown = handle.on("pointerdown", () => {
+            pointer.value = seed();
+            active.value = id;
+            live.value = spec(id, pointer);
+            onGrab?.();
+        });
+        const offDrag = drag(handle, pointer, dragging);
+        const offEdge = onGesture(dragging, {
+            drop: () => {
+                const s = live.peek();
+                if (s)
+                    model.value = s.drop.peek();
+                active.value = null;
+                live.value = null;
+            },
+        });
+        return () => {
+            offDown();
+            offDrag();
+            offEdge();
+        };
+    };
+    return { active, pointer, preview, at, grip };
+}

package/dist/shapes/drag-spec.d.ts

@@ -0,0 +1,52 @@
+import { type Read } from "../core/index.js";
+type V = {
+    x: number;
+    y: number;
+};
+/** A drag behavior: Dragology's `DragBehavior`, reactive and parametric in the
+ *  MODEL `M` (positions are just `M = Vec`). */
+export interface Drag<M> {
+    /** Model rendered this frame (non-dragged elements reflow toward this). */
+    preview: Read<M>;
+    /** Model committed on release. */
+    drop: Read<M>;
+    /** Where the dragged handle sits this frame (the renderer floats it here). */
+    at: Read<V>;
+    /** Residual |pointer − achievable|; combinators arbitrate on this. */
+    gap: Read<number>;
+}
+/** `d.fixed`: a single reachable model; `locate` reads where the dragged handle
+ *  lands in it (a layout cell, or a pure layout fn). */
+declare function fixed<M>(pointer: Read<V>, state: M, locate: (m: M) => V): Drag<M>;
+/** `d.vary`: a continuous family; `place` is the BACKWARD map pointer→model (a
+ *  lens / `argminVec`, not numerical search), `gap` the residual off the family. */
+declare function vary<M>(pointer: Read<V>, place: (p: V) => M, locate: (m: M) => V): Drag<M>;
+/** `d.closest`: the behavior with the smallest `gap` (discrete snapping and
+ *  continuous tracks both pick with it). */
+declare function closest<M>(bs: readonly Drag<M>[]): Drag<M>;
+/** `d.between`: free motion in the candidates' convex hull; preview is their
+ *  barycentric blend (`mix` any `Lerp`/`Linear` model). Unlike `closest` it does
+ *  NOT snap — it rests at the blend, so `drop` is the previewed mix. */
+declare function between<M>(pointer: Read<V>, bs: readonly Drag<M>[], mix: (ms: readonly M[], ws: readonly number[]) => M): Drag<M>;
+/** `d.whenFar`: use `near` unless its gap exceeds `radius`, then `far` (snap
+ *  into a port, else float free). */
+declare function whenFar<M>(near: Drag<M>, far: Drag<M>, radius: number): Drag<M>;
+/** `d.withFloating`: the dragged handle follows the pointer while the rest
+ *  reflow (they already do — `preview` is reactive); just an `at` override. */
+declare function withFloating<M>(pointer: Read<V>, b: Drag<M>): Drag<M>;
+/** `d.onDrop`: transform the committed model (create/destroy, snap-to-grid),
+ *  the escape hatch beyond repositional drags. */
+declare function onDrop<M>(b: Drag<M>, f: (m: M) => M): Drag<M>;
+/** The drag-behavior DSL (Dragology's `d.`): primitives `fixed`/`vary`,
+ *  combinators `closest`/`between`/`whenFar`, modifiers `withFloating`/`onDrop`.
+ *  Build a `Drag<M>` once at grab; the renderer reads `preview`/`at`/`drop`. */
+export declare const d: {
+    readonly fixed: typeof fixed;
+    readonly vary: typeof vary;
+    readonly closest: typeof closest;
+    readonly between: typeof between;
+    readonly whenFar: typeof whenFar;
+    readonly withFloating: typeof withFloating;
+    readonly onDrop: typeof onDrop;
+};
+export {};