@enigmax/primitives 0.4.0 → 0.6.0

package/dist/{chunk-W2DRHYC2.js → chunk-WCB7V7XO.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,4 +477,164 @@ function createInput(input, options = {}) {
   };
 }
 
-export { createInput, createMarquee };
+// src/core/button.ts
+var TICK_MS = 100;
+function store(cooldown) {
+  if (!cooldown.key || typeof window === "undefined") return null;
+  try {
+    const target = cooldown.storage === "local" ? window.localStorage : window.sessionStorage;
+    const probe = "__enigma_probe__";
+    target.setItem(probe, "1");
+    target.removeItem(probe);
+    return target;
+  } catch {
+    return null;
+  }
+}
+function normalize(cooldown) {
+  if (cooldown == null) return null;
+  return typeof cooldown === "number" ? { ms: cooldown } : cooldown;
+}
+function isTyping(target) {
+  const element = target;
+  if (!element) return false;
+  const tag = element.tagName;
+  return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT" || element.isContentEditable === true;
+}
+function createButton(options = {}) {
+  let opts = { ...options };
+  let loading = Boolean(opts.loading);
+  let readyAt = 0;
+  let timer = null;
+  let destroyed = false;
+  const listeners = /* @__PURE__ */ new Set();
+  const storageKey = () => {
+    const cooldown = normalize(opts.cooldown);
+    return cooldown?.key ? `enigma:cooldown:${cooldown.key}` : null;
+  };
+  function restore() {
+    const cooldown = normalize(opts.cooldown);
+    if (!cooldown) return;
+    const target = store(cooldown);
+    const key = storageKey();
+    if (!target || !key) return;
+    const saved = Number(target.getItem(key));
+    if (Number.isFinite(saved) && saved > Date.now()) readyAt = saved;
+  }
+  function remaining() {
+    return Math.max(0, readyAt - Date.now());
+  }
+  function snapshot() {
+    const disabled = Boolean(opts.disabled);
+    const cooldown = remaining();
+    return {
+      element: opts.href ? "a" : "button",
+      available: !disabled && !loading && cooldown === 0,
+      loading,
+      disabled,
+      cooldown,
+      shortcut: opts.shortcut ?? null
+    };
+  }
+  function emit() {
+    const state = snapshot();
+    opts.onChange?.(state);
+    for (const listener of listeners) listener(state);
+  }
+  function stopTicking() {
+    if (timer === null) return;
+    clearInterval(timer);
+    timer = null;
+  }
+  function startTicking() {
+    if (timer !== null || remaining() === 0) return;
+    timer = setInterval(() => {
+      if (remaining() > 0) {
+        emit();
+        return;
+      }
+      stopTicking();
+      emit();
+    }, TICK_MS);
+  }
+  function beginCooldown() {
+    const cooldown = normalize(opts.cooldown);
+    if (!cooldown || cooldown.ms <= 0) return;
+    readyAt = Date.now() + cooldown.ms;
+    const target = store(cooldown);
+    const key = storageKey();
+    if (target && key) {
+      try {
+        target.setItem(key, String(readyAt));
+      } catch {
+      }
+    }
+    startTicking();
+  }
+  async function press(event) {
+    if (destroyed || !snapshot().available) return;
+    const result = opts.onPress?.(event);
+    if (result instanceof Promise) {
+      loading = true;
+      emit();
+      try {
+        await result;
+      } finally {
+        loading = false;
+        beginCooldown();
+        emit();
+      }
+      return;
+    }
+    beginCooldown();
+    emit();
+  }
+  function onKeyDown(event) {
+    if (!opts.shortcut || isTyping(event.target)) return;
+    if (event.ctrlKey || event.metaKey || event.altKey || event.shiftKey) return;
+    if (event.key.toLowerCase() !== opts.shortcut.toLowerCase()) return;
+    if (!snapshot().available) return;
+    event.preventDefault();
+    void press(event);
+  }
+  if (typeof window !== "undefined") {
+    restore();
+    startTicking();
+    window.addEventListener("keydown", onKeyDown);
+  }
+  return {
+    get state() {
+      return snapshot();
+    },
+    press,
+    update(next) {
+      const hadCooldown = JSON.stringify(normalize(opts.cooldown));
+      opts = { ...opts, ...next };
+      if (next.loading !== void 0) loading = Boolean(next.loading);
+      if (JSON.stringify(normalize(opts.cooldown)) !== hadCooldown) restore();
+      emit();
+    },
+    reset() {
+      readyAt = 0;
+      stopTicking();
+      const cooldown = normalize(opts.cooldown);
+      const key = storageKey();
+      if (cooldown && key) store(cooldown)?.removeItem(key);
+      emit();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    destroy() {
+      destroyed = true;
+      stopTicking();
+      listeners.clear();
+      if (typeof window !== "undefined") window.removeEventListener("keydown", onKeyDown);
+    }
+  };
+}
+
+export { createButton, createInput, createMarquee };

package/dist/index.d.ts

@@ -11,6 +11,21 @@ export { F as FuseConstructor, a as FuseLike, S as SearchInstance, b as SearchMa
  * 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
@@ -23,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;
     /**
@@ -147,4 +162,66 @@ interface InputInstance {
  */
 declare function createInput(input: HTMLInputElement, options?: InputOptions): InputInstance;
 
-export { type InputAction, type InputActionState, type InputIcon, type InputInstance, type InputOptions, type MarqueeInstance, type MarqueeOptions, createInput, createMarquee };
+/**
+ * Button behaviour: what makes it unavailable, and everything that follows from that.
+ *
+ * Disabled, loading and a cooldown are three reasons for the same state, so they collapse
+ * into one `available` the renderer reads, instead of three flags every call site has to
+ * combine correctly. The element to render is reported rather than chosen, because a
+ * framework-agnostic package cannot import next/link.
+ */
+/** Which tag the consumer should render. An href makes it a link, and a link is not a button. */
+type ButtonElement = "button" | "a";
+interface ButtonCooldown {
+    /** How long the button stays unavailable after a press, in ms. */
+    ms: number;
+    /**
+     * Survive a reload under this key. Without it the cooldown is in memory only, and a
+     * refresh is a free retry - which is the whole thing a cooldown exists to prevent.
+     */
+    key?: string;
+    storage?: "local" | "session";
+}
+interface ButtonOptions {
+    /** Turns into an `a`, and a link cannot be `disabled` - only `aria-disabled`. */
+    href?: string;
+    disabled?: boolean;
+    /** Unavailable and busy. Set it yourself, or let an async `onPress` manage it. */
+    loading?: boolean;
+    /** ms, or the full shape for a cooldown that outlives a reload. */
+    cooldown?: number | ButtonCooldown;
+    /**
+     * A single key that presses the button. Ignored while the visitor is typing, and
+     * while any modifier is held, so it never steals a real shortcut.
+     */
+    shortcut?: string;
+    /** Async work flips `loading` for its duration and only then starts the cooldown. */
+    onPress?: (event?: Event) => void | Promise<void>;
+    /** Called whenever anything below changes. */
+    onChange?: (state: ButtonState) => void;
+}
+interface ButtonState {
+    /** The tag to render. */
+    element: ButtonElement;
+    /** Pressable: not disabled, not loading, not cooling down. */
+    available: boolean;
+    loading: boolean;
+    disabled: boolean;
+    /** ms left on the cooldown, 0 when there is none. */
+    cooldown: number;
+    /** The accessible name for the shortcut, when there is one. */
+    shortcut: string | null;
+}
+interface ButtonInstance {
+    readonly state: ButtonState;
+    /** Run the press as if it had been clicked. Ignored while unavailable. */
+    press(event?: Event): Promise<void>;
+    update(options: Partial<ButtonOptions>): void;
+    /** Clear a cooldown early, including its stored entry. */
+    reset(): void;
+    subscribe(listener: (state: ButtonState) => void): () => void;
+    destroy(): void;
+}
+declare function createButton(options?: ButtonOptions): ButtonInstance;
+
+export { type ButtonCooldown, type ButtonElement, type ButtonInstance, type ButtonOptions, type ButtonState, type InputAction, type InputActionState, type InputIcon, type InputInstance, type InputOptions, type MarqueeHover, type MarqueeInstance, type MarqueeOptions, createButton, createInput, createMarquee };

package/dist/index.js

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

package/dist/react/index.d.ts

@@ -1,6 +1,6 @@
 import { RefObject } from 'react';
-import { MarqueeOptions, InputOptions } from '../index.js';
-export { InputAction, InputIcon, MarqueeInstance } from '../index.js';
+import { MarqueeOptions, InputOptions, ButtonState, ButtonOptions } 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';
 
@@ -28,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" }}>
@@ -94,4 +94,38 @@ interface UseSearchResult<T> {
  */
 declare function useSearch<T>(options?: SearchOptions<T>): UseSearchResult<T>;
 
-export { InputOptions, MarqueeOptions, SearchMatch, SearchOptions, type UseInputResult, type UseMarqueeResult, type UseSearchResult, useInput, useMarquee, useSearch };
+interface UseButtonResult extends ButtonState {
+    /** Spread onto the element named by `element`. */
+    props: {
+        onClick: (event: {
+            preventDefault(): void;
+        }) => void;
+        "aria-disabled": boolean;
+        "aria-busy": boolean;
+        "data-loading"?: "";
+        "data-cooldown"?: "";
+        /** Only on a real button: an anchor has no `disabled`. */
+        disabled?: boolean;
+        href?: string;
+        title?: string;
+    };
+    press: () => void;
+    reset: () => void;
+}
+/**
+ * Button behaviour: disabled, loading, a cooldown and a keyboard shortcut collapsed into
+ * one `available`, plus the attributes that follow from it.
+ *
+ * ```tsx
+ * const { element: Tag, props, loading, cooldown } = useButton({
+ *     cooldown: { ms: 30_000, key: "resend-code", storage: "local" },
+ *     shortcut: "r",
+ *     onPress: () => resendCode()
+ * });
+ *
+ * return <Tag {...props}>{loading ? "Sending" : cooldown ? `Wait ${Math.ceil(cooldown / 1000)}s` : "Resend"}</Tag>;
+ * ```
+ */
+declare function useButton(options?: ButtonOptions): UseButtonResult;
+
+export { ButtonOptions, ButtonState, InputOptions, MarqueeOptions, SearchMatch, SearchOptions, type UseButtonResult, type UseInputResult, type UseMarqueeResult, type UseSearchResult, useButton, useInput, useMarquee, useSearch };

package/dist/react/index.js

@@ -1,6 +1,6 @@
-import { createMarquee, createInput } from '../chunk-W2DRHYC2.js';
+import { createMarquee, createInput, createButton } from '../chunk-WCB7V7XO.js';
 import { createSearch } from '../chunk-UZFEEFMF.js';
-import { useRef, useState, useMemo, useEffect, useLayoutEffect } from 'react';
+import { useRef, useState, useMemo, useEffect, useCallback, useLayoutEffect } from 'react';
 
 var useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
 function useMarquee(options = {}) {
@@ -39,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]);
@@ -130,5 +130,57 @@ function useSearch(options = {}) {
     }
   };
 }
+function useButton(options = {}) {
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const instance = useMemo(() => createButton({
+    ...optionsRef.current,
+    onPress: (event) => optionsRef.current.onPress?.(event),
+    onChange: (next) => optionsRef.current.onChange?.(next)
+    // Built once: recreating it would drop a running cooldown on every render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }), []);
+  const [state, setState] = useState(() => instance.state);
+  useEffect(() => {
+    const unsubscribe = instance.subscribe(setState);
+    setState(instance.state);
+    return () => {
+      unsubscribe();
+      instance.destroy();
+    };
+  }, [instance]);
+  useEffect(() => {
+    instance.update({
+      href: options.href,
+      disabled: options.disabled,
+      loading: options.loading,
+      cooldown: options.cooldown,
+      shortcut: options.shortcut
+    });
+  }, [instance, options.href, options.disabled, options.loading, options.cooldown, options.shortcut]);
+  const press = useCallback(() => {
+    void instance.press();
+  }, [instance]);
+  return {
+    ...state,
+    press,
+    reset: () => instance.reset(),
+    props: {
+      onClick: (event) => {
+        if (!state.available) {
+          event.preventDefault();
+          return;
+        }
+        void instance.press();
+      },
+      "aria-disabled": !state.available,
+      "aria-busy": state.loading,
+      ...state.loading ? { "data-loading": "" } : {},
+      ...state.cooldown > 0 ? { "data-cooldown": "" } : {},
+      ...state.element === "button" ? { disabled: state.disabled } : { href: options.href },
+      ...state.shortcut ? { title: `Shortcut: ${state.shortcut.toUpperCase()}` } : {}
+    }
+  };
+}
 
-export { useInput, useMarquee, useSearch };
+export { useButton, useInput, useMarquee, useSearch };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enigmax/primitives",
-  "version": "0.4.0",
+  "version": "0.6.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",

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

@@ -245,6 +245,61 @@
       "dependencies": {
         "fuse.js": "^7.0.0"
       }
+    },
+    {
+      "name": "button",
+      "title": "Button behaviour",
+      "description": "Disabled, loading, a keyboard shortcut and a cooldown that can outlive a reload, collapsed into one `available` the renderer reads. An href reports an anchor rather than a button, so the framework's own Link stays your choice.",
+      "targets": [
+        "vanilla",
+        "astro",
+        "react"
+      ],
+      "entry": {
+        "vanilla": "@enigmax/primitives",
+        "astro": "@enigmax/primitives",
+        "react": "@enigmax/primitives/react"
+      },
+      "exports": {
+        "vanilla": [
+          "createButton"
+        ],
+        "astro": [
+          "createButton"
+        ],
+        "react": [
+          "useButton"
+        ]
+      },
+      "files": [
+        {
+          "path": "src/core/button.ts",
+          "dest": "button.ts",
+          "targets": [
+            "vanilla",
+            "astro",
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/use-button.ts",
+          "dest": "use-button.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/button": "./button"
+          }
+        }
+      ],
+      "styles": false,
+      "themeHooks": [
+        "[data-loading]",
+        "[data-cooldown]",
+        "[aria-disabled=true]",
+        "[aria-busy=true]"
+      ],
+      "docs": "docs/notes/primitives.md#button"
     }
   ]
 }

package/src/core/button.ts

@@ -0,0 +1,238 @@
+/**
+ * Button behaviour: what makes it unavailable, and everything that follows from that.
+ *
+ * Disabled, loading and a cooldown are three reasons for the same state, so they collapse
+ * into one `available` the renderer reads, instead of three flags every call site has to
+ * combine correctly. The element to render is reported rather than chosen, because a
+ * framework-agnostic package cannot import next/link.
+ */
+
+/** Which tag the consumer should render. An href makes it a link, and a link is not a button. */
+export type ButtonElement = "button" | "a";
+
+export interface ButtonCooldown {
+    /** How long the button stays unavailable after a press, in ms. */
+    ms: number;
+    /**
+     * Survive a reload under this key. Without it the cooldown is in memory only, and a
+     * refresh is a free retry - which is the whole thing a cooldown exists to prevent.
+     */
+    key?: string;
+    storage?: "local" | "session";
+}
+
+export interface ButtonOptions {
+    /** Turns into an `a`, and a link cannot be `disabled` - only `aria-disabled`. */
+    href?: string;
+    disabled?: boolean;
+    /** Unavailable and busy. Set it yourself, or let an async `onPress` manage it. */
+    loading?: boolean;
+    /** ms, or the full shape for a cooldown that outlives a reload. */
+    cooldown?: number | ButtonCooldown;
+    /**
+     * A single key that presses the button. Ignored while the visitor is typing, and
+     * while any modifier is held, so it never steals a real shortcut.
+     */
+    shortcut?: string;
+    /** Async work flips `loading` for its duration and only then starts the cooldown. */
+    onPress?: (event?: Event) => void | Promise<void>;
+    /** Called whenever anything below changes. */
+    onChange?: (state: ButtonState) => void;
+}
+
+export interface ButtonState {
+    /** The tag to render. */
+    element: ButtonElement;
+    /** Pressable: not disabled, not loading, not cooling down. */
+    available: boolean;
+    loading: boolean;
+    disabled: boolean;
+    /** ms left on the cooldown, 0 when there is none. */
+    cooldown: number;
+    /** The accessible name for the shortcut, when there is one. */
+    shortcut: string | null;
+}
+
+export interface ButtonInstance {
+    readonly state: ButtonState;
+    /** Run the press as if it had been clicked. Ignored while unavailable. */
+    press(event?: Event): Promise<void>;
+    update(options: Partial<ButtonOptions>): void;
+    /** Clear a cooldown early, including its stored entry. */
+    reset(): void;
+    subscribe(listener: (state: ButtonState) => void): () => void;
+    destroy(): void;
+}
+
+const TICK_MS = 100;
+
+function store(cooldown: ButtonCooldown): Storage | null {
+    if (!cooldown.key || typeof window === "undefined") return null;
+    try {
+        const target = cooldown.storage === "local" ? window.localStorage : window.sessionStorage;
+        const probe = "__enigma_probe__";
+        target.setItem(probe, "1");
+        target.removeItem(probe);
+        return target;
+    } catch {
+        // Private-mode Safari exposes the object and throws on write.
+        return null;
+    }
+}
+
+function normalize(cooldown: ButtonOptions["cooldown"]): ButtonCooldown | null {
+    if (cooldown == null) return null;
+    return typeof cooldown === "number" ? { ms: cooldown } : cooldown;
+}
+
+/** A shortcut must not fire while the visitor is writing, or it types into the page. */
+function isTyping(target: EventTarget | null): boolean {
+    const element = target as HTMLElement | null;
+    if (!element) return false;
+    const tag = element.tagName;
+    return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT" || element.isContentEditable === true;
+}
+
+export function createButton(options: ButtonOptions = {}): ButtonInstance {
+    let opts: ButtonOptions = { ...options };
+    let loading = Boolean(opts.loading);
+    let readyAt = 0;
+    let timer: ReturnType<typeof setInterval> | null = null;
+    let destroyed = false;
+    const listeners = new Set<(state: ButtonState) => void>();
+
+    const storageKey = () => {
+        const cooldown = normalize(opts.cooldown);
+        return cooldown?.key ? `enigma:cooldown:${cooldown.key}` : null;
+    };
+
+    function restore(): void {
+        const cooldown = normalize(opts.cooldown);
+        if (!cooldown) return;
+        const target = store(cooldown);
+        const key = storageKey();
+        if (!target || !key) return;
+        const saved = Number(target.getItem(key));
+        // A stored time in the past is finished, not pending.
+        if (Number.isFinite(saved) && saved > Date.now()) readyAt = saved;
+    }
+
+    function remaining(): number {
+        return Math.max(0, readyAt - Date.now());
+    }
+
+    function snapshot(): ButtonState {
+        const disabled = Boolean(opts.disabled);
+        const cooldown = remaining();
+        return {
+            element: opts.href ? "a" : "button",
+            available: !disabled && !loading && cooldown === 0,
+            loading,
+            disabled,
+            cooldown,
+            shortcut: opts.shortcut ?? null
+        };
+    }
+
+    function emit(): void {
+        const state = snapshot();
+        opts.onChange?.(state);
+        for (const listener of listeners) listener(state);
+    }
+
+    function stopTicking(): void {
+        if (timer === null) return;
+        clearInterval(timer);
+        timer = null;
+    }
+
+    function startTicking(): void {
+        if (timer !== null || remaining() === 0) return;
+        timer = setInterval(() => {
+            if (remaining() > 0) { emit(); return; }
+            stopTicking();
+            emit();
+        }, TICK_MS);
+    }
+
+    function beginCooldown(): void {
+        const cooldown = normalize(opts.cooldown);
+        if (!cooldown || cooldown.ms <= 0) return;
+        readyAt = Date.now() + cooldown.ms;
+        const target = store(cooldown);
+        const key = storageKey();
+        if (target && key) {
+            try { target.setItem(key, String(readyAt)); } catch { /* quota */ }
+        }
+        startTicking();
+    }
+
+    async function press(event?: Event): Promise<void> {
+        if (destroyed || !snapshot().available) return;
+        const result = opts.onPress?.(event);
+
+        if (result instanceof Promise) {
+            loading = true;
+            emit();
+            try {
+                await result;
+            } finally {
+                loading = false;
+                // The cooldown starts when the work FINISHES, not when it was asked for -
+                // otherwise a slow request eats its own cooldown and the button is free
+                // again the moment it returns.
+                beginCooldown();
+                emit();
+            }
+            return;
+        }
+
+        beginCooldown();
+        emit();
+    }
+
+    function onKeyDown(event: KeyboardEvent): void {
+        if (!opts.shortcut || isTyping(event.target)) return;
+        if (event.ctrlKey || event.metaKey || event.altKey || event.shiftKey) return;
+        if (event.key.toLowerCase() !== opts.shortcut.toLowerCase()) return;
+        if (!snapshot().available) return;
+        event.preventDefault();
+        void press(event);
+    }
+
+    if (typeof window !== "undefined") {
+        restore();
+        startTicking();
+        window.addEventListener("keydown", onKeyDown);
+    }
+
+    return {
+        get state() { return snapshot(); },
+        press,
+        update(next: Partial<ButtonOptions>) {
+            const hadCooldown = JSON.stringify(normalize(opts.cooldown));
+            opts = { ...opts, ...next };
+            if (next.loading !== undefined) loading = Boolean(next.loading);
+            if (JSON.stringify(normalize(opts.cooldown)) !== hadCooldown) restore();
+            emit();
+        },
+        reset() {
+            readyAt = 0;
+            stopTicking();
+            const cooldown = normalize(opts.cooldown);
+            const key = storageKey();
+            if (cooldown && key) store(cooldown)?.removeItem(key);
+            emit();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        destroy() {
+            destroyed = true;
+            stopTicking();
+            listeners.clear();
+            if (typeof window !== "undefined") window.removeEventListener("keydown", onKeyDown);
+        }
+    };
+}

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,4 @@
-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";
+export { createButton, type ButtonOptions, type ButtonInstance, type ButtonState, type ButtonElement, type ButtonCooldown } from "@/core/button";

package/src/react/index.ts

@@ -1,6 +1,8 @@
 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";
 export { type SearchOptions, type SearchMatch, type FuseConstructor } from "@/core/search";
+export { useButton, type UseButtonResult } from "@/react/use-button";
+export { type ButtonOptions, type ButtonState } from "@/core/button";

package/src/react/use-button.ts

@@ -0,0 +1,89 @@
+import { useRef, useMemo, useEffect, useState, useCallback } from "react";
+import { createButton, type ButtonOptions, type ButtonState } from "@/core/button";
+
+export interface UseButtonResult extends ButtonState {
+    /** Spread onto the element named by `element`. */
+    props: {
+        onClick: (event: { preventDefault(): void; }) => void;
+        "aria-disabled": boolean;
+        "aria-busy": boolean;
+        "data-loading"?: "";
+        "data-cooldown"?: "";
+        /** Only on a real button: an anchor has no `disabled`. */
+        disabled?: boolean;
+        href?: string;
+        title?: string;
+    };
+    press: () => void;
+    reset: () => void;
+}
+
+/**
+ * Button behaviour: disabled, loading, a cooldown and a keyboard shortcut collapsed into
+ * one `available`, plus the attributes that follow from it.
+ *
+ * ```tsx
+ * const { element: Tag, props, loading, cooldown } = useButton({
+ *     cooldown: { ms: 30_000, key: "resend-code", storage: "local" },
+ *     shortcut: "r",
+ *     onPress: () => resendCode()
+ * });
+ *
+ * return <Tag {...props}>{loading ? "Sending" : cooldown ? `Wait ${Math.ceil(cooldown / 1000)}s` : "Resend"}</Tag>;
+ * ```
+ */
+export function useButton(options: ButtonOptions = {}): UseButtonResult {
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+
+    const instance = useMemo(() => createButton({
+        ...optionsRef.current,
+        onPress: (event) => optionsRef.current.onPress?.(event),
+        onChange: (next) => optionsRef.current.onChange?.(next)
+    // Built once: recreating it would drop a running cooldown on every render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    }), []);
+
+    const [state, setState] = useState<ButtonState>(() => instance.state);
+
+    useEffect(() => {
+        const unsubscribe = instance.subscribe(setState);
+        setState(instance.state);
+        return () => {
+            unsubscribe();
+            instance.destroy();
+        };
+    }, [instance]);
+
+    useEffect(() => {
+        instance.update({
+            href: options.href,
+            disabled: options.disabled,
+            loading: options.loading,
+            cooldown: options.cooldown,
+            shortcut: options.shortcut
+        });
+    }, [instance, options.href, options.disabled, options.loading, options.cooldown, options.shortcut]);
+
+    const press = useCallback(() => { void instance.press(); }, [instance]);
+
+    return {
+        ...state,
+        press,
+        reset: () => instance.reset(),
+        props: {
+            onClick: (event) => {
+                // An unavailable link still receives clicks - aria-disabled is advisory -
+                // so the press is refused here rather than relying on the attribute.
+                if (!state.available) { event.preventDefault(); return; }
+                void instance.press();
+            },
+            "aria-disabled": !state.available,
+            "aria-busy": state.loading,
+            ...(state.loading ? { "data-loading": "" as const } : {}),
+            ...(state.cooldown > 0 ? { "data-cooldown": "" as const } : {}),
+            ...(state.element === "button" ? { disabled: state.disabled } : { href: options.href }),
+            ...(state.shortcut ? { title: `Shortcut: ${state.shortcut.toUpperCase()}` } : {})
+        }
+    };
+}

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(() => {