@czap/quantizer 0.1.0

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/testing.js

@@ -0,0 +1,15 @@
+/**
+ * Test-only entrypoint for `@czap/quantizer`. Imported as
+ * `@czap/quantizer/testing`.
+ *
+ * `MemoCache` and `TIER_TARGETS` are implementation primitives that
+ * power the public `Q.from()` builder internally. Consumers don't need
+ * direct access; tests do (for content-address cache assertions and
+ * tier-gating verification). Partitioning them off the main entry keeps
+ * the public surface focused on the builder.
+ *
+ * @module
+ */
+export { MemoCache } from './memo-cache.js';
+export { TIER_TARGETS } from './quantizer.js';
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/transition.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Transition configuration for state crossings.
+ * Maps `from->to` state pairs to duration/easing/delay configs.
+ *
+ * @module
+ */
+import type { Boundary, StateUnion, Quantizer, Easing, Millis } from '@czap/core';
+/**
+ * Per-transition animation parameters.
+ *
+ * Used by {@link AnimatedQuantizer} to drive interpolation between two
+ * state output records. `duration` of `0` produces an instantaneous snap.
+ */
+export interface TransitionConfig {
+    /** Animation duration in milliseconds (branded via {@link Millis}). */
+    readonly duration: Millis;
+    /** Easing function applied to progress; defaults to linear. */
+    readonly easing?: Easing.Fn;
+    /** Delay before the animation begins, in milliseconds. */
+    readonly delay?: Millis;
+}
+/**
+ * State-transition map keyed by `"from->to"` literal or `"*"` wildcard.
+ *
+ * Lookup resolves exact keys first, then the wildcard, then falls back to
+ * an instantaneous transition (duration: 0).
+ */
+export interface TransitionMap<_S extends string = string> {
+    /** Wildcard fallback applied when no exact `from->to` key matches. */
+    readonly '*'?: TransitionConfig;
+    /** Exact `"from->to"` transition key. */
+    readonly [key: `${string}->${string}`]: TransitionConfig;
+}
+/**
+ * Resolver that maps a boundary crossing to its {@link TransitionConfig}.
+ *
+ * Produced by {@link Transition.for}; consumed by {@link AnimatedQuantizer}
+ * during animation loop setup.
+ */
+export interface Transition<B extends Boundary.Shape> {
+    /** The raw transition map used to create this resolver. */
+    readonly config: TransitionMap<StateUnion<B> & string>;
+    /** Resolve the transition config for a specific `from -> to` state pair. */
+    getTransition(from: StateUnion<B>, to: StateUnion<B>): TransitionConfig;
+}
+/**
+ * Build a Transition resolver for a given quantizer and transition map.
+ *
+ * Resolution order:
+ *   1. Exact match: `"stateA->stateB"`
+ *   2. Wildcard: `"*"`
+ *   3. Fallback: instant transition (duration: 0)
+ */
+declare function createTransition<B extends Boundary.Shape>(_quantizer: Quantizer<B>, transitionConfig: TransitionMap<StateUnion<B> & string>): Transition<B>;
+/**
+ * Transition resolver namespace.
+ *
+ * `Transition.for(quantizer, map)` produces a {@link Transition} that looks
+ * up animation parameters by `from->to` state pairs. Consumed by
+ * {@link AnimatedQuantizer} for interpolation setup.
+ */
+export declare const Transition: {
+    /** Build a {@link Transition} resolver for the given quantizer and transition map. */
+    readonly for: typeof createTransition;
+};
+export {};
+//# sourceMappingURL=transition.d.ts.map

package/dist/transition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition.d.ts","sourceRoot":"","sources":["../src/transition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGlF;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM;IACvD,sEAAsE;IACtE,QAAQ,CAAC,GAAG,CAAC,EAAE,gBAAgB,CAAC;IAChC,yCAAyC;IACzC,QAAQ,EAAE,GAAG,EAAE,GAAG,MAAM,KAAK,MAAM,EAAE,GAAG,gBAAgB,CAAC;CAC1D;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,QAAQ,CAAC,KAAK;IAClD,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;IACvD,4EAA4E;IAC5E,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC;CACzE;AAMD;;;;;;;GAOG;AACH,iBAAS,gBAAgB,CAAC,CAAC,SAAS,QAAQ,CAAC,KAAK,EAChD,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,EACxB,gBAAgB,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,GACtD,UAAU,CAAC,CAAC,CAAC,CAkBf;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU;IACrB,sFAAsF;;CAE9E,CAAC"}

package/dist/transition.js

@@ -0,0 +1,49 @@
+/**
+ * Transition configuration for state crossings.
+ * Maps `from->to` state pairs to duration/easing/delay configs.
+ *
+ * @module
+ */
+import { Millis as mkMillis } from '@czap/core';
+const DEFAULT_TRANSITION = {
+    duration: mkMillis(0),
+};
+/**
+ * Build a Transition resolver for a given quantizer and transition map.
+ *
+ * Resolution order:
+ *   1. Exact match: `"stateA->stateB"`
+ *   2. Wildcard: `"*"`
+ *   3. Fallback: instant transition (duration: 0)
+ */
+function createTransition(_quantizer, transitionConfig) {
+    return {
+        config: transitionConfig,
+        getTransition(from, to) {
+            // Exact match first. The key is typed as the template-literal pattern
+            // declared on TransitionMap, so we can index directly.
+            const exactKey = `${from}->${to}`;
+            const exact = transitionConfig[exactKey];
+            if (exact !== undefined)
+                return exact;
+            // Wildcard fallback
+            const wildcard = transitionConfig['*'];
+            if (wildcard !== undefined)
+                return wildcard;
+            // No transition configured -- instant
+            return DEFAULT_TRANSITION;
+        },
+    };
+}
+/**
+ * Transition resolver namespace.
+ *
+ * `Transition.for(quantizer, map)` produces a {@link Transition} that looks
+ * up animation parameters by `from->to` state pairs. Consumed by
+ * {@link AnimatedQuantizer} for interpolation setup.
+ */
+export const Transition = {
+    /** Build a {@link Transition} resolver for the given quantizer and transition map. */
+    for: createTransition,
+};
+//# sourceMappingURL=transition.js.map

package/dist/transition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition.js","sourceRoot":"","sources":["../src/transition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,MAAM,IAAI,QAAQ,EAAE,MAAM,YAAY,CAAC;AA2ChD,MAAM,kBAAkB,GAAqB;IAC3C,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;CACtB,CAAC;AAEF;;;;;;;GAOG;AACH,SAAS,gBAAgB,CACvB,UAAwB,EACxB,gBAAuD;IAEvD,OAAO;QACL,MAAM,EAAE,gBAAgB;QACxB,aAAa,CAAC,IAAmB,EAAE,EAAiB;YAClD,sEAAsE;YACtE,uDAAuD;YACvD,MAAM,QAAQ,GAAG,GAAG,IAAc,KAAK,EAAY,EAAW,CAAC;YAC/D,MAAM,KAAK,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;YACzC,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,KAAK,CAAC;YAEtC,oBAAoB;YACpB,MAAM,QAAQ,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;YACvC,IAAI,QAAQ,KAAK,SAAS;gBAAE,OAAO,QAAQ,CAAC;YAE5C,sCAAsC;YACtC,OAAO,kBAAkB,CAAC;QAC5B,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,sFAAsF;IACtF,GAAG,EAAE,gBAAgB;CACb,CAAC"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@czap/quantizer",
+  "version": "0.1.0",
+  "description": "Boundary quantizer with animated transitions",
+  "license": "MIT",
+  "author": "Eassa Ayoub <eassa@heyoub.dev>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heyoub/LiteShip",
+    "directory": "packages/quantizer"
+  },
+  "bugs": "https://github.com/heyoub/LiteShip/issues",
+  "homepage": "https://github.com/heyoub/LiteShip#readme",
+  "keywords": [
+    "czap",
+    "quantizer",
+    "boundary",
+    "state-machine",
+    "adaptive-rendering",
+    "typescript"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "development": "./src/index.ts"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "development": "./src/testing.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@czap/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "effect": ">=4.0.0-beta.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/src/animated-quantizer.ts

@@ -0,0 +1,272 @@
+/**
+ * AnimatedQuantizer -- wraps a Quantizer with Transitions.
+ * On boundary crossing, interpolates between old and new output values
+ * over the configured transition duration/easing.
+ */
+
+import type { Scope } from 'effect';
+import { Effect, Stream, SubscriptionRef, Queue, Fiber, Ref, Duration } from 'effect';
+import type { Boundary, StateUnion, BoundaryCrossing, Quantizer, Easing } from '@czap/core';
+import type { Transition, TransitionMap } from './transition.js';
+import { Transition as TransitionFactory } from './transition.js';
+
+// ---------------------------------------------------------------------------
+// Animated quantizer interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Quantizer augmented with transition-aware output interpolation.
+ *
+ * The `interpolated` stream emits a frame on each animation tick containing
+ * the target state, normalized progress (0-1), and the current lerped
+ * output record. Non-numeric values snap at the 50% mark.
+ */
+export interface AnimatedQuantizerShape<B extends Boundary.Shape> extends Quantizer<B> {
+  /** Resolver that maps `from -> to` crossings to {@link TransitionConfig}. */
+  readonly transition: Transition<B>;
+  /** Stream of interpolated animation frames during crossings. */
+  readonly interpolated: Stream.Stream<{
+    /** Target state of the in-flight transition. */
+    readonly state: StateUnion<B>;
+    /** Progress in `[0, 1]`, where `1` means the animation has landed. */
+    readonly progress: number;
+    /** Interpolated output record for the current frame. */
+    readonly outputs: Record<string, number | string>;
+  }>;
+}
+
+// ---------------------------------------------------------------------------
+// Linear easing fallback
+// ---------------------------------------------------------------------------
+
+const linearEasing: Easing.Fn = (t: number) => t;
+
+// ---------------------------------------------------------------------------
+// Interpolate numeric values between two output records
+// ---------------------------------------------------------------------------
+
+function lerpOutputs(
+  from: Record<string, number | string>,
+  to: Record<string, number | string>,
+  t: number,
+): Record<string, number | string> {
+  const result: Record<string, number | string> = {};
+  const allKeys = new Set([...Object.keys(from), ...Object.keys(to)]);
+  for (const key of allKeys) {
+    const a = from[key];
+    const b = to[key];
+    if (typeof a === 'number' && typeof b === 'number') {
+      result[key] = a + (b - a) * t;
+    } else {
+      // Non-numeric values snap to target at progress >= 0.5
+      result[key] = (t < 0.5 ? (a ?? b) : (b ?? a)) as number | string;
+    }
+  }
+  return result;
+}
+
+function nowMs(): number {
+  // performance.now() is standard in browsers and Node ≥ 16.
+  // Optional chaining guards against stripped worker/SSR environments.
+  if (typeof globalThis.performance?.now === 'function') {
+    return globalThis.performance.now();
+  }
+  return Date.now();
+}
+
+// ---------------------------------------------------------------------------
+// Factory (internal impl)
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an animated quantizer that interpolates outputs during transitions.
+ *
+ * Wraps an existing {@link Quantizer} and applies easing/duration-based
+ * interpolation between old and new output values when a boundary crossing
+ * occurs. Produces an `interpolated` stream of frames with progress and
+ * lerped numeric outputs at ~60fps.
+ *
+ * @example
+ * ```ts
+ * import { Boundary } from '@czap/core';
+ * import { Q, AnimatedQuantizer } from '@czap/quantizer';
+ * import { Effect, Stream } from 'effect';
+ *
+ * const boundary = Boundary.make({
+ *   input: 'scroll', states: ['top', 'bottom'] as const,
+ *   thresholds: [0, 500],
+ * });
+ * const config = Q.from(boundary).outputs({
+ *   css: { top: { opacity: '1' }, bottom: { opacity: '0.5' } },
+ * });
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const live = yield* config.create();
+ *   const animated = yield* AnimatedQuantizer.make(
+ *     live,
+ *     { '*->*': { duration: 300 } },
+ *     { top: { opacity: 1 }, bottom: { opacity: 0.5 } },
+ *   );
+ *   live.evaluate(600); // triggers interpolation
+ *   return animated;
+ * }));
+ * ```
+ *
+ * @param quantizer   - The base quantizer to wrap
+ * @param transitions - Map of state transition configs keyed by `from->to` pattern
+ * @param outputs     - Per-state numeric output maps for interpolation
+ * @returns An Effect yielding an {@link AnimatedQuantizerShape} (scoped)
+ */
+function makeAnimatedQuantizer<B extends Boundary.Shape>(
+  quantizer: Quantizer<B>,
+  transitions: TransitionMap<StateUnion<B> & string>,
+  outputs?: Record<string, Record<string, number | string>>,
+): Effect.Effect<AnimatedQuantizerShape<B>, never, Scope.Scope> {
+  return Effect.gen(function* () {
+    const boundary = quantizer.boundary;
+    const transitionResolver = TransitionFactory.for(quantizer, transitions);
+
+    const initialState: StateUnion<B> = yield* quantizer.state;
+    const stateRef = yield* SubscriptionRef.make<StateUnion<B>>(initialState);
+
+    type InterpolatedFrame = {
+      readonly state: StateUnion<B>;
+      readonly progress: number;
+      readonly outputs: Record<string, number | string>;
+    };
+
+    const currentOutputsRef = yield* Ref.make<Record<string, number | string>>(outputs?.[initialState as string] ?? {});
+    const currentFiberRef = yield* Ref.make<Fiber.Fiber<void> | null>(null);
+
+    const interpolatedStream: Stream.Stream<InterpolatedFrame> = Stream.callback<InterpolatedFrame>((queue) =>
+      Effect.gen(function* () {
+        yield* Effect.addFinalizer(() =>
+          Effect.gen(function* () {
+            const currentFiber = yield* Ref.get(currentFiberRef);
+            if (currentFiber !== null) {
+              yield* Fiber.interrupt(currentFiber);
+            }
+          }),
+        );
+
+        yield* Stream.runForEach(quantizer.changes, (crossing: BoundaryCrossing<StateUnion<B> & string>) =>
+          Effect.gen(function* () {
+            const existingFiber = yield* Ref.get(currentFiberRef);
+            if (existingFiber !== null) {
+              yield* Fiber.interrupt(existingFiber);
+            }
+
+            // crossing.from/to are StateName<StateUnion<B> & string>, which is a branded
+            // subtype of StateUnion<B>; assignable directly without a cast.
+            const { from, to } = crossing;
+            const config = transitionResolver.getTransition(from, to);
+            const duration = config.duration;
+            const easing = config.easing ?? linearEasing;
+            const delay = config.delay ?? 0;
+
+            const fromOutputs = { ...(yield* Ref.get(currentOutputsRef)) };
+            const toOutputs: Record<string, number | string> = outputs?.[crossing.to as string] ?? {};
+
+            const animationLoop = Effect.gen(function* () {
+              if (delay > 0) {
+                yield* Effect.sleep(Duration.millis(delay));
+              }
+
+              if (duration <= 0) {
+                Queue.offerUnsafe(queue, { state: to, progress: 1, outputs: toOutputs });
+                yield* Ref.set(currentOutputsRef, toOutputs);
+                yield* SubscriptionRef.set(stateRef, to);
+                return;
+              }
+
+              // Time-sliced animation loop (~60fps via 16ms sleep)
+              const startTime = nowMs();
+              let progress = 0;
+              while (progress < 1) {
+                const elapsed = nowMs() - startTime;
+                progress = Math.min(elapsed / duration, 1);
+                const eased = easing(progress);
+                const interpolated = lerpOutputs(fromOutputs, toOutputs, eased);
+                yield* Ref.set(currentOutputsRef, interpolated);
+                Queue.offerUnsafe(queue, { state: to, progress, outputs: interpolated });
+
+                if (progress < 1) {
+                  yield* Effect.sleep(Duration.millis(16));
+                }
+              }
+
+              yield* Ref.set(currentOutputsRef, toOutputs);
+              yield* SubscriptionRef.set(stateRef, to);
+            });
+
+            const fiber = yield* Effect.forkChild(animationLoop);
+            yield* Ref.set(currentFiberRef, fiber);
+          }),
+        );
+
+        const finalFiber = yield* Ref.get(currentFiberRef);
+        const fibers = [finalFiber].filter((fiber): fiber is Fiber.Fiber<void> => fiber !== null);
+        yield* Effect.forEach(fibers, Fiber.join, { discard: true });
+        yield* Ref.set(currentFiberRef, null);
+      }),
+    );
+
+    const animatedQuantizer: AnimatedQuantizerShape<B> = {
+      _tag: 'Quantizer',
+      boundary,
+      transition: transitionResolver,
+      state: SubscriptionRef.get(stateRef),
+      stateSync: quantizer.stateSync ? () => quantizer.stateSync!() : undefined,
+      changes: quantizer.changes,
+      evaluate(value: number): StateUnion<B> {
+        return quantizer.evaluate(value);
+      },
+      interpolated: interpolatedStream,
+    };
+
+    return animatedQuantizer;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// AnimatedQuantizer module object
+// ---------------------------------------------------------------------------
+
+/**
+ * Animated quantizer namespace.
+ *
+ * Wraps a base quantizer with transition-aware interpolation. When a boundary
+ * crossing occurs, numeric output values are lerped over a configurable
+ * duration and easing curve. Non-numeric values snap at the 50% mark.
+ * The `interpolated` stream emits frames containing progress (0-1) and
+ * the current interpolated output record.
+ *
+ * @example
+ * ```ts
+ * import { Boundary } from '@czap/core';
+ * import { Q, AnimatedQuantizer } from '@czap/quantizer';
+ * import { Effect } from 'effect';
+ *
+ * const boundary = Boundary.make({
+ *   input: 'scroll', states: ['top', 'bottom'] as const,
+ *   thresholds: [0, 500],
+ * });
+ * const config = Q.from(boundary).outputs({});
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const live = yield* config.create();
+ *   const animated = yield* AnimatedQuantizer.make(
+ *     live,
+ *     { '*->*': { duration: 200 } },
+ *   );
+ *   return animated.transition; // TransitionResolver
+ * }));
+ * ```
+ */
+export const AnimatedQuantizer = {
+  /** Wrap a quantizer with transition-aware output interpolation. */
+  make: makeAnimatedQuantizer,
+} as const;
+
+export declare namespace AnimatedQuantizer {
+  /** Shape of an animated quantizer parameterized by boundary `B`. */
+  export type Shape<B extends Boundary.Shape> = AnimatedQuantizerShape<B>;
+}

package/src/evaluate.ts

@@ -0,0 +1,160 @@
+/**
+ * Binary search evaluation of a value against boundary thresholds.
+ * Supports hysteresis to prevent state jitter at threshold edges.
+ */
+
+import type { Boundary, StateUnion } from '@czap/core';
+
+/**
+ * Result of quantizing a single numeric value against a boundary.
+ *
+ * `crossed` is true only when `previousState` was supplied and differs
+ * from the resolved state; it is the signal consumers use to emit
+ * transition events and route side effects.
+ */
+export interface EvaluateResult<S extends string = string> {
+  /** The resolved state literal. */
+  readonly state: S;
+  /** Index of `state` within the boundary's states tuple. */
+  readonly index: number;
+  /** The input value that was evaluated. */
+  readonly value: number;
+  /** Whether evaluation produced a change from `previousState`. */
+  readonly crossed: boolean;
+}
+
+/**
+ * Find which state a value maps to via binary search over sorted thresholds.
+ * With hysteresis: if previousState is provided and the value is within the
+ * hysteresis dead zone of a threshold, transition is suppressed.
+ *
+ * BoundaryDef contract: `thresholds[i]` = lower bound of `states[i]`.
+ * Binary search finds the largest index `i` where `thresholds[i] <= value`.
+ *
+ * @example
+ * ```ts
+ * import { Boundary } from '@czap/core';
+ * import { evaluate } from '@czap/quantizer';
+ *
+ * const boundary = Boundary.make({
+ *   input: 'width', states: ['sm', 'md', 'lg'] as const,
+ *   thresholds: [0, 640, 1024], hysteresis: 20,
+ * });
+ * const result = evaluate(boundary, 800);
+ * // result => { state: 'md', index: 1, value: 800, crossed: false }
+ *
+ * const cross = evaluate(boundary, 1100, 'md');
+ * // cross => { state: 'lg', index: 2, value: 1100, crossed: true }
+ * ```
+ *
+ * @param boundary      - The boundary definition with states and thresholds
+ * @param value         - The numeric value to evaluate
+ * @param previousState - Optional previous state for hysteresis and crossing detection
+ * @returns An {@link EvaluateResult} with the resolved state, index, and crossing flag
+ */
+export function evaluate<B extends Boundary.Shape>(
+  boundary: B,
+  value: number,
+  previousState?: StateUnion<B>,
+): EvaluateResult<StateUnion<B> & string> {
+  const { thresholds, states, hysteresis } = boundary;
+  // Boundary.make guarantees states is non-empty; index access below yields StateUnion<B>.
+  // `& string` is structurally satisfied because every state literal is a string.
+  const stateAt = (index: number): StateUnion<B> & string => states[index] as StateUnion<B> & string;
+
+  if (thresholds.length === 0) {
+    return {
+      state: stateAt(0),
+      index: 0,
+      value,
+      crossed: false,
+    };
+  }
+
+  // Binary search: find largest index i where thresholds[i] <= value
+  // This gives the state whose lower bound is satisfied.
+  let lo = 0;
+  let hi = thresholds.length - 1;
+  let rawIndex = 0; // default: first state (value below all thresholds)
+  while (lo <= hi) {
+    const mid = (lo + hi) >>> 1;
+    if ((thresholds[mid] as number) <= value) {
+      rawIndex = mid;
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+
+  const state = stateAt(rawIndex);
+
+  // Without hysteresis or no previous state, return raw result
+  if (!hysteresis || hysteresis <= 0 || previousState === undefined) {
+    const crossed = previousState !== undefined && previousState !== state;
+    return { state, index: rawIndex, value, crossed };
+  }
+
+  // Find previous state index
+  const prevIndex = (states as readonly string[]).indexOf(previousState as string);
+  if (prevIndex === -1) {
+    return { state, index: rawIndex, value, crossed: true };
+  }
+
+  // No crossing needed
+  if (rawIndex === prevIndex) {
+    return { state, index: rawIndex, value, crossed: false };
+  }
+
+  // Half-width hysteresis: dead zone of h/2 each side of threshold
+  const half = hysteresis / 2;
+
+  // Check ALL intermediate thresholds for dead zone suppression
+  if (rawIndex > prevIndex) {
+    // Crossing upward -- check thresholds from prevIndex+1 to rawIndex
+    for (let i = prevIndex + 1; i <= rawIndex; i++) {
+      const threshold = thresholds[i] as number | undefined;
+      if (threshold !== undefined && value < threshold + half) {
+        // In dead zone -- settle at state just below this threshold
+        const settleIndex = i - 1;
+        return { state: stateAt(settleIndex), index: settleIndex, value, crossed: settleIndex !== prevIndex };
+      }
+    }
+  } else {
+    // Crossing downward -- check thresholds from prevIndex down to rawIndex+1
+    for (let i = prevIndex; i > rawIndex; i--) {
+      const threshold = thresholds[i] as number | undefined;
+      if (threshold !== undefined && value > threshold - half) {
+        // In dead zone -- settle at this state
+        return { state: stateAt(i), index: i, value, crossed: i !== prevIndex };
+      }
+    }
+  }
+
+  // Cleared all dead zones -- full transition
+  return { state, index: rawIndex, value, crossed: true };
+}
+
+/**
+ * Boundary evaluation namespace.
+ *
+ * Provides `evaluate()` for mapping a numeric value to a discrete state
+ * via binary search over boundary thresholds with optional hysteresis
+ * to prevent jitter at threshold edges.
+ *
+ * @example
+ * ```ts
+ * import { Boundary } from '@czap/core';
+ * import { Evaluate } from '@czap/quantizer';
+ *
+ * const boundary = Boundary.make({
+ *   input: 'width', states: ['sm', 'lg'] as const,
+ *   thresholds: [0, 768], hysteresis: 10,
+ * });
+ * const r1 = Evaluate.evaluate(boundary, 500);
+ * // r1.state => 'sm', r1.crossed => false
+ *
+ * const r2 = Evaluate.evaluate(boundary, 900, 'sm');
+ * // r2.state => 'lg', r2.crossed => true
+ * ```
+ */
+export const Evaluate = { evaluate } as const;

package/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * `@czap/quantizer` — **LiteShip** quantizer: **rigged** boundary evaluation,
+ * live state, animated transitions between bearings, and motion-tier gating on
+ * the working line.
+ *
+ * @module
+ */
+
+export { evaluate, Evaluate } from './evaluate.js';
+export type { EvaluateResult } from './evaluate.js';
+
+export { Q } from './quantizer.js';
+export type { OutputTarget, QuantizerOutputs, QuantizerConfig, LiveQuantizer, QuantizerBuilder } from './quantizer.js';
+
+export { Transition } from './transition.js';
+export type { TransitionConfig, TransitionMap, Transition as TransitionType } from './transition.js';
+
+export { AnimatedQuantizer } from './animated-quantizer.js';
+export type { AnimatedQuantizerShape } from './animated-quantizer.js';
+
+export { TransitionConfigSchema, TransitionMapSchema, OutputTargetSchema, QuantizerOutputsSchema } from './schemas.js';
+
+export type { MotionTier, SpringConfig, QuantizerFromOptions } from './quantizer.js';
+// `MemoCache` and `TIER_TARGETS` ship via `@czap/quantizer/testing` —
+// implementation primitives that power the public `Q.from()` builder
+// internally but are not consumer-facing API.