@thomasfosterau/components 0.0.0 → 0.2.0

package/dist/hotkeys/context.svelte.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Svelte context plumbing for the hotkey registry, plus the declarative
+ * `registerHotkeys` helper that pages and shared page components call to
+ * contribute page-scoped actions.
+ *
+ * @module
+ */
+import { HotkeyRegistry, type HotkeyRegistryOptions } from './registry.svelte.ts';
+import type { CommandAction, HotkeyScope } from './types.ts';
+/** Raised by {@link getHotkeyRegistry} when no registry has been created above. */
+export declare class HotkeyRegistryMissing extends Error {
+    readonly name = "HotkeyRegistryMissing";
+}
+/**
+ * Create the registry and place it in context. Call once, from the root
+ * layout, during component initialisation.
+ */
+export declare function createHotkeyRegistry(options: HotkeyRegistryOptions): HotkeyRegistry;
+/**
+ * Read the registry from context, or `undefined` when none was created.
+ *
+ * This is the seam that lets `CommandPalette` work in an app that never
+ * mounted a registry: it falls back to its `items` prop. Components that
+ * cannot work without one (`HotkeyProvider`, `HotkeyHelpDialog`) call
+ * {@link getHotkeyRegistry} instead, so the failure is loud.
+ */
+export declare function tryGetHotkeyRegistry(): HotkeyRegistry | undefined;
+/** Read the registry from context. Throws when none was created. */
+export declare function getHotkeyRegistry(): HotkeyRegistry;
+/**
+ * Declaratively register actions for the lifetime of the calling component.
+ * Registration is reactive: the `actions` thunk re-runs when its dependencies
+ * change (a resource's `canEdit` resolving, say), replacing the previous
+ * registration.
+ *
+ * ```svelte
+ * registerHotkeys(() =>
+ *   post.canEdit
+ *     ? [{ id: 'post.edit', label: 'Edit post', trigger: 'e', group: 'actions',
+ *          run: () => goto(`/posts/${post.id}/edit`) }]
+ *     : [],
+ * );
+ * ```
+ */
+export declare function registerHotkeys(actions: () => readonly CommandAction[], options?: {
+    scope?: HotkeyScope | undefined;
+}): void;

package/dist/hotkeys/context.svelte.js

@@ -0,0 +1,72 @@
+/**
+ * Svelte context plumbing for the hotkey registry, plus the declarative
+ * `registerHotkeys` helper that pages and shared page components call to
+ * contribute page-scoped actions.
+ *
+ * @module
+ */
+import { getContext, setContext, untrack } from 'svelte';
+import { HotkeyRegistry } from "./registry.svelte.js";
+const CONTEXT_KEY = Symbol('@thomasfosterau/components:hotkey-registry');
+/** Raised by {@link getHotkeyRegistry} when no registry has been created above. */
+export class HotkeyRegistryMissing extends Error {
+    name = 'HotkeyRegistryMissing';
+}
+/**
+ * Create the registry and place it in context. Call once, from the root
+ * layout, during component initialisation.
+ */
+export function createHotkeyRegistry(options) {
+    const registry = new HotkeyRegistry(options);
+    setContext(CONTEXT_KEY, registry);
+    return registry;
+}
+/**
+ * Read the registry from context, or `undefined` when none was created.
+ *
+ * This is the seam that lets `CommandPalette` work in an app that never
+ * mounted a registry: it falls back to its `items` prop. Components that
+ * cannot work without one (`HotkeyProvider`, `HotkeyHelpDialog`) call
+ * {@link getHotkeyRegistry} instead, so the failure is loud.
+ */
+export function tryGetHotkeyRegistry() {
+    return getContext(CONTEXT_KEY);
+}
+/** Read the registry from context. Throws when none was created. */
+export function getHotkeyRegistry() {
+    const registry = tryGetHotkeyRegistry();
+    if (!registry) {
+        throw new HotkeyRegistryMissing('HotkeyRegistry not found in context. ' +
+            'createHotkeyRegistry() must be called by an ancestor (the root layout).');
+    }
+    return registry;
+}
+/**
+ * Declaratively register actions for the lifetime of the calling component.
+ * Registration is reactive: the `actions` thunk re-runs when its dependencies
+ * change (a resource's `canEdit` resolving, say), replacing the previous
+ * registration.
+ *
+ * ```svelte
+ * registerHotkeys(() =>
+ *   post.canEdit
+ *     ? [{ id: 'post.edit', label: 'Edit post', trigger: 'e', group: 'actions',
+ *          run: () => goto(`/posts/${post.id}/edit`) }]
+ *     : [],
+ * );
+ * ```
+ */
+export function registerHotkeys(actions, options = {}) {
+    const registry = getHotkeyRegistry();
+    const scope = options.scope ?? 'page';
+    $effect(() => {
+        // Track only the `actions` thunk's own reactive inputs. `register()`
+        // reads *and* writes the registry's `#registrations` `$state`; left
+        // tracked, that read-then-write makes the effect re-trigger itself
+        // forever (`effect_update_depth_exceeded`, which crashed hydration on
+        // every page). `untrack` isolates the register call so the effect re-runs
+        // only when `actions()` changes, not when the array it writes does.
+        const batch = actions();
+        return untrack(() => registry.register(scope, batch));
+    });
+}

package/dist/hotkeys/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * hotkeys — the registry that answers "what can the viewer do right now", and
+ * the two surfaces that read it back.
+ *
+ * An app creates one registry in its root layout (`createHotkeyRegistry`),
+ * renders `HotkeyProvider` once to mount the key listener, and registers
+ * actions from anywhere below with `registerHotkeys` — global ones from the
+ * layout, page ones from the page, torn down when it unmounts. `search/`'s
+ * `CommandPalette` and `HotkeyHelpDialog` then list exactly what is live.
+ *
+ * Everything user-facing is a prop: the registry stores the labels the app
+ * registered, and the two components take their own chrome copy
+ * (`title`, `closeLabel`, `commandLabel`, …) with English defaults.
+ *
+ * The family is re-exported from the root barrel and is also its own entry,
+ * `@thomasfosterau/components/hotkeys`, so a consumer can
+ * `import('@thomasfosterau/components/hotkeys')` to load `HotkeyHelpDialog`
+ * lazily, on the first `?`, instead of in its entry chunk.
+ *
+ * @module
+ */
+export { HotkeyRegistryMissing, createHotkeyRegistry, getHotkeyRegistry, registerHotkeys, tryGetHotkeyRegistry, } from './context.svelte.ts';
+export { HotkeyRegistry, type HotkeyRegistryOptions } from './registry.svelte.ts';
+export { default as HotkeyBadge } from './HotkeyBadge.svelte';
+export { default as HotkeyHelpDialog } from './HotkeyHelpDialog.svelte';
+export { default as HotkeyProvider } from './HotkeyProvider.svelte';
+export { SEQUENCE_TIMEOUT_MS, hasChordModifier, isApplePlatform, isEditableTarget, isSequenceKey, matchChord, matchSequence, triggerDisplay, type SequenceMatch, type TriggerDisplay, } from './match.ts';
+export type { CommandAction, CommandActionGroup, HotkeyChord, HotkeyScope, HotkeySequence, HotkeyTrigger, RegisteredAction, } from './types.ts';

package/dist/hotkeys/index.js

@@ -0,0 +1,27 @@
+/**
+ * hotkeys — the registry that answers "what can the viewer do right now", and
+ * the two surfaces that read it back.
+ *
+ * An app creates one registry in its root layout (`createHotkeyRegistry`),
+ * renders `HotkeyProvider` once to mount the key listener, and registers
+ * actions from anywhere below with `registerHotkeys` — global ones from the
+ * layout, page ones from the page, torn down when it unmounts. `search/`'s
+ * `CommandPalette` and `HotkeyHelpDialog` then list exactly what is live.
+ *
+ * Everything user-facing is a prop: the registry stores the labels the app
+ * registered, and the two components take their own chrome copy
+ * (`title`, `closeLabel`, `commandLabel`, …) with English defaults.
+ *
+ * The family is re-exported from the root barrel and is also its own entry,
+ * `@thomasfosterau/components/hotkeys`, so a consumer can
+ * `import('@thomasfosterau/components/hotkeys')` to load `HotkeyHelpDialog`
+ * lazily, on the first `?`, instead of in its entry chunk.
+ *
+ * @module
+ */
+export { HotkeyRegistryMissing, createHotkeyRegistry, getHotkeyRegistry, registerHotkeys, tryGetHotkeyRegistry, } from "./context.svelte.js";
+export { HotkeyRegistry } from "./registry.svelte.js";
+export { default as HotkeyBadge } from './HotkeyBadge.svelte';
+export { default as HotkeyHelpDialog } from './HotkeyHelpDialog.svelte';
+export { default as HotkeyProvider } from './HotkeyProvider.svelte';
+export { SEQUENCE_TIMEOUT_MS, hasChordModifier, isApplePlatform, isEditableTarget, isSequenceKey, matchChord, matchSequence, triggerDisplay, } from "./match.js";

package/dist/hotkeys/match.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure key-matching helpers for the hotkey registry. No Svelte, no DOM
+ * mutation — just functions over `KeyboardEvent`s, trigger grammars and the
+ * sequence buffer, so the matching rules stay testable and `HotkeyProvider`
+ * stays thin.
+ *
+ * Trigger model:
+ *
+ * - **Modifier chords** (`'$mod+k'`) — held together. `$mod` is ⌘ on macOS
+ *   and Ctrl elsewhere. Matched on their own; never buffered.
+ * - **Plain keys / sequences** (`'e'`, `'/'`, `['g', 'p']`) — pressed in
+ *   order with no modifier held. A plain single key is just a sequence of
+ *   length one, so matching is uniform.
+ *
+ * @module
+ */
+import type { CommandAction, HotkeyTrigger, RegisteredAction } from './types.ts';
+/** Sequence buffer entries expire after this many milliseconds. */
+export declare const SEQUENCE_TIMEOUT_MS = 1000;
+/** Whether the runtime platform treats `$mod` as ⌘ (macOS / iOS). */
+export declare function isApplePlatform(): boolean;
+/**
+ * Whether a keyboard event's target is an editable surface — a form field or
+ * a contenteditable region (which covers a rich-text editor's root). Hotkeys
+ * without `allowInEditable` stay inert there so typing never fires actions.
+ */
+export declare function isEditableTarget(target: EventTarget | null): boolean;
+/** Whether an event carries a chord modifier (⌘ / Ctrl / Alt). */
+export declare function hasChordModifier(event: KeyboardEvent): boolean;
+/**
+ * Whether an event's key can participate in a sequence: a single printable
+ * character pressed without chord modifiers.
+ */
+export declare function isSequenceKey(event: KeyboardEvent): boolean;
+/**
+ * Find the action whose modifier chord matches the event. `actions` must
+ * already be in precedence order (page before global, later registrations
+ * first).
+ */
+export declare function matchChord(event: KeyboardEvent, actions: readonly RegisteredAction[]): CommandAction | undefined;
+/** The result of `matchSequence`: the action a key buffer completes, and whether it could still grow into another. */
+export interface SequenceMatch {
+    /** The action whose sequence the buffer completes, if any. */
+    exact: CommandAction | undefined;
+    /** Whether the buffer is a strict prefix of at least one sequence. */
+    isPrefix: boolean;
+}
+/**
+ * Match a candidate key buffer against the active plain-key triggers.
+ * `actions` must already be in precedence order.
+ */
+export declare function matchSequence(buffer: readonly string[], actions: readonly RegisteredAction[]): SequenceMatch;
+/** A trigger split into the keys a `HotkeyBadge` renders, and whether they are pressed in turn or together. */
+export interface TriggerDisplay {
+    /**
+     * Keys to render as `<kbd>` chips, in order. `'$mod'` is left un-resolved
+     * so the rendering component can substitute the platform-appropriate
+     * label.
+     */
+    keys: readonly string[];
+    /** True when keys are pressed one after another rather than held together. */
+    sequential: boolean;
+}
+/** Project a trigger into its display form for help overlays and badges. */
+export declare function triggerDisplay(trigger: HotkeyTrigger): TriggerDisplay;

package/dist/hotkeys/match.js

@@ -0,0 +1,135 @@
+/**
+ * Pure key-matching helpers for the hotkey registry. No Svelte, no DOM
+ * mutation — just functions over `KeyboardEvent`s, trigger grammars and the
+ * sequence buffer, so the matching rules stay testable and `HotkeyProvider`
+ * stays thin.
+ *
+ * Trigger model:
+ *
+ * - **Modifier chords** (`'$mod+k'`) — held together. `$mod` is ⌘ on macOS
+ *   and Ctrl elsewhere. Matched on their own; never buffered.
+ * - **Plain keys / sequences** (`'e'`, `'/'`, `['g', 'p']`) — pressed in
+ *   order with no modifier held. A plain single key is just a sequence of
+ *   length one, so matching is uniform.
+ *
+ * @module
+ */
+/** Sequence buffer entries expire after this many milliseconds. */
+export const SEQUENCE_TIMEOUT_MS = 1000;
+/** Whether the runtime platform treats `$mod` as ⌘ (macOS / iOS). */
+export function isApplePlatform() {
+    // `globalThis.navigator` rather than the bare identifier: on a runtime
+    // without one, a direct reference would throw before the guard could run.
+    if (typeof globalThis.navigator === 'undefined')
+        return false;
+    return /mac|iphone|ipad|ipod/i.test(globalThis.navigator.platform);
+}
+/**
+ * Whether a keyboard event's target is an editable surface — a form field or
+ * a contenteditable region (which covers a rich-text editor's root). Hotkeys
+ * without `allowInEditable` stay inert there so typing never fires actions.
+ */
+export function isEditableTarget(target) {
+    if (!(target instanceof HTMLElement))
+        return false;
+    return target.matches('input, textarea, select') || target.isContentEditable;
+}
+/** Whether a trigger is in the modifier-chord form (`'$mod+…'`). */
+function isModifierChord(trigger) {
+    return typeof trigger === 'string' && trigger.includes('+');
+}
+/** Normalise a plain-key trigger to its sequence form. `undefined` for a chord. */
+function asSequence(trigger) {
+    if (typeof trigger === 'string') {
+        return isModifierChord(trigger) ? undefined : [trigger];
+    }
+    return trigger;
+}
+/** Whether the event matches a `'$mod+key'` chord. */
+// Modifier matching is a flat run of guard comparisons (mod / alt / shift /
+// cross-platform exclusion); each early return is one rule of the chord
+// grammar, and extracting them would obscure the contract.
+function eventMatchesChord(event, chord) {
+    const parts = chord.split('+');
+    const key = parts.at(-1) ?? '';
+    // A plain array, not a `Set`: a chord carries at most three modifiers, so
+    // three `includes` scans beat building a hashed collection on every
+    // keystroke.
+    const modifiers = parts.slice(0, -1);
+    const wantsMod = modifiers.includes('$mod');
+    const wantsAlt = modifiers.includes('alt');
+    const wantsShift = modifiers.includes('shift');
+    const apple = isApplePlatform();
+    const modPressed = apple ? event.metaKey : event.ctrlKey;
+    // The non-$mod modifier must not also be held, so e.g. Ctrl+K on macOS
+    // doesn't trigger a ⌘K hotkey.
+    const otherModPressed = apple ? event.ctrlKey : event.metaKey;
+    if (wantsMod !== modPressed || otherModPressed)
+        return false;
+    if (wantsAlt !== event.altKey)
+        return false;
+    if (wantsShift && !event.shiftKey)
+        return false;
+    return event.key.toLowerCase() === key.toLowerCase();
+}
+/** Whether an event carries a chord modifier (⌘ / Ctrl / Alt). */
+export function hasChordModifier(event) {
+    return event.metaKey || event.ctrlKey || event.altKey;
+}
+/**
+ * Whether an event's key can participate in a sequence: a single printable
+ * character pressed without chord modifiers.
+ */
+export function isSequenceKey(event) {
+    return !hasChordModifier(event) && event.key.length === 1;
+}
+/**
+ * Find the action whose modifier chord matches the event. `actions` must
+ * already be in precedence order (page before global, later registrations
+ * first).
+ */
+export function matchChord(event, actions) {
+    return actions.find(({ action }) => typeof action.trigger === 'string' &&
+        action.trigger.includes('+') &&
+        eventMatchesChord(event, action.trigger))?.action;
+}
+// A single-pass scan that classifies every trigger as exact-match / prefix /
+// miss in one loop; splitting it into separate passes would be simpler per
+// function but iterate the registrations three times per keystroke.
+/**
+ * Match a candidate key buffer against the active plain-key triggers.
+ * `actions` must already be in precedence order.
+ */
+export function matchSequence(buffer, actions) {
+    let exact;
+    let isPrefix = false;
+    for (const { action } of actions) {
+        const trigger = action.trigger;
+        if (trigger === undefined)
+            continue;
+        const sequence = asSequence(trigger);
+        if (sequence === undefined)
+            continue;
+        if (sequence.length === buffer.length) {
+            if (exact === undefined && sequence.every((key, i) => key === buffer[i]))
+                exact = action;
+        }
+        else if (sequence.length > buffer.length && buffer.every((key, i) => key === sequence[i])) {
+            isPrefix = true;
+        }
+    }
+    return { exact, isPrefix };
+}
+/** Project a trigger into its display form for help overlays and badges. */
+export function triggerDisplay(trigger) {
+    if (typeof trigger === 'string') {
+        if (isModifierChord(trigger)) {
+            return {
+                keys: trigger.split('+').map((part) => (part === '$mod' ? part : part.toUpperCase())),
+                sequential: false,
+            };
+        }
+        return { keys: [trigger.toUpperCase()], sequential: false };
+    }
+    return { keys: trigger.map((key) => key.toUpperCase()), sequential: true };
+}

package/dist/hotkeys/registry.svelte.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The reactive hotkey / command registry.
+ *
+ * One instance lives in the app's Svelte context. The root layout registers
+ * `global` actions; pages register `page` actions that are torn down when the
+ * page unmounts. The registry is the single source of truth for three
+ * consumers:
+ *
+ * - `HotkeyProvider` — matches keyboard events against active triggers.
+ * - `CommandPalette` — lists palette-visible actions.
+ * - `HotkeyHelpDialog` — lists actions that carry triggers.
+ *
+ * Role gating happens here: actions registered with `requiresAdmin` are
+ * dropped from every read surface when the viewer is not an administrator, so
+ * non-admin users never see (or can fire) them.
+ *
+ * @module
+ */
+import type { CommandAction, HotkeyScope, RegisteredAction } from './types.ts';
+/** What `createHotkeyRegistry` needs from the app: the admin check and the dev flag. */
+export interface HotkeyRegistryOptions {
+    /** Whether the current viewer is an administrator. Read lazily so it can be reactive. */
+    isAdmin: () => boolean;
+    /**
+     * Whether this is a dev build. When true, registering a batch whose trigger
+     * shadows an existing one logs a console warning. An app wires this to its
+     * bundler's dev flag (SvelteKit's `$app/environment` `dev`); defaults to
+     * `false`.
+     */
+    dev?: boolean | undefined;
+}
+/** The reactive set of registered hotkey actions that `HotkeyProvider`, `CommandPalette` and `HotkeyHelpDialog` read; page registrations win over global ones. */
+export declare class HotkeyRegistry {
+    #private;
+    /** Whether the command palette is open. Bound by `CommandPalette`. */
+    paletteOpen: boolean;
+    /** Whether the hotkey help overlay is open. Bound by `HotkeyHelpDialog`. */
+    helpOpen: boolean;
+    constructor(options: HotkeyRegistryOptions);
+    /**
+     * Register a batch of actions under a scope. Returns an unregister
+     * function; callers are expected to invoke it on unmount (the
+     * `registerHotkeys` helper wires this to `$effect` cleanup).
+     */
+    register(scope: HotkeyScope, actions: readonly CommandAction[]): () => void;
+    /**
+     * Role-filtered active registrations in match-precedence order: page scope
+     * before global, later registrations first within a scope.
+     */
+    readonly active: readonly RegisteredAction[];
+    /** Active actions that should appear in the command palette, in registration order. */
+    readonly paletteActions: readonly RegisteredAction[];
+    /** Active actions that carry a keyboard trigger, for the help overlay. */
+    readonly hotkeys: readonly RegisteredAction[];
+}

package/dist/hotkeys/registry.svelte.js

@@ -0,0 +1,110 @@
+/**
+ * The reactive hotkey / command registry.
+ *
+ * One instance lives in the app's Svelte context. The root layout registers
+ * `global` actions; pages register `page` actions that are torn down when the
+ * page unmounts. The registry is the single source of truth for three
+ * consumers:
+ *
+ * - `HotkeyProvider` — matches keyboard events against active triggers.
+ * - `CommandPalette` — lists palette-visible actions.
+ * - `HotkeyHelpDialog` — lists actions that carry triggers.
+ *
+ * Role gating happens here: actions registered with `requiresAdmin` are
+ * dropped from every read surface when the viewer is not an administrator, so
+ * non-admin users never see (or can fire) them.
+ *
+ * @module
+ */
+/**
+ * Whether two triggers denote the same keystroke. A structural comparison
+ * rather than a JSON round-trip: a chord is a string and a sequence is an
+ * array, so the two forms never collide.
+ */
+function sameTrigger(self, that) {
+    return typeof self === 'string' || typeof that === 'string'
+        ? self === that
+        : self.length === that.length && self.every((key, index) => key === that[index]);
+}
+/** A trigger rendered for the dev warning below. */
+function formatTrigger(trigger) {
+    return typeof trigger === 'string' ? `"${trigger}"` : `["${trigger.join('", "')}"]`;
+}
+/** Dev-only console warning when a new registration shadows an existing trigger. */
+function warnOnTriggerConflicts(added, existing) {
+    for (const entry of added) {
+        const trigger = entry.action.trigger;
+        if (trigger === undefined)
+            continue;
+        const conflict = existing.find((other) => other.action.trigger !== undefined && sameTrigger(other.action.trigger, trigger));
+        if (conflict) {
+            // A dev-build diagnostic: it has to reach the browser console the
+            // developer is looking at, which is why this is the one `console` call
+            // in the package.
+            console.warn(`[hotkeys] Trigger ${formatTrigger(trigger)} of "${entry.action.id}" ` +
+                `shadows "${conflict.action.id}" (${conflict.scope}). ` +
+                `Page-scope and later registrations win.`);
+        }
+    }
+}
+/** Page scope sorts before global scope. */
+const scopeRank = (entry) => (entry.scope === 'page' ? 0 : 1);
+/**
+ * Match precedence: page scope first, then the most recent registration.
+ * A plain comparator — the composed `Order` this was ported from is the only
+ * thing that changed.
+ */
+const byMatchPrecedence = (a, b) => scopeRank(a) - scopeRank(b) || b.order - a.order;
+/** Ascending registration order (earlier registrations first). */
+const byOrder = (a, b) => a.order - b.order;
+/** The reactive set of registered hotkey actions that `HotkeyProvider`, `CommandPalette` and `HotkeyHelpDialog` read; page registrations win over global ones. */
+export class HotkeyRegistry {
+    #registrations = $state([]);
+    #nextOrder = 0;
+    #isAdmin;
+    #dev;
+    /** Whether the command palette is open. Bound by `CommandPalette`. */
+    paletteOpen = $state(false);
+    /** Whether the hotkey help overlay is open. Bound by `HotkeyHelpDialog`. */
+    helpOpen = $state(false);
+    constructor(options) {
+        this.#isAdmin = options.isAdmin;
+        this.#dev = options.dev ?? false;
+    }
+    /**
+     * Register a batch of actions under a scope. Returns an unregister
+     * function; callers are expected to invoke it on unmount (the
+     * `registerHotkeys` helper wires this to `$effect` cleanup).
+     */
+    register(scope, actions) {
+        const added = actions.map((action) => ({ scope, action, order: this.#nextOrder++ }));
+        if (this.#dev)
+            warnOnTriggerConflicts(added, this.#registrations);
+        this.#registrations = [...this.#registrations, ...added];
+        return () => {
+            // Remove by the stable monotonic `order`, NOT object identity. `$state`
+            // deep-proxies `#registrations`, so entries read back here are proxies
+            // that never `===` the raw objects captured in `added` — a `Set(added)`
+            // membership test would match nothing and remove nothing, leaking the
+            // batch. `registerHotkeys` wires this closure to `$effect` cleanup, so
+            // every reactive re-registration would otherwise accumulate duplicates.
+            const orders = new Set(added.map((entry) => entry.order));
+            this.#registrations = this.#registrations.filter((entry) => !orders.has(entry.order));
+        };
+    }
+    /**
+     * Role-filtered active registrations in match-precedence order: page scope
+     * before global, later registrations first within a scope.
+     */
+    active = $derived(this.#registrations
+        .filter((entry) => !entry.action.requiresAdmin || this.#isAdmin())
+        .toSorted(byMatchPrecedence));
+    /** Active actions that should appear in the command palette, in registration order. */
+    paletteActions = $derived(this.#registrations
+        .filter((entry) => (!entry.action.requiresAdmin || this.#isAdmin()) && entry.action.paletteVisible !== false)
+        .toSorted(byOrder));
+    /** Active actions that carry a keyboard trigger, for the help overlay. */
+    hotkeys = $derived(this.#registrations
+        .filter((entry) => (!entry.action.requiresAdmin || this.#isAdmin()) && entry.action.trigger !== undefined)
+        .toSorted(byOrder));
+}

package/dist/hotkeys/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The registration contract shared by the hotkey registry and the command
+ * palette.
+ *
+ * A {@link CommandAction} is the unit of both systems: a labelled, runnable
+ * action that may carry a keyboard trigger (making it a hotkey) and may
+ * appear in the command palette (making it discoverable). Pages and the
+ * global shell register actions through the registry; the palette and the
+ * help overlay read the same registrations back, so there is exactly one
+ * source of truth for "what can the viewer do right now".
+ *
+ * Every optional member is declared `T | undefined`: the workspace compiles
+ * with `exactOptionalPropertyTypes`, and these objects are written as plain
+ * literals by application code that forwards its own optional values.
+ *
+ * @module
+ */
+/**
+ * A single-keystroke trigger.
+ *
+ * Grammar: zero or more `+`-separated modifiers followed by a key, e.g.
+ * `'$mod+k'`, `'/'`, `'?'`, `'e'`. `$mod` resolves to ⌘ on macOS and Ctrl
+ * elsewhere. Shift is never written explicitly — shifted characters (like
+ * `?`) already arrive shifted in `KeyboardEvent.key`.
+ */
+export type HotkeyChord = string;
+/**
+ * A multi-keystroke trigger pressed in order, e.g. `['g', 'p']`. Only plain
+ * (unmodified) printable keys participate in sequences.
+ */
+export type HotkeySequence = readonly string[];
+/** A hotkey trigger: a chord pressed together (`'$mod+k'`) or a sequence pressed in turn (`['g', 'p']`). */
+export type HotkeyTrigger = HotkeyChord | HotkeySequence;
+/** The command-palette section a `CommandAction` is listed under. Drives section headings and ordering. */
+export type CommandActionGroup = 'actions' | 'navigation';
+/**
+ * Where a hotkey registration lives: `global` for the app shell, `page` for the mounted page. Page registrations are torn down when the
+ * registering page unmounts and win over global registrations on trigger
+ * conflicts.
+ */
+export type HotkeyScope = 'global' | 'page';
+/** One action the hotkey registry and the command palette offer: an id, a label, what it runs and, optionally, its trigger. */
+export interface CommandAction {
+    /** Stable unique id, e.g. `'nav.posts'`, `'posts.create'`. */
+    id: string;
+    /** Human-readable label. An i18n app resolves its message at registration. */
+    label: string;
+    /** What runs on activation (navigate, focus, open a dialog, …). */
+    run: () => void | Promise<void>;
+    /** Palette section. */
+    group: CommandActionGroup;
+    /** Optional keyboard trigger. Actions without one are palette-only. */
+    trigger?: HotkeyTrigger | undefined;
+    /**
+     * When true the registry drops the action entirely for non-admin viewers —
+     * it neither fires as a hotkey nor appears in the palette.
+     */
+    requiresAdmin?: boolean | undefined;
+    /** Set false to keep an action hotkey-only (hidden from the palette). */
+    paletteVisible?: boolean | undefined;
+    /**
+     * Allow the trigger to fire while focus is inside an editable element
+     * (input / textarea / contenteditable). Reserved for the palette opener;
+     * everything else stays inert while typing.
+     */
+    allowInEditable?: boolean | undefined;
+}
+/** A registration entry: an action plus the scope it was registered under. */
+export interface RegisteredAction {
+    /** The scope it was registered under. */
+    scope: HotkeyScope;
+    /** The action as registered. */
+    action: CommandAction;
+}

package/dist/hotkeys/types.js

@@ -0,0 +1,18 @@
+/**
+ * The registration contract shared by the hotkey registry and the command
+ * palette.
+ *
+ * A {@link CommandAction} is the unit of both systems: a labelled, runnable
+ * action that may carry a keyboard trigger (making it a hotkey) and may
+ * appear in the command palette (making it discoverable). Pages and the
+ * global shell register actions through the registry; the palette and the
+ * help overlay read the same registrations back, so there is exactly one
+ * source of truth for "what can the viewer do right now".
+ *
+ * Every optional member is declared `T | undefined`: the workspace compiles
+ * with `exactOptionalPropertyTypes`, and these objects are written as plain
+ * literals by application code that forwards its own optional values.
+ *
+ * @module
+ */
+export {};