@czap/core 0.1.0

package/dist/signal.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Signal -- live data feeds from the browser environment.
+ *
+ * (viewport, scroll, pointer, time, media queries, custom).
+ *
+ * @module
+ */
+import type { Stream, Scope } from 'effect';
+import { Effect } from 'effect';
+import type { AVBridge } from './av-bridge.js';
+/** Tag of a {@link SignalSource} — the family of live data feed a signal binds to. */
+export type SignalSourceType = 'viewport' | 'time' | 'pointer' | 'scroll' | 'media' | 'custom' | 'audio';
+/**
+ * Configuration describing what a {@link Signal} reads from: viewport axis,
+ * time mode, pointer axis, scroll axis, media query, custom push source,
+ * or audio sample/normalized mode.
+ */
+export type SignalSource = {
+    readonly type: 'viewport';
+    readonly axis: 'width' | 'height';
+} | {
+    readonly type: 'time';
+    readonly mode: 'elapsed' | 'absolute' | 'scheduled';
+} | {
+    readonly type: 'pointer';
+    readonly axis: 'x' | 'y' | 'pressure';
+} | {
+    readonly type: 'scroll';
+    readonly axis: 'x' | 'y' | 'progress';
+} | {
+    readonly type: 'media';
+    readonly query: string;
+} | {
+    readonly type: 'custom';
+    readonly id: string;
+} | {
+    readonly type: 'audio';
+    readonly mode: 'sample' | 'normalized';
+};
+interface SignalShape<T> {
+    readonly source: SignalSource;
+    readonly current: Effect.Effect<T>;
+    readonly changes: Stream.Stream<T>;
+}
+interface ControllableSignalShape<T> extends SignalShape<T> {
+    seek(to: T): Effect.Effect<void>;
+    pause(): Effect.Effect<void>;
+    resume(): Effect.Effect<void>;
+}
+/**
+ * Create a reactive signal from a browser environment source.
+ *
+ * Returns a scoped Effect that sets up event listeners (resize, scroll,
+ * pointermove, etc.) and cleans them up when the scope closes. The signal
+ * exposes `.current` (latest value) and `.changes` (stream of updates).
+ *
+ * @example
+ * ```ts
+ * import { Effect, Scope } from 'effect';
+ * import { Signal } from '@czap/core';
+ *
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const sig = yield* Signal.make({ type: 'viewport', axis: 'width' });
+ *   const width = yield* sig.current;
+ *   // width === current window.innerWidth
+ * }));
+ * ```
+ */
+declare function _make(source: SignalSource): Effect.Effect<SignalShape<number>, never, Scope.Scope>;
+/**
+ * Create a controllable time signal for video rendering / scrubbing.
+ *
+ * External code drives the signal value via seek(); no automatic ticking.
+ * Supports pause/resume to temporarily ignore seek updates.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from 'effect';
+ * import { Signal } from '@czap/core';
+ *
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const ctrl = yield* Signal.controllable();
+ *   yield* ctrl.seek(1500);
+ *   const t = yield* ctrl.current;
+ *   // t === 1500
+ *   yield* ctrl.pause();
+ *   yield* ctrl.seek(2000); // ignored while paused
+ * }));
+ * ```
+ */
+declare function _controllable(): Effect.Effect<ControllableSignalShape<number>, never, Scope.Scope>;
+interface AudioSignalShape extends SignalShape<number> {
+    poll(): Effect.Effect<number>;
+}
+/**
+ * Create an audio signal backed by an AVBridge.
+ *
+ * In 'sample' mode, returns the raw sample index. In 'normalized' mode,
+ * returns a 0..1 progress value based on totalDurationSec. Call `.poll()`
+ * to read the latest sample from the bridge and update the signal.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from 'effect';
+ * import { Signal } from '@czap/core';
+ *
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const audioSig = yield* Signal.audio(bridge, 'normalized', 120);
+ *   const progress = yield* audioSig.poll();
+ *   // progress is a number between 0 and 1
+ * }));
+ * ```
+ */
+declare function _audio(bridge: AVBridge.Shape, mode?: 'sample' | 'normalized', totalDurationSec?: number): Effect.Effect<AudioSignalShape, never, Scope.Scope>;
+/**
+ * Signal namespace -- live data feeds from the browser environment.
+ *
+ * Create reactive signals from viewport, scroll, pointer, time, media query,
+ * audio, or custom sources. Each signal provides `.current` and `.changes`
+ * backed by Effect's SubscriptionRef. Scoped for automatic listener cleanup.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from 'effect';
+ * import { Signal } from '@czap/core';
+ *
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const viewport = yield* Signal.make({ type: 'viewport', axis: 'width' });
+ *   const width = yield* viewport.current;
+ *   const ctrl = yield* Signal.controllable();
+ *   yield* ctrl.seek(500);
+ * }));
+ * ```
+ */
+export declare const Signal: {
+    make: typeof _make;
+    controllable: typeof _controllable;
+    audio: typeof _audio;
+};
+export declare namespace Signal {
+    /** Structural shape of a passive {@link Signal}: `source` + `current` + `changes`. */
+    type Shape<T> = SignalShape<T>;
+    /** Structural shape of a seekable, pausable signal — e.g. driven by Remotion or a scrub UI. */
+    type Controllable<T> = ControllableSignalShape<T>;
+    /** Structural shape of an audio-sourced signal backed by an {@link AVBridge}. */
+    type Audio = AudioSignalShape;
+}
+export {};
+//# sourceMappingURL=signal.d.ts.map

package/dist/signal.d.ts.map

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

package/dist/signal.js

@@ -0,0 +1,277 @@
+/**
+ * Signal -- live data feeds from the browser environment.
+ *
+ * (viewport, scroll, pointer, time, media queries, custom).
+ *
+ * @module
+ */
+import { Effect, SubscriptionRef, Ref } from 'effect';
+function initialValueForSource(source) {
+    switch (source.type) {
+        case 'viewport':
+            return typeof globalThis.window !== 'undefined'
+                ? source.axis === 'width'
+                    ? window.innerWidth
+                    : window.innerHeight
+                : 0;
+        case 'scroll':
+            if (typeof globalThis.window === 'undefined')
+                return 0;
+            if (source.axis === 'x')
+                return window.scrollX;
+            if (source.axis === 'y')
+                return window.scrollY;
+            {
+                const max = document.documentElement.scrollHeight - window.innerHeight;
+                return max > 0 ? window.scrollY / max : 0;
+            }
+        case 'pointer':
+            return 0;
+        case 'time':
+            return source.mode === 'absolute' ? Date.now() : 0;
+        case 'media':
+            return typeof globalThis.window !== 'undefined' && window.matchMedia(source.query).matches ? 1 : 0;
+        case 'custom':
+            return 0;
+        case 'audio':
+            return 0;
+    }
+}
+/**
+ * Create a reactive signal from a browser environment source.
+ *
+ * Returns a scoped Effect that sets up event listeners (resize, scroll,
+ * pointermove, etc.) and cleans them up when the scope closes. The signal
+ * exposes `.current` (latest value) and `.changes` (stream of updates).
+ *
+ * @example
+ * ```ts
+ * import { Effect, Scope } from 'effect';
+ * import { Signal } from '@czap/core';
+ *
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const sig = yield* Signal.make({ type: 'viewport', axis: 'width' });
+ *   const width = yield* sig.current;
+ *   // width === current window.innerWidth
+ * }));
+ * ```
+ */
+function _make(source) {
+    return Effect.gen(function* () {
+        const initial = initialValueForSource(source);
+        const ref = yield* SubscriptionRef.make(initial);
+        const setupListener = Effect.gen(function* () {
+            switch (source.type) {
+                case 'viewport': {
+                    if (typeof globalThis.window === 'undefined')
+                        return;
+                    const handler = () => {
+                        const val = source.axis === 'width' ? window.innerWidth : window.innerHeight;
+                        Effect.runSync(SubscriptionRef.set(ref, val));
+                    };
+                    yield* Effect.acquireRelease(Effect.sync(() => {
+                        window.addEventListener('resize', handler);
+                    }), () => Effect.sync(() => {
+                        window.removeEventListener('resize', handler);
+                    }));
+                    break;
+                }
+                case 'scroll': {
+                    if (typeof globalThis.window === 'undefined')
+                        return;
+                    const handler = () => {
+                        let val;
+                        if (source.axis === 'x')
+                            val = window.scrollX;
+                        else if (source.axis === 'y')
+                            val = window.scrollY;
+                        else {
+                            const max = document.documentElement.scrollHeight - window.innerHeight;
+                            val = max > 0 ? window.scrollY / max : 0;
+                        }
+                        Effect.runSync(SubscriptionRef.set(ref, val));
+                    };
+                    yield* Effect.acquireRelease(Effect.sync(() => {
+                        window.addEventListener('scroll', handler, { passive: true });
+                    }), () => Effect.sync(() => {
+                        window.removeEventListener('scroll', handler);
+                    }));
+                    break;
+                }
+                case 'pointer': {
+                    if (typeof globalThis.window === 'undefined')
+                        return;
+                    const handler = (e) => {
+                        const val = source.axis === 'x' ? e.clientX : source.axis === 'y' ? e.clientY : e.pressure;
+                        Effect.runSync(SubscriptionRef.set(ref, val));
+                    };
+                    yield* Effect.acquireRelease(Effect.sync(() => {
+                        window.addEventListener('pointermove', handler);
+                    }), () => Effect.sync(() => {
+                        window.removeEventListener('pointermove', handler);
+                    }));
+                    break;
+                }
+                case 'time': {
+                    if (source.mode === 'elapsed') {
+                        if (typeof requestAnimationFrame === 'undefined')
+                            return;
+                        const start = Date.now();
+                        const id = { current: 0 };
+                        const tick = () => {
+                            Effect.runSync(SubscriptionRef.set(ref, Date.now() - start));
+                            id.current = requestAnimationFrame(tick);
+                        };
+                        id.current = requestAnimationFrame(tick);
+                        yield* Effect.addFinalizer(() => Effect.sync(() => cancelAnimationFrame(id.current)));
+                    }
+                    else if (source.mode === 'absolute') {
+                        const id = setInterval(() => {
+                            Effect.runSync(SubscriptionRef.set(ref, Date.now()));
+                        }, 1000);
+                        yield* Effect.addFinalizer(() => Effect.sync(() => clearInterval(id)));
+                    }
+                    else {
+                        // Scheduled mode: no automatic ticking.
+                        // External code drives this signal via SubscriptionRef.set(ref, value).
+                        // The ref is already created -- caller controls it via ControllableSignal.
+                    }
+                    break;
+                }
+                case 'media': {
+                    if (typeof globalThis.window === 'undefined')
+                        return;
+                    const mql = window.matchMedia(source.query);
+                    const handler = (e) => {
+                        Effect.runSync(SubscriptionRef.set(ref, e.matches ? 1 : 0));
+                    };
+                    yield* Effect.acquireRelease(Effect.sync(() => {
+                        mql.addEventListener('change', handler);
+                    }), () => Effect.sync(() => {
+                        mql.removeEventListener('change', handler);
+                    }));
+                    break;
+                }
+                case 'custom':
+                    // Custom signals are driven externally via Signal.custom() push API.
+                    // No browser listener needed — the caller pushes values directly.
+                    break;
+                case 'audio':
+                    // Audio signals are driven externally via Signal.audio() / AVBridge.
+                    // No browser listener needed — audio analysis pushes values on its own cadence.
+                    break;
+            }
+        });
+        yield* Effect.forkScoped(setupListener);
+        return {
+            source,
+            current: SubscriptionRef.get(ref),
+            changes: SubscriptionRef.changes(ref),
+        };
+    });
+}
+/**
+ * Create a controllable time signal for video rendering / scrubbing.
+ *
+ * External code drives the signal value via seek(); no automatic ticking.
+ * Supports pause/resume to temporarily ignore seek updates.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from 'effect';
+ * import { Signal } from '@czap/core';
+ *
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const ctrl = yield* Signal.controllable();
+ *   yield* ctrl.seek(1500);
+ *   const t = yield* ctrl.current;
+ *   // t === 1500
+ *   yield* ctrl.pause();
+ *   yield* ctrl.seek(2000); // ignored while paused
+ * }));
+ * ```
+ */
+function _controllable() {
+    return Effect.gen(function* () {
+        const ref = yield* SubscriptionRef.make(0);
+        const pausedRef = yield* Ref.make(false);
+        return {
+            source: { type: 'time', mode: 'scheduled' },
+            current: SubscriptionRef.get(ref),
+            changes: SubscriptionRef.changes(ref),
+            seek: (to) => Effect.gen(function* () {
+                const paused = yield* Ref.get(pausedRef);
+                if (!paused) {
+                    yield* SubscriptionRef.set(ref, to);
+                }
+            }),
+            pause: () => Ref.set(pausedRef, true),
+            resume: () => Ref.set(pausedRef, false),
+        };
+    });
+}
+/**
+ * Create an audio signal backed by an AVBridge.
+ *
+ * In 'sample' mode, returns the raw sample index. In 'normalized' mode,
+ * returns a 0..1 progress value based on totalDurationSec. Call `.poll()`
+ * to read the latest sample from the bridge and update the signal.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from 'effect';
+ * import { Signal } from '@czap/core';
+ *
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const audioSig = yield* Signal.audio(bridge, 'normalized', 120);
+ *   const progress = yield* audioSig.poll();
+ *   // progress is a number between 0 and 1
+ * }));
+ * ```
+ */
+function _audio(bridge, mode = 'sample', totalDurationSec) {
+    return Effect.gen(function* () {
+        const ref = yield* SubscriptionRef.make(0);
+        const poll = () => Effect.gen(function* () {
+            const sample = bridge.getCurrentSample();
+            let value;
+            if (mode === 'normalized' && totalDurationSec !== undefined && totalDurationSec > 0) {
+                const totalSamples = totalDurationSec * bridge.sampleRate;
+                value = Math.min(sample / totalSamples, 1);
+            }
+            else {
+                value = sample;
+            }
+            yield* SubscriptionRef.set(ref, value);
+            return value;
+        });
+        return {
+            source: { type: 'audio', mode },
+            current: SubscriptionRef.get(ref),
+            changes: SubscriptionRef.changes(ref),
+            poll: () => poll(),
+        };
+    });
+}
+/**
+ * Signal namespace -- live data feeds from the browser environment.
+ *
+ * Create reactive signals from viewport, scroll, pointer, time, media query,
+ * audio, or custom sources. Each signal provides `.current` and `.changes`
+ * backed by Effect's SubscriptionRef. Scoped for automatic listener cleanup.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from 'effect';
+ * import { Signal } from '@czap/core';
+ *
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const viewport = yield* Signal.make({ type: 'viewport', axis: 'width' });
+ *   const width = yield* viewport.current;
+ *   const ctrl = yield* Signal.controllable();
+ *   yield* ctrl.seek(500);
+ * }));
+ * ```
+ */
+export const Signal = { make: _make, controllable: _controllable, audio: _audio };
+//# sourceMappingURL=signal.js.map

package/dist/signal.js.map

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

package/dist/speculative.d.ts

@@ -0,0 +1,67 @@
+/**
+ * SpeculativeEvaluator -- threshold proximity prefetching.
+ *
+ * When a boundary signal is near a threshold, pre-compute the next state.
+ * Uses hysteresis dead zone as the prefetch window and linear extrapolation
+ * from velocity (last 3-4 signal values) to predict crossings.
+ *
+ * Wrong prediction cost: ~80ns to recompute (negligible).
+ *
+ * @module
+ */
+import { Boundary } from './boundary.js';
+import type { StateUnion } from './type-utils.js';
+interface SpeculativeResult<B extends Boundary.Shape> {
+    readonly current: StateUnion<B>;
+    readonly prefetched?: StateUnion<B>;
+    readonly confidence: number;
+}
+interface SpeculativeEvaluatorShape<B extends Boundary.Shape> {
+    evaluate(value: number, velocity?: number): SpeculativeResult<B>;
+}
+/**
+ * Creates a speculative evaluator for a boundary that prefetches the next state
+ * when the signal value is near a threshold and moving toward it.
+ *
+ * @example
+ * ```ts
+ * const boundary = Boundary.make({
+ *   thresholds: [768, 1024],
+ *   states: ['mobile', 'tablet', 'desktop'] as const,
+ *   hysteresis: 20,
+ * });
+ * const spec = SpeculativeEvaluator.make(boundary);
+ * const result = spec.evaluate(760, 2.0); // approaching 768 threshold
+ * result.current;     // 'mobile'
+ * result.prefetched;  // 'tablet' (pre-computed)
+ * result.confidence;  // 0.0-1.0 likelihood of crossing
+ * ```
+ */
+declare function _make<B extends Boundary.Shape>(boundary: B): SpeculativeEvaluatorShape<B>;
+/**
+ * SpeculativeEvaluator -- threshold proximity prefetching for boundaries.
+ * Pre-computes the next discrete state when a signal is near a threshold,
+ * using velocity estimation and hysteresis-based prefetch windows.
+ *
+ * @example
+ * ```ts
+ * const boundary = Boundary.make({
+ *   thresholds: [600],
+ *   states: ['small', 'large'] as const,
+ * });
+ * const spec = SpeculativeEvaluator.make(boundary);
+ * const { current, prefetched, confidence } = spec.evaluate(595, 1.5);
+ * // current='small', prefetched='large', confidence ~0.85
+ * ```
+ */
+export declare const SpeculativeEvaluator: {
+    make: typeof _make;
+};
+export declare namespace SpeculativeEvaluator {
+    /** Structural shape of an evaluator bound to a specific {@link Boundary}. */
+    type Shape<B extends Boundary.Shape> = SpeculativeEvaluatorShape<B>;
+    /** Prediction result from `evaluate()` — current state, optional prefetched next state, and confidence. */
+    type Result<B extends Boundary.Shape> = SpeculativeResult<B>;
+}
+export {};
+//# sourceMappingURL=speculative.d.ts.map

package/dist/speculative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speculative.d.ts","sourceRoot":"","sources":["../src/speculative.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIlD,UAAU,iBAAiB,CAAC,CAAC,SAAS,QAAQ,CAAC,KAAK;IAClD,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,UAAU,yBAAyB,CAAC,CAAC,SAAS,QAAQ,CAAC,KAAK;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC;CAClE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAS,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,GAAG,yBAAyB,CAAC,CAAC,CAAC,CAmHlF;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oBAAoB;;CAAkB,CAAC;AAEpD,MAAM,CAAC,OAAO,WAAW,oBAAoB,CAAC;IAC5C,6EAA6E;IAC7E,KAAY,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,KAAK,IAAI,yBAAyB,CAAC,CAAC,CAAC,CAAC;IAC3E,2GAA2G;IAC3G,KAAY,MAAM,CAAC,CAAC,SAAS,QAAQ,CAAC,KAAK,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAC;CACrE"}

package/dist/speculative.js

@@ -0,0 +1,139 @@
+/**
+ * SpeculativeEvaluator -- threshold proximity prefetching.
+ *
+ * When a boundary signal is near a threshold, pre-compute the next state.
+ * Uses hysteresis dead zone as the prefetch window and linear extrapolation
+ * from velocity (last 3-4 signal values) to predict crossings.
+ *
+ * Wrong prediction cost: ~80ns to recompute (negligible).
+ *
+ * @module
+ */
+import { Boundary } from './boundary.js';
+/**
+ * Creates a speculative evaluator for a boundary that prefetches the next state
+ * when the signal value is near a threshold and moving toward it.
+ *
+ * @example
+ * ```ts
+ * const boundary = Boundary.make({
+ *   thresholds: [768, 1024],
+ *   states: ['mobile', 'tablet', 'desktop'] as const,
+ *   hysteresis: 20,
+ * });
+ * const spec = SpeculativeEvaluator.make(boundary);
+ * const result = spec.evaluate(760, 2.0); // approaching 768 threshold
+ * result.current;     // 'mobile'
+ * result.prefetched;  // 'tablet' (pre-computed)
+ * result.confidence;  // 0.0-1.0 likelihood of crossing
+ * ```
+ */
+function _make(boundary) {
+    const thresholds = boundary.thresholds;
+    const hysteresis = boundary.hysteresis ?? 0;
+    const prefetchWindow = Math.max(hysteresis, 1); // Use hysteresis as window, min 1
+    // Compute epsilon from boundary scale rather than hardcoded constant
+    const minGap = thresholds.length >= 2
+        ? Math.min(...Array.from({ length: thresholds.length - 1 }, (_, i) => thresholds[i + 1] - thresholds[i]))
+        : 1;
+    const epsilon = Math.min(minGap * 0.001, hysteresis > 0 ? hysteresis * 0.01 : 0.001);
+    // Velocity estimation ring buffer (last 2 values)
+    const history = [];
+    // 2-sample velocity estimation buffer — gives instant responsiveness
+    const HISTORY_SIZE = 2;
+    // Boundary.make guarantees states is non-empty (readonly [string, ...string[]]).
+    let previousState = boundary.states[0];
+    // Simple finite difference (not least-squares) — 2-sample gives instant responsiveness
+    // for UI prefetch.
+    function estimateVelocity(currentValue, explicitVelocity) {
+        if (explicitVelocity !== undefined)
+            return explicitVelocity;
+        if (history.length < 2)
+            return 0;
+        // Linear regression over recent samples
+        const last = history[history.length - 1];
+        const prev = history[history.length - 2];
+        const dt = last.time - prev.time;
+        if (dt <= 0)
+            return 0;
+        return (last.value - prev.value) / dt;
+    }
+    function findNearestThreshold(value) {
+        let nearest = null;
+        for (const t of thresholds) {
+            const dist = Math.abs(value - t);
+            if (nearest === null || dist < nearest.distance) {
+                nearest = {
+                    threshold: t,
+                    distance: dist,
+                    direction: value < t ? 'up' : 'down',
+                };
+            }
+        }
+        return nearest;
+    }
+    return {
+        evaluate(value, velocity) {
+            const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+            history.push({ value, time: now });
+            if (history.length > HISTORY_SIZE)
+                history.shift();
+            // Evaluate current state
+            const current = boundary.hysteresis
+                ? Boundary.evaluateWithHysteresis(boundary, value, previousState)
+                : Boundary.evaluate(boundary, value);
+            previousState = current;
+            // Find nearest threshold
+            const nearest = findNearestThreshold(value);
+            if (!nearest) {
+                return { current, confidence: 0 };
+            }
+            const vel = estimateVelocity(value, velocity);
+            // Check if moving toward the threshold
+            const movingToward = (nearest.direction === 'up' && vel > 0) || (nearest.direction === 'down' && vel < 0);
+            if (!movingToward || nearest.distance > prefetchWindow) {
+                return { current, confidence: 0 };
+            }
+            // Compute confidence: closer to threshold + faster velocity = higher confidence
+            const distanceFactor = 1 - nearest.distance / prefetchWindow;
+            // Distance weighted 70%, velocity 30% — distance is more reliable for prefetch confidence
+            const velocityFactor = Math.min(Math.abs(vel) * 10, 1); // Normalize velocity contribution
+            const confidence = distanceFactor * 0.7 + velocityFactor * 0.3;
+            // Below 30% confidence, skip prefetch — not worth the speculative cost
+            if (confidence < 0.3) {
+                return { current, confidence };
+            }
+            // Pre-compute the predicted next state (jump past hysteresis zone if present)
+            const hysteresisJump = boundary.hysteresis ?? 0;
+            const predictedValue = nearest.direction === 'up'
+                ? nearest.threshold + hysteresisJump + epsilon
+                : nearest.threshold - hysteresisJump - epsilon;
+            const prefetched = boundary.hysteresis
+                ? Boundary.evaluateWithHysteresis(boundary, predictedValue, current)
+                : Boundary.evaluate(boundary, predictedValue);
+            // Only return prefetch if it's actually different
+            if (prefetched === current) {
+                return { current, confidence: 0 };
+            }
+            return { current, prefetched, confidence };
+        },
+    };
+}
+/**
+ * SpeculativeEvaluator -- threshold proximity prefetching for boundaries.
+ * Pre-computes the next discrete state when a signal is near a threshold,
+ * using velocity estimation and hysteresis-based prefetch windows.
+ *
+ * @example
+ * ```ts
+ * const boundary = Boundary.make({
+ *   thresholds: [600],
+ *   states: ['small', 'large'] as const,
+ * });
+ * const spec = SpeculativeEvaluator.make(boundary);
+ * const { current, prefetched, confidence } = spec.evaluate(595, 1.5);
+ * // current='small', prefetched='large', confidence ~0.85
+ * ```
+ */
+export const SpeculativeEvaluator = { make: _make };
+//# sourceMappingURL=speculative.js.map

package/dist/speculative.js.map

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