@haruhimemoe/ui 0.6.0 → 0.8.0

package/dist/components/forms/RadioGroup.d.ts

@@ -7,7 +7,7 @@
  *       native radios do. Controlled (`value`) or uncontrolled (`defaultValue`).
  * @author David @dvhsh (https://dvh.sh)
  * @created Mon Sep 28, 2026
- * @modified Mon Sep 28, 2026
+ * @modified Sat Oct 3, 2026
  */
 import { type ComponentProps, type ReactNode } from "react";
 /** One radio: its value, its label, an optional inline hint, and whether it can be picked. */

package/dist/components/forms/RadioGroup.js

@@ -7,7 +7,7 @@
  *       native radios do. Controlled (`value`) or uncontrolled (`defaultValue`).
  * @author David @dvhsh (https://dvh.sh)
  * @created Mon Sep 28, 2026
- * @modified Mon Sep 28, 2026
+ * @modified Sat Oct 3, 2026
  */
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
@@ -27,6 +27,8 @@ export function RadioGroup({ label, options, name, value, defaultValue, onChange
                 const optionId = `${id}-${i}`;
                 return (_jsxs("label", { className: "flex items-start gap-2 text-sm", children: [_jsx("input", { type: "radio", id: optionId, name: name ?? id, value: option.value, ...(value === undefined
                                 ? { defaultChecked: option.value === defaultValue }
-                                : { checked: option.value === value }), disabled: option.disabled, required: required, "aria-invalid": error ? true : undefined, "aria-labelledby": `${optionId}-label`, "aria-describedby": option.hint ? hintId(optionId) : undefined, onChange: () => onChange?.(option.value), className: "mt-1 accent-h1" }), _jsxs("span", { children: [_jsx("span", { id: `${optionId}-label`, className: "font-bold text-c1", children: option.label }), option.hint ? (_jsxs("span", { className: "text-c3", children: [" · ", _jsx("span", { id: hintId(optionId), children: option.hint })] })) : null] })] }, option.value));
+                                : { checked: option.value === value }), disabled: option.disabled, required: required, "aria-labelledby": `${optionId}-label`, "aria-describedby": option.hint ? hintId(optionId) : undefined, onChange: () => onChange?.(option.value), 
+                            // 24px, the WCAG 2.2 target size; -mt-0.5 centers it on the first text-sm line.
+                            className: "-mt-0.5 size-6 shrink-0 accent-h1" }), _jsxs("span", { children: [_jsx("span", { id: `${optionId}-label`, className: "font-bold text-c1", children: option.label }), option.hint ? (_jsxs("span", { className: "text-c3", children: [" · ", _jsx("span", { id: hintId(optionId), children: option.hint })] })) : null] })] }, option.value));
             }), hint ? (_jsx("div", { id: hintId(id), className: "text-c4 text-xs", children: hint })) : null, _jsx(FieldError, { id: id, error: error })] }));
 }

package/dist/components/forms/ReportDisclosure.d.ts

@@ -6,7 +6,7 @@
  *       at a time; a throw reads as `failedMessage`. Moved from bb.haruhime.moe (ReportForm).
  * @author David @dvhsh (https://dvh.sh)
  * @created Mon Sep 28, 2026
- * @modified Mon Sep 28, 2026
+ * @modified Sat Oct 3, 2026
  */
 import { type ReactNode } from "react";
 /** What `onSubmit` says: done (with what to say) or not (with the error). */

package/dist/components/forms/ReportDisclosure.js

@@ -6,11 +6,11 @@
  *       at a time; a throw reads as `failedMessage`. Moved from bb.haruhime.moe (ReportForm).
  * @author David @dvhsh (https://dvh.sh)
  * @created Mon Sep 28, 2026
- * @modified Mon Sep 28, 2026
+ * @modified Sat Oct 3, 2026
  */
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useId, useRef, useState } from "react";
+import { useEffect, useId, useRef, useState } from "react";
 import { cx } from "../../utils/cx.js";
 import { Button } from "../basics/Button.js";
 import { Disclosure } from "../basics/Disclosure.js";
@@ -27,9 +27,13 @@ export function ReportDisclosure({ onSubmit, summary = "Report", label = "What's
     const [error, setError] = useState(null);
     const [done, setDone] = useState(null);
     const running = useRef(false);
-    if (done !== null) {
-        return (_jsx("p", { role: "status", className: cx("text-c2 text-sm", className), children: done }));
-    }
+    const status = useRef(null);
+    // The form goes away with the button that had focus, so focus lands on the outcome instead
+    // of falling to the body.
+    useEffect(() => {
+        if (done !== null)
+            status.current?.focus();
+    }, [done]);
     const send = async (event) => {
         event.preventDefault();
         if (running.current)
@@ -50,5 +54,5 @@ export function ReportDisclosure({ onSubmit, summary = "Report", label = "What's
         running.current = false;
         setPending(false);
     };
-    return (_jsx(Disclosure, { summary: summary, className: className, children: _jsxs("form", { className: "flex flex-col gap-2", onSubmit: send, children: [_jsx(Textarea, { id: `${id}-reason`, label: label, hint: hint, error: error ?? undefined, value: reason, rows: rows, minLength: minLength, maxLength: maxLength, required: true, onChange: (event) => setReason(event.currentTarget.value) }), _jsx(Button, { type: "submit", variant: "secondary", disabled: pending, className: "self-start", children: pending ? pendingLabel : submitLabel })] }) }));
+    return (_jsxs("div", { className: cx("flex flex-col gap-2", className), children: [done === null ? (_jsx(Disclosure, { summary: summary, children: _jsxs("form", { className: "flex flex-col gap-2", onSubmit: send, children: [_jsx(Textarea, { id: `${id}-reason`, label: label, hint: hint, error: error ?? undefined, value: reason, rows: rows, minLength: minLength, maxLength: maxLength, required: true, onChange: (event) => setReason(event.currentTarget.value) }), _jsx(Button, { type: "submit", variant: "secondary", disabled: pending, className: "self-start", children: pending ? pendingLabel : submitLabel })] }) })) : null, _jsx("p", { ref: status, role: "status", tabIndex: -1, className: done === null ? "sr-only" : "text-c2 text-sm", children: done })] }));
 }

package/dist/components/forms/fieldStyles.d.ts

@@ -1,13 +1,12 @@
 /**
  * @file src/components/forms/fieldStyles.ts
- * @desc Shared classes for inputs, selects, and textareas (osu!-web dark fields). Focus shows as
- *       an h1 border. On an invalid field it also gets an h1 ring, since rose to pink alone is
- *       hard to see. `outline-hidden` (not `outline-none`) leaves a transparent outline that
- *       forced-colors mode paints, so focus shows there too. Also the one label look that fields,
- *       groups and filter rows share.
+ *  * @desc Shared field classes for TextInput, Select, Textarea and RangeBox (the packs look), and
+ *       the label class the fieldsets share. Focus is the theme's 2px h1 outline, the same ring
+ *       every control gets, plus an h1 border; an invalid field keeps its rose border until it
+ *       takes focus, when the h1 border and ring take over so focus stays visible.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Mon Sep 28, 2026
+ * @modified Sat Oct 3, 2026
  */
 /** A field or group label: bold c3 at text-sm (internal). */
 export declare const FIELD_LABEL = "font-bold text-c3 text-sm";

package/dist/components/forms/fieldStyles.js

@@ -1,16 +1,15 @@
 /**
  * @file src/components/forms/fieldStyles.ts
- * @desc Shared classes for inputs, selects, and textareas (osu!-web dark fields). Focus shows as
- *       an h1 border. On an invalid field it also gets an h1 ring, since rose to pink alone is
- *       hard to see. `outline-hidden` (not `outline-none`) leaves a transparent outline that
- *       forced-colors mode paints, so focus shows there too. Also the one label look that fields,
- *       groups and filter rows share.
+ *  * @desc Shared field classes for TextInput, Select, Textarea and RangeBox (the packs look), and
+ *       the label class the fieldsets share. Focus is the theme's 2px h1 outline, the same ring
+ *       every control gets, plus an h1 border; an invalid field keeps its rose border until it
+ *       takes focus, when the h1 border and ring take over so focus stays visible.
  * @author David @dvhsh (https://dvh.sh)
  * @created Wed Sep 23, 2026
- * @modified Mon Sep 28, 2026
+ * @modified Sat Oct 3, 2026
  */
 import { cx } from "../../utils/cx.js";
-const FIELD = "w-full rounded-md border border-b3 bg-b6 px-3 py-2 text-c1 text-sm placeholder:text-c4 focus-visible:border-h1 focus-visible:outline-hidden disabled:opacity-50 aria-invalid:border-rose-400 aria-invalid:focus-visible:border-h1 aria-invalid:focus-visible:ring-1 aria-invalid:focus-visible:ring-h1";
+const FIELD = "w-full rounded-md border border-b3 bg-b6 px-3 py-2 text-c1 text-sm placeholder:text-c4 focus-visible:border-h1 disabled:opacity-50 aria-invalid:border-rose-400 aria-invalid:focus-visible:border-h1";
 /** A field or group label: bold c3 at text-sm (internal). */
 export const FIELD_LABEL = "font-bold text-c3 text-sm";
 /**

package/dist/components/osu/BeatmapStats.d.ts

@@ -5,7 +5,7 @@
  *       not finite doesn't show. The short names are `<abbr>`s with the full name as a title.
  * @author David @dvhsh (https://dvh.sh)
  * @created Mon Sep 28, 2026
- * @modified Mon Sep 28, 2026
+ * @modified Sat Oct 3, 2026
  */
 import type { ComponentProps, ReactNode } from "react";
 /** The stats BeatmapStats shows, in order. */

package/dist/components/osu/BeatmapStats.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from "../../utils/cx.js";
-const abbr = (short, full) => _jsx("abbr", { title: full, children: short });
+// The short form shows (and titles a tooltip); screen readers get the full name instead.
+const abbr = (short, full) => (_jsxs("abbr", { title: full, children: [_jsx("span", { "aria-hidden": "true", children: short }), _jsx("span", { className: "sr-only", children: full })] }));
 const LABELS = {
     cs: abbr("CS", "Circle size"),
     ar: abbr("AR", "Approach rate"),

package/dist/components/osu/starColors.d.ts

@@ -5,8 +5,9 @@
  *       They are the same at every --hue, like the wordmark's brand colors.
  * @author David @dvhsh (https://dvh.sh)
  * @created Mon Sep 28, 2026
- * @modified Mon Sep 28, 2026
+ * @modified Sat Oct 3, 2026
  */
+type Rgb = readonly [number, number, number];
 /**
  * @function starRatingColor
  * @param stars {number} a star rating
@@ -14,10 +15,19 @@
  *          straight blend between the two stops around it otherwise
  */
 export declare const starRatingColor: (stars: number) => string;
+/**
+ * @function contrastRatio
+ * @param a {Rgb} one color
+ * @param b {Rgb} the other
+ * @returns {number} the WCAG contrast ratio between them, 1 to 21
+ */
+export declare const contrastRatio: (a: Rgb, b: Rgb) => number;
 /**
  * @function starRatingTextColor
- * @param stars {number} a star rating
- * @returns {string} text that reads on `starRatingColor(stars)`: black up to 6.5, then osu!'s pale
- *          yellow on the dark end of the spectrum
+ * @param stars {number} the rating
+ * @returns {string} the text color on {@link starRatingColor}'s pill: osu!'s black up to the
+ *          dark end, its pale gold from there, white only where neither clears 4.5:1 (the violet
+ *          band around 6.5 to 7 stars)
  */
 export declare const starRatingTextColor: (stars: number) => string;
+export {};

package/dist/components/osu/starColors.js

@@ -5,7 +5,7 @@
  *       They are the same at every --hue, like the wordmark's brand colors.
  * @author David @dvhsh (https://dvh.sh)
  * @created Mon Sep 28, 2026
- * @modified Mon Sep 28, 2026
+ * @modified Sat Oct 3, 2026
  */
 const STOPS = [
     [0.1, [66, 144, 251]],
@@ -45,4 +45,41 @@ export const starRatingColor = (stars) => {
  * @returns {string} text that reads on `starRatingColor(stars)`: black up to 6.5, then osu!'s pale
  *          yellow on the dark end of the spectrum
  */
-export const starRatingTextColor = (stars) => stars >= 6.5 ? css([255, 217, 102]) : css([0, 0, 0]);
+const BLACK = [0, 0, 0];
+const GOLD = [255, 217, 102];
+const WHITE = [255, 255, 255];
+const luminance = ([r, g, b]) => {
+    const channel = (v) => {
+        const c = v / 255;
+        return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+};
+/**
+ * @function contrastRatio
+ * @param a {Rgb} one color
+ * @param b {Rgb} the other
+ * @returns {number} the WCAG contrast ratio between them, 1 to 21
+ */
+export const contrastRatio = (a, b) => {
+    const [light, dark] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (light + 0.05) / (dark + 0.05);
+};
+const parse = (color) => (color.match(/\d+/g) ?? ["0", "0", "0"]).slice(0, 3).map(Number);
+/**
+ * @function starRatingTextColor
+ * @param stars {number} the rating
+ * @returns {string} the text color on {@link starRatingColor}'s pill: osu!'s black up to the
+ *          dark end, its pale gold from there, white only where neither clears 4.5:1 (the violet
+ *          band around 6.5 to 7 stars)
+ */
+export const starRatingTextColor = (stars) => {
+    const pill = parse(starRatingColor(stars));
+    if (stars < 6.5 && contrastRatio(BLACK, pill) >= 4.5)
+        return css(BLACK);
+    if (contrastRatio(GOLD, pill) >= 4.5)
+        return css(GOLD);
+    if (contrastRatio(BLACK, pill) >= 4.5)
+        return css(BLACK);
+    return css(WHITE);
+};

package/dist/components/palette/CommandPalette.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file src/components/palette/CommandPalette.tsx
+ * @desc The command palette: a native <dialog> opened by mod+k, `openCommandPalette()` or a
+ *       command shortcut, with a combobox over the rows the store and row builder produce.
+ *       Enter runs a command, pushes its page, or starts collecting its args; Escape and
+ *       Backspace on an empty input go back a level, then close. Providers search as you type.
+ *       Recents are read on open and written on every run. The calculator row copies its result.
+ *       Mount once, inside a client component, since commands carry functions.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { CommandPaletteProps } from "./types.js";
+export type { CommandPaletteProps } from "./types.js";
+/**
+ * @function CommandPalette
+ * @param props {CommandPaletteProps} commands, root providers, storage key, hotkey, placeholder,
+ *        label, calculator and recents switches, panel classes
+ * @returns {JSX.Element} the dialog, empty until opened
+ */
+export declare function CommandPalette({ commands, providers, storageKey, hotkey, placeholder, label, calculator, recents: recentsOn, className, }: CommandPaletteProps): import("react").JSX.Element;

package/dist/components/palette/CommandPalette.js

@@ -0,0 +1,315 @@
+/**
+ * @file src/components/palette/CommandPalette.tsx
+ * @desc The command palette: a native <dialog> opened by mod+k, `openCommandPalette()` or a
+ *       command shortcut, with a combobox over the rows the store and row builder produce.
+ *       Enter runs a command, pushes its page, or starts collecting its args; Escape and
+ *       Backspace on an empty input go back a level, then close. Providers search as you type.
+ *       Recents are read on open and written on every run. The calculator row copies its result.
+ *       Mount once, inside a client component, since commands carry functions.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { usePathname, useRouter } from "next/navigation.js";
+import { useCallback, useEffect, useId, useMemo, useReducer, useRef, useState, } from "react";
+import { cx } from "../../utils/cx.js";
+import { useLatestStatus } from "../actions/useLatestStatus.js";
+import { isEditableTarget, matchesCombo, parseShortcut } from "./hotkeys.js";
+import { PaletteFooter } from "./PaletteFooter.js";
+import { PaletteInput } from "./PaletteInput.js";
+import { PaletteList } from "./PaletteList.js";
+import { PALETTE_EVENT } from "./paletteEvents.js";
+import { isMac } from "./platform.js";
+import { boostFrom, readRecents, recentIds, recordRecent } from "./recents.js";
+import { buildRows, CALC_ID, optionAt, optionCount } from "./rows.js";
+import { initialState, reduce, topFrame } from "./store.js";
+import { useProviderSearch } from "./useProviderSearch.js";
+const NONE = [];
+const CHORD_MS = 800;
+const DIALOG = "m-0 h-dvh max-h-none w-full max-w-none bg-transparent p-0 text-c1 backdrop:bg-b6/70 backdrop:backdrop-blur-sm sm:h-auto sm:pt-[12vh]";
+const PANEL = "mx-auto flex h-full max-h-dvh w-full flex-col overflow-hidden border-b3 bg-b6 shadow-2xl sm:h-auto sm:max-h-[70vh] sm:max-w-xl sm:rounded-xl sm:border";
+/**
+ * @function CommandPalette
+ * @param props {CommandPaletteProps} commands, root providers, storage key, hotkey, placeholder,
+ *        label, calculator and recents switches, panel classes
+ * @returns {JSX.Element} the dialog, empty until opened
+ */
+export function CommandPalette({ commands, providers = NONE, storageKey = "default", hotkey = "mod+k", placeholder = "Search commands…", label = "Command palette", calculator = true, recents: recentsOn = true, className, }) {
+    const router = useRouter();
+    const pathname = usePathname() ?? "";
+    const [state, dispatch] = useReducer(reduce, undefined, initialState);
+    const [recents, setRecents] = useState({});
+    const [mac, setMac] = useState(false);
+    const dialog = useRef(null);
+    const input = useRef(null);
+    const opener = useRef(null);
+    const chord = useRef(null);
+    // Where the pointer last was over a row. Chrome fires a pointermove at the same spot after the
+    // list scrolls under a still cursor; only a real move may take the active row from the keys.
+    const pointer = useRef(null);
+    const { status, start, settle } = useLatestStatus();
+    // The copy status reads until the query changes or the palette reopens, then the count again.
+    const [statusShown, setStatusShown] = useState(false);
+    const baseId = useId();
+    const listId = `${baseId}-list`;
+    const optionId = useCallback((index) => `${baseId}-option-${index}`, [baseId]);
+    useEffect(() => setMac(isMac()), []);
+    const root = useMemo(() => ({ title: label, placeholder, commands, providers }), [label, placeholder, commands, providers]);
+    const open = useCallback((page) => {
+        // Opening onto a page while already open keeps the original opener.
+        if (!state.open)
+            opener.current = document.activeElement;
+        if (recentsOn)
+            setRecents(readRecents(storageKey));
+        setStatusShown(false);
+        dispatch({ type: "open", root, page });
+    }, [root, recentsOn, storageKey, state.open]);
+    const close = useCallback(() => dispatch({ type: "close" }), []);
+    const ctx = useMemo(() => ({
+        navigate: (href) => router.push(href),
+        close,
+        push: (page) => (state.open ? dispatch({ type: "push", page }) : open(page)),
+        copy: async (text) => {
+            const run = start();
+            setStatusShown(true);
+            try {
+                await navigator.clipboard.writeText(text);
+                settle(run, "Copied");
+            }
+            catch {
+                settle(run, "Couldn't copy");
+            }
+        },
+        pathname,
+        commands,
+    }), [router, close, state.open, open, start, settle, pathname, commands]);
+    const frame = topFrame(state);
+    const depth = state.stack.length - 1;
+    const isRoot = depth === 0;
+    const query = state.arg ? state.arg.query : (frame?.query ?? "");
+    const rows = useMemo(() => frame
+        ? buildRows({
+            query: frame.query,
+            commands: frame.page.commands ?? [],
+            providers: frame.page.providers ?? NONE,
+            providerResults: frame.providers,
+            recentIds: isRoot && recentsOn ? recentIds(recents) : [],
+            boost: boostFrom(recents),
+            isRoot,
+            calculator,
+            arg: state.arg,
+            ctx,
+        })
+        : [], [frame, isRoot, recentsOn, recents, calculator, state.arg, ctx]);
+    const count = optionCount(rows);
+    const active = state.arg ? state.arg.active : (frame?.active ?? 0);
+    useProviderSearch({
+        providers: frame?.page.providers ?? NONE,
+        query: frame?.query ?? "",
+        depth,
+        dispatch,
+        enabled: state.open && state.arg === null && frame !== undefined,
+    });
+    // The dialog follows `open`: show it modally, focus the input, lock the page's scroll; on
+    // close, hand focus back to whatever had it.
+    useEffect(() => {
+        const element = dialog.current;
+        if (!element)
+            return;
+        if (state.open) {
+            if (!element.open)
+                element.showModal();
+            input.current?.focus();
+            document.documentElement.style.overflow = "hidden";
+            return;
+        }
+        if (element.open)
+            element.close();
+        document.documentElement.style.overflow = "";
+        if (opener.current instanceof HTMLElement)
+            opener.current.focus();
+        opener.current = null;
+    }, [state.open]);
+    useEffect(() => () => {
+        document.documentElement.style.overflow = "";
+    }, []);
+    const remember = (id) => {
+        if (recentsOn && id !== CALC_ID)
+            setRecents(recordRecent(storageKey, id));
+    };
+    const runCommand = (command, args = {}) => {
+        remember(command.id);
+        try {
+            const result = command.run?.(ctx, args);
+            if (result instanceof Promise)
+                result.catch((error) => console.error(`CommandPalette: "${command.id}" failed`, error));
+        }
+        catch (error) {
+            console.error(`CommandPalette: "${command.id}" failed`, error);
+        }
+        if (command.closeOnRun !== false)
+            close();
+    };
+    const acceptArg = (value) => {
+        const arg = state.arg;
+        const spec = arg?.command.args?.[arg.index];
+        if (!arg || !spec)
+            return;
+        const trimmed = value.trim();
+        if (spec.type !== "choice" && trimmed === "")
+            return dispatch({ type: "argError", message: "Required" });
+        if (spec.type === "number" && Number.isNaN(Number(trimmed)))
+            return dispatch({ type: "argError", message: "Enter a number" });
+        const message = spec.validate?.(trimmed);
+        if (message)
+            return dispatch({ type: "argError", message });
+        dispatch({ type: "argAccept", value: trimmed });
+        if (arg.index + 1 >= (arg.command.args?.length ?? 0))
+            runCommand(arg.command, { ...arg.values, [spec.name]: trimmed });
+    };
+    const select = (command) => {
+        if (state.arg)
+            return acceptArg(command.id);
+        if (command.page) {
+            remember(command.id);
+            return dispatch({ type: "push", page: command.page });
+        }
+        if (command.args && command.args.length > 0)
+            return dispatch({ type: "beginArgs", command });
+        runCommand(command);
+    };
+    const fire = (command) => {
+        try {
+            if (command.when && !command.when(ctx))
+                return;
+        }
+        catch {
+            return;
+        }
+        if (command.page)
+            return open(command.page);
+        if (command.args && command.args.length > 0) {
+            open();
+            return dispatch({ type: "beginArgs", command });
+        }
+        runCommand(command);
+    };
+    const back = () => {
+        if (state.arg || depth > 0)
+            dispatch({ type: "pop" });
+        else
+            close();
+    };
+    const onKeyDown = (event) => {
+        const spec = state.arg?.command.args?.[state.arg.index];
+        switch (event.key) {
+            case "ArrowDown":
+            case "ArrowUp":
+                event.preventDefault();
+                return dispatch({ type: "move", delta: event.key === "ArrowDown" ? 1 : -1, count });
+            case "Home":
+            case "End":
+                if (count === 0)
+                    return;
+                event.preventDefault();
+                return dispatch({ type: "move", delta: event.key === "Home" ? "home" : "end", count });
+            case "Enter": {
+                event.preventDefault();
+                if (state.arg && spec && spec.type !== "choice")
+                    return acceptArg(state.arg.query);
+                const option = optionAt(rows, active);
+                return option ? select(option.command) : undefined;
+            }
+            case "Escape":
+                event.preventDefault();
+                return back();
+            case "Backspace":
+                if (query !== "" || (!state.arg && depth === 0))
+                    return;
+                event.preventDefault();
+                return dispatch({ type: "pop" });
+            case "Tab":
+                return event.preventDefault();
+            default:
+                return;
+        }
+    };
+    // Global keys: the opening hotkey anywhere; command shortcuts (combos and chords) only while
+    // closed and outside editable targets.
+    useEffect(() => {
+        const toggle = parseShortcut(hotkey);
+        const shortcuts = commands.flatMap((command) => {
+            const shortcut = command.shortcut ? parseShortcut(command.shortcut) : null;
+            return shortcut ? [{ command, shortcut }] : [];
+        });
+        const onKey = (event) => {
+            if (toggle?.kind === "combo" && matchesCombo(event, toggle.combo, mac)) {
+                event.preventDefault();
+                return state.open ? close() : open();
+            }
+            if (state.open || isEditableTarget(event.target))
+                return;
+            const bare = !event.metaKey && !event.ctrlKey && !event.altKey && event.key.length === 1;
+            const key = event.key.toLowerCase();
+            const pending = chord.current;
+            chord.current = null;
+            for (const { command, shortcut } of shortcuts) {
+                if (shortcut.kind === "combo") {
+                    if (!matchesCombo(event, shortcut.combo, mac))
+                        continue;
+                    event.preventDefault();
+                    return fire(command);
+                }
+                if (!bare)
+                    continue;
+                if (pending &&
+                    pending.key === shortcut.keys[0] &&
+                    key === shortcut.keys[1] &&
+                    Date.now() - pending.at < CHORD_MS) {
+                    event.preventDefault();
+                    return fire(command);
+                }
+            }
+            if (bare &&
+                shortcuts.some((entry) => entry.shortcut.kind === "chord" && entry.shortcut.keys[0] === key)) {
+                chord.current = { key, at: Date.now() };
+            }
+        };
+        window.addEventListener("keydown", onKey);
+        return () => window.removeEventListener("keydown", onKey);
+    });
+    useEffect(() => {
+        const onOpen = (event) => open(event.detail?.page);
+        window.addEventListener(PALETTE_EVENT, onOpen);
+        return () => window.removeEventListener(PALETTE_EVENT, onOpen);
+    }, [open]);
+    const argSpec = state.arg?.command.args?.[state.arg.index];
+    const crumbs = state.arg
+        ? [
+            state.arg.command.title,
+            ...(state.arg.command.args ?? [])
+                .slice(0, state.arg.index)
+                .map((a) => state.arg?.values[a.name] ?? ""),
+        ]
+        : state.stack.slice(1).map((f) => f.page.title);
+    return (_jsx("dialog", { ref: dialog, "data-palette": "", "aria-label": label, className: DIALOG, onCancel: (event) => {
+            event.preventDefault();
+            back();
+        }, onKeyDown: onKeyDown, 
+        // The browser can close the dialog itself (a back gesture, a close watcher): follow it.
+        onClose: close, onClick: (event) => {
+            if (event.target === event.currentTarget)
+                close();
+        }, children: state.open && frame ? (_jsxs("div", { className: cx(PANEL, className), children: [_jsx(PaletteInput, { ref: input, value: query, placeholder: argSpec ? argSpec.label : (frame.page.placeholder ?? "Search…"), label: label, crumbs: crumbs, listId: listId, activeId: count > 0 ? optionId(active) : undefined, error: state.arg?.error, onChange: (value) => {
+                        setStatusShown(false);
+                        dispatch({ type: "query", value });
+                    } }), _jsx(PaletteList, { id: listId, rows: rows, active: active, mac: mac, optionId: optionId, busy: Object.values(frame.providers).some((result) => result.state === "loading"), onActivate: (index, x, y) => {
+                        const last = pointer.current;
+                        if (last && last.x === x && last.y === y)
+                            return;
+                        pointer.current = { x, y };
+                        dispatch({ type: "active", index, count });
+                    }, onSelect: select }), _jsx(PaletteFooter, { count: count, nested: depth > 0 || state.arg !== null, status: statusShown ? (status?.result ?? null) : null, statusRun: statusShown ? (status?.run ?? null) : null })] })) : null }));
+}

package/dist/components/palette/CommandPaletteButton.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file src/components/palette/CommandPaletteButton.tsx
+ * @desc A header button that opens the mounted CommandPalette: a magnifier, optional text, and
+ *       the hotkey hint ("Ctrl K", or "⌘K" once a Mac is detected after mount). Goes anywhere;
+ *       it only dispatches the palette event.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { type ButtonProps } from "../basics/Button.js";
+/** Every Button prop except onClick, plus the accessible name. */
+export type CommandPaletteButtonProps = Omit<ButtonProps, "onClick"> & {
+    /** The accessible name. Default "Open command palette". */
+    label?: string | undefined;
+};
+/**
+ * @function CommandPaletteButton
+ * @param props {CommandPaletteButtonProps} label, children (text beside the icon) and Button props
+ * @returns {JSX.Element} a ghost Button
+ */
+export declare function CommandPaletteButton({ label, children, variant, ...props }: CommandPaletteButtonProps): import("react").JSX.Element;

package/dist/components/palette/CommandPaletteButton.js

@@ -0,0 +1,26 @@
+/**
+ * @file src/components/palette/CommandPaletteButton.tsx
+ * @desc A header button that opens the mounted CommandPalette: a magnifier, optional text, and
+ *       the hotkey hint ("Ctrl K", or "⌘K" once a Mac is detected after mount). Goes anywhere;
+ *       it only dispatches the palette event.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { Button } from "../basics/Button.js";
+import { openCommandPalette } from "./paletteEvents.js";
+import { isMac } from "./platform.js";
+const KBD = "rounded border border-b3 bg-b5 px-1.5 font-sans text-c3 text-xs";
+/**
+ * @function CommandPaletteButton
+ * @param props {CommandPaletteButtonProps} label, children (text beside the icon) and Button props
+ * @returns {JSX.Element} a ghost Button
+ */
+export function CommandPaletteButton({ label = "Open command palette", children, variant = "ghost", ...props }) {
+    const [mac, setMac] = useState(false);
+    useEffect(() => setMac(isMac()), []);
+    return (_jsxs(Button, { type: "button", variant: variant, "aria-label": children === undefined || children === null ? label : undefined, onClick: () => openCommandPalette(), ...props, children: [_jsxs("svg", { "aria-hidden": "true", viewBox: "0 0 20 20", fill: "none", stroke: "currentColor", strokeWidth: "2", className: "size-4", children: [_jsx("circle", { cx: "8.5", cy: "8.5", r: "5.5" }), _jsx("path", { d: "m13 13 4 4", strokeLinecap: "round" })] }), children, _jsx("kbd", { "aria-hidden": "true", className: KBD, children: mac ? "⌘K" : "Ctrl K" })] }));
+}

package/dist/components/palette/PaletteFooter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file src/components/palette/PaletteFooter.tsx
+ * @desc The palette's bottom line (internal): the live region that announces the result count
+ *       or the latest copy status, and the key hints (hidden on phones). No hooks, no cx.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+/** The option count, whether Backspace goes back, and the latest status (keyed by its run). */
+export type PaletteFooterProps = {
+    count: number;
+    nested: boolean;
+    status: string | null;
+    statusRun: number | null;
+};
+/**
+ * @function PaletteFooter
+ * @param props {PaletteFooterProps} count, nested, status and its run
+ * @returns {JSX.Element} the footer with its `<output>` live region
+ */
+export declare function PaletteFooter({ count, nested, status, statusRun }: PaletteFooterProps): import("react").JSX.Element;