@perxel/spotlight 0.0.0-stage → 0.1.1

package/dist/liquid/panel.d.ts

@@ -0,0 +1,8 @@
+import "./liquid.css";
+import type { PanelProps } from "../types.js";
+/**
+ * The liquid panel: a floating card on desktop (non-modal: the page stays usable), a bottom sheet
+ * on phones (dim backdrop, swipe down to close, the page behind does not scroll). The header and
+ * composer float over the conversation as glass; it scrolls under them.
+ */
+export default function LiquidPanel({ open, onOpenChange }: PanelProps): import("react").JSX.Element;

package/dist/liquid/panel.js

@@ -0,0 +1,186 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import "./liquid.css";
+import * as Dialog from "@radix-ui/react-dialog";
+import { Suspense, useEffect, useRef, useState } from "react";
+import { Chat } from "../chat/parts.js";
+import { useAskChat } from "../chat/useAskChat.js";
+import { useSpotlight } from "../react/provider.js";
+import { useLiquid } from "./context.js";
+import { ArrowDownIcon, ArrowLeftIcon, ArrowUpIcon, ArrowUpRightIcon, ChevronDownIcon, FileTextIcon, SquareIcon, SquarePenIcon, XIcon } from "./icons.js";
+import { cx, PHONE_QUERY, useMedia } from "./util.js";
+/**
+ * The liquid panel: a floating card on desktop (non-modal: the page stays usable), a bottom sheet
+ * on phones (dim backdrop, swipe down to close, the page behind does not scroll). The header and
+ * composer float over the conversation as glass; it scrolls under them.
+ */
+export default function LiquidPanel({ open, onOpenChange }) {
+    const liquid = useLiquid();
+    const s = useSpotlight();
+    const chat = useAskChat({ uiTools: liquid.uiTools ?? [] });
+    const { copy, view } = chat;
+    const phone = useMedia(PHONE_QUERY);
+    const composer = useRef(null);
+    // Desktop: ready for a follow-up after a question or "show" from the gate (also when the panel
+    // was already open, so no open focus runs).
+    const req = s.request;
+    useEffect(() => {
+        if (!req || phone)
+            return;
+        if (req.r.kind === "ask" || req.r.kind === "show")
+            requestAnimationFrame(() => composer.current?.focus({ preventScroll: true }));
+    }, [req?.n]);
+    // Links in answers and sources: in-app ones navigate without a page load; phones close the sheet
+    // (it covers the page), the conversation stays. Streamdown opens links in a new tab: overridden.
+    const local = new Set([...(liquid.localHosts ?? [])]);
+    const onLinkClick = (e) => {
+        if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey)
+            return;
+        const a = e.target.closest?.("a[href]");
+        if (!a || a.hasAttribute("download"))
+            return;
+        if (a.target && a.target !== "_self" && a.dataset.streamdown !== "link")
+            return;
+        const url = new URL(a.href, location.href);
+        if (url.origin !== location.origin && !local.has(url.hostname))
+            return;
+        e.preventDefault();
+        s.navigate(url.pathname + url.search + url.hash, { from: "answer" });
+        if (phone)
+            onOpenChange(false);
+    };
+    const localPath = (href) => {
+        try {
+            const u = new URL(href);
+            return local.has(u.hostname) ? u.pathname + u.search + u.hash : href;
+        }
+        catch {
+            return href;
+        }
+    };
+    const viewport = usePhoneViewport(open && phone);
+    const sheet = useRef(null);
+    const drag = useSheetDrag(sheet, () => onOpenChange(false), open && phone);
+    useEffect(() => {
+        if (!open || !phone)
+            return;
+        const html = document.documentElement;
+        const prev = html.style.overflow;
+        html.style.overflow = "hidden";
+        return () => {
+            html.style.overflow = prev;
+        };
+    }, [open, phone]);
+    // Phones: as tall as the visible screen allows; with the keyboard up, all of what is left.
+    const sheetStyle = viewport
+        ? (() => {
+            const keyboard = viewport.height < window.innerHeight * 0.75;
+            const height = keyboard ? viewport.height : Math.round(viewport.height * 0.92);
+            return { top: viewport.top + viewport.height - height, height };
+        })()
+        : undefined;
+    const [head, setHead] = useState(null);
+    const [foot, setFoot] = useState(null);
+    useOverlayInsets(head, foot);
+    const title = view.kind === "action" ? view.action.title ?? copy.panelTitle : copy.panelTitle;
+    const handoff = liquid.handoff?.(chat);
+    const ActionView = view.kind === "action" ? view.action.view : undefined;
+    return (_jsx(Dialog.Root, { open: open, onOpenChange: onOpenChange, modal: false, children: _jsxs(Dialog.Portal, { children: [phone && _jsx("div", { "aria-hidden": true, onClick: () => onOpenChange(false), "data-state": open ? "open" : "closed", className: cx("sp-backdrop", liquid.className) }), _jsxs(Dialog.Content, { ref: sheet, "data-spotlight-panel": "", "data-status": chat.status, "data-view": view.kind, "aria-describedby": undefined, ...liquid.panelProps, className: cx("sp-panel", liquid.className, liquid.panelProps?.className), style: sheetStyle, onClickCapture: onLinkClick, onInteractOutside: (e) => e.preventDefault(), onOpenAutoFocus: (e) => {
+                        e.preventDefault();
+                        // Desktop: the cursor goes to the composer. Phones: nothing, so the keyboard does not cover the answer.
+                        if (!phone)
+                            composer.current?.focus({ preventScroll: true });
+                    }, children: [_jsxs("div", { ref: setHead, ...drag, className: "sp-panel-head", children: [_jsx("div", { "aria-hidden": true, className: "sp-grab" }), _jsxs("header", { className: "sp-liquid sp-panel-pill", children: [view.kind !== "chat" && (_jsx("button", { type: "button", onClick: chat.back, className: "sp-icon-button sp-back", "aria-label": copy.back, title: copy.back, children: _jsx(ArrowLeftIcon, {}) })), _jsxs(Dialog.Title, { className: "sp-panel-title", children: [view.kind === "chat" && liquid.logo && _jsx("span", { "aria-hidden": true, className: "sp-logo", children: liquid.logo }), _jsx("span", { className: "sp-truncate", children: title })] }), view.kind === "chat" && chat.messages.length > 0 && (_jsx("button", { type: "button", onClick: chat.newChat, className: "sp-icon-button", "aria-label": copy.newChat, title: copy.newChat, children: _jsx(SquarePenIcon, {}) })), _jsx(Dialog.Close, { className: "sp-icon-button", "aria-label": copy.close, children: _jsx(XIcon, {}) })] })] }), ActionView && view.kind === "action" ? (_jsx("div", { className: "sp-view", "data-lenis-prevent": "", children: _jsx(Suspense, { fallback: null, children: _jsx(ActionView, { input: view.input, messages: chat.messages, conversationId: chat.messages.length ? chat.id : null, back: chat.back, close: chat.close }) }) }, view.key)) : (_jsxs(_Fragment, { children: [_jsxs(Chat.Messages, { className: "sp-messages", children: [_jsxs(Chat.Content, { className: "sp-messages-content", viewportProps: { className: "sp-messages-viewport sp-scroll" }, children: [liquid.privacyNote && _jsx("div", { className: "sp-privacy", children: _jsx(Suspense, { fallback: null, children: liquid.privacyNote }) }), chat.messages.map((m, i) => {
+                                                    const text = chat.textOf(m);
+                                                    const sources = m.role === "assistant" ? chat.sourcesOf(m) : [];
+                                                    const action = chat.actionOf(m);
+                                                    if (!text && !sources.length && !action)
+                                                        return null;
+                                                    return (_jsxs("div", { "data-role": m.role, className: cx("sp-message", m.role === "user" && i > 0 && "sp-message-gap"), children: [text && (m.role === "assistant" ? _jsx("div", { className: "sp-answer", children: _jsx(Chat.Markdown, { text: text, className: "sp-md" }) }) : _jsx("p", { className: "sp-bubble", children: text })), sources.length > 0 && (_jsxs("details", { className: "sp-sources", children: [_jsxs("summary", { children: [copy.sources, " (", sources.length, ")", _jsx(ChevronDownIcon, { className: "sp-chevron" })] }), _jsx("div", { className: "sp-sources-list", children: sources.map((src) => (_jsxs("a", { href: localPath(src.url), children: [_jsx(FileTextIcon, {}), _jsx("span", { children: src.title })] }, src.url))) })] })), action && (_jsxs("button", { type: "button", className: "sp-action-row", onClick: () => chat.openAction(action.action, action.input), children: [action.action.label ?? action.action.title ?? action.action.id, _jsx(ArrowUpRightIcon, {})] }))] }, m.id));
+                                                }), chat.waiting && (_jsxs("div", { className: "sp-waiting", role: "status", children: [liquid.logo && _jsx("span", { "aria-hidden": true, className: "sp-logo sp-pulse", children: liquid.logo }), copy.thinking] })), chat.errorCode && !chat.busy && (_jsx("p", { className: "sp-error", role: "alert", children: copy.errors[chat.errorCode] ?? copy.errors.generic })), !chat.busy && handoff && _jsx(Suspense, { fallback: null, children: handoff })] }), _jsx(Chat.ScrollButton, { className: "sp-scroll-button", "aria-label": copy.scrollToEnd, children: _jsx(ArrowDownIcon, {}) })] }), _jsxs(Chat.Composer, { chat: chat, ref: setFoot, className: "sp-panel-foot", textareaProps: { ref: composer, className: "sp-textarea" }, children: [liquid.tide && _jsxs("div", { "aria-hidden": true, className: "sp-tide", children: [_jsx("span", {}), _jsx("span", {}), _jsx("span", {})] }), _jsxs("div", { className: "sp-composer-row", children: [_jsx(Suspense, { fallback: _jsx("span", {}), children: liquid.composerExtra?.(chat) ?? _jsx("span", {}) }), _jsx(Chat.Submit, { chat: chat, className: "sp-fill sp-submit", send: _jsx(ArrowUpIcon, {}), stop: _jsx(SquareIcon, { className: "sp-stop-icon" }) })] })] })] }))] })] }) }));
+}
+/** Writes the floating header's and composer's heights to `--sp-top` / `--sp-bottom` on the panel, so the content rests clear of them. */
+function useOverlayInsets(head, foot) {
+    useEffect(() => {
+        const panel = (head ?? foot)?.closest(".sp-panel");
+        if (!panel)
+            return;
+        const write = () => {
+            panel.style.setProperty("--sp-top", `${head?.offsetHeight ?? 0}px`);
+            panel.style.setProperty("--sp-bottom", `${foot?.offsetHeight ?? 0}px`);
+        };
+        write();
+        const ro = new ResizeObserver(write);
+        if (head)
+            ro.observe(head);
+        if (foot)
+            ro.observe(foot);
+        return () => ro.disconnect();
+    }, [head, foot]);
+}
+/** The visual viewport while `active` (phones with the panel open): it shrinks when the keyboard opens, which `svh`/`dvh` do not. */
+function usePhoneViewport(active) {
+    const [vp, setVp] = useState(null);
+    useEffect(() => {
+        const vv = window.visualViewport;
+        if (!active || !vv) {
+            setVp(null);
+            return;
+        }
+        const update = () => setVp({ top: vv.offsetTop, height: vv.height });
+        update();
+        vv.addEventListener("resize", update);
+        vv.addEventListener("scroll", update);
+        return () => {
+            vv.removeEventListener("resize", update);
+            vv.removeEventListener("scroll", update);
+        };
+    }, [active]);
+    return vp;
+}
+/** Swipe-down-to-close for the phone sheet: pointer handlers for its grab area. */
+function useSheetDrag(sheet, close, enabled) {
+    const start = useRef(null);
+    const dy = useRef(0);
+    const set = (y, animate) => {
+        const el = sheet.current;
+        if (!el)
+            return;
+        el.style.transition = animate ? "transform 200ms ease-out" : "none";
+        el.style.transform = y ? `translateY(${y}px)` : "";
+    };
+    useEffect(() => {
+        if (enabled)
+            set(0, false);
+    }, [enabled]);
+    if (!enabled)
+        return {};
+    return {
+        onPointerDown: (e) => {
+            if (e.target.closest("button"))
+                return;
+            start.current = e.clientY;
+            dy.current = 0;
+            e.currentTarget.setPointerCapture(e.pointerId);
+        },
+        onPointerMove: (e) => {
+            if (start.current === null)
+                return;
+            dy.current = Math.max(0, e.clientY - start.current);
+            set(dy.current, false);
+        },
+        onPointerUp: () => {
+            if (start.current === null)
+                return;
+            start.current = null;
+            if (dy.current > 80)
+                close();
+            else
+                set(0, true);
+        },
+        onPointerCancel: () => {
+            start.current = null;
+            set(0, true);
+        },
+    };
+}

package/dist/liquid/util.d.ts

@@ -0,0 +1,6 @@
+/** Below this the panel is a bottom sheet and the gate sits near the top edge (matches the CSS). */
+export declare const PHONE_QUERY = "(max-width: 1023.98px)";
+export declare const REDUCED_MOTION = "(prefers-reduced-motion: reduce)";
+export declare function cx(...parts: (string | false | null | undefined)[]): string;
+/** A media query, `false` on the server and during hydration. */
+export declare function useMedia(query: string): boolean;

package/dist/liquid/util.js

@@ -0,0 +1,16 @@
+"use client";
+import { useSyncExternalStore } from "react";
+/** Below this the panel is a bottom sheet and the gate sits near the top edge (matches the CSS). */
+export const PHONE_QUERY = "(max-width: 1023.98px)";
+export const REDUCED_MOTION = "(prefers-reduced-motion: reduce)";
+export function cx(...parts) {
+    return parts.filter(Boolean).join(" ");
+}
+/** A media query, `false` on the server and during hydration. */
+export function useMedia(query) {
+    return useSyncExternalStore((cb) => {
+        const m = matchMedia(query);
+        m.addEventListener("change", cb);
+        return () => m.removeEventListener("change", cb);
+    }, () => matchMedia(query).matches, () => false);
+}

package/dist/react/index.d.ts

@@ -0,0 +1,6 @@
+export { SpotlightProvider, Trigger, useSpotlight, isMac, shortcutLabel, defaultNavigate, type SpotlightState } from "./provider.js";
+export { localStorageAdapter, noPersist } from "../core/storage.js";
+export { fold, emailIn } from "../core/fold.js";
+export { turnstileWidget, type TurnstileWidget, type TurnstileWidgetOptions } from "./turnstile.js";
+export { defineAction } from "../types.js";
+export type * from "../types.js";

package/dist/react/index.js

@@ -0,0 +1,10 @@
+// `@perxel/spotlight/react`: what a page's first load needs, and nothing more. The provider (state,
+// the shortcut, lazy loading of the gate and panel modules, the iOS keyboard bridge), a trigger,
+// `useSpotlight`. No styling: state is in `data-*` attributes. The gate's parts are in
+// `@perxel/spotlight/gate` and the chat's in `@perxel/spotlight/chat`: import those only from the
+// lazily loaded gate and panel modules.
+export { SpotlightProvider, Trigger, useSpotlight, isMac, shortcutLabel, defaultNavigate } from "./provider.js";
+export { localStorageAdapter, noPersist } from "../core/storage.js";
+export { fold, emailIn } from "../core/fold.js";
+export { turnstileWidget } from "./turnstile.js";
+export { defineAction } from "../types.js";

package/dist/react/provider.d.ts

@@ -0,0 +1,52 @@
+import { type ButtonHTMLAttributes, type ReactNode } from "react";
+import type { Action, AskConfig, Navigate, PersistAdapter, SearchConfig, SpotlightCopy, SpotlightMode, SpotlightProps, SpotlightRequest } from "../types.js";
+/** Everything the gate, the panel and the triggers read. */
+export interface SpotlightState {
+    mode: SpotlightMode;
+    /** On and with something to show: triggers render, the shortcut is bound. */
+    available: boolean;
+    search: SearchConfig | undefined;
+    ask: AskConfig | undefined;
+    actions: Action[];
+    /** The site's copy overrides; the gate and the panel merge them with the English defaults (`mergeCopy`), so the defaults stay out of first load. */
+    copy: Partial<SpotlightCopy>;
+    navigate: Navigate;
+    /** Where the conversation is kept (`ask.persist`, default `localStorage`). */
+    persist: PersistAdapter;
+    gateOpen: boolean;
+    /** Open the gate. Call it inside the click or key handler: iOS opens the keyboard only inside the gesture. */
+    openGate: () => void;
+    closeGate: () => void;
+    setGateOpen: (open: boolean) => void;
+    panelOpen: boolean;
+    setPanelOpen: (open: boolean) => void;
+    /** Start downloading the gate (pointer enter, focus, touch start on a trigger). */
+    prefetch: () => void;
+    /** From the gate: close it and give the panel its job. */
+    handOff: (request: SpotlightRequest) => void;
+    /** The panel's current job; `n` changes with every new one. */
+    request: {
+        n: number;
+        r: SpotlightRequest;
+    } | null;
+    /** The gate closed by itself (Escape, outside, the shortcut): focus goes back where it was. */
+    restoreFocus: () => void;
+}
+/** The provider's state. Outside a provider: an unavailable stub, so a trigger renders nothing. */
+export declare function useSpotlight(): SpotlightState;
+/** Apple keyboard: the shortcut is ⌘ there, Ctrl elsewhere. Client only. */
+export declare function isMac(): boolean;
+/** The shortcut as shown to the visitor ("⌘K", "Ctrl K"); `null` when off. Client only. */
+export declare function shortcutLabel(shortcut?: string | false): string | null;
+/** Default navigation: a hash on this page scrolls; another site opens in a new tab; anything else is a page load. */
+export declare const defaultNavigate: Navigate;
+export declare function SpotlightProvider({ search, ask, actions, gate, panel, navigate, shortcut, enabled, copy, prefetch: prefetchWhen, children, }: SpotlightProps): import("react").JSX.Element;
+/**
+ * A headless trigger: a `<button>` that opens the gate and prefetches it on pointer enter, focus
+ * and touch. Renders nothing while Spotlight is unavailable, unless `always` (for a trigger that
+ * must be in the server HTML, so the layout never shifts).
+ */
+export declare function Trigger({ children, always, onClick, ...props }: ButtonHTMLAttributes<HTMLButtonElement> & {
+    always?: boolean;
+    children?: ReactNode;
+}): import("react").JSX.Element | null;

package/dist/react/provider.js

@@ -0,0 +1,218 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, lazy, Suspense, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { localStorageAdapter } from "../core/storage.js";
+const SpotlightContext = createContext(null);
+/** The provider's state. Outside a provider: an unavailable stub, so a trigger renders nothing. */
+export function useSpotlight() {
+    return useContext(SpotlightContext) ?? STUB;
+}
+const noop = () => { };
+const STUB = {
+    mode: "none",
+    available: false,
+    search: undefined,
+    ask: undefined,
+    actions: [],
+    copy: {},
+    navigate: noop,
+    persist: { read: () => null, write: noop },
+    gateOpen: false,
+    openGate: noop,
+    closeGate: noop,
+    setGateOpen: noop,
+    panelOpen: false,
+    setPanelOpen: noop,
+    prefetch: noop,
+    handOff: noop,
+    request: null,
+    restoreFocus: noop,
+};
+/** Apple keyboard: the shortcut is ⌘ there, Ctrl elsewhere. Client only. */
+export function isMac() {
+    const nav = navigator;
+    return /mac|iphone|ipad|ipod/i.test(nav.userAgentData?.platform || nav.platform || nav.userAgent);
+}
+/** The shortcut as shown to the visitor ("⌘K", "Ctrl K"); `null` when off. Client only. */
+export function shortcutLabel(shortcut = "mod+k") {
+    if (!shortcut)
+        return null;
+    const key = shortcut.split("+").at(-1).toUpperCase();
+    return isMac() ? `⌘${key}` : `Ctrl ${key}`;
+}
+/** Default navigation: a hash on this page scrolls; another site opens in a new tab; anything else is a page load. */
+export const defaultNavigate = (url, { newTab }) => {
+    if (newTab || new URL(url, location.href).origin !== location.origin) {
+        window.open(url, "_blank", "noopener");
+        return;
+    }
+    const u = new URL(url, location.href);
+    if (u.origin === location.origin && u.pathname === location.pathname && u.search === location.search && u.hash) {
+        location.hash = u.hash;
+        return;
+    }
+    location.assign(u.href);
+};
+function useLazy(loader) {
+    // One lazy component per loader: pass a stable (module-level) loader.
+    return useMemo(() => (loader ? lazy(loader) : null), [loader]);
+}
+/** True once the page is idle after load (`delay` ms), or at the first input, whichever comes first. */
+function useIdle(delay) {
+    const [idle, setIdle] = useState(false);
+    useEffect(() => {
+        if (delay === false)
+            return;
+        let timer;
+        const wake = () => setIdle(true);
+        const events = ["pointerdown", "keydown", "wheel", "touchstart", "scroll"];
+        const start = () => {
+            timer = setTimeout(wake, delay);
+        };
+        if (document.readyState === "complete")
+            start();
+        else
+            window.addEventListener("load", start, { once: true });
+        for (const e of events)
+            window.addEventListener(e, wake, { once: true, passive: true });
+        return () => {
+            clearTimeout(timer);
+            window.removeEventListener("load", start);
+            for (const e of events)
+                window.removeEventListener(e, wake);
+        };
+    }, [delay]);
+    return idle;
+}
+export function SpotlightProvider({ search, ask, actions = [], gate, panel, navigate = defaultNavigate, shortcut = "mod+k", enabled = true, copy, prefetch: prefetchWhen = true, children, }) {
+    const mode = search && ask ? "both" : search ? "search" : ask ? "ask" : "none";
+    const available = enabled && mode !== "none";
+    const merged = useMemo(() => copy ?? {}, [copy]);
+    const persist = useMemo(() => (ask?.persist === false ? { read: () => null, write: () => { } } : ask?.persist ?? localStorageAdapter()), [ask?.persist]);
+    if (ask && !panel && typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+        console.warn("[spotlight] `ask` is set but no `panel` module: questions have nowhere to go. Pass `panel` (or use a skin).");
+    }
+    const Gate = useLazy(gate);
+    const Panel = useLazy(ask ? panel : undefined);
+    const [panelOpen, setPanelOpenRaw] = useState(false);
+    // Once opened, the panel stays mounted (hidden when closed) so the conversation survives.
+    const [panelMounted, setPanelMounted] = useState(false);
+    const setPanelOpen = useCallback((next) => {
+        if (next)
+            setPanelMounted(true);
+        setPanelOpenRaw(next);
+    }, []);
+    const [gateOpen, setGateOpenRaw] = useState(false);
+    const [gateMounted, setGateMounted] = useState(false);
+    const [request, setRequest] = useState(null);
+    const prefetch = useCallback(() => {
+        void gate().catch(() => undefined);
+    }, [gate]);
+    const idle = useIdle(prefetchWhen === false ? false : prefetchWhen === true ? 1500 : prefetchWhen);
+    useEffect(() => {
+        if (idle && available)
+            prefetch();
+    }, [idle, available, prefetch]);
+    // iOS opens the keyboard only for a focus inside the tap itself, and the gate may still be
+    // loading then. So the tap focuses this always-present field, and the gate moves the focus to
+    // its own input once mounted (iOS keeps the keyboard up across that move).
+    const bridge = useRef(null);
+    const returnFocus = useRef(null);
+    const askRef = useRef(ask);
+    askRef.current = ask;
+    const openGate = useCallback(() => {
+        const active = document.activeElement;
+        if (active !== bridge.current && !active?.closest("[data-spotlight-gate]"))
+            returnFocus.current = active;
+        bridge.current?.focus({ preventScroll: true });
+        setGateMounted(true);
+        setGateOpenRaw(true);
+        if (panel && askRef.current)
+            void panel().catch(() => undefined);
+        void Promise.resolve(askRef.current?.prepare?.()).catch(() => undefined);
+    }, [panel]);
+    const closeGate = useCallback(() => setGateOpenRaw(false), []);
+    const setGateOpen = useCallback((open) => (open ? openGate() : closeGate()), [openGate, closeGate]);
+    const restoreFocus = useCallback(() => {
+        const el = returnFocus.current;
+        returnFocus.current = null;
+        if (el && el !== document.body && el.isConnected)
+            el.focus({ preventScroll: true });
+        else
+            bridge.current?.blur();
+    }, []);
+    const handOff = useCallback((r) => {
+        returnFocus.current = null;
+        setGateOpenRaw(false);
+        setRequest((prev) => ({ n: (prev?.n ?? 0) + 1, r }));
+        setPanelOpen(true);
+    }, [setPanelOpen]);
+    // The shortcut opens the gate from anywhere, even from a text field or over the open panel;
+    // pressed again it closes the gate, like Spotlight.
+    const gateOpenRef = useRef(gateOpen);
+    gateOpenRef.current = gateOpen;
+    useEffect(() => {
+        if (!available || !shortcut)
+            return;
+        const key = shortcut.split("+").at(-1).toLowerCase();
+        const mac = isMac();
+        const onKey = (e) => {
+            if (e.key.toLowerCase() !== key || e.altKey || e.shiftKey)
+                return;
+            if (mac ? !e.metaKey || e.ctrlKey : !e.ctrlKey || e.metaKey)
+                return;
+            e.preventDefault();
+            if (gateOpenRef.current)
+                setGateOpenRaw(false);
+            else
+                openGate();
+        };
+        window.addEventListener("keydown", onKey);
+        return () => window.removeEventListener("keydown", onKey);
+    }, [available, shortcut, openGate]);
+    const value = useMemo(() => ({
+        mode,
+        available,
+        search,
+        ask,
+        actions,
+        copy: merged,
+        navigate,
+        persist,
+        gateOpen,
+        openGate,
+        closeGate,
+        setGateOpen,
+        panelOpen,
+        setPanelOpen,
+        prefetch,
+        handOff,
+        request,
+        restoreFocus,
+    }), [mode, available, search, ask, actions, merged, navigate, persist, gateOpen, openGate, closeGate, setGateOpen, panelOpen, setPanelOpen, prefetch, handOff, request, restoreFocus]);
+    return (_jsxs(SpotlightContext.Provider, { value: value, children: [children, available && (_jsx("input", { ref: bridge, "aria-hidden": true, tabIndex: -1, "data-spotlight-bridge": "", style: { position: "fixed", top: 0, left: 0, width: 1, height: 1, fontSize: 16, opacity: 0, pointerEvents: "none", border: 0, padding: 0 } })), available && gateMounted && Gate && (_jsx(Suspense, { fallback: null, children: _jsx(Gate, { open: gateOpen, onOpenChange: setGateOpen }) })), available && ask && panelMounted && Panel && (_jsx(Suspense, { fallback: null, children: _jsx(Panel, { open: panelOpen, onOpenChange: setPanelOpen }) }))] }));
+}
+/**
+ * A headless trigger: a `<button>` that opens the gate and prefetches it on pointer enter, focus
+ * and touch. Renders nothing while Spotlight is unavailable, unless `always` (for a trigger that
+ * must be in the server HTML, so the layout never shifts).
+ */
+export function Trigger({ children, always, onClick, ...props }) {
+    const s = useSpotlight();
+    if (!s.available && !always)
+        return null;
+    return (_jsx("button", { type: "button", "aria-haspopup": "dialog", "data-spotlight-trigger": "", ...props, onClick: (e) => {
+            onClick?.(e);
+            if (!e.defaultPrevented)
+                s.openGate();
+        }, onPointerEnter: (e) => {
+            props.onPointerEnter?.(e);
+            s.prefetch();
+        }, onFocus: (e) => {
+            props.onFocus?.(e);
+            s.prefetch();
+        }, onTouchStart: (e) => {
+            props.onTouchStart?.(e);
+            s.prefetch();
+        }, children: children }));
+}

package/dist/react/turnstile.d.ts

@@ -0,0 +1,16 @@
+export interface TurnstileWidgetOptions {
+    siteKey: string;
+    /** The widget's language (`auto` by default). */
+    language?: string;
+    /** Class on the container the widget renders into (appended to `<body>`): place its checkbox. */
+    className?: string;
+}
+export interface TurnstileWidget {
+    /** Load the script and start on a token. Safe to call often. */
+    prepare: () => void;
+    /** A fresh token (waits for one if none is ready); `undefined` if Turnstile failed. */
+    token: () => Promise<string | undefined>;
+    /** Remove the widget and its container. */
+    dispose: () => void;
+}
+export declare function turnstileWidget({ siteKey, language, className }: TurnstileWidgetOptions): TurnstileWidget;

package/dist/react/turnstile.js

@@ -0,0 +1,100 @@
+// Cloudflare Turnstile in the browser, for `ask.prepare` and `ask.body`: the script is injected
+// only when `prepare()` first runs (the gate opening), the widget runs invisibly
+// ("interaction-only": a checkbox shows only when Cloudflare is unsure). A token is single use;
+// `token()` hands the ready one over and the widget starts on the next.
+//
+//   const bot = turnstileWidget({siteKey})
+//   ask={{endpoint: "/api/ask", prepare: bot.prepare, body: async () => ({turnstileToken: await bot.token()})}}
+//
+// Pairs with `turnstile({secret})` from `@perxel/spotlight/server`.
+const SRC = "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit";
+let loading = null;
+function load() {
+    const w = window;
+    if (w.turnstile)
+        return Promise.resolve(w.turnstile);
+    loading ??= new Promise((resolve, reject) => {
+        const script = document.createElement("script");
+        script.src = SRC;
+        script.async = true;
+        script.onload = () => (w.turnstile ? resolve(w.turnstile) : reject(new Error("turnstile")));
+        script.onerror = () => {
+            loading = null;
+            reject(new Error("turnstile"));
+        };
+        document.head.appendChild(script);
+    });
+    return loading;
+}
+export function turnstileWidget({ siteKey, language = "auto", className }) {
+    let el = null;
+    let widgetId = null;
+    let ready = null;
+    let token = null;
+    let waiting = [];
+    const start = () => {
+        if (ready)
+            return ready;
+        el = document.createElement("div");
+        el.dataset.spotlightTurnstile = "";
+        if (className)
+            el.className = className;
+        else
+            Object.assign(el.style, { position: "fixed", left: "50%", bottom: "16px", transform: "translateX(-50%)", zIndex: "2147483000" });
+        document.body.appendChild(el);
+        ready = load().then((api) => {
+            widgetId = api.render(el, {
+                sitekey: siteKey,
+                appearance: "interaction-only",
+                language,
+                callback: (t) => {
+                    const next = waiting.shift();
+                    if (next) {
+                        next(t);
+                        api.reset(widgetId);
+                    }
+                    else
+                        token = t;
+                },
+                "error-callback": () => {
+                    for (const w of waiting)
+                        w(undefined);
+                    waiting = [];
+                },
+            });
+            return api;
+        });
+        ready.catch(() => {
+            for (const w of waiting)
+                w(undefined);
+            waiting = [];
+        });
+        return ready;
+    };
+    return {
+        prepare: () => void start().catch(() => undefined),
+        async token() {
+            const api = await start().catch(() => null);
+            if (!api)
+                return undefined;
+            if (token) {
+                const t = token;
+                token = null;
+                if (widgetId)
+                    api.reset(widgetId); // the next call gets a fresh one
+                return t;
+            }
+            return new Promise((resolve) => waiting.push(resolve));
+        },
+        dispose() {
+            const w = window;
+            if (widgetId)
+                w.turnstile?.remove(widgetId);
+            el?.remove();
+            el = null;
+            ready = null;
+            widgetId = null;
+            token = null;
+        },
+    };
+}