@haruhimemoe/ui 0.7.0 → 0.8.0

package/dist/components/palette/calc.js

@@ -0,0 +1,226 @@
+/**
+ * @file src/components/palette/calc.ts
+ * @desc The palette's calculator, pure and without eval: a tokenizer and the shunting-yard
+ *       algorithm over + - * / % ^, unary minus, parentheses, k and m number suffixes, pi and e,
+ *       and sqrt, abs, round, floor, ceil, min and max. Anything it can't parse, and any result
+ *       that isn't finite (division by zero), is null.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+const CONSTANTS = { pi: Math.PI, e: Math.E };
+const FUNCTIONS = {
+    sqrt: ([x]) => (x === undefined ? undefined : Math.sqrt(x)),
+    abs: ([x]) => (x === undefined ? undefined : Math.abs(x)),
+    round: ([x]) => (x === undefined ? undefined : Math.round(x)),
+    floor: ([x]) => (x === undefined ? undefined : Math.floor(x)),
+    ceil: ([x]) => (x === undefined ? undefined : Math.ceil(x)),
+    min: (args) => (args.length === 0 ? undefined : Math.min(...args)),
+    max: (args) => (args.length === 0 ? undefined : Math.max(...args)),
+};
+const SUFFIX = { k: 1e3, m: 1e6 };
+const NUMBER = /^(\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?([km])?/i;
+const IDENT = /^[a-z]+/i;
+const tokenize = (expression) => {
+    const tokens = [];
+    let rest = expression.trim();
+    while (rest.length > 0) {
+        const space = /^\s+/.exec(rest);
+        if (space) {
+            rest = rest.slice(space[0].length);
+            continue;
+        }
+        const num = NUMBER.exec(rest);
+        const ident = num ? null : IDENT.exec(rest);
+        if (num) {
+            const value = Number(num[0].replace(/[km]$/i, "")) * (SUFFIX[(num[2] ?? "").toLowerCase()] ?? 1);
+            tokens.push({ kind: "num", value });
+            rest = rest.slice(num[0].length);
+        }
+        else if (ident) {
+            const name = ident[0].toLowerCase();
+            rest = rest.slice(ident[0].length);
+            if (name in CONSTANTS)
+                tokens.push({ kind: "num", value: CONSTANTS[name] });
+            else if (name in FUNCTIONS)
+                tokens.push({ kind: "fn", value: name });
+            else
+                return null;
+        }
+        else {
+            const ch = rest[0];
+            rest = rest.slice(1);
+            if (ch === "(" || ch === ")" || ch === ",")
+                tokens.push({ kind: ch });
+            else if ("+-*/%^".includes(ch)) {
+                const previous = tokens[tokens.length - 1];
+                const unary = ch === "-" &&
+                    (!previous || previous.kind === "op" || previous.kind === "(" || previous.kind === ",");
+                tokens.push({
+                    kind: "op",
+                    value: unary ? "neg" : ch,
+                });
+            }
+            else
+                return null;
+        }
+    }
+    return tokens;
+};
+const PRECEDENCE = {
+    "+": 1,
+    "-": 1,
+    "*": 2,
+    "/": 2,
+    "%": 2,
+    "^": 4,
+    neg: 3,
+};
+const RIGHT = new Set(["^", "neg"]);
+const apply = (op, values) => {
+    if (op === "neg") {
+        const x = values.pop();
+        if (x === undefined)
+            return false;
+        values.push(-x);
+        return true;
+    }
+    const b = values.pop();
+    const a = values.pop();
+    if (a === undefined || b === undefined)
+        return false;
+    const result = op === "+"
+        ? a + b
+        : op === "-"
+            ? a - b
+            : op === "*"
+                ? a * b
+                : op === "/"
+                    ? a / b
+                    : op === "%"
+                        ? a % b
+                        : a ** b;
+    values.push(result);
+    return true;
+};
+/**
+ * @function evaluate
+ * @param expression {string} what was typed, e.g. "1.5k * (2 + sqrt(9))"
+ * @returns {number | null} the value, or null when it doesn't parse or isn't finite
+ */
+export function evaluate(expression) {
+    const tokens = tokenize(expression);
+    if (!tokens || tokens.length === 0)
+        return null;
+    const values = [];
+    const ops = [];
+    const argc = [];
+    let expectValue = true;
+    const popOps = (until) => {
+        while (ops.length > 0) {
+            const top = ops[ops.length - 1];
+            if (until(top))
+                return true;
+            ops.pop();
+            if (top.kind !== "op" || !apply(top.value, values))
+                return false;
+        }
+        return false;
+    };
+    for (const [i, token] of tokens.entries()) {
+        const next = tokens[i + 1];
+        if (token.kind === "num") {
+            if (!expectValue)
+                return null;
+            values.push(token.value);
+            expectValue = false;
+        }
+        else if (token.kind === "fn") {
+            if (!expectValue || next?.kind !== "(")
+                return null;
+            ops.push({ kind: "(", fn: token.value });
+            argc.push(next === undefined ? 0 : tokens[i + 2]?.kind === ")" ? 0 : 1);
+            tokens.splice(i + 1, 1);
+        }
+        else if (token.kind === "(") {
+            if (!expectValue)
+                return null;
+            ops.push(token);
+            argc.push(0);
+            expectValue = true;
+        }
+        else if (token.kind === ",") {
+            if (expectValue)
+                return null;
+            if (!popOps((top) => top.kind === "("))
+                return null;
+            const top = ops[ops.length - 1];
+            if (top?.kind !== "(" || !top.fn)
+                return null;
+            argc[argc.length - 1] = (argc[argc.length - 1] ?? 0) + 1;
+            expectValue = true;
+        }
+        else if (token.kind === ")") {
+            if (expectValue && ops[ops.length - 1]?.kind !== "(")
+                return null;
+            if (!popOps((top) => top.kind === "("))
+                return null;
+            const open = ops.pop();
+            const count = argc.pop() ?? 0;
+            if (open?.kind === "(" && open.fn) {
+                const n = expectValue ? count : count;
+                const args = values.splice(values.length - n, n);
+                if (args.length !== n)
+                    return null;
+                const result = FUNCTIONS[open.fn]?.(args);
+                if (result === undefined)
+                    return null;
+                values.push(result);
+            }
+            else if (expectValue)
+                return null;
+            expectValue = false;
+        }
+        else {
+            const op = token.value;
+            if (op === "neg") {
+                if (!expectValue)
+                    return null;
+                ops.push(token);
+                continue;
+            }
+            if (expectValue)
+                return null;
+            const p = PRECEDENCE[op];
+            popOps((top) => {
+                if (top.kind !== "op")
+                    return true;
+                const topP = PRECEDENCE[top.value];
+                return topP < p || (topP === p && RIGHT.has(op));
+            });
+            ops.push(token);
+            expectValue = true;
+        }
+    }
+    if (expectValue)
+        return null;
+    if (popOps((top) => top.kind === "("))
+        return null;
+    const result = values.length === 1 ? values[0] : undefined;
+    return result !== undefined && Number.isFinite(result) ? result : null;
+}
+/**
+ * @function formatResult
+ * @param value {number} a result
+ * @returns {string} up to 10 significant digits, trailing zeros dropped, "-0" as "0"
+ */
+export function formatResult(value) {
+    const text = String(Number(value.toPrecision(10)));
+    return text === "-0" ? "0" : text;
+}
+/**
+ * @function isBareNumber
+ * @param expression {string} what was typed
+ * @returns {boolean} true for just a number ("2", " -2.5 "), when the palette shows no "= 2" row
+ */
+export const isBareNumber = (expression) => /^\s*-?(\d+\.?\d*|\.\d+)\s*$/.test(expression);

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

@@ -0,0 +1,51 @@
+/**
+ * @file src/components/palette/fuzzy.ts
+ * @desc The palette's scorer, pure. A query matches a text when its characters appear in order
+ *       (case-insensitive). Each matched character scores 10 at a word start, 8 when it follows
+ *       the previous match, 4 otherwise, minus one per skipped character; a query that prefixes
+ *       the text adds 20. A command's score is the best of its title, keywords (0.7), subtitle
+ *       (0.5) and group (0.3). A cased letter or digit may only match at a word start or right
+ *       after the previous match, so "cpu" lands on "Copy page URL"'s initials and "go" never
+ *       finds "Sign out"; punctuation and uncased scripts (kanji, kana) match anywhere, since
+ *       they have no word starts. Backtracking, left to right, memoized.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { Command } from "./types.js";
+/** A match: its score and the matched [start, end) spans in the text, for highlighting. */
+export type FuzzyMatch = {
+    score: number;
+    ranges: readonly (readonly [number, number])[];
+};
+/** A command with its score and the title's matched spans (empty when another field matched). */
+export type Scored = {
+    command: Command;
+    score: number;
+    ranges: FuzzyMatch["ranges"];
+};
+/**
+ * @function fuzzyScore
+ * @param query {string} what was typed; surrounding spaces are ignored
+ * @param text {string} a title, keyword or heading
+ * @returns {FuzzyMatch | null} the score and matched spans, or null when the query isn't a
+ *          subsequence of the text. An empty query scores 0 with no spans.
+ */
+export declare function fuzzyScore(query: string, text: string): FuzzyMatch | null;
+/**
+ * @function scoreCommand
+ * @param query {string} what was typed
+ * @param command {Command} a row
+ * @returns {Scored | null} the best weighted field match, with title spans only when the title
+ *          itself matched; null when no field matches
+ */
+export declare function scoreCommand(query: string, command: Command): Scored | null;
+/**
+ * @function rankResults
+ * @param query {string} what was typed
+ * @param commands {readonly Command[]} the rows to search
+ * @param boost {(id: string) => number} a tie-breaker per id (recents count)
+ * @returns {Scored[]} the matching rows, best first; ties go to the higher boost, then to
+ *          declaration order
+ */
+export declare function rankResults(query: string, commands: readonly Command[], boost: (id: string) => number): Scored[];

package/dist/components/palette/fuzzy.js

@@ -0,0 +1,138 @@
+/**
+ * @file src/components/palette/fuzzy.ts
+ * @desc The palette's scorer, pure. A query matches a text when its characters appear in order
+ *       (case-insensitive). Each matched character scores 10 at a word start, 8 when it follows
+ *       the previous match, 4 otherwise, minus one per skipped character; a query that prefixes
+ *       the text adds 20. A command's score is the best of its title, keywords (0.7), subtitle
+ *       (0.5) and group (0.3). A cased letter or digit may only match at a word start or right
+ *       after the previous match, so "cpu" lands on "Copy page URL"'s initials and "go" never
+ *       finds "Sign out"; punctuation and uncased scripts (kanji, kana) match anywhere, since
+ *       they have no word starts. Backtracking, left to right, memoized.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+const WORD_BREAK = /[\s\-_/.]/;
+const isWordStart = (text, at) => {
+    if (at === 0)
+        return true;
+    const before = text[at - 1] ?? "";
+    const here = text[at] ?? "";
+    if (WORD_BREAK.test(before))
+        return true;
+    return before === before.toLowerCase() && here !== here.toLowerCase();
+};
+/**
+ * A character the word-start rule applies to: a digit or a letter with case. Scripts without
+ * case (kanji, kana, hangul) have no spaces to start words at, so they may match anywhere.
+ */
+const isStrict = (ch) => /\p{N}/u.test(ch) || (/\p{L}/u.test(ch) && ch.toLowerCase() !== ch.toUpperCase());
+/**
+ * The positions where the query's characters match, found left to right with backtracking,
+ * memoized on (index, from, consecutive) so a repetitive query stays polynomial. A cased letter
+ * or a digit may only match at a word start or right after the previous match (so "go" never
+ * lands on the g inside "Sign out"); punctuation and uncased letters may match anywhere. Null
+ * when the query can't be placed.
+ */
+const place = (chars, i, from, prev, text, t, memo) => {
+    const ch = chars[i];
+    if (ch === undefined)
+        return [];
+    const key = `${i}:${from}:${prev === from - 1 ? 1 : 0}`;
+    const seen = memo.get(key);
+    if (seen !== undefined)
+        return seen;
+    let found = null;
+    for (let at = t.indexOf(ch, from); at >= 0; at = t.indexOf(ch, at + 1)) {
+        const allowed = !isStrict(ch) || (prev >= 0 && at === prev + 1) || isWordStart(text, at);
+        if (!allowed)
+            continue;
+        const rest = place(chars, i + 1, at + 1, at, text, t, memo);
+        if (rest) {
+            found = [at, ...rest];
+            break;
+        }
+    }
+    memo.set(key, found);
+    return found;
+};
+/**
+ * @function fuzzyScore
+ * @param query {string} what was typed; surrounding spaces are ignored
+ * @param text {string} a title, keyword or heading
+ * @returns {FuzzyMatch | null} the score and matched spans, or null when the query isn't a
+ *          subsequence of the text. An empty query scores 0 with no spans.
+ */
+export function fuzzyScore(query, text) {
+    const q = query.trim().toLowerCase();
+    if (q.length === 0)
+        return { score: 0, ranges: [] };
+    const t = text.toLowerCase();
+    const positions = place([...q], 0, 0, -1, text, t, new Map());
+    if (!positions)
+        return null;
+    let score = 0;
+    let prev = -1;
+    const ranges = [];
+    for (const at of positions) {
+        if (prev >= 0 && at === prev + 1)
+            score += 8;
+        else if (isWordStart(text, at))
+            score += 10;
+        else
+            score += 4;
+        if (prev >= 0)
+            score -= Math.max(0, at - prev - 1);
+        const last = ranges[ranges.length - 1];
+        if (last && last[1] === at)
+            last[1] = at + 1;
+        else
+            ranges.push([at, at + 1]);
+        prev = at;
+    }
+    if (t.startsWith(q))
+        score += 20;
+    return { score, ranges };
+}
+const WEIGHTS = { keyword: 0.7, subtitle: 0.5, group: 0.3 };
+/**
+ * @function scoreCommand
+ * @param query {string} what was typed
+ * @param command {Command} a row
+ * @returns {Scored | null} the best weighted field match, with title spans only when the title
+ *          itself matched; null when no field matches
+ */
+export function scoreCommand(query, command) {
+    const title = fuzzyScore(query, command.title);
+    let best = title ? { score: title.score, ranges: title.ranges } : null;
+    const consider = (text, weight) => {
+        if (!text)
+            return;
+        const match = fuzzyScore(query, text);
+        if (match && (!best || match.score * weight > best.score)) {
+            best = { score: match.score * weight, ranges: [] };
+        }
+    };
+    for (const keyword of command.keywords ?? [])
+        consider(keyword, WEIGHTS.keyword);
+    consider(command.subtitle, WEIGHTS.subtitle);
+    consider(command.group, WEIGHTS.group);
+    return best ? { command, ...best } : null;
+}
+/**
+ * @function rankResults
+ * @param query {string} what was typed
+ * @param commands {readonly Command[]} the rows to search
+ * @param boost {(id: string) => number} a tie-breaker per id (recents count)
+ * @returns {Scored[]} the matching rows, best first; ties go to the higher boost, then to
+ *          declaration order
+ */
+export function rankResults(query, commands, boost) {
+    return commands
+        .map((command, index) => ({ scored: scoreCommand(query, command), index }))
+        .filter((entry) => entry.scored !== null)
+        .sort((a, b) => b.scored.score - a.scored.score ||
+        boost(b.scored.command.id) - boost(a.scored.command.id) ||
+        a.index - b.index)
+        .map((entry) => entry.scored);
+}

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

@@ -0,0 +1,57 @@
+/**
+ * @file src/components/palette/hotkeys.ts
+ * @desc Shortcut text ("mod+k", "?", a chord "g p") parsed, matched against keydown events and
+ *       shown as kbd parts. `mod` is Command on a Mac (platform.ts decides) and Control
+ *       elsewhere. A chord is two bare keys in a row; CommandPalette times it. Editable targets
+ *       (fields, contenteditable, a dialog that isn't the palette) never fire command shortcuts.
+ *       Pure: no directive, so server-safe files (PaletteRow) can import it.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+/** A key with modifiers. `key` is lower-case, compared to `event.key`. */
+export type Combo = {
+    key: string;
+    mod: boolean;
+    shift: boolean;
+    alt: boolean;
+    ctrl: boolean;
+    meta: boolean;
+};
+/** A combo, or a chord of two bare keys pressed in turn. */
+export type Shortcut = {
+    kind: "combo";
+    combo: Combo;
+} | {
+    kind: "chord";
+    keys: readonly [string, string];
+};
+/**
+ * @function parseShortcut
+ * @param text {string} "mod+shift+c", "?" or "g p"
+ * @returns {Shortcut | null} the parsed shortcut, or null for text that isn't one
+ */
+export declare function parseShortcut(text: string): Shortcut | null;
+/**
+ * @function matchesCombo
+ * @param event {KeyboardEvent} a keydown
+ * @param combo {Combo} the parsed combo
+ * @param mac {boolean} whether `mod` means Meta
+ * @returns {boolean} true when the key and the exact modifier set match. Shift is not required
+ *          for a symbol key such as "?", which needs it on most layouts.
+ */
+export declare function matchesCombo(event: KeyboardEvent, combo: Combo, mac: boolean): boolean;
+/**
+ * @function isEditableTarget
+ * @param target {EventTarget | null} the keydown's target
+ * @returns {boolean} true inside an input, textarea, select, contenteditable, or a `<dialog>`
+ *          without `data-palette`
+ */
+export declare function isEditableTarget(target: EventTarget | null): boolean;
+/**
+ * @function displayShortcut
+ * @param shortcut {Shortcut} a parsed shortcut
+ * @param mac {boolean} symbols (⌘ ⇧ ⌥ ⌃) on a Mac, words elsewhere
+ * @returns {string[]} one entry per `<kbd>`, in order
+ */
+export declare function displayShortcut(shortcut: Shortcut, mac: boolean): string[];

package/dist/components/palette/hotkeys.js

@@ -0,0 +1,111 @@
+/**
+ * @file src/components/palette/hotkeys.ts
+ * @desc Shortcut text ("mod+k", "?", a chord "g p") parsed, matched against keydown events and
+ *       shown as kbd parts. `mod` is Command on a Mac (platform.ts decides) and Control
+ *       elsewhere. A chord is two bare keys in a row; CommandPalette times it. Editable targets
+ *       (fields, contenteditable, a dialog that isn't the palette) never fire command shortcuts.
+ *       Pure: no directive, so server-safe files (PaletteRow) can import it.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+const MODIFIERS = new Set(["mod", "shift", "alt", "ctrl", "meta"]);
+/**
+ * @function parseShortcut
+ * @param text {string} "mod+shift+c", "?" or "g p"
+ * @returns {Shortcut | null} the parsed shortcut, or null for text that isn't one
+ */
+export function parseShortcut(text) {
+    const trimmed = text.trim().toLowerCase();
+    if (trimmed.length === 0)
+        return null;
+    const chord = trimmed.split(/\s+/);
+    if (chord.length === 2 && chord.every((k) => k.length === 1)) {
+        return { kind: "chord", keys: [chord[0], chord[1]] };
+    }
+    if (chord.length !== 1)
+        return null;
+    const parts = trimmed.split("+");
+    const key = parts.pop();
+    if (!key || parts.some((part) => !MODIFIERS.has(part)))
+        return null;
+    const has = (name) => parts.includes(name);
+    return {
+        kind: "combo",
+        combo: {
+            key,
+            mod: has("mod"),
+            shift: has("shift"),
+            alt: has("alt"),
+            ctrl: has("ctrl"),
+            meta: has("meta"),
+        },
+    };
+}
+const isLetterOrDigit = (key) => /^[a-z0-9]$/i.test(key);
+/**
+ * @function matchesCombo
+ * @param event {KeyboardEvent} a keydown
+ * @param combo {Combo} the parsed combo
+ * @param mac {boolean} whether `mod` means Meta
+ * @returns {boolean} true when the key and the exact modifier set match. Shift is not required
+ *          for a symbol key such as "?", which needs it on most layouts.
+ */
+export function matchesCombo(event, combo, mac) {
+    if (event.key.toLowerCase() !== combo.key)
+        return false;
+    const wantMeta = combo.meta || (combo.mod && mac);
+    const wantCtrl = combo.ctrl || (combo.mod && !mac);
+    if (event.metaKey !== wantMeta || event.ctrlKey !== wantCtrl || event.altKey !== combo.alt)
+        return false;
+    if (combo.key.length === 1 && !isLetterOrDigit(combo.key) && !combo.shift)
+        return true;
+    return event.shiftKey === combo.shift;
+}
+/**
+ * @function isEditableTarget
+ * @param target {EventTarget | null} the keydown's target
+ * @returns {boolean} true inside an input, textarea, select, contenteditable, or a `<dialog>`
+ *          without `data-palette`
+ */
+export function isEditableTarget(target) {
+    if (!(target instanceof Element))
+        return false;
+    const tag = target.tagName;
+    if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT")
+        return true;
+    if (target instanceof HTMLElement && target.isContentEditable)
+        return true;
+    const dialog = target.closest("dialog");
+    return dialog !== null && !dialog.hasAttribute("data-palette");
+}
+const KEY_NAMES = {
+    arrowup: "↑",
+    arrowdown: "↓",
+    enter: "↵",
+    escape: "Esc",
+    backspace: "⌫",
+};
+/**
+ * @function displayShortcut
+ * @param shortcut {Shortcut} a parsed shortcut
+ * @param mac {boolean} symbols (⌘ ⇧ ⌥ ⌃) on a Mac, words elsewhere
+ * @returns {string[]} one entry per `<kbd>`, in order
+ */
+export function displayShortcut(shortcut, mac) {
+    const name = (key) => KEY_NAMES[key] ?? key.toUpperCase();
+    if (shortcut.kind === "chord")
+        return shortcut.keys.map(name);
+    const { combo } = shortcut;
+    const parts = [];
+    if (combo.ctrl || (combo.mod && !mac))
+        parts.push(mac ? "⌃" : "Ctrl");
+    if (combo.alt)
+        parts.push(mac ? "⌥" : "Alt");
+    if (combo.shift)
+        parts.push(mac ? "⇧" : "Shift");
+    if (combo.meta || (combo.mod && mac))
+        parts.push(mac ? "⌘" : "Win");
+    parts.push(name(combo.key));
+    return parts;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * @file src/components/palette/paletteEvents.ts
+ * @desc How anything opens the mounted CommandPalette without a context provider: a CustomEvent
+ *       on window that the palette listens for. `CommandPaletteButton` and app code call
+ *       `openCommandPalette`, optionally with a page to open onto.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { Page } from "./types.js";
+/** The event name CommandPalette listens for on window. */
+export declare const PALETTE_EVENT = "haruhime:palette";
+/** The event's detail. */
+export type PaletteEventDetail = {
+    page?: Page | undefined;
+};
+/**
+ * @function openCommandPalette
+ * @param page {Page} a page to open straight onto, above the root
+ * @returns {void}
+ */
+export declare function openCommandPalette(page?: Page): void;

package/dist/components/palette/paletteEvents.js

@@ -0,0 +1,22 @@
+/**
+ * @file src/components/palette/paletteEvents.ts
+ * @desc How anything opens the mounted CommandPalette without a context provider: a CustomEvent
+ *       on window that the palette listens for. `CommandPaletteButton` and app code call
+ *       `openCommandPalette`, optionally with a page to open onto.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+"use client";
+/** The event name CommandPalette listens for on window. */
+export const PALETTE_EVENT = "haruhime:palette";
+/**
+ * @function openCommandPalette
+ * @param page {Page} a page to open straight onto, above the root
+ * @returns {void}
+ */
+export function openCommandPalette(page) {
+    if (typeof window === "undefined")
+        return;
+    window.dispatchEvent(new CustomEvent(PALETTE_EVENT, { detail: { page } }));
+}

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

@@ -0,0 +1,13 @@
+/**
+ * @file src/components/palette/platform.ts
+ * @desc Whether this is a Mac, so `mod` means Command and hints say ⌘. Client-only (reads
+ *       navigator); the palette and its button call it after mount.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+/**
+ * @function isMac
+ * @returns {boolean} true on macOS, from `userAgentData.platform` or `navigator.platform`
+ */
+export declare function isMac(): boolean;

package/dist/components/palette/platform.js

@@ -0,0 +1,21 @@
+/**
+ * @file src/components/palette/platform.ts
+ * @desc Whether this is a Mac, so `mod` means Command and hints say ⌘. Client-only (reads
+ *       navigator); the palette and its button call it after mount.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+"use client";
+/**
+ * @function isMac
+ * @returns {boolean} true on macOS, from `userAgentData.platform` or `navigator.platform`
+ */
+export function isMac() {
+    if (typeof navigator === "undefined")
+        return false;
+    const data = navigator.userAgentData;
+    if (data?.platform)
+        return data.platform === "macOS";
+    return /^Mac/.test(navigator.platform ?? "");
+}