foldkit 0.160.0 → 0.161.0

package/dist/subscription/keyboardShortcuts.d.ts

@@ -0,0 +1,110 @@
+import { Duration, Stream } from 'effect';
+/** Whether a shortcut may fire when its keyboard event comes from an editable element. */
+export type WhileTyping = 'Suppress' | 'Allow';
+/** A single key press or a sequence of two or more key presses. */
+export type KeyboardShortcut = string | Readonly<[string, string, ...Array<string>]>;
+type BindingBase<Message> = Readonly<{
+    shortcut: KeyboardShortcut;
+    toMessage: (event: KeyboardEvent) => Message;
+    isEnabled?: boolean;
+    whileTyping?: WhileTyping;
+    preventDefault?: boolean;
+}>;
+/**
+ * One entry in a {@link keyboardShortcuts} binding table.
+ *
+ * A string describes one key press, such as `'/'`, `'Escape'`, or `'Mod+K'`.
+ * An array describes a sequence of at least two presses, such as
+ * `['G', 'H']` or `['G', 'Shift+G']`.
+ */
+export type KeyboardShortcutBinding<Message> = BindingBase<Message> & (Readonly<{
+    shortcut: string;
+    whenRepeated?: 'Ignore' | 'Allow';
+}> | Readonly<{
+    shortcut: Readonly<[string, string, ...Array<string>]>;
+    whenRepeated?: never;
+}>);
+type ModKey = 'Control' | 'Meta';
+/** Configuration for the {@link keyboardShortcuts} Stream helper. */
+export type KeyboardShortcutsConfig<Message> = Readonly<{
+    bindings: ReadonlyArray<KeyboardShortcutBinding<Message>>;
+    target?: EventTarget | (() => EventTarget);
+    modKey?: ModKey;
+    sequenceTimeout?: Duration.Input;
+}>;
+/**
+ * Build a Stream that turns declarative keyboard shortcuts into Messages.
+ *
+ * A string shortcut describes one key press. Modifiers are joined with `+`:
+ * `'Mod+K'`, `'Control+Shift+P'`, or `'Alt+ArrowDown'`. The supported modifiers
+ * are `Mod`, `Control`, `Meta`, `Alt`, and `Shift`. `Mod` resolves to Meta on
+ * Apple platforms and Control elsewhere; `modKey` can override that choice.
+ * Matching uses `KeyboardEvent.key`, case-insensitively, after the active
+ * keyboard layout has been applied. Use `Space` and `Plus` for those keys.
+ *
+ * An array describes an ordered sequence of two or more presses. Every press
+ * uses the same grammar, so `['G', 'Shift+G']` is valid. Sequences reset after
+ * one second by default; `sequenceTimeout` accepts any Effect Duration input.
+ * Modifier-only events and repeated keydowns do not advance a sequence.
+ *
+ * Shortcuts are suppressed by default when the event's composed path contains
+ * an `input`, `textarea`, `select`, or contenteditable element. Set
+ * `whileTyping` to `'Allow'` for a binding that must work there. Events emitted
+ * during IME composition are always ignored. Repeated keydowns are ignored for
+ * one-press shortcuts unless `whenRepeated` is `'Allow'`. An event another
+ * handler already canceled is ignored and clears any sequence in progress.
+ *
+ * Matched key presses call `preventDefault()` before dispatching. For a
+ * sequence, that policy applies to every matched press. Set `preventDefault`
+ * to `false` to opt out. Sequences sharing a prefix must use the same policy.
+ * Duplicate bindings and a complete shortcut that is also a sequence prefix
+ * are rejected when the Stream is created.
+ *
+ * This helper returns a Stream, not a complete Subscription entry. Use
+ * `Subscription.persistent` for a fixed table. When availability depends on
+ * the Model that owns the entry, build it inside `dependenciesToStream` and
+ * derive each binding's `isEnabled` from the dependency record. A dependency
+ * change opens a new Stream scope and resets any sequence in progress. If a
+ * parent owns a condition for a lifted child, declare the table at that parent
+ * or put shortcuts with different parent-owned lifetimes in separate child
+ * entries so `Subscription.lift` can gate them individually. If the meaning
+ * of a key depends on the Model, dispatch a factual key Message and decide
+ * what it means in update instead of reading the Model from `toMessage`.
+ *
+ * @example
+ * ```typescript
+ * const subscriptions = Subscription.make<Model, Message>()(entry => ({
+ *   shortcuts: entry(
+ *     { isPaletteOpen: Schema.Boolean },
+ *     {
+ *       modelToDependencies: model => ({
+ *         isPaletteOpen: model.paletteState._tag === 'Open',
+ *       }),
+ *       dependenciesToStream: ({ isPaletteOpen }) =>
+ *         Subscription.keyboardShortcuts<Message>({
+ *           bindings: [
+ *             {
+ *               shortcut: 'Escape',
+ *               isEnabled: isPaletteOpen,
+ *               whileTyping: 'Allow',
+ *               toMessage: () => Message.PressedEscape(),
+ *             },
+ *             {
+ *               shortcut: 'Mod+K',
+ *               whileTyping: 'Allow',
+ *               toMessage: () => Message.PressedSearchShortcut(),
+ *             },
+ *             {
+ *               shortcut: ['G', 'L'],
+ *               toMessage: () => Message.PressedListShortcut(),
+ *             },
+ *           ],
+ *         }),
+ *     },
+ *   ),
+ * }))
+ * ```
+ */
+export declare const keyboardShortcuts: <Message>(config: KeyboardShortcutsConfig<Message>) => Stream.Stream<Message>;
+export {};
+//# sourceMappingURL=keyboardShortcuts.d.ts.map

package/dist/subscription/keyboardShortcuts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboardShortcuts.d.ts","sourceRoot":"","sources":["../../src/subscription/keyboardShortcuts.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,QAAQ,EAOR,MAAM,EAGP,MAAM,QAAQ,CAAA;AAEf,0FAA0F;AAC1F,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,OAAO,CAAA;AAE9C,mEAAmE;AACnE,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;AAEhD,KAAK,WAAW,CAAC,OAAO,IAAI,QAAQ,CAAC;IACnC,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,SAAS,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAA;IAC5C,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB,CAAC,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,CAAC,OAAO,IAAI,WAAW,CAAC,OAAO,CAAC,GACjE,CACI,QAAQ,CAAC;IACP,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAA;CAClC,CAAC,GACF,QAAQ,CAAC;IACP,QAAQ,EAAE,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IACtD,YAAY,CAAC,EAAE,KAAK,CAAA;CACrB,CAAC,CACL,CAAA;AAEH,KAAK,MAAM,GAAG,SAAS,GAAG,MAAM,CAAA;AAEhC,qEAAqE;AACrE,MAAM,MAAM,uBAAuB,CAAC,OAAO,IAAI,QAAQ,CAAC;IACtD,QAAQ,EAAE,aAAa,CAAC,uBAAuB,CAAC,OAAO,CAAC,CAAC,CAAA;IACzD,MAAM,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,CAAC,CAAA;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,eAAe,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAA;CACjC,CAAC,CAAA;AA8sBF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,UAC/B,uBAAuB,CAAC,OAAO,CAAC,KACvC,MAAM,CAAC,MAAM,CAAC,OAAO,CACwC,CAAA"}

package/dist/subscription/keyboardShortcuts.js

@@ -0,0 +1,444 @@
+import { Array, Duration, Effect, Match, Number, Option, Predicate, Queue, Stream, String, pipe, } from 'effect';
+const DEFAULT_SEQUENCE_TIMEOUT = Duration.seconds(1);
+const APPLE_PLATFORM_PATTERN = /Mac|iPhone|iPad|iPod/;
+const MODIFIER_KEYS = [
+    'alt',
+    'altgraph',
+    'capslock',
+    'control',
+    'fn',
+    'fnlock',
+    'hyper',
+    'meta',
+    'numlock',
+    'os',
+    'scrolllock',
+    'shift',
+    'super',
+    'symbol',
+    'symbollock',
+];
+const SHORTCUT_MODIFIERS = [
+    'alt',
+    'control',
+    'meta',
+    'mod',
+    'shift',
+];
+const NON_CANONICAL_MODIFIERS = [
+    'cmd',
+    'command',
+    'ctrl',
+    'option',
+];
+const normalizeKey = (key) => {
+    if (key === ' ') {
+        return key;
+    }
+    const normalized = pipe(key, String.trim, String.toLowerCase);
+    return Match.value(normalized).pipe(Match.withReturnType(), Match.when('space', () => ' '), Match.when('plus', () => '+'), Match.orElse(value => value));
+};
+const displayKey = (key) => Match.value(key).pipe(Match.withReturnType(), Match.when(' ', () => 'space'), Match.when('+', () => 'plus'), Match.orElse(value => value));
+const identifierPartWhen = (isIncluded, identifier) => Option.liftPredicate(identifier, () => isIncluded);
+const pressIdentifier = (press, modKey) => {
+    const isModUnresolved = press.isModRequired && modKey === undefined;
+    const isControlRequired = press.isControlRequired || (press.isModRequired && modKey === 'Control');
+    const isMetaRequired = press.isMetaRequired || (press.isModRequired && modKey === 'Meta');
+    return pipe([
+        identifierPartWhen(isModUnresolved, 'mod'),
+        identifierPartWhen(isControlRequired, 'control'),
+        identifierPartWhen(isMetaRequired, 'meta'),
+        identifierPartWhen(press.isAltRequired, 'alt'),
+        identifierPartWhen(press.isShiftRequired, 'shift'),
+        Option.some(displayKey(press.key)),
+    ], Array.getSomes, Array.join('+'));
+};
+const throwInvalidShortcut = (shortcut, reason) => {
+    throw new Error(`Invalid keyboard shortcut "${shortcut}": ${reason}`);
+};
+const hasDuplicateModifiers = (modifiers) => Array.length(Array.dedupe(modifiers)) !== Array.length(modifiers);
+const parsePress = (shortcut) => {
+    const tokens = pipe(shortcut, String.split('+'), Array.map(token => pipe(token, String.trim, String.toLowerCase)));
+    if (Array.some(tokens, String.isEmpty)) {
+        return throwInvalidShortcut(shortcut, 'each modifier and key must be named; use "Plus" for the + key');
+    }
+    const maybeNonCanonicalModifier = Array.findFirst(tokens, token => Array.contains(NON_CANONICAL_MODIFIERS, token));
+    if (Option.isSome(maybeNonCanonicalModifier)) {
+        return throwInvalidShortcut(shortcut, `unknown modifier "${maybeNonCanonicalModifier.value}"`);
+    }
+    const [modifiers, keyToken] = Array.unappend(tokens);
+    const key = normalizeKey(keyToken);
+    if (Array.contains(SHORTCUT_MODIFIERS, keyToken) ||
+        Array.contains(MODIFIER_KEYS, key)) {
+        return throwInvalidShortcut(shortcut, 'a non-modifier key is required');
+    }
+    const maybeUnknownModifier = Array.findFirst(modifiers, modifier => !Array.contains(SHORTCUT_MODIFIERS, modifier));
+    if (Option.isSome(maybeUnknownModifier)) {
+        return throwInvalidShortcut(shortcut, `unknown modifier "${maybeUnknownModifier.value}"`);
+    }
+    if (hasDuplicateModifiers(modifiers)) {
+        return throwInvalidShortcut(shortcut, 'a modifier is repeated');
+    }
+    const isModRequired = Array.contains(modifiers, 'mod');
+    const isControlRequired = Array.contains(modifiers, 'control');
+    const isMetaRequired = Array.contains(modifiers, 'meta');
+    if (isModRequired && (isControlRequired || isMetaRequired)) {
+        return throwInvalidShortcut(shortcut, 'Mod cannot be combined with Control or Meta');
+    }
+    const isAltRequired = Array.contains(modifiers, 'alt');
+    const isShiftRequired = Array.contains(modifiers, 'shift');
+    const pressRequirements = {
+        key,
+        isAltRequired,
+        isControlRequired,
+        isMetaRequired,
+        isModRequired,
+        isShiftRequired,
+    };
+    return {
+        ...pressRequirements,
+        identifier: pressIdentifier(pressRequirements),
+    };
+};
+const compileBinding = (binding) => {
+    if (!Predicate.isString(binding.shortcut) &&
+        Array.length(binding.shortcut) < 2) {
+        throw new Error('A keyboard shortcut sequence requires at least two keys');
+    }
+    const presses = Predicate.isString(binding.shortcut)
+        ? Array.of(parsePress(binding.shortcut))
+        : Array.map(binding.shortcut, parsePress);
+    return {
+        presses,
+        toMessage: binding.toMessage,
+        whileTyping: binding.whileTyping ?? 'Suppress',
+        preventDefault: binding.preventDefault ?? true,
+        whenRepeated: binding.whenRepeated ?? 'Ignore',
+    };
+};
+const bindingLabel = (binding) => pipe(binding.presses, Array.map(press => press.identifier), Array.join(' '));
+const pressesOverlap = (first, second, modKey) => pressIdentifier(first, modKey) === pressIdentifier(second, modKey);
+const isBindingPrefix = (prefix, binding, modKey) => {
+    if (Array.length(prefix.presses) > Array.length(binding.presses)) {
+        return false;
+    }
+    return Array.every(Array.zip(prefix.presses, binding.presses), ([prefixPress, bindingPress]) => pressesOverlap(prefixPress, bindingPress, modKey));
+};
+const sharesFirstPress = (first, second, modKey) => pressesOverlap(Array.headNonEmpty(first.presses), Array.headNonEmpty(second.presses), modKey);
+const validateBindingPair = (binding, otherBinding, modKey) => {
+    const bindingIsPrefix = isBindingPrefix(binding, otherBinding, modKey);
+    const otherBindingIsPrefix = isBindingPrefix(otherBinding, binding, modKey);
+    if (bindingIsPrefix || otherBindingIsPrefix) {
+        const relation = Array.length(binding.presses) === Array.length(otherBinding.presses)
+            ? 'duplicates'
+            : 'overlaps as a complete shortcut and a sequence prefix';
+        throw new Error(`Keyboard shortcut "${bindingLabel(binding)}" ${relation} "${bindingLabel(otherBinding)}"`);
+    }
+    if (sharesFirstPress(binding, otherBinding, modKey) &&
+        binding.preventDefault !== otherBinding.preventDefault) {
+        throw new Error(`Keyboard shortcut sequences beginning with the same key must use the same preventDefault setting: "${bindingLabel(binding)}" and "${bindingLabel(otherBinding)}"`);
+    }
+};
+const validateBindings = (bindings, modKey) => {
+    Array.forEach(bindings, (binding, index) => {
+        Array.forEach(Array.drop(bindings, index + 1), otherBinding => {
+            validateBindingPair(binding, otherBinding, modKey);
+        });
+    });
+};
+const compileEnabledBindings = (bindings) => pipe(bindings, Array.filter(binding => binding.isEnabled !== false), Array.map(compileBinding));
+const isSequence = (binding) => Array.length(binding.presses) > 1;
+const isModifierEvent = (event) => Array.contains(MODIFIER_KEYS, normalizeKey(event.key));
+const isEditableTarget = (target) => {
+    if (!(target instanceof HTMLElement)) {
+        return false;
+    }
+    const tag = String.toLowerCase(target.tagName);
+    return (tag === 'input' ||
+        tag === 'textarea' ||
+        tag === 'select' ||
+        target.isContentEditable);
+};
+const isFromEditable = (event) => Array.some(event.composedPath(), isEditableTarget);
+const isAllowedWhileTyping = (binding, isEditable) => !isEditable || binding.whileTyping === 'Allow';
+const resolveModKey = (configuredModKey) => {
+    if (configuredModKey !== undefined) {
+        return configuredModKey;
+    }
+    return APPLE_PLATFORM_PATTERN.test(navigator.userAgent) ? 'Meta' : 'Control';
+};
+const pressMatches = (press, event, modKey) => {
+    const isControlRequired = press.isControlRequired || (press.isModRequired && modKey === 'Control');
+    const isMetaRequired = press.isMetaRequired || (press.isModRequired && modKey === 'Meta');
+    return (press.key === normalizeKey(event.key) &&
+        press.isAltRequired === event.altKey &&
+        isControlRequired === event.ctrlKey &&
+        isMetaRequired === event.metaKey &&
+        press.isShiftRequired === event.shiftKey);
+};
+const firstPressMatches = (binding, event, modKey) => pressMatches(Array.headNonEmpty(binding.presses), event, modKey);
+const nextPressMatches = (binding, matchedPressCount, event, modKey) => Option.exists(Array.get(binding.presses, matchedPressCount), press => pressMatches(press, event, modKey));
+const resolveTarget = (target) => {
+    if (Predicate.isFunction(target)) {
+        return target();
+    }
+    return target ?? document;
+};
+const resolveValidationModKey = (configuredModKey) => {
+    if (configuredModKey !== undefined) {
+        return Option.some(configuredModKey);
+    }
+    if (typeof navigator === 'undefined') {
+        return Option.none();
+    }
+    return Option.some(resolveModKey(undefined));
+};
+const compileKeyboardShortcutsConfig = (config) => {
+    const bindings = compileEnabledBindings(config.bindings);
+    const sequenceTimeout = Duration.toMillis(config.sequenceTimeout ?? DEFAULT_SEQUENCE_TIMEOUT);
+    if (!globalThis.Number.isFinite(sequenceTimeout) || sequenceTimeout <= 0) {
+        throw new Error('sequenceTimeout must be a finite duration above zero');
+    }
+    const maybeValidationModKey = resolveValidationModKey(config.modKey);
+    if (Option.isSome(maybeValidationModKey)) {
+        validateBindings(bindings, maybeValidationModKey.value);
+    }
+    return {
+        bindings,
+        modKey: config.modKey,
+        sequenceTimeout,
+        target: config.target,
+    };
+};
+const makeSequenceController = (sequenceTimeout) => {
+    const state = {
+        maybeSequence: Option.none(),
+    };
+    const clearSequence = () => {
+        if (Option.isSome(state.maybeSequence)) {
+            clearTimeout(state.maybeSequence.value.timeout);
+        }
+        state.maybeSequence = Option.none();
+    };
+    const setSequence = (sequence) => {
+        clearSequence();
+        state.maybeSequence = Option.some({
+            ...sequence,
+            timeout: setTimeout(clearSequence, sequenceTimeout),
+        });
+    };
+    return {
+        clearSequence,
+        readSequence: () => state.maybeSequence,
+        setSequence,
+    };
+};
+const emitBindingMessage = (context, binding, event) => {
+    context.sequenceController.clearSequence();
+    if (binding.preventDefault) {
+        event.preventDefault();
+    }
+    context.emitMessage(binding.toMessage(event));
+};
+const isMatchingOnePressBinding = (event, modKey, isEditable) => (binding) => !isSequence(binding) &&
+    isAllowedWhileTyping(binding, isEditable) &&
+    (!event.repeat || binding.whenRepeated === 'Allow') &&
+    firstPressMatches(binding, event, modKey);
+const startFreshSequence = (context, event) => {
+    const isEditable = isFromEditable(event);
+    const maybeKeyBinding = Array.findFirst(context.bindings, isMatchingOnePressBinding(event, context.modKey, isEditable));
+    if (Option.isSome(maybeKeyBinding)) {
+        emitBindingMessage(context, maybeKeyBinding.value, event);
+        return;
+    }
+    if (event.repeat) {
+        return;
+    }
+    const sequenceBindings = Array.filter(context.bindings, binding => isSequence(binding) &&
+        isAllowedWhileTyping(binding, isEditable) &&
+        firstPressMatches(binding, event, context.modKey));
+    if (Array.isArrayNonEmpty(sequenceBindings)) {
+        const firstBinding = Array.headNonEmpty(sequenceBindings);
+        context.sequenceController.setSequence({
+            bindings: sequenceBindings,
+            matchedPressCount: 1,
+        });
+        if (firstBinding.preventDefault) {
+            event.preventDefault();
+        }
+    }
+};
+const continueSequence = (context, sequence, event) => {
+    const isEditable = isFromEditable(event);
+    const matchingBindings = Array.filter(sequence.bindings, binding => isAllowedWhileTyping(binding, isEditable) &&
+        nextPressMatches(binding, sequence.matchedPressCount, event, context.modKey));
+    if (!Array.isReadonlyArrayNonEmpty(matchingBindings)) {
+        context.sequenceController.clearSequence();
+        startFreshSequence(context, event);
+        return;
+    }
+    const firstBinding = Array.headNonEmpty(matchingBindings);
+    const nextMatchedPressCount = Number.increment(sequence.matchedPressCount);
+    const maybeCompletedBinding = Array.findFirst(matchingBindings, binding => Array.length(binding.presses) === nextMatchedPressCount);
+    if (Option.isSome(maybeCompletedBinding)) {
+        emitBindingMessage(context, maybeCompletedBinding.value, event);
+        return;
+    }
+    context.sequenceController.setSequence({
+        bindings: matchingBindings,
+        matchedPressCount: nextMatchedPressCount,
+    });
+    if (firstBinding.preventDefault) {
+        event.preventDefault();
+    }
+};
+const handleKeyboardShortcutEvent = (context, event) => {
+    if (!(event instanceof KeyboardEvent)) {
+        return;
+    }
+    if (event.defaultPrevented || event.isComposing) {
+        context.sequenceController.clearSequence();
+        return;
+    }
+    if (isModifierEvent(event)) {
+        return;
+    }
+    const maybeSequence = context.sequenceController.readSequence();
+    if (event.repeat && Option.isSome(maybeSequence)) {
+        return;
+    }
+    Option.match(maybeSequence, {
+        onNone: () => startFreshSequence(context, event),
+        onSome: sequence => continueSequence(context, sequence, event),
+    });
+};
+const makeKeyboardShortcutHandler = (config) => {
+    const sequenceController = makeSequenceController(config.sequenceTimeout);
+    const context = {
+        bindings: config.bindings,
+        emitMessage: config.emitMessage,
+        modKey: config.modKey,
+        sequenceController,
+    };
+    return {
+        clearSequence: sequenceController.clearSequence,
+        handleEvent: event => handleKeyboardShortcutEvent(context, event),
+    };
+};
+const resolveOwnerDocument = (target) => {
+    if (target instanceof Document) {
+        return target;
+    }
+    if (target instanceof Node && target.ownerDocument !== null) {
+        return target.ownerDocument;
+    }
+    return document;
+};
+const acquireKeyboardShortcutListener = (config, emitMessage) => {
+    const target = resolveTarget(config.target);
+    const modKey = resolveModKey(config.modKey);
+    validateBindings(config.bindings, modKey);
+    const handler = makeKeyboardShortcutHandler({
+        bindings: config.bindings,
+        emitMessage,
+        modKey,
+        sequenceTimeout: config.sequenceTimeout,
+    });
+    const ownerDocument = resolveOwnerDocument(target);
+    const ownerWindow = ownerDocument.defaultView ?? window;
+    target.addEventListener('keydown', handler.handleEvent);
+    ownerWindow.addEventListener('blur', handler.clearSequence);
+    ownerDocument.addEventListener('visibilitychange', handler.clearSequence);
+    return {
+        ...handler,
+        ownerDocument,
+        ownerWindow,
+        target,
+    };
+};
+const releaseKeyboardShortcutListener = (listener) => {
+    listener.target.removeEventListener('keydown', listener.handleEvent);
+    listener.ownerWindow.removeEventListener('blur', listener.clearSequence);
+    listener.ownerDocument.removeEventListener('visibilitychange', listener.clearSequence);
+    listener.clearSequence();
+};
+const keyboardShortcutStream = (config) => Stream.callback(queue => {
+    const emitMessage = (message) => {
+        Queue.offerUnsafe(queue, message);
+    };
+    return Effect.acquireRelease(Effect.sync(() => acquireKeyboardShortcutListener(config, emitMessage)), listener => Effect.sync(() => releaseKeyboardShortcutListener(listener)));
+});
+/**
+ * Build a Stream that turns declarative keyboard shortcuts into Messages.
+ *
+ * A string shortcut describes one key press. Modifiers are joined with `+`:
+ * `'Mod+K'`, `'Control+Shift+P'`, or `'Alt+ArrowDown'`. The supported modifiers
+ * are `Mod`, `Control`, `Meta`, `Alt`, and `Shift`. `Mod` resolves to Meta on
+ * Apple platforms and Control elsewhere; `modKey` can override that choice.
+ * Matching uses `KeyboardEvent.key`, case-insensitively, after the active
+ * keyboard layout has been applied. Use `Space` and `Plus` for those keys.
+ *
+ * An array describes an ordered sequence of two or more presses. Every press
+ * uses the same grammar, so `['G', 'Shift+G']` is valid. Sequences reset after
+ * one second by default; `sequenceTimeout` accepts any Effect Duration input.
+ * Modifier-only events and repeated keydowns do not advance a sequence.
+ *
+ * Shortcuts are suppressed by default when the event's composed path contains
+ * an `input`, `textarea`, `select`, or contenteditable element. Set
+ * `whileTyping` to `'Allow'` for a binding that must work there. Events emitted
+ * during IME composition are always ignored. Repeated keydowns are ignored for
+ * one-press shortcuts unless `whenRepeated` is `'Allow'`. An event another
+ * handler already canceled is ignored and clears any sequence in progress.
+ *
+ * Matched key presses call `preventDefault()` before dispatching. For a
+ * sequence, that policy applies to every matched press. Set `preventDefault`
+ * to `false` to opt out. Sequences sharing a prefix must use the same policy.
+ * Duplicate bindings and a complete shortcut that is also a sequence prefix
+ * are rejected when the Stream is created.
+ *
+ * This helper returns a Stream, not a complete Subscription entry. Use
+ * `Subscription.persistent` for a fixed table. When availability depends on
+ * the Model that owns the entry, build it inside `dependenciesToStream` and
+ * derive each binding's `isEnabled` from the dependency record. A dependency
+ * change opens a new Stream scope and resets any sequence in progress. If a
+ * parent owns a condition for a lifted child, declare the table at that parent
+ * or put shortcuts with different parent-owned lifetimes in separate child
+ * entries so `Subscription.lift` can gate them individually. If the meaning
+ * of a key depends on the Model, dispatch a factual key Message and decide
+ * what it means in update instead of reading the Model from `toMessage`.
+ *
+ * @example
+ * ```typescript
+ * const subscriptions = Subscription.make<Model, Message>()(entry => ({
+ *   shortcuts: entry(
+ *     { isPaletteOpen: Schema.Boolean },
+ *     {
+ *       modelToDependencies: model => ({
+ *         isPaletteOpen: model.paletteState._tag === 'Open',
+ *       }),
+ *       dependenciesToStream: ({ isPaletteOpen }) =>
+ *         Subscription.keyboardShortcuts<Message>({
+ *           bindings: [
+ *             {
+ *               shortcut: 'Escape',
+ *               isEnabled: isPaletteOpen,
+ *               whileTyping: 'Allow',
+ *               toMessage: () => Message.PressedEscape(),
+ *             },
+ *             {
+ *               shortcut: 'Mod+K',
+ *               whileTyping: 'Allow',
+ *               toMessage: () => Message.PressedSearchShortcut(),
+ *             },
+ *             {
+ *               shortcut: ['G', 'L'],
+ *               toMessage: () => Message.PressedListShortcut(),
+ *             },
+ *           ],
+ *         }),
+ *     },
+ *   ),
+ * }))
+ * ```
+ */
+export const keyboardShortcuts = (config) => keyboardShortcutStream(compileKeyboardShortcutsConfig(config));

package/dist/subscription/public.d.ts

@@ -3,5 +3,7 @@ export type { EntryWithoutKeepAlive, GatedDependencies, Subscription, Subscripti
 export { animationFrame } from './animationFrame.js';
 export type { AnimationFrameConfig } from './animationFrame.js';
 export { fromEvent, fromEventFilterMap, fromEventFilterMapPreventDefault, } from './fromEvent.js';
-export type { FromEventConfig, FromEventFilterMapConfig, FromEventFilterMapPreventDefaultConfig, } from './fromEvent.js';
+export type { FromEventConfig, FromEventFilterMapConfig, FromEventFilterMapPreventDefaultConfig, TypedEventTarget, } from './fromEvent.js';
+export { keyboardShortcuts } from './keyboardShortcuts.js';
+export type { KeyboardShortcut, KeyboardShortcutBinding, KeyboardShortcutsConfig, WhileTyping, } from './keyboardShortcuts.js';
 //# sourceMappingURL=public.d.ts.map

package/dist/subscription/public.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/subscription/public.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAErE,YAAY,EACV,qBAAqB,EACrB,iBAAiB,EACjB,YAAY,EACZ,aAAa,GACd,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAE/D,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,gCAAgC,GACjC,MAAM,gBAAgB,CAAA;AAEvB,YAAY,EACV,eAAe,EACf,wBAAwB,EACxB,sCAAsC,GACvC,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/subscription/public.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAErE,YAAY,EACV,qBAAqB,EACrB,iBAAiB,EACjB,YAAY,EACZ,aAAa,GACd,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAE/D,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,gCAAgC,GACjC,MAAM,gBAAgB,CAAA;AAEvB,YAAY,EACV,eAAe,EACf,wBAAwB,EACxB,sCAAsC,EACtC,gBAAgB,GACjB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAE1D,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,uBAAuB,EACvB,WAAW,GACZ,MAAM,wBAAwB,CAAA"}

package/dist/subscription/public.js

@@ -1,3 +1,4 @@
 export { aggregate, lift, make, persistent } from './subscription.js';
 export { animationFrame } from './animationFrame.js';
 export { fromEvent, fromEventFilterMap, fromEventFilterMapPreventDefault, } from './fromEvent.js';
+export { keyboardShortcuts } from './keyboardShortcuts.js';

package/dist/subscription/subscription.d.ts

@@ -114,12 +114,72 @@ export type EntryBuilder<Model, Message, Services> = <const Fields extends Schem
  * ```
  */
 export declare const make: <Model, Message, Services = never>() => <Entries extends Readonly<Record<string, Entry<Model, Message, any, Services>>>>(build: (entry: EntryBuilder<Model, Message, Services>) => Entries) => { readonly [K in keyof Entries]: Entries[K] & SubscriptionBrand; };
+type AnySubscriptions = Readonly<Record<string, Subscription<any, any, any, any>>>;
+type AnySubscriptionsList = readonly [
+    AnySubscriptions,
+    ...ReadonlyArray<AnySubscriptions>
+];
+type EntriesOfRecord<SubscriptionsRecord> = SubscriptionsRecord extends unknown ? SubscriptionsRecord[keyof SubscriptionsRecord] : never;
+type EntriesOf<Records extends AnySubscriptionsList> = EntriesOfRecord<Records[number]>;
+type ModelOfEntry<AnyEntry> = [AnyEntry] extends [
+    Subscription<infer Model, any, any, any>
+] ? unknown extends Model ? never : Model : never;
+type MessageOfEntry<AnyEntry> = AnyEntry extends Subscription<any, infer Message, any, any> ? Message : never;
+type ServicesOfEntry<AnyEntry> = AnyEntry extends Subscription<any, any, any, infer Services> ? Services : never;
+type MessageOf<Records extends AnySubscriptionsList> = MessageOfEntry<EntriesOf<Records>>;
+type ServicesOf<Records extends AnySubscriptionsList> = ServicesOfEntry<EntriesOf<Records>>;
+type ReferenceModel<Records extends ReadonlyArray<AnySubscriptions>> = Records extends readonly [
+    infer Head extends AnySubscriptions,
+    ...infer Rest extends ReadonlyArray<AnySubscriptions>
+] ? [ModelOfEntry<EntriesOfRecord<Head>>] extends [never] ? ReferenceModel<Rest> : ModelOfEntry<EntriesOfRecord<Head>> : never;
+type CompatibleSubscriptions<Records extends AnySubscriptionsList> = {
+    readonly [Index in keyof Records]: Records[Index] & Subscriptions<ReferenceModel<Records>, MessageOf<Records>, ServicesOf<Records>>;
+};
+type RuntimeKey<Key> = Key extends string ? Key : Key extends number ? `${Key}` : never;
+type RuntimeEntries<RecordType> = {
+    readonly [Key in keyof RecordType as RuntimeKey<Key>]: RecordType[Key];
+};
+type MergeSubscriptions<Records extends ReadonlyArray<unknown>> = Records extends readonly [infer Head, ...infer Rest] ? RuntimeEntries<Head> & (Rest extends ReadonlyArray<unknown> ? MergeSubscriptions<Rest> : {}) : {};
 /**
  * Combines multiple Subscriptions records into one. Throws on duplicate
  * keys so a misconfigured aggregate fails loudly at startup rather than
  * silently overriding.
+ *
+ * Pass the records directly and the Model, Message, and Services are read
+ * off them. The Model of the first record with a Model dependency is the one
+ * every later record is checked against, so a record from another Model
+ * universe fails at its own argument position. Message and Services widen to
+ * the union across all records, which is what lets a record that needs an
+ * Effect service sit beside records that need none.
+ *
+ * The result keeps each record's keys and each entry's exact dependency type,
+ * schema, and `keepAliveEquivalence` variant, so a lifted entry's
+ * {@link GatedDependencies} survives aggregation.
+ *
+ * The curried form remains available for a record that has to be typed before
+ * its entries exist, such as a value annotated as
+ * `Subscriptions<Model, Message>` at a module boundary. It erases keys and
+ * per-entry dependency types, so reach for it only when the explicit contract
+ * is the point.
+ *
+ * @example
+ * ```ts
+ * const subscriptions = Subscription.aggregate(
+ *   homeSubscriptions,
+ *   roomSubscriptions,
+ * )
+ * ```
+ *
+ * @example Curried, when the record is typed before its entries exist:
+ * ```ts
+ * export const subscriptions: Subscription.Subscriptions<Model, Message> =
+ *   Subscription.aggregate<Model, Message>()(...records)
+ * ```
  */
-export declare const aggregate: <Model, Message, Services = never>() => (...records: ReadonlyArray<Subscriptions<Model, Message, Services>>) => Subscriptions<Model, Message, Services>;
+export declare const aggregate: {
+    <Model, Message, Services = never>(): (...records: ReadonlyArray<Subscriptions<Model, Message, Services>>) => Subscriptions<Model, Message, Services>;
+    <Records extends AnySubscriptionsList>(...records: CompatibleSubscriptions<Records>): MergeSubscriptions<Records>;
+};
 /**
  * Wraps a Stream as a Subscription entry whose lifecycle is independent of
  * the Model. The Stream runs for the lifetime of the Subscriptions record;