kuinetic 0.1.0

package/dist/types/core/activation.d.ts

@@ -0,0 +1,21 @@
+import type { Activation, Cleanup } from './types.js';
+export interface ActivationBinder {
+    bind(el: Element, activation: Activation, threshold: string, onActivate: () => void): Cleanup;
+    destroy(): void;
+}
+export interface ActivationBinderOptions {
+    /** Injected so tests can supply a controllable observer and assert without layout. */
+    createObserver?: (callback: IntersectionObserverCallback, options: IntersectionObserverInit) => IntersectionObserver;
+}
+/**
+ * Bind activations to elements, sharing one IntersectionObserver per distinct threshold.
+ *
+ * One observer per threshold rather than per element is the difference between a constant number
+ * of observers and one per animated node on a long page.
+ *
+ * @param options - Optional observer factory; defaults to the global constructor when present.
+ * @returns A binder whose `bind` returns the teardown for that single binding.
+ * @complexity O(1) per bind; O(t) space in the number of distinct thresholds.
+ * @overallScore 100
+ */
+export declare function createActivationBinder(options?: ActivationBinderOptions): ActivationBinder;

package/dist/types/core/animator.d.ts

@@ -0,0 +1,216 @@
+import type { ActivationBinder } from './activation.js';
+import { ATTR } from './attrs.js';
+import type { Capabilities } from './capabilities.js';
+import type { DomWatcher } from './dom-watcher.js';
+import type { JsEffectPreparer } from './js-effect-preparer.js';
+import type { ScrollRoot, ScrollScheduler } from './scroll-scheduler.js';
+import type { PlaybackHandle, PlayOptions, Target } from './play.js';
+import { Registry } from './registry.js';
+import type { Reporter } from './reporter.js';
+import type { InstanceState } from './types.js';
+export { ATTR };
+export interface AnimatorOptions {
+    root?: ParentNode;
+    /** Effect catalog. Injected so a consumer can ship only the effects they use. */
+    registry?: Registry;
+    /** Environment capabilities. Injected so timeline and fallback paths are testable. */
+    capabilities?: Capabilities;
+    /** Diagnostic sink. Defaults to silent; pass `consoleReporter()` in development. */
+    reporter?: Reporter;
+    /** Activation strategy. Injected so tests can drive visibility without layout. */
+    binder?: ActivationBinder;
+    /** Shared scroll orchestration for JS-rendered effects. Injected for testability. */
+    scheduler?: ScrollScheduler;
+    /** Maps an element to the scroll root that moves it. Injected so nesting is fakeable. */
+    rootResolver?: (el: Element) => ScrollRoot;
+    /** Wires up JS-rendered effects' setup context. Injected so it is testable in isolation. */
+    jsEffectPreparer?: JsEffectPreparer;
+    /**
+     * Watches for DOM insertions, removals, and attribute changes. Injected for testability;
+     * defaults to a real `MutationObserver`-backed watcher, built lazily so nothing observes unless
+     * `observe: true` and `start()` actually run.
+     */
+    domWatcher?: DomWatcher;
+    /** `'respect'` honours prefers-reduced-motion. `'ignore'` is for demos and tests only. */
+    reducedMotion?: 'respect' | 'ignore';
+    /** Watch for DOM insertions and attribute changes. Off by default. */
+    observe?: boolean;
+}
+/**
+ * Scans a document for authored effects and installs them.
+ *
+ * Every collaborator — registry, capabilities, reporter, activation binder — is injected, so no
+ * behaviour depends on module state or globals. The class itself only orchestrates: parsing,
+ * compilation, and style decisions all live in pure modules it calls.
+ */
+export declare class Animator {
+    readonly registry: Registry;
+    readonly capabilities: Capabilities;
+    private readonly root;
+    private readonly reporter;
+    private readonly binder;
+    private readonly scheduler;
+    private readonly rootResolver;
+    private readonly jsEffectPreparer;
+    private readonly respectReducedMotion;
+    private readonly shouldObserve;
+    /** Runtime truth. Attributes are for CSS and debugging; they make a poor state machine. */
+    private readonly states;
+    /** Iterable lifecycle index; the WeakMap remains the fast state lookup. */
+    private readonly liveElements;
+    /** Built lazily by `watch()` when not injected, so nothing observes until `start()` needs it. */
+    private domWatcher;
+    private started;
+    constructor(options?: AnimatorOptions);
+    /**
+     * Explicit entry point. Importing the library never touches the document, which keeps SSR,
+     * hydration, and tests deterministic.
+     *
+     * @complexity O(n) time in the number of elements scanned.
+     * @overallScore 100
+     */
+    start(): this;
+    /**
+     * Process every unprocessed element in a subtree, including the root.
+     *
+     * `querySelectorAll` excludes the root, but an inserted subtree very often carries the
+     * attribute on its top node — skipping it silently drops those animations.
+     *
+     * @param root - Subtree to scan. Defaults to the animator's root.
+     * @complexity O(n) time in the subtree size; O(1) extra space.
+     * @overallScore 100
+     */
+    scan(root?: ParentNode): this;
+    /**
+     * Compile and install one element's effects, recompiling if its attribute changed.
+     *
+     * @param el - Element carrying `data-kui`.
+     * @complexity O(e) time in the number of composed effects; O(e) space for the plan.
+     * @overallScore 100
+     */
+    process(el: Element): void;
+    /**
+     * Apply a compiled plan and bind its activation.
+     *
+     * @complexity O(e) time in composed effects; O(e) space for retained cleanups.
+     * @overallScore 100
+     */
+    /**
+     * Choose the activation, letting a primitive's preference fill in only when the author named
+     * none, and warning when an authored activation is not one the effect supports.
+     *
+     * Declared capability metadata was previously never checked anywhere, which made
+     * `supportedActivations` documentation rather than a contract.
+     *
+     * @complexity O(a) time in supported activations; O(1) space.
+     * @overallScore 100
+     */
+    private resolveActivation;
+    private install;
+    /**
+     * Decide whether, and when, the effects on this element are allowed to start.
+     *
+     * The single place any effect begins. Routing both renderers through it is what makes
+     * `on:enter`, `on:click`, `manual`, and `reducedMotion: 'disable'` mean the same thing for a
+     * pinned section as for a fade — previously JS effects started during `prepare` and honoured
+     * none of them.
+     *
+     * @complexity O(n) time in the number of instances; O(1) space.
+     * @overallScore 100
+     */
+    private openGate;
+    /**
+     * Start a deferred animation.
+     *
+     * A JS-rendered effect's real setup work is postponed until this call — `deferPrepare` in
+     * `instances.ts` only wires up an inert instance during `prepare` — so a broken primitive (a bad
+     * selector, a malformed param) first throws here, not while the plan was being built. `scan()`
+     * reaches this synchronously for every `on:load` element, inside the very loop that processes
+     * every other element on the page; an uncaught throw here previously unwound that loop and
+     * silently orphaned every element after the broken one — the same blast radius the `__proto__`
+     * scan-crash fix closed for a different door. Each instance is isolated so one effect's failure
+     * can neither strand a sibling effect on the same element nor abort the rest of the scan.
+     *
+     * @complexity O(n) time in composed instances; O(1) space.
+     * @overallScore 100
+     */
+    activate(el: Element): void;
+    /**
+     * Activate one instance, isolating a throw from its (possibly deferred) setup.
+     *
+     * @returns Whether the instance actually started — a failed instance is excluded from the
+     * `finished` gate in `activate()`, since something that never started can never legitimately
+     * finish (see `EffectInstance.finished`'s "resolves, never rejects" contract in `types.ts`).
+     * @complexity O(1) time, O(1) space.
+     * @overallScore 100
+     */
+    private startInstance;
+    /**
+     * Programmatic entry point. Accepts a selector, an Element, a NodeList, or any iterable, so
+     * `getElementById`, `getElementsByClassName`, and `querySelectorAll` all work directly.
+     *
+     * @complexity O(n) time in selected elements.
+     * @overallScore 100
+     */
+    play(target: Target, effect: string, options?: PlayOptions): PlaybackHandle;
+    /**
+     * Remove the opt-in cloak so a stalled or failed initialisation can never leave a page hidden.
+     *
+     * @complexity O(1) time, O(1) space.
+     * @overallScore 100
+     */
+    uncloak(): void;
+    stateOf(el: Element): InstanceState | undefined;
+    /**
+     * Tear an element's effects down so the next `process()` reinstalls from scratch.
+     *
+     * Needed for replay: `process()` short-circuits when the configuration fingerprint is
+     * unchanged, so playing the same effect twice was previously a no-op.
+     *
+     * @complexity O(c) time in retained instances; O(1) space.
+     * @overallScore 100
+     */
+    reset(el: Element): void;
+    /**
+     * Tear down one element's effects and clear its library-owned attributes.
+     *
+     * @complexity O(c) time in retained cleanups; O(1) extra space.
+     * @overallScore 100
+     */
+    private release;
+    /**
+     * Tear down every tracked element inside a removed subtree.
+     *
+     * Scoped to `node`'s own descendants rather than re-scanning `liveElements` against the whole
+     * page, so a removal event costs O(removed subtree), not O(every animated element alive
+     * anywhere) — `dom-watcher.ts` can queue up to 100 removed roots per frame, and `liveElements`
+     * only shrinks on release, so it stays large on a scroll-reveal-heavy page.
+     *
+     * Membership is checked against `liveElements` (the ground truth) rather than re-querying
+     * `[${ATTR.source}]` the way `scan()` does: `dom-watcher.ts`'s `flush()` drains removed roots
+     * before attribute-change roots, so if calling code strips `data-kui` and removes the element in
+     * the same tick, a selector-based query would already miss it here and leak its teardown.
+     *
+     * `node` is typed `Element`, not `ParentNode`: `dom-watcher.ts`'s `onElementRemoved` — this
+     * method's only caller — is itself typed `(el: Element) => void`, so there is no runtime case
+     * where `node` is a `Document`/`DocumentFragment` to guard against.
+     *
+     * @complexity O(s) time in the removed subtree's element count; O(1) per candidate via the
+     * `liveElements` Set lookup.
+     * @overallScore 100
+     */
+    private releaseTree;
+    destroy(): void;
+    /**
+     * Start watching for DOM insertions, removals, and attribute changes.
+     *
+     * Attribute changes recompile in place; insertions scan; removals tear down so listeners and
+     * observers do not outlive their elements.
+     *
+     * @complexity O(1) time and space to build and start; the watcher's own callback runs O(n) time
+     * in the nodes one mutation record carries.
+     * @overallScore 100
+     */
+    private watch;
+}
+export declare function createAnimator(options?: AnimatorOptions): Animator;

package/dist/types/core/attrs.d.ts

@@ -0,0 +1,15 @@
+/** Attribute names, in one place so the namespace is a single rename before publish. */
+export declare const ATTR: {
+    /** Authored. The rich grammar. */
+    readonly source: "data-kui";
+    /** Library-owned and unstable: normalized effect names, for CSS hooks and debugging. */
+    readonly normalized: "data-kui-fx";
+    readonly state: "data-kui-state";
+    readonly on: "data-kui-on";
+    readonly timeline: "data-kui-timeline";
+    readonly threshold: "data-kui-threshold";
+    readonly stagger: "data-kui-stagger";
+    readonly cloak: "data-kui-cloak";
+    /** Reduced-motion policy, stamped from the primitive so the CSS layer can act on it. */
+    readonly rm: "data-kui-rm";
+};

package/dist/types/core/capabilities.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Per-feature detection.
+ *
+ * One global `CSS.supports('animation-timeline','view()')` check is not an abstraction boundary:
+ * `animation-range`, named timelines, and individual transform properties all ship separately.
+ * Each capability is probed independently and cached. See docs/design.md §6.
+ */
+export interface Capabilities {
+    viewTimeline: boolean;
+    scrollTimeline: boolean;
+    animationRange: boolean;
+    individualTransforms: boolean;
+    scrollTimelineName: boolean;
+    viewTransitions: boolean;
+    intersectionObserver: boolean;
+    reducedMotion: boolean;
+}
+export declare function detect(force?: boolean): Capabilities;
+export declare function resetCapabilities(): void;

package/dist/types/core/channels.d.ts

@@ -0,0 +1,25 @@
+import type { Channel } from './types.js';
+/**
+ * Composition safety.
+ *
+ * Two CSS rules that each declare `animation` do NOT concatenate — the cascade discards one.
+ * So a comma list is compiled into a single declaration with parallel value lists. That fixes
+ * the cascade problem but not the *property* problem: two animations writing `opacity` replace
+ * rather than blend.
+ *
+ * Hence channels. An effect declares the property groups it owns; a comma list is only safe to
+ * compile when those sets are pairwise disjoint. See docs/design.md §4.
+ */
+export interface ChannelClaim {
+    name: string;
+    channels: Channel[];
+}
+export interface Conflict {
+    channel: Channel;
+    effects: [string, string];
+}
+/** Every pair of effects claiming the same channel. Empty array means the list composes. */
+export declare function findConflicts(claims: ChannelClaim[]): Conflict[];
+export declare function describeConflicts(conflicts: Conflict[]): string;
+/** Union of all claimed channels, for debugging and perf accounting. */
+export declare function claimedChannels(claims: ChannelClaim[]): Channel[];

package/dist/types/core/compile.d.ts

@@ -0,0 +1,49 @@
+import type { Registry, ResolvedEffect } from './registry.js';
+import type { Activation, Channel, EffectSpec, ParsedValue, ReducedMotionPolicy, Timeline } from './types.js';
+export interface Entry {
+    spec: EffectSpec;
+    resolved: ResolvedEffect;
+}
+export interface CompiledPlan {
+    /** Effect names to stamp into `data-kui-fx` for CSS hooks and debugging. */
+    fxNames: string[];
+    /** Custom properties to write. Author overrides only — defaults stay in CSS `var()` fallbacks. */
+    vars: Record<string, string>;
+    /** Longhand animation declarations, compiled as parallel lists so effects compose. */
+    declarations: Record<string, string>;
+    /** Effects whose renderer needs JS setup. */
+    jsEffects: Entry[];
+    /** Names that are not registered. Must NOT be stamped, or the element is never rescanned. */
+    unknown: string[];
+    /** Strictest reduced-motion policy among the composed effects. */
+    reducedMotion: ReducedMotionPolicy;
+    /** Activation preferred by the composed primitives when the author named none. */
+    defaultActivation?: Activation;
+    /** Activations every composed primitive supports, for enforcement by the animator. */
+    supportedActivations: Activation[];
+    /**
+     * Timelines every composed primitive supports. Empty means none — `style-plan.ts` must not
+     * apply a native `view()`/`scroll()` timeline the author's effect doesn't declare support for,
+     * even when the browser itself is capable of one; `warnUnsupportedTimeline` only warns, it
+     * doesn't change what's compiled, so this is what actually stops the mismatch from being applied.
+     */
+    supportedTimelines: Timeline[];
+    /** Union of channels every composed effect writes to, so callers can react to what actually moves. */
+    channels: Channel[];
+    warnings: string[];
+}
+/**
+ * Turn a parsed `data-kui` value into the writes an element needs.
+ *
+ * Pure: same inputs always produce the same plan, and nothing is applied to the DOM here. That
+ * is what lets composition rules, parameter validation, and declaration output be asserted
+ * directly rather than through a rendered document.
+ *
+ * @param parsed - Output of `parse`.
+ * @param registry - Effect catalog to resolve names against.
+ * @param timeline - Element-scoped timeline, used to warn on unsupported combinations.
+ * @returns A plan describing custom properties, declarations, JS effects, and warnings.
+ * @complexity O(e * p) time in composed effects and their parameters; O(e) space.
+ * @overallScore 100
+ */
+export declare function compile(parsed: ParsedValue, registry: Registry, timeline: Timeline): CompiledPlan;

package/dist/types/core/dom-watcher.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Watches a subtree for authored-effect insertions, removals, and attribute changes.
+ *
+ * Extracted from `Animator` as an injected collaborator — same shape as `binder` or `scheduler` —
+ * owning its own `MutationObserver` lifecycle exactly as the class did inline: nothing observes
+ * until `watch()` is called, and `destroy()` disconnects whatever `watch()` started (or safely
+ * no-ops if it never ran).
+ */
+export interface DomWatcher {
+    /** Start observing. No-op if `MutationObserver` is unavailable in this environment. */
+    watch(): void;
+    /** Stop observing. Safe to call even if `watch()` was never called. */
+    destroy(): void;
+}
+export interface DomWatcherOptions {
+    root: ParentNode;
+    /** An element was inserted into the watched subtree. */
+    onElementAdded(el: Element): void;
+    /** An element left the watched subtree. */
+    onElementRemoved(el: Element): void;
+    /** One of the watched authoring attributes changed on an existing element. */
+    onAttributeChanged(el: Element): void;
+    /** Injected frame queue used to budget mutation work. */
+    schedule?: (callback: () => void) => void;
+    /** Injected observer factory for realm isolation and deterministic tests. */
+    createObserver?: (callback: MutationCallback) => MutationObserver;
+}
+/**
+ * Build a `DomWatcher` closed over one animator's root and mutation callbacks.
+ *
+ * @complexity O(1) time and space to build. The mutation callback it installs runs O(n) time in
+ * the nodes one `MutationRecord` carries.
+ * @overallScore 100
+ */
+export declare function createDomWatcher(options: DomWatcherOptions): DomWatcher;

package/dist/types/core/effect-context.d.ts

@@ -0,0 +1,49 @@
+import type { Capabilities } from './capabilities.js';
+import type { StyleLedger } from './owned-styles.js';
+import type { ScrollRoot, ScrollScheduler } from './scroll-scheduler.js';
+/**
+ * What a JS-rendered primitive receives.
+ *
+ * v1 handed `prepare` only `{ doc, warn }`, which was enough for effects the browser drove and
+ * nothing else. Pinning, scrubbing, and FLIP all need the scroll position as a number, the
+ * environment's real capabilities, and a way to say "geometry moved" — and every one of those has
+ * to be injected rather than read off a global, or the primitive becomes untestable and each
+ * instance installs its own listeners.
+ *
+ * `params` are validated and defaulted (see `js-params.ts`). A primitive never sees a raw author
+ * string.
+ */
+export interface PrepareContext {
+    doc: Document;
+    win: Window;
+    /** Shared frame source. One listener per scroll root, one rAF per dirtied frame. */
+    scheduler: ScrollScheduler;
+    /** The scroll root that actually moves this element — the window, or a nested scroller. */
+    rootFor(el: Element): ScrollRoot;
+    capabilities: Capabilities;
+    /**
+     * Bump the measurement epoch and schedule a frame. Call after a DOM change the scheduler
+     * cannot observe, such as inserting a pin spacer.
+     */
+    invalidate(): void;
+    warn(message: string): void;
+    /**
+     * Whether the user has asked for reduced motion.
+     *
+     * The animator refuses to activate any effect whose declared policy is `'disable'` when this is
+     * true, so a primitive never has to enforce that itself. It is exposed because effects that
+     * remain interactive under reduced motion — a drag still has to follow the finger — need to
+     * skip only their decorative parts.
+     */
+    reducedMotion: boolean;
+    /** Aborted on teardown, so a primitive can pass it straight to `addEventListener`. */
+    signal: AbortSignal;
+    /**
+     * Ledger for this element's inline style.
+     *
+     * Primitives must write through it rather than touching `element.style` directly. Several were
+     * previously *removing* properties on teardown — `translate`, `scroll-snap-align` — that the
+     * consumer had set themselves and the library never owned.
+     */
+    style: StyleLedger;
+}

package/dist/types/core/element-config.d.ts

@@ -0,0 +1,52 @@
+import type { Activation, ParsedValue, Timeline } from './types.js';
+/** The subset of an element's attributes this module needs. Keeps resolution DOM-free. */
+export interface ElementAttributes {
+    source: string;
+    on: string | null;
+    timeline: string | null;
+    threshold: string | null;
+}
+export interface ElementConfig {
+    activation: Activation;
+    /** Whether the author named an activation, so a primitive default may fill in when not. */
+    activationAuthored: boolean;
+    timeline: Timeline;
+    /** Trailing tokens of `data-kui-timeline`, e.g. `entry 0% cover 60%`. */
+    range: string;
+    threshold: string;
+}
+/**
+ * Read the attributes this module consumes off a live element.
+ *
+ * The only DOM-touching function here, so every downstream decision can be tested with a plain
+ * object instead of a rendered document.
+ *
+ * @param el - Element carrying the authored attributes.
+ * @returns A plain snapshot of the relevant attribute values.
+ * @complexity O(1) time, O(1) space.
+ * @overallScore 100
+ */
+export declare function readAttributes(el: Element): ElementAttributes;
+/**
+ * Resolve element-scoped activation and timeline settings.
+ *
+ * Activation and timeline are element-scoped rather than per-effect because one element has one
+ * activation; values written inline (`on:enter`) are a convenience that takes precedence over the
+ * longhand attribute.
+ *
+ * @param attributes - Snapshot from `readAttributes`.
+ * @param parsed - Result of parsing the `data-kui` value, whose hoisted keys win.
+ * @returns Fully defaulted configuration; unknown values fall back rather than throwing.
+ * @complexity O(k) time in the length of the timeline attribute; O(1) extra space.
+ * @overallScore 100
+ */
+export declare function resolveConfig(attributes: ElementAttributes, parsed: ParsedValue): ElementConfig;
+/**
+ * Convert an IntersectionObserver threshold from `"30%"` or `"0.3"` into a clamped ratio.
+ *
+ * @param raw - Authored threshold value.
+ * @returns A ratio in [0, 1]; unparseable input yields 0 rather than throwing.
+ * @complexity O(1) time, O(1) space.
+ * @overallScore 100
+ */
+export declare function toThresholdRatio(raw: string): number;

package/dist/types/core/flip.d.ts

@@ -0,0 +1,80 @@
+import type { Cleanup } from './types.js';
+/**
+ * FLIP — First, Last, Invert, Play.
+ *
+ * Measure where things are, let the layout change however it likes, measure again, then apply the
+ * inverse transform and animate it away. The layout change itself is never animated, which is why
+ * this works for reordering, filtering, sorting, and expanding: none of those are expressible as
+ * keyframes, but all of them are expressible as two measurements.
+ *
+ * Measurement and animation are both injected. Reading `getBoundingClientRect` directly would make
+ * every consumer untestable without real layout, and jsdom reports zeroes for everything.
+ */
+export interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface FlipSnapshot {
+    boxes: Map<Element, Box>;
+}
+export interface FlipOptions {
+    durationMs?: number;
+    easing?: string;
+    /** Animate width/height differences as a scale. Off for elements with visible borders. */
+    scale?: boolean;
+}
+export interface FlipRun {
+    /** Elements that actually moved. Unmoved elements are skipped, not animated to identity. */
+    moved: Element[];
+    finished: Promise<void>;
+    cancel(): void;
+}
+export interface FlipDeps {
+    measure(el: Element): Box;
+    /** Returns `null` where the Web Animations API is unavailable; the move then applies instantly. */
+    animate(el: Element, keyframes: Keyframe[], options: KeyframeAnimationOptions): Animation | null;
+}
+export interface FlipEngine {
+    snapshot(elements: Iterable<Element>): FlipSnapshot;
+    play(before: FlipSnapshot, elements: Iterable<Element>, options?: FlipOptions): FlipRun;
+}
+/**
+ * Read an element's box from real layout.
+ *
+ * @complexity O(1) time, but forces layout — call once per batch, never per element in a loop.
+ * @overallScore 100
+ */
+export declare function domMeasure(el: Element): Box;
+/**
+ * Create a FLIP engine.
+ *
+ * @param deps - Measurement and animation sources; both default to the DOM implementations.
+ * @returns An engine exposing `snapshot` and `play`.
+ * @complexity O(n) per call in the number of elements; O(n) space for the snapshot.
+ * @overallScore 100
+ */
+export declare function createFlipEngine(deps?: Partial<FlipDeps>): FlipEngine;
+/**
+ * Watch a container and FLIP its children whenever its child list changes.
+ *
+ * This is what turns one engine into the whole layout category: reorder, filter, sort, shuffle,
+ * and grid↔list are all "the children moved", and none of them need to know why.
+ *
+ * @param container - Element whose children are animated.
+ * @param engine - FLIP engine to use.
+ * @param options - Timing and scaling.
+ * @param observe - MutationObserver factory, injected for tests.
+ * @returns Teardown that disconnects the observer.
+ * @complexity O(n) per mutation batch in the number of children.
+ * @overallScore 100
+ */
+export declare function observeLayout(container: Element, engine: FlipEngine, options: FlipOptions, observe: (callback: () => void) => Cleanup): Cleanup;
+/**
+ * MutationObserver-backed layout watcher.
+ *
+ * @complexity O(1) to install; callback cost is the caller's.
+ * @overallScore 100
+ */
+export declare function mutationWatcher(container: Element): (callback: () => void) => Cleanup;

package/dist/types/core/gesture.d.ts

@@ -0,0 +1,99 @@
+import type { Cleanup } from './types.js';
+/**
+ * Pointer gesture recognition.
+ *
+ * Drag, swipe, and long-press are the same stream of pointer events read with different
+ * questions, so they share one recogniser. Velocity is the reason this cannot be a thin wrapper:
+ * a throw needs the speed of the last few milliseconds of movement, not the average over the
+ * whole gesture, and a single trailing sample is far too noisy to use.
+ *
+ * Every input is injected — the event target, the clock, and pointer capture — so the whole
+ * recogniser is drivable from tests with synthetic events and a fake clock.
+ */
+export interface Sample {
+    x: number;
+    y: number;
+    time: number;
+}
+export interface GestureVector {
+    dx: number;
+    dy: number;
+    /** Pixels per second. */
+    vx: number;
+    vy: number;
+}
+export type Axis = 'x' | 'y' | 'both';
+export type Direction = 'left' | 'right' | 'up' | 'down';
+export interface GestureHandlers {
+    onStart?(sample: Sample): void;
+    onMove?(vector: GestureVector, sample: Sample): void;
+    onEnd?(vector: GestureVector, sample: Sample): void;
+    onSwipe?(direction: Direction, vector: GestureVector): void;
+    onLongPress?(sample: Sample): void;
+}
+export interface GestureOptions {
+    /** Movement below this many pixels is a tap, not a drag. */
+    threshold?: number;
+    axis?: Axis;
+    /** Minimum speed, px/s, for a movement to count as a swipe. */
+    swipeVelocity?: number;
+    /** Hold duration in ms before `onLongPress`. Zero disables it. */
+    longPressMs?: number;
+}
+export interface GestureDeps {
+    now(): number;
+    setTimer(callback: () => void, ms: number): number;
+    clearTimer(handle: number): void;
+}
+/**
+ * Estimate velocity from recent samples.
+ *
+ * Uses the oldest sample still inside the window rather than the previous frame: consecutive
+ * pointer events can be microseconds apart, and dividing by that produces enormous, meaningless
+ * speeds that throw an element off screen.
+ *
+ * @param samples - Recent positions, oldest first.
+ * @returns Pixels per second on both axes; zero when the window has no span.
+ * @complexity O(n) time in retained samples; O(1) space.
+ * @overallScore 100
+ */
+export declare function velocityFrom(samples: Sample[]): {
+    vx: number;
+    vy: number;
+};
+/**
+ * Classify a release into a swipe direction.
+ *
+ * @returns The dominant direction, or `null` when neither axis is fast enough.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function swipeDirection(vector: GestureVector, minVelocity: number): Direction | null;
+/**
+ * Recognise drag, swipe, and long-press on an element.
+ *
+ * @param el - Element to observe.
+ * @param handlers - Callbacks for each recognised phase.
+ * @param options - Threshold, axis lock, swipe velocity, long-press duration.
+ * @param deps - Clock and timer source, injected for tests.
+ * @returns Teardown removing every listener and pending timer.
+ * @complexity O(1) per pointer event; O(1) space (samples are capped).
+ * @overallScore 100
+ */
+export declare function recognise(el: Element, handlers: GestureHandlers, options?: GestureOptions, deps?: GestureDeps): Cleanup;
+export declare function defaultGestureDeps(): GestureDeps;
+/**
+ * Apply rubber-band resistance past a boundary.
+ *
+ * Past the edge, movement is damped rather than blocked, so the surface still tracks the finger
+ * but signals that it has run out. Hard-clamping instead feels broken, which is why every native
+ * scroller does this.
+ *
+ * @param offset - Raw offset from the boundary.
+ * @param limit - Distance at which resistance approaches its maximum.
+ * @param tension - 0–1; lower resists harder.
+ * @returns The damped offset.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function rubberBand(offset: number, limit: number, tension?: number): number;