@enigmax/primitives 0.3.0 → 0.5.0

package/dist/{chunk-OKNWKBQI.js → chunk-2DVVWPHM.js}

@@ -11,7 +11,7 @@ var DEFAULTS = {
   reverse: false,
   vertical: false,
   draggable: true,
-  hoverScale: 1,
+  hover: "off",
   decay: DEFAULT_DECAY,
   manageStyles: true,
   copies: "clone"
@@ -37,10 +37,17 @@ function createMarquee(lane, track, options = {}) {
   let lastTouchAt = 0;
   const motionQuery = typeof window.matchMedia === "function" ? window.matchMedia("(prefers-reduced-motion: reduce)") : null;
   let reducedMotion = motionQuery?.matches ?? false;
+  function hoverTarget(cruise) {
+    const hover = opts.hover ?? "off";
+    if (hover === "off") return cruise;
+    if (hover === "pause") return 0;
+    if (typeof hover === "number") return cruise * hover;
+    return (cruise < 0 ? -1 : 1) * Math.abs(hover.speed);
+  }
   function target() {
     if (reducedMotion || paused) return 0;
     const cruise = opts.reverse ? -opts.speed : opts.speed;
-    return hovering ? cruise * opts.hoverScale : cruise;
+    return hovering ? hoverTarget(cruise) : cruise;
   }
   function axisSize(element) {
     return opts.vertical ? element.offsetHeight : element.offsetWidth;
@@ -470,148 +477,4 @@ function createInput(input, options = {}) {
   };
 }
 
-// src/core/search.ts
-var DEFAULT_DEBOUNCE = 120;
-function fold(value) {
-  return value.normalize("NFD").replace(/\p{Diacritic}/gu, "").toLowerCase();
-}
-function readPath(item, path) {
-  let cursor = item;
-  for (const step of path.split(".")) {
-    if (cursor == null || typeof cursor !== "object") return "";
-    cursor = cursor[step];
-  }
-  return cursor == null ? "" : String(cursor);
-}
-function substringMatcher(query, items, keys) {
-  const needle = fold(query);
-  const results = [];
-  for (const item of items) {
-    const fields = keys.length ? keys : [""];
-    let best = null;
-    for (let index = 0; index < fields.length; index++) {
-      const key = fields[index];
-      const haystack = fold(key ? readPath(item, key) : String(item));
-      const at = haystack.indexOf(needle);
-      if (at < 0) continue;
-      const score = haystack === needle ? 0 : (at + 1) / (haystack.length + 1) + index * 0.01;
-      if (!best || score < best.score) best = { item, score, key: key || void 0 };
-    }
-    if (best) results.push(best);
-  }
-  return results.sort((left, right) => left.score - right.score);
-}
-function createSearch(options = {}) {
-  let opts = { ...options };
-  let items = opts.items ?? [];
-  let query = "";
-  let results = [];
-  let timer = null;
-  let engine = null;
-  let destroyed = false;
-  const listeners = /* @__PURE__ */ new Set();
-  function buildEngine() {
-    engine = null;
-    if (opts.matcher || !opts.fuse) return;
-    engine = new opts.fuse(items, { keys: opts.keys ?? [], includeScore: true, includeMatches: true, threshold: 0.4, ...opts.fuseOptions });
-  }
-  function run(next) {
-    const trimmed = next.trim();
-    const minLength = opts.minLength ?? 1;
-    let found;
-    if (trimmed.length < minLength) {
-      found = (opts.empty ?? "none") === "all" ? items.map((item) => ({ item, score: 0 })) : [];
-    } else if (opts.matcher) {
-      found = opts.matcher(trimmed, items);
-    } else if (engine) {
-      found = engine.search(trimmed).map((hit) => ({
-        item: hit.item,
-        score: hit.score ?? 0,
-        key: hit.matches?.[0]?.key
-      }));
-    } else {
-      found = substringMatcher(trimmed, items, opts.keys ?? []);
-    }
-    return opts.limit != null ? found.slice(0, opts.limit) : found;
-  }
-  function publish(next) {
-    query = next;
-    results = run(next);
-    opts.onResults?.(results, query);
-    for (const listener of listeners) listener(results, query);
-    return results;
-  }
-  function clearTimer() {
-    if (timer === null) return;
-    clearTimeout(timer);
-    timer = null;
-  }
-  buildEngine();
-  return {
-    get query() {
-      return query;
-    },
-    get results() {
-      return results;
-    },
-    search(next) {
-      if (destroyed) return;
-      clearTimer();
-      const wait = opts.debounce ?? DEFAULT_DEBOUNCE;
-      if (wait <= 0) {
-        publish(next);
-        return;
-      }
-      timer = setTimeout(() => {
-        timer = null;
-        publish(next);
-      }, wait);
-    },
-    searchNow(next) {
-      clearTimer();
-      return publish(next);
-    },
-    setItems(next) {
-      items = next;
-      buildEngine();
-      if (query) publish(query);
-    },
-    update(next) {
-      opts = { ...opts, ...next };
-      if (next.items) items = next.items;
-      buildEngine();
-      if (query) publish(query);
-    },
-    attach(input) {
-      const onInput = () => this.search(input.value);
-      const onKeyDown = (event) => {
-        if (event.key !== "Escape" || !input.value) return;
-        event.stopPropagation();
-        input.value = "";
-        this.searchNow("");
-      };
-      input.addEventListener("input", onInput);
-      input.addEventListener("keydown", onKeyDown);
-      input.dataset.enigmaSearch = "";
-      return () => {
-        input.removeEventListener("input", onInput);
-        input.removeEventListener("keydown", onKeyDown);
-        delete input.dataset.enigmaSearch;
-      };
-    },
-    subscribe(listener) {
-      listeners.add(listener);
-      return () => {
-        listeners.delete(listener);
-      };
-    },
-    destroy() {
-      destroyed = true;
-      clearTimer();
-      listeners.clear();
-      engine = null;
-    }
-  };
-}
-
-export { createInput, createMarquee, createSearch };
+export { createInput, createMarquee };

package/dist/chunk-UZFEEFMF.js

@@ -0,0 +1,145 @@
+// src/core/search.ts
+var DEFAULT_DEBOUNCE = 120;
+function fold(value) {
+  return value.normalize("NFD").replace(/\p{Diacritic}/gu, "").toLowerCase();
+}
+function readPath(item, path) {
+  let cursor = item;
+  for (const step of path.split(".")) {
+    if (cursor == null || typeof cursor !== "object") return "";
+    cursor = cursor[step];
+  }
+  return cursor == null ? "" : String(cursor);
+}
+function substringMatcher(query, items, keys) {
+  const needle = fold(query);
+  const results = [];
+  for (const item of items) {
+    const fields = keys.length ? keys : [""];
+    let best = null;
+    for (let index = 0; index < fields.length; index++) {
+      const key = fields[index];
+      const haystack = fold(key ? readPath(item, key) : String(item));
+      const at = haystack.indexOf(needle);
+      if (at < 0) continue;
+      const score = haystack === needle ? 0 : (at + 1) / (haystack.length + 1) + index * 0.01;
+      if (!best || score < best.score) best = { item, score, key: key || void 0 };
+    }
+    if (best) results.push(best);
+  }
+  return results.sort((left, right) => left.score - right.score);
+}
+function createSearch(options = {}) {
+  let opts = { ...options };
+  let items = opts.items ?? [];
+  let query = "";
+  let results = [];
+  let timer = null;
+  let engine = null;
+  let destroyed = false;
+  const listeners = /* @__PURE__ */ new Set();
+  function buildEngine() {
+    engine = null;
+    if (opts.matcher || !opts.fuse) return;
+    engine = new opts.fuse(items, { keys: opts.keys ?? [], includeScore: true, includeMatches: true, threshold: 0.4, ...opts.fuseOptions });
+  }
+  function run(next) {
+    const trimmed = next.trim();
+    const minLength = opts.minLength ?? 1;
+    let found;
+    if (trimmed.length < minLength) {
+      found = (opts.empty ?? "none") === "all" ? items.map((item) => ({ item, score: 0 })) : [];
+    } else if (opts.matcher) {
+      found = opts.matcher(trimmed, items);
+    } else if (engine) {
+      found = engine.search(trimmed).map((hit) => ({
+        item: hit.item,
+        score: hit.score ?? 0,
+        key: hit.matches?.[0]?.key
+      }));
+    } else {
+      found = substringMatcher(trimmed, items, opts.keys ?? []);
+    }
+    return opts.limit != null ? found.slice(0, opts.limit) : found;
+  }
+  function publish(next) {
+    query = next;
+    results = run(next);
+    opts.onResults?.(results, query);
+    for (const listener of listeners) listener(results, query);
+    return results;
+  }
+  function clearTimer() {
+    if (timer === null) return;
+    clearTimeout(timer);
+    timer = null;
+  }
+  buildEngine();
+  return {
+    get query() {
+      return query;
+    },
+    get results() {
+      return results;
+    },
+    search(next) {
+      if (destroyed) return;
+      clearTimer();
+      const wait = opts.debounce ?? DEFAULT_DEBOUNCE;
+      if (wait <= 0) {
+        publish(next);
+        return;
+      }
+      timer = setTimeout(() => {
+        timer = null;
+        publish(next);
+      }, wait);
+    },
+    searchNow(next) {
+      clearTimer();
+      return publish(next);
+    },
+    setItems(next) {
+      items = next;
+      buildEngine();
+      if (query) publish(query);
+    },
+    update(next) {
+      opts = { ...opts, ...next };
+      if (next.items) items = next.items;
+      buildEngine();
+      if (query) publish(query);
+    },
+    attach(input) {
+      const onInput = () => this.search(input.value);
+      const onKeyDown = (event) => {
+        if (event.key !== "Escape" || !input.value) return;
+        event.stopPropagation();
+        input.value = "";
+        this.searchNow("");
+      };
+      input.addEventListener("input", onInput);
+      input.addEventListener("keydown", onKeyDown);
+      input.dataset.enigmaSearch = "";
+      return () => {
+        input.removeEventListener("input", onInput);
+        input.removeEventListener("keydown", onKeyDown);
+        delete input.dataset.enigmaSearch;
+      };
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    destroy() {
+      destroyed = true;
+      clearTimer();
+      listeners.clear();
+      engine = null;
+    }
+  };
+}
+
+export { createSearch };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { F as FuseConstructor, a as FuseLike, S as SearchInstance, b as SearchMatch, c as SearchOptions, d as createSearch } from './search-CsO3L1Lw.js';
+
 /**
  * Draggable infinite marquee: the behaviour engine, with no styling of its own.
  *
@@ -9,6 +11,21 @@
  * comments marked "non-negotiable" name the bug that the obvious implementation
  * shipped with.
  */
+/**
+ * What a MOUSE resting on the row does to its speed. One option covers every case, so
+ * there is no pile of booleans to reconcile:
+ *
+ * - `"off"`   ignore hover entirely (the default)
+ * - `"pause"` stop while the pointer is on it
+ * - a number  multiply the cruise speed: `0.15` crawls, `1` changes nothing, `2` doubles
+ * - `{ speed }` an ABSOLUTE speed in px/s, whatever the cruise is; direction still
+ *   follows `reverse`, so you give a magnitude and not a sign
+ *
+ * Touch never triggers any of it - see the pointerType note on the hover handler.
+ */
+type MarqueeHover = number | "off" | "pause" | {
+    speed: number;
+};
 interface MarqueeOptions {
     /**
      * Pixels per second. NOT a duration: a duration ties the speed to the item
@@ -21,8 +38,8 @@ interface MarqueeOptions {
     vertical?: boolean;
     /** Allow grabbing and throwing the row. */
     draggable?: boolean;
-    /** Speed multiplier while a MOUSE rests on the row. 0 pauses it. */
-    hoverScale?: number;
+    /** What a mouse resting on the row does to its speed. See {@link MarqueeHover}. */
+    hover?: MarqueeHover;
     /** Fraction of the remaining velocity gap left after one second. */
     decay?: number;
     /**
@@ -145,71 +162,4 @@ interface InputInstance {
  */
 declare function createInput(input: HTMLInputElement, options?: InputOptions): InputInstance;
 
-/**
- * Search-as-you-type: debouncing, ordering, cancellation and the field wiring, with the
- * matching left pluggable.
- *
- * Fuse.js is NOT a dependency of this package. Hand it the constructor and you get fuzzy
- * matching configured exactly as if you had called it yourself - `fuseOptions` is passed
- * through untouched. Hand it nothing and a built-in accent-insensitive substring matcher
- * runs instead, so the primitive works with zero dependencies. Hand it a `matcher` and
- * every part of this is replaced by your own.
- */
-interface SearchMatch<T> {
-    item: T;
-    /** Lower is better, matching Fuse's convention. 0 is an exact hit. */
-    score: number;
-    /** Which key matched, when the matcher reports it. */
-    key?: string;
-}
-/** The shape of Fuse's constructor, declared here so the package need not depend on it. */
-interface FuseLike<T> {
-    search(query: string): {
-        item: T;
-        score?: number;
-        matches?: {
-            key?: string;
-        }[];
-    }[];
-}
-type FuseConstructor = new <T>(items: readonly T[], options?: Record<string, unknown>) => FuseLike<T>;
-interface SearchOptions<T> {
-    items?: readonly T[];
-    /** Fields to search. Dotted paths work with the built-in matcher and with Fuse. */
-    keys?: string[];
-    /**
-     * Pass Fuse.js's constructor to get fuzzy matching. Omit it for the built-in
-     * substring matcher. Ignored when `matcher` is set.
-     */
-    fuse?: FuseConstructor;
-    /** Handed to Fuse verbatim, so any Fuse option behaves exactly as documented there. */
-    fuseOptions?: Record<string, unknown>;
-    /** Replaces the engine entirely. Return the results in the order you want them. */
-    matcher?: (query: string, items: readonly T[]) => SearchMatch<T>[];
-    /** ms to wait after the last keystroke. 0 searches on every one. */
-    debounce?: number;
-    /** Queries shorter than this return nothing rather than everything. */
-    minLength?: number;
-    /** Cap the result list. */
-    limit?: number;
-    /** What an empty query returns. "none" (default) or "all". */
-    empty?: "none" | "all";
-    onResults?: (results: SearchMatch<T>[], query: string) => void;
-}
-interface SearchInstance<T> {
-    readonly query: string;
-    readonly results: SearchMatch<T>[];
-    /** Debounced. */
-    search(query: string): void;
-    /** Skips the debounce, e.g. on Enter. */
-    searchNow(query: string): SearchMatch<T>[];
-    setItems(items: readonly T[]): void;
-    update(options: Partial<SearchOptions<T>>): void;
-    /** Bind to a field: input events search, Escape clears. Returns an unbind. */
-    attach(input: HTMLInputElement): () => void;
-    subscribe(listener: (results: SearchMatch<T>[], query: string) => void): () => void;
-    destroy(): void;
-}
-declare function createSearch<T>(options?: SearchOptions<T>): SearchInstance<T>;
-
-export { type FuseConstructor, type FuseLike, type InputAction, type InputActionState, type InputIcon, type InputInstance, type InputOptions, type MarqueeInstance, type MarqueeOptions, type SearchInstance, type SearchMatch, type SearchOptions, createInput, createMarquee, createSearch };
+export { type InputAction, type InputActionState, type InputIcon, type InputInstance, type InputOptions, type MarqueeHover, type MarqueeInstance, type MarqueeOptions, createInput, createMarquee };

package/dist/index.js

@@ -1 +1,2 @@
-export { createInput, createMarquee, createSearch } from './chunk-OKNWKBQI.js';
+export { createInput, createMarquee } from './chunk-2DVVWPHM.js';
+export { createSearch } from './chunk-UZFEEFMF.js';

package/dist/react/index.d.ts

@@ -1,6 +1,8 @@
 import { RefObject } from 'react';
-import { MarqueeOptions, InputOptions, SearchMatch, SearchOptions } from '../index.js';
-export { FuseConstructor, InputAction, InputIcon, MarqueeInstance } from '../index.js';
+import { MarqueeOptions, InputOptions } from '../index.js';
+export { InputAction, InputIcon, MarqueeHover, MarqueeInstance } from '../index.js';
+import { b as SearchMatch, c as SearchOptions } from '../search-CsO3L1Lw.js';
+export { F as FuseConstructor } from '../search-CsO3L1Lw.js';
 
 interface UseMarqueeResult {
     /** Attach to the clipping viewport. */
@@ -26,7 +28,7 @@ interface UseMarqueeResult {
  * to the item count, so the row accelerates every time content is added.
  *
  * ```tsx
- * const { laneRef, trackRef, copies } = useMarquee({ speed: 80, hoverScale: 0.15 });
+ * const { laneRef, trackRef, copies } = useMarquee({ speed: 80, hover: 0.15 });
  * return (
  *     <div ref={laneRef}>
  *         <div ref={trackRef} style={{ display: "flex" }}>

package/dist/react/index.js

@@ -1,4 +1,5 @@
-import { createMarquee, createInput, createSearch } from '../chunk-OKNWKBQI.js';
+import { createMarquee, createInput } from '../chunk-2DVVWPHM.js';
+import { createSearch } from '../chunk-UZFEEFMF.js';
 import { useRef, useState, useMemo, useEffect, useLayoutEffect } from 'react';
 
 var useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
@@ -38,7 +39,7 @@ function useMarquee(options = {}) {
   }, []);
   useIsomorphicLayoutEffect(() => {
     instanceRef.current?.update(options);
-  }, [options.speed, options.reverse, options.vertical, options.draggable, options.hoverScale, options.decay]);
+  }, [options.speed, options.reverse, options.vertical, options.draggable, options.hover, options.decay]);
   useIsomorphicLayoutEffect(() => {
     instanceRef.current?.measure();
   }, [copies]);

package/dist/search/index.d.ts

@@ -0,0 +1,29 @@
+import { c as SearchOptions, S as SearchInstance } from '../search-CsO3L1Lw.js';
+export { b as SearchMatch } from '../search-CsO3L1Lw.js';
+
+/**
+ * Search with Fuse.js already wired: the batteries-included entry point.
+ *
+ * `@enigmax/primitives` stays dependency-free, so someone who only wants the marquee
+ * never pulls a search engine into their bundle. Importing THIS subpath is the explicit
+ * opt-in, and it is what `enigma add search` sets a project up for - it installs fuse.js
+ * alongside the package.
+ *
+ * Everything else is identical to `createSearch` from the main entry: pass `fuseOptions`
+ * to configure Fuse, or `matcher` to replace it outright.
+ */
+
+/**
+ * Search as you type, fuzzy by default.
+ *
+ * ```js
+ * import { createSearch } from "@enigmax/primitives/search";
+ *
+ * const search = createSearch({ items: docs, keys: ["title", "body"] });
+ * ```
+ *
+ * Pass `fuse: undefined` explicitly to fall back to the built-in substring matcher.
+ */
+declare function createSearch<T>(options?: SearchOptions<T>): SearchInstance<T>;
+
+export { SearchInstance, SearchOptions, createSearch };

package/dist/search/index.js

@@ -0,0 +1,12 @@
+import { createSearch } from '../chunk-UZFEEFMF.js';
+import Fuse from 'fuse.js';
+
+function createSearch2(options = {}) {
+  return createSearch({
+    // A caller-supplied `fuse` or `matcher` still wins; this only fills the blank.
+    fuse: Fuse,
+    ...options
+  });
+}
+
+export { createSearch2 as createSearch };

package/dist/search-CsO3L1Lw.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Search-as-you-type: debouncing, ordering, cancellation and the field wiring, with the
+ * matching left pluggable.
+ *
+ * Fuse.js is NOT a dependency of this package. Hand it the constructor and you get fuzzy
+ * matching configured exactly as if you had called it yourself - `fuseOptions` is passed
+ * through untouched. Hand it nothing and a built-in accent-insensitive substring matcher
+ * runs instead, so the primitive works with zero dependencies. Hand it a `matcher` and
+ * every part of this is replaced by your own.
+ */
+interface SearchMatch<T> {
+    item: T;
+    /** Lower is better, matching Fuse's convention. 0 is an exact hit. */
+    score: number;
+    /** Which key matched, when the matcher reports it. */
+    key?: string;
+}
+/** The shape of Fuse's constructor, declared here so the package need not depend on it. */
+interface FuseLike<T> {
+    search(query: string): {
+        item: T;
+        score?: number;
+        matches?: {
+            key?: string;
+        }[];
+    }[];
+}
+type FuseConstructor = new <T>(items: readonly T[], options?: Record<string, unknown>) => FuseLike<T>;
+interface SearchOptions<T> {
+    items?: readonly T[];
+    /** Fields to search. Dotted paths work with the built-in matcher and with Fuse. */
+    keys?: string[];
+    /**
+     * Pass Fuse.js's constructor to get fuzzy matching. Omit it for the built-in
+     * substring matcher. Ignored when `matcher` is set.
+     */
+    fuse?: FuseConstructor;
+    /** Handed to Fuse verbatim, so any Fuse option behaves exactly as documented there. */
+    fuseOptions?: Record<string, unknown>;
+    /** Replaces the engine entirely. Return the results in the order you want them. */
+    matcher?: (query: string, items: readonly T[]) => SearchMatch<T>[];
+    /** ms to wait after the last keystroke. 0 searches on every one. */
+    debounce?: number;
+    /** Queries shorter than this return nothing rather than everything. */
+    minLength?: number;
+    /** Cap the result list. */
+    limit?: number;
+    /** What an empty query returns. "none" (default) or "all". */
+    empty?: "none" | "all";
+    onResults?: (results: SearchMatch<T>[], query: string) => void;
+}
+interface SearchInstance<T> {
+    readonly query: string;
+    readonly results: SearchMatch<T>[];
+    /** Debounced. */
+    search(query: string): void;
+    /** Skips the debounce, e.g. on Enter. */
+    searchNow(query: string): SearchMatch<T>[];
+    setItems(items: readonly T[]): void;
+    update(options: Partial<SearchOptions<T>>): void;
+    /** Bind to a field: input events search, Escape clears. Returns an unbind. */
+    attach(input: HTMLInputElement): () => void;
+    subscribe(listener: (results: SearchMatch<T>[], query: string) => void): () => void;
+    destroy(): void;
+}
+declare function createSearch<T>(options?: SearchOptions<T>): SearchInstance<T>;
+
+export { type FuseConstructor as F, type SearchInstance as S, type FuseLike as a, type SearchMatch as b, type SearchOptions as c, createSearch as d };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enigmax/primitives",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Headless interaction primitives: the behaviour, the timing and the accessibility of components like a draggable infinite marquee, with no styles of their own. Framework-agnostic core plus thin adapters.",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,7 +14,11 @@
       "types": "./dist/react/index.d.ts",
       "import": "./dist/react/index.js"
     },
-    "./registry.json": "./registry.json"
+    "./registry.json": "./registry.json",
+    "./search": {
+      "types": "./dist/search/index.d.ts",
+      "import": "./dist/search/index.js"
+    }
   },
   "scripts": {
     "build": "tsup",

package/recipes/marquee.css.tsx

@@ -1,6 +1,6 @@
 import "./marquee.css";
 import type { ReactNode, Ref } from "react";
-import { useMarquee } from "@enigmax/primitives/react";
+import { useMarquee, type MarqueeHover } from "@enigmax/primitives/react";
 
 /**
  * A styled marquee, yours to edit.
@@ -12,8 +12,12 @@ export interface MarqueeProps<T> {
     items: T[];
     /** Pixels per second. Never a duration - the row would speed up as items are added. */
     speed?: number;
-    /** Speed multiplier while a mouse rests on the row. 0 pauses it. */
-    hoverScale?: number;
+    /**
+     * What a mouse resting on the row does to its speed:
+     * "off" ignores hover, "pause" stops, a number multiplies the cruise speed
+     * (0.15 crawls, 2 doubles), { speed } sets an absolute px/s.
+     */
+    hover?: MarqueeHover;
     reverse?: boolean;
     /** Fade both ends so items enter and leave instead of being cut. */
     fade?: boolean;
@@ -24,13 +28,13 @@ export interface MarqueeProps<T> {
 export function Marquee<T>({
     items,
     speed = 70,
-    hoverScale = 1,
+    hover = "off",
     reverse = false,
     fade = true,
     className = "",
     children
 }: MarqueeProps<T>) {
-    const { laneRef, trackRef, copies, dragging } = useMarquee({ speed, hoverScale, reverse });
+    const { laneRef, trackRef, copies, dragging } = useMarquee({ speed, hover, reverse });
 
     return (
         <div

package/recipes/marquee.tailwind.tsx

@@ -1,5 +1,5 @@
 import type { ReactNode, Ref } from "react";
-import { useMarquee } from "@enigmax/primitives/react";
+import { useMarquee, type MarqueeHover } from "@enigmax/primitives/react";
 
 /**
  * A styled marquee, yours to edit.
@@ -16,8 +16,12 @@ export interface MarqueeProps<T> {
     items: T[];
     /** Pixels per second. Never a duration - the row would speed up as items are added. */
     speed?: number;
-    /** Speed multiplier while a mouse rests on the row. 0 pauses it. */
-    hoverScale?: number;
+    /**
+     * What a mouse resting on the row does to its speed:
+     * "off" ignores hover, "pause" stops, a number multiplies the cruise speed
+     * (0.15 crawls, 2 doubles), { speed } sets an absolute px/s.
+     */
+    hover?: MarqueeHover;
     reverse?: boolean;
     /** Fade both ends so items enter and leave instead of being cut. */
     fade?: boolean;
@@ -28,13 +32,13 @@ export interface MarqueeProps<T> {
 export function Marquee<T>({
     items,
     speed = 70,
-    hoverScale = 1,
+    hover = "off",
     reverse = false,
     fade = true,
     className = "",
     children
 }: MarqueeProps<T>) {
-    const { laneRef, trackRef, copies, dragging } = useMarquee({ speed, hoverScale, reverse });
+    const { laneRef, trackRef, copies, dragging } = useMarquee({ speed, hover, reverse });
 
     return (
         <div

package/registry.json

@@ -180,15 +180,15 @@
     {
       "name": "search",
       "title": "Search as you type",
-      "description": "Debouncing, ranking, cancellation and the field wiring, with the matching pluggable. Pass Fuse.js for fuzzy search, your own function to replace the engine, or neither for the built-in accent-insensitive substring matcher.",
+      "description": "Search as you type, fuzzy by default with Fuse.js. Debouncing, ranking and cancellation are the primitive's; the matching is replaceable, and dropping Fuse falls back to a built-in accent-insensitive substring matcher.",
       "targets": [
         "vanilla",
         "astro",
         "react"
       ],
       "entry": {
-        "vanilla": "@enigmax/primitives",
-        "astro": "@enigmax/primitives",
+        "vanilla": "@enigmax/primitives/search",
+        "astro": "@enigmax/primitives/search",
         "react": "@enigmax/primitives/react"
       },
       "exports": {
@@ -241,7 +241,10 @@
       "docs": "docs/notes/primitives.md#search",
       "recipes": [
         "tailwind"
-      ]
+      ],
+      "dependencies": {
+        "fuse.js": "^7.0.0"
+      }
     }
   ]
 }

package/src/core/marquee.ts

@@ -29,6 +29,20 @@ const TOUCH_HOVER_SUPPRESS_MS = 1000;
 /** Below this the row is idle and the frame loop can stop. */
 const IDLE_EPSILON = 0.01;
 
+/**
+ * What a MOUSE resting on the row does to its speed. One option covers every case, so
+ * there is no pile of booleans to reconcile:
+ *
+ * - `"off"`   ignore hover entirely (the default)
+ * - `"pause"` stop while the pointer is on it
+ * - a number  multiply the cruise speed: `0.15` crawls, `1` changes nothing, `2` doubles
+ * - `{ speed }` an ABSOLUTE speed in px/s, whatever the cruise is; direction still
+ *   follows `reverse`, so you give a magnitude and not a sign
+ *
+ * Touch never triggers any of it - see the pointerType note on the hover handler.
+ */
+export type MarqueeHover = number | "off" | "pause" | { speed: number; };
+
 export interface MarqueeOptions {
     /**
      * Pixels per second. NOT a duration: a duration ties the speed to the item
@@ -41,8 +55,8 @@ export interface MarqueeOptions {
     vertical?: boolean;
     /** Allow grabbing and throwing the row. */
     draggable?: boolean;
-    /** Speed multiplier while a MOUSE rests on the row. 0 pauses it. */
-    hoverScale?: number;
+    /** What a mouse resting on the row does to its speed. See {@link MarqueeHover}. */
+    hover?: MarqueeHover;
     /** Fraction of the remaining velocity gap left after one second. */
     decay?: number;
     /**
@@ -94,7 +108,7 @@ const DEFAULTS: ResolvedOptions = {
     reverse: false,
     vertical: false,
     draggable: true,
-    hoverScale: 1,
+    hover: "off",
     decay: DEFAULT_DECAY,
     manageStyles: true,
     copies: "clone"
@@ -134,11 +148,21 @@ export function createMarquee(lane: HTMLElement, track: HTMLElement, options: Ma
         : null;
     let reducedMotion = motionQuery?.matches ?? false;
 
+    /** The speed a mouse on the row asks for. One option, four shapes, no flags to reconcile. */
+    function hoverTarget(cruise: number): number {
+        const hover = opts.hover ?? "off";
+        if (hover === "off") return cruise;
+        if (hover === "pause") return 0;
+        if (typeof hover === "number") return cruise * hover;
+        // An absolute speed is a magnitude: the row keeps travelling the way it was.
+        return (cruise < 0 ? -1 : 1) * Math.abs(hover.speed);
+    }
+
     /** Read live every frame, never captured: cruise, hover and reduced motion all ease. */
     function target(): number {
         if (reducedMotion || paused) return 0;
         const cruise = opts.reverse ? -opts.speed : opts.speed;
-        return hovering ? cruise * opts.hoverScale : cruise;
+        return hovering ? hoverTarget(cruise) : cruise;
     }
 
     function axisSize(element: HTMLElement): number {

package/src/index.ts

@@ -1,3 +1,3 @@
-export { createMarquee, type MarqueeOptions, type MarqueeInstance } from "@/core/marquee";
+export { createMarquee, type MarqueeOptions, type MarqueeInstance, type MarqueeHover } from "@/core/marquee";
 export { createInput, type InputOptions, type InputInstance, type InputAction, type InputIcon, type InputActionState } from "@/core/input";
 export { createSearch, type SearchOptions, type SearchInstance, type SearchMatch, type FuseConstructor, type FuseLike } from "@/core/search";

package/src/react/index.ts

@@ -1,5 +1,5 @@
 export { useMarquee, type UseMarqueeResult } from "@/react/use-marquee";
-export { type MarqueeOptions, type MarqueeInstance } from "@/core/marquee";
+export { type MarqueeOptions, type MarqueeInstance, type MarqueeHover } from "@/core/marquee";
 export { useInput, type UseInputResult } from "@/react/use-input";
 export { useSearch, type UseSearchResult } from "@/react/use-search";
 export { type InputOptions, type InputAction, type InputIcon } from "@/core/input";

package/src/react/use-marquee.ts

@@ -29,7 +29,7 @@ export interface UseMarqueeResult {
  * to the item count, so the row accelerates every time content is added.
  *
  * ```tsx
- * const { laneRef, trackRef, copies } = useMarquee({ speed: 80, hoverScale: 0.15 });
+ * const { laneRef, trackRef, copies } = useMarquee({ speed: 80, hover: 0.15 });
  * return (
  *     <div ref={laneRef}>
  *         <div ref={trackRef} style={{ display: "flex" }}>
@@ -87,7 +87,7 @@ export function useMarquee(options: MarqueeOptions = {}): UseMarqueeResult {
 
     useIsomorphicLayoutEffect(() => {
         instanceRef.current?.update(options);
-    }, [options.speed, options.reverse, options.vertical, options.draggable, options.hoverScale, options.decay]);
+    }, [options.speed, options.reverse, options.vertical, options.draggable, options.hover, options.decay]);
 
     // A copy count change means new children; the lap has to be read again.
     useIsomorphicLayoutEffect(() => {

package/src/search/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Search with Fuse.js already wired: the batteries-included entry point.
+ *
+ * `@enigmax/primitives` stays dependency-free, so someone who only wants the marquee
+ * never pulls a search engine into their bundle. Importing THIS subpath is the explicit
+ * opt-in, and it is what `enigma add search` sets a project up for - it installs fuse.js
+ * alongside the package.
+ *
+ * Everything else is identical to `createSearch` from the main entry: pass `fuseOptions`
+ * to configure Fuse, or `matcher` to replace it outright.
+ */
+
+import Fuse from "fuse.js";
+import { createSearch as createBaseSearch, type SearchOptions, type SearchInstance } from "@/core/search";
+
+export type { SearchOptions, SearchInstance, SearchMatch } from "@/core/search";
+
+/**
+ * Search as you type, fuzzy by default.
+ *
+ * ```js
+ * import { createSearch } from "@enigmax/primitives/search";
+ *
+ * const search = createSearch({ items: docs, keys: ["title", "body"] });
+ * ```
+ *
+ * Pass `fuse: undefined` explicitly to fall back to the built-in substring matcher.
+ */
+export function createSearch<T>(options: SearchOptions<T> = {}): SearchInstance<T> {
+    return createBaseSearch<T>({
+        // A caller-supplied `fuse` or `matcher` still wins; this only fills the blank.
+        fuse: Fuse as never,
+        ...options
+    });
+}