@inklu/keys 1.4.0 → 2.0.0

package/dist/src-DgYjA1oS.mjs

@@ -0,0 +1,1697 @@
+import { DEFAULT_SEQUENCE_TIMEOUT, HotkeyRecorder, HotkeySequenceRecorder, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, detectPlatform, formatForDisplay, getHotkeyManager, getSequenceManager, isModifierKey, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, validateHotkey } from "@tanstack/hotkeys";
+//#region src/bindings.ts
+/** Comparing, validating and serializing hotkey bindings. */
+/** Type guard narrowing a JSON value to a string. */
+function isJsonString(value) {
+	return typeof value === "string";
+}
+/**
+* Creates a sequence binding from ordered hotkey steps.
+*
+* @example
+* ```ts
+* keys: seq("G", "I")
+* ```
+*/
+function seq(...steps) {
+	return { sequence: steps };
+}
+/** Type guard checking if a binding is a sequence. */
+function isSequence(binding) {
+	return typeof binding === "object" && binding !== null && "sequence" in binding;
+}
+/**
+* Normalizes a binding input into an array of bindings. A one-step sequence
+* becomes a plain chord: it fires on exactly the same keypress, and keeping it
+* a sequence gave it a different signature from the chord, so the two were
+* neither arbitrated nor reported as conflicting — both ran.
+*/
+function toBindings(input) {
+	if (input == null) return [];
+	const candidates = Array.isArray(input) ? input : [input];
+	const bindings = [];
+	for (const candidate of candidates) {
+		if (candidate == null) continue;
+		if (isSequence(candidate) && candidate.sequence.length !== 1) {
+			if (candidate.sequence.length > 0) bindings.push({ sequence: [...candidate.sequence] });
+			continue;
+		}
+		const chord = isSequence(candidate) ? candidate.sequence[0] : candidate;
+		const trimmed = String(chord).trim();
+		if (trimmed) bindings.push(trimmed);
+	}
+	return bindings;
+}
+/** Generates a normalized signature for binding comparison and conflict detection. */
+function bindingSignature(binding, platform) {
+	if (isSequence(binding)) return `seq:${binding.sequence.map((step) => safeNormalize(step, platform)).join(" ")}`;
+	return `chord:${safeNormalize(binding, platform)}`;
+}
+/**
+* Whether one binding is a strict prefix of the other — chord `G` against
+* `G then I`, or `G then G` against `G then G then I`. The shorter binding
+* fires on the way to the longer one, so both run for a single intent.
+*/
+function isPrefixCollision(a, b, platform) {
+	const left = normalizedSteps(a, platform);
+	const right = normalizedSteps(b, platform);
+	if (left.length === right.length) return false;
+	const [short, long] = left.length < right.length ? [left, right] : [right, left];
+	return short.every((step, index) => step === long[index]);
+}
+function normalizedSteps(binding, platform) {
+	return (isSequence(binding) ? binding.sequence : [binding]).map((step) => safeNormalize(step, platform));
+}
+/**
+* Whether every step of a binding is a single printable character with no
+* Control, Alt or Meta — the "character key shortcuts" WCAG 2.1.4 lets users
+* turn off, since speech input and stray keypresses trigger them by accident.
+* Shift does not count as a modifier here: `Shift+A` still types a character.
+*/
+function isSingleKeyBinding(binding, platform) {
+	return (isSequence(binding) ? binding.sequence : [binding]).every((step) => {
+		try {
+			const parsed = parseHotkey(step, platform);
+			const character = parsed.key === void 0 ? /^(Key[A-Z]|Digit[0-9])$/.test(parsed.code ?? "") : parsed.key.length === 1;
+			return !parsed.ctrl && !parsed.alt && !parsed.meta && character;
+		} catch {
+			return false;
+		}
+	});
+}
+function safeNormalize(hotkey, platform) {
+	try {
+		return normalizeHotkey(hotkey, platform);
+	} catch {
+		return hotkey;
+	}
+}
+/** Converts a binding to a JSON-serializable format. */
+function serializeBinding(binding) {
+	return isSequence(binding) ? [...binding.sequence] : binding;
+}
+/** Deserializes a stored value into a valid binding, or `null` if invalid. */
+function deserializeBinding(value) {
+	if (isJsonString(value)) {
+		const trimmed = value.trim();
+		return trimmed && isBindingValid(trimmed) ? trimmed : null;
+	}
+	if (Array.isArray(value)) {
+		const steps = value.filter((step) => typeof step === "string" && step !== "");
+		if (steps.length === 0) return null;
+		const binding = steps.length === 1 ? steps[0] : { sequence: steps };
+		return isBindingValid(binding) ? binding : null;
+	}
+	return null;
+}
+/** Validates a binding's syntax without logging warnings or errors. */
+function validateBinding(binding) {
+	const steps = isSequence(binding) ? binding.sequence : [binding];
+	if (steps.length === 0) return {
+		valid: false,
+		errors: ["Sequence has no steps"],
+		warnings: []
+	};
+	const errors = [];
+	const warnings = [];
+	for (const step of steps) {
+		const result = validateHotkey(step);
+		errors.push(...result.errors);
+		warnings.push(...result.warnings);
+	}
+	return {
+		valid: errors.length === 0,
+		errors,
+		warnings
+	};
+}
+/** Checks whether a binding has valid syntax. */
+function isBindingValid(binding) {
+	return validateBinding(binding).valid;
+}
+//#endregion
+//#region src/display.ts
+/** Platform-aware hotkey display formatting and accessibility attributes. */
+const MAC_MODIFIER_RANK = new Map([
+	"Control",
+	"Alt",
+	"Shift",
+	"Meta"
+].flatMap((modifier, rank) => [[MAC_MODIFIER_SYMBOLS[modifier], rank], [MAC_MODIFIER_LABELS[modifier], rank]]));
+/** Formats a binding for display on the target platform (e.g. `⌘K` or `Ctrl+K`). */
+function formatBinding(binding, options) {
+	if (isSequence(binding)) return binding.sequence.map((step) => formatChord(step, options)).join(" ");
+	return formatChord(binding, options);
+}
+/** Splits a binding into display tokens for rendering `<kbd>` elements. */
+function bindingTokens(binding, options) {
+	if (isSequence(binding)) return binding.sequence.map((step) => formatChord(step, options));
+	return chordTokens(binding, options);
+}
+function formatChord(chord, options) {
+	const platform = options?.platform ?? detectPlatform();
+	if (platform !== "mac") return formatForDisplay(chord, {
+		...options,
+		platform
+	});
+	const symbols = options?.useSymbols ?? true;
+	const modifierSymbols = typeof symbols === "boolean" ? symbols : symbols.modifiers ?? true;
+	const separator = options?.separatorToken ?? (modifierSymbols ? " " : "+");
+	return chordTokens(chord, {
+		...options,
+		platform
+	}).join(separator);
+}
+function chordTokens(chord, options) {
+	const platform = options?.platform ?? detectPlatform();
+	const tokens = formatForDisplay(chord, {
+		...options,
+		platform,
+		parts: true
+	});
+	if (platform !== "mac" || tokens.length < 3) return tokens;
+	const key = tokens.pop() ?? "";
+	tokens.sort((a, b) => (MAC_MODIFIER_RANK.get(a) ?? MAC_MODIFIER_RANK.size) - (MAC_MODIFIER_RANK.get(b) ?? MAC_MODIFIER_RANK.size));
+	return [...tokens, key];
+}
+/**
+* Phrases a binding for a screen reader: `"Control+K"` for a chord,
+* `"G then I"` for a sequence. `aria-keyshortcuts` cannot express a sequence
+* (a space there means "or"), so this is how a sequence gets announced — put it
+* in visually hidden text or `aria-description`.
+*/
+function spokenBinding(binding, platform) {
+	return (isSequence(binding) ? binding.sequence : [binding]).map((step) => ariaChord(step, platform) || step).join(" then ");
+}
+/** Generates an `aria-keyshortcuts` attribute string for a binding. */
+function ariaKeyShortcuts(binding, platform) {
+	if (isSequence(binding)) return "";
+	return ariaChord(binding, platform);
+}
+function ariaChord(chord, platform) {
+	try {
+		return resolveMod(normalizeHotkey(chord, platform), platform);
+	} catch {
+		return "";
+	}
+}
+function resolveMod(hotkey, platform) {
+	if (!hotkey.includes("Mod")) return hotkey;
+	const modifier = (platform ?? detectPlatform()) === "mac" ? "Meta" : "Control";
+	return hotkey.split("+").map((part) => part === "Mod" ? modifier : part).join("+");
+}
+//#endregion
+//#region src/rebind.ts
+/** Controller for recording and applying hotkey rebindings. */
+const RECORDING_SCOPE = "inklu-keys:recording";
+const NO_STEPS = [];
+function toRecordedBinding(sequence) {
+	if (sequence.length === 0) return null;
+	if (sequence.length === 1) return sequence[0];
+	return { sequence: [...sequence] };
+}
+/**
+* Creates a rebinder instance for capturing and remapping a command's keys.
+*
+* @example
+* ```ts
+* const rebinder = createRebinder(commands, "palette.open", {
+*   onRecord: (binding, conflicts) => {
+*     if (conflicts.length) console.warn("Conflict with", conflicts[0].id);
+*   },
+* });
+* rebinder.start();
+* ```
+*/
+function createRebinder(registry, id, options = {}) {
+	const listeners = /* @__PURE__ */ new Set();
+	let state = {
+		recording: false,
+		binding: null,
+		steps: NO_STEPS,
+		conflicts: []
+	};
+	let scope = null;
+	const notify = (next) => {
+		state = next;
+		for (const listener of listeners) listener();
+	};
+	const releaseScope = () => {
+		scope?.();
+		scope = null;
+	};
+	const record = (binding) => {
+		releaseScope();
+		const conflicts = registry.conflicts(binding, {
+			ignore: id,
+			scope: registry.get(id)?.scope
+		});
+		const blocked = options.rejectConflicts === true && conflicts.length > 0;
+		if (options.apply !== false && !blocked) {
+			if (options.add) registry.keymap.add(id, binding);
+			else registry.keymap.set(id, binding);
+		}
+		notify({
+			recording: false,
+			binding,
+			steps: NO_STEPS,
+			conflicts
+		});
+		options.onRecord?.(binding, conflicts);
+	};
+	const cancelled = () => {
+		releaseScope();
+		notify({
+			...state,
+			recording: false,
+			steps: NO_STEPS
+		});
+		options.onCancel?.();
+	};
+	const cleared = () => {
+		releaseScope();
+		if (options.apply !== false) registry.keymap.set(id, null);
+		notify({
+			recording: false,
+			binding: null,
+			steps: NO_STEPS,
+			conflicts: []
+		});
+		options.onClear?.();
+	};
+	const sequenceMode = options.mode === "sequence";
+	const recordBy = "key";
+	const recorder = sequenceMode ? new HotkeySequenceRecorder({
+		recordBy,
+		ignoreInputs: options.ignoreInputs ?? true,
+		idleTimeoutMs: options.idleTimeout,
+		onRecord: (sequence) => {
+			const binding = toRecordedBinding(sequence);
+			if (binding === null) return;
+			record(binding);
+		},
+		onCancel: cancelled,
+		onClear: cleared
+	}) : new HotkeyRecorder({
+		recordBy,
+		ignoreInputs: options.ignoreInputs ?? true,
+		onRecord: (hotkey) => {
+			if (hotkey) record(hotkey);
+		},
+		onCancel: cancelled,
+		onClear: cleared
+	});
+	const stepsSubscription = recorder instanceof HotkeySequenceRecorder ? recorder.store.subscribe(() => {
+		if (!state.recording) return;
+		const steps = recorder.store.state.steps;
+		if (steps.length === state.steps.length) return;
+		notify({
+			...state,
+			steps: [...steps]
+		});
+	}) : null;
+	return {
+		start: () => {
+			if (state.recording) return;
+			scope ??= registry.pushScope(RECORDING_SCOPE, {
+				exclusive: true,
+				strict: true
+			});
+			recorder.setOptions({ ignoreInputs: options.ignoreInputs ?? true });
+			recorder.start();
+			notify({
+				recording: true,
+				binding: null,
+				steps: NO_STEPS,
+				conflicts: []
+			});
+		},
+		stop: () => {
+			if (!state.recording) return;
+			recorder.stop();
+			releaseScope();
+			notify({
+				...state,
+				recording: false,
+				steps: NO_STEPS
+			});
+		},
+		cancel: () => {
+			if (!state.recording) return;
+			recorder.cancel();
+		},
+		commit: () => {
+			if (!state.recording || !(recorder instanceof HotkeySequenceRecorder)) return;
+			recorder.commit();
+		},
+		get state() {
+			return state;
+		},
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		destroy: () => {
+			releaseScope();
+			stepsSubscription?.unsubscribe();
+			recorder.destroy();
+			listeners.clear();
+		}
+	};
+}
+//#endregion
+//#region src/scopes.ts
+/** Wildcard scope identifier for commands that remain active across exclusive scopes. */
+const ALWAYS_SCOPE = "*";
+/** Whether two scopes can be active at once, so their commands' bindings can collide. */
+function scopesOverlap(a, b) {
+	if (a === void 0 || b === void 0) return true;
+	if (a === "*" || b === "*") return true;
+	return a === b;
+}
+/** Stack managing active scopes and command reachability. */
+var ScopeStack = class {
+	#entries = [];
+	#listeners = /* @__PURE__ */ new Set();
+	/** Activates a scope until the returned disposal function is called. */
+	push(name, options = {}) {
+		const strict = options.strict === true;
+		const entry = {
+			name,
+			exclusive: strict || options.exclusive === true,
+			strict
+		};
+		this.#entries.push(entry);
+		this.#notify();
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			const index = this.#entries.indexOf(entry);
+			if (index !== -1) this.#entries.splice(index, 1);
+			this.#notify();
+		};
+	}
+	/** Checks whether commands in the specified scope can execute given the current scope stack. */
+	isActive(scope) {
+		if (scope === "*") return !this.#entries.some((entry) => entry.strict);
+		const barrier = this.#barrierIndex();
+		if (barrier === -1) return scope === void 0 || this.#entries.some((entry) => entry.name === scope);
+		if (scope === void 0) return false;
+		for (let index = barrier; index < this.#entries.length; index++) if (this.#entries[index]?.name === scope) return true;
+		return false;
+	}
+	/** Checks whether an exclusive scope is active. */
+	hasBarrier() {
+		return this.#barrierIndex() !== -1;
+	}
+	/** Clears all active scopes. */
+	clear() {
+		if (this.#entries.length === 0) return;
+		this.#entries = [];
+		this.#notify();
+	}
+	/** Subscribes to scope stack changes. Returns an unsubscribe function. */
+	subscribe(listener) {
+		this.#listeners.add(listener);
+		return () => {
+			this.#listeners.delete(listener);
+		};
+	}
+	#barrierIndex() {
+		for (let index = this.#entries.length - 1; index >= 0; index--) if (this.#entries[index]?.exclusive) return index;
+		return -1;
+	}
+	#notify() {
+		for (const listener of this.#listeners) listener();
+	}
+};
+//#endregion
+//#region src/arbitration.ts
+/**
+* Deciding which of several commands sharing one binding gets to run.
+*
+* Without this every registration for the pressed chord fires, so two
+* commands bound to `Mod+S` in overlapping scopes both ran and the only
+* defence was a dev-time console warning. Exclusive scopes could not fix it
+* either: a barrier shadows *every* global command, not just the one
+* colliding, so "Esc closes the dialog, and the panel otherwise" forced the
+* whole dialog to become exclusive.
+*
+* Ranking, highest first:
+*
+*   1. A command in a named scope beats a global one. `ALWAYS_SCOPE` is
+*      global for this purpose — it means "survives barriers", not "belongs
+*      to some region of the UI".
+*   2. Later registration beats earlier. Registration order tracks mount
+*      order, so the most recently opened surface claims the key — the same
+*      intuition that makes `add()` stack definitions per id.
+*
+* Guards are not part of the ranking. The registry evaluates them live at
+* keypress time, so a winner whose `when()` currently returns false steps
+* aside instead of swallowing the keypress.
+*/
+/** Negative when `a` outranks `b`, positive when `b` does. */
+function compareClaims(a, b) {
+	return scopeRank(b.scope) - scopeRank(a.scope) || b.order - a.order;
+}
+function scopeRank(scope) {
+	return scope === void 0 || scope === "*" ? 0 : 1;
+}
+/** Binding signature → ids of the commands bound to it, highest-ranked first. */
+function rankOwners(source) {
+	const index = /* @__PURE__ */ new Map();
+	source.ids.forEach((id, order) => {
+		const claimant = {
+			id,
+			scope: source.scope(id),
+			order
+		};
+		for (const binding of source.bindings(id)) {
+			const signature = bindingSignature(binding, source.platform);
+			const claimants = index.get(signature);
+			if (claimants) claimants.push(claimant);
+			else index.set(signature, [claimant]);
+		}
+	});
+	return new Map(Array.from(index, ([signature, claimants]) => [signature, claimants.sort(compareClaims).map((claimant) => claimant.id)]));
+}
+//#endregion
+//#region src/audit.ts
+/** Development-only warnings about bindings that cannot work as written. */
+/** Warns about every registered command: bad syntax, unknown overrides, collisions. */
+function auditRegistry(source) {
+	if (!isDevelopment()) return;
+	for (const id of source.ids) warnAboutBindings(source, id);
+	warnAboutUnknownOverrides(source);
+	warnAboutConflicts(source);
+}
+/** Warns about a command added at runtime and the keys it now shares. */
+function auditAdded(source, id) {
+	if (!isDevelopment()) return;
+	warnAboutBindings(source, id);
+	const scope = source.scope(id);
+	const claimant = (other) => ({
+		scope: source.scope(other),
+		order: source.ids.indexOf(other)
+	});
+	for (const conflict of source.conflicts(source.bindings(id), {
+		ignore: id,
+		scope
+	})) {
+		if (conflict.kind === "prefix") {
+			console.warn(`[@inklu/keys] "${id}" and "${conflict.id}" (${conflict.display}) have bindings where one is a prefix of the other, so the shorter one fires on the way to the longer one.`);
+			continue;
+		}
+		const winner = compareClaims(claimant(conflict.id), claimant(id)) < 0 ? conflict.id : id;
+		console.warn(`[@inklu/keys] "${id}" binds ${conflict.display}, which "${conflict.id}" already uses. While both are runnable the key goes to "${winner}".`);
+	}
+}
+function warnAboutConflicts(source) {
+	const { platform, display } = source;
+	const seen = /* @__PURE__ */ new Map();
+	const collisions = [];
+	const prefixes = [];
+	const visited = [];
+	for (const id of source.ids) {
+		const scope = source.scope(id);
+		for (const binding of source.bindings(id)) {
+			for (const other of visited) {
+				if (other.id === id || !scopesOverlap(other.scope, scope)) continue;
+				if (!isPrefixCollision(other.binding, binding, platform)) continue;
+				prefixes.push(`${formatBinding(other.binding, display)} ("${other.id}") is a prefix of ${formatBinding(binding, display)} ("${id}")`);
+			}
+			visited.push({
+				id,
+				scope,
+				binding
+			});
+			const key = `${scope ?? ""}::${bindingSignature(binding, platform)}`;
+			const owner = seen.get(key);
+			if (owner === void 0) {
+				seen.set(key, id);
+				continue;
+			}
+			collisions.push(`${formatBinding(binding, display)} — "${id}" shadows "${owner}"`);
+		}
+	}
+	if (collisions.length > 0) console.warn(`[@inklu/keys] ${collisions.length} unreachable binding(s) — same chord, same scope:\n  ${collisions.join("\n  ")}`);
+	if (prefixes.length > 0) console.warn(`[@inklu/keys] ${prefixes.length} prefix collision(s) — the shorter binding fires on the way to the longer one:\n  ${prefixes.join("\n  ")}`);
+}
+function warnAboutBindings(source, id) {
+	for (const binding of source.declared(id)) {
+		const { valid, errors } = validateBinding(binding);
+		if (valid) continue;
+		const resolved = formatBinding(binding, source.display);
+		console.warn(`[@inklu/keys] "${id}" has an unrecognized binding ${describeBinding(binding)}, which resolves to "${resolved}". ${errors.join("; ")}.`);
+	}
+}
+/** Catches ids in `options.bindings` that TypeScript could not — plain JS, or a runtime-only command. */
+function warnAboutUnknownOverrides(source) {
+	if (!source.overrides) return;
+	const unknown = Object.keys(source.overrides).filter((id) => !source.isRegistered(id));
+	if (unknown.length > 0) console.warn(`[@inklu/keys] bindings override ${unknown.map((id) => `"${id}"`).join(", ")}, which ${unknown.length === 1 ? "is not a registered command" : "are not registered commands"}.`);
+}
+function describeBinding(binding) {
+	return isSequence(binding) ? `"${binding.sequence.join(" ")}"` : `"${binding}"`;
+}
+function isDevelopment() {
+	const environment = globalThis.process?.env?.NODE_ENV;
+	return environment !== void 0 && environment !== "production";
+}
+//#endregion
+//#region src/binder.ts
+/** Bridge connecting commands to underlying hotkey event listeners. */
+var Binder = class {
+	#host;
+	#target;
+	#bound = /* @__PURE__ */ new Map();
+	#ran = /* @__PURE__ */ new WeakMap();
+	#continued = /* @__PURE__ */ new WeakSet();
+	#capture = null;
+	constructor(host, target) {
+		this.#host = host;
+		this.#target = target;
+	}
+	/** Syncs hotkey registrations for a command with its current bindings. */
+	sync(id) {
+		const definition = this.#host.getDefinition(id);
+		if (!definition) {
+			this.release(id);
+			return;
+		}
+		const existing = this.#bound.get(id) ?? [];
+		const reusable = new Map(existing.map((bound) => [bound.signature, bound]));
+		const next = [];
+		const enabled = this.#host.isReachable(id);
+		const config = registrationConfig(definition, this.#host.platform());
+		for (const binding of this.#host.getBindings(id)) {
+			const signature = bindingSignature(binding, this.#host.platform());
+			if (next.some((bound) => bound.signature === signature)) continue;
+			const kept = reusable.get(signature);
+			if (kept && kept.config === config) {
+				reusable.delete(signature);
+				setEnabled(kept, enabled);
+				next.push(kept);
+				continue;
+			}
+			const bound = this.#register(id, binding, signature, definition, enabled);
+			if (bound) next.push(bound);
+		}
+		for (const stale of reusable.values()) stale.handle.unregister();
+		if (next.length === 0) this.#bound.delete(id);
+		else this.#bound.set(id, next);
+		this.#updateCapture();
+	}
+	/**
+	* Updates enabled state for all active registrations without re-registering.
+	* A sequence that becomes unreachable halfway through also loses its
+	* progress: TanStack only skips a disabled sequence, so without the reset a
+	* scope that closed and reopened within the timeout would let the next key
+	* complete a sequence begun in a different context.
+	*/
+	refreshEnabled() {
+		for (const [id, bindings] of this.#bound) {
+			const enabled = this.#host.isReachable(id);
+			const abandoned = (bound) => bound.enabled && !enabled && bound.steps !== null && hasProgress(bound);
+			if (bindings.some(abandoned)) {
+				this.#reregister(id, abandoned);
+				continue;
+			}
+			for (const bound of bindings) setEnabled(bound, enabled);
+		}
+	}
+	/** Returns all registered sequences with their manager registration IDs. */
+	sequences() {
+		const entries = [];
+		for (const [id, bindings] of this.#bound) for (const bound of bindings) {
+			if (bound.steps === null || !isSequence(bound.binding)) continue;
+			entries.push({
+				id,
+				binding: bound.binding,
+				registrationId: bound.handle.id
+			});
+		}
+		return entries;
+	}
+	/**
+	* Abandons half-typed progress on this binder's sequences only. TanStack's
+	* `resetAll()` is global — it would also wipe sequences other registries,
+	* or the app itself, registered on the shared manager — and there is no
+	* per-registration reset, so each sequence is re-registered from scratch.
+	*/
+	resetSequences() {
+		for (const id of this.#bound.keys()) this.#reregister(id, (bound) => bound.steps !== null);
+	}
+	/** Removes all registrations for a specific command. */
+	release(id) {
+		const bindings = this.#bound.get(id);
+		if (!bindings) return;
+		for (const bound of bindings) bound.handle.unregister();
+		this.#bound.delete(id);
+		this.#updateCapture();
+	}
+	/** Removes all registrations. */
+	destroy() {
+		for (const bindings of this.#bound.values()) for (const bound of bindings) bound.handle.unregister();
+		this.#bound.clear();
+		this.#updateCapture();
+	}
+	/** Re-registers the bindings of `id` that `select` picks, resetting their progress. */
+	#reregister(id, select) {
+		const bindings = this.#bound.get(id);
+		const definition = this.#host.getDefinition(id);
+		if (!bindings || !definition) return;
+		const enabled = this.#host.isReachable(id);
+		const next = [];
+		for (const bound of bindings) {
+			if (!select(bound)) {
+				setEnabled(bound, enabled);
+				next.push(bound);
+				continue;
+			}
+			bound.handle.unregister();
+			const fresh = this.#register(id, bound.binding, bound.signature, definition, enabled);
+			if (fresh) next.push(fresh);
+		}
+		if (next.length === 0) this.#bound.delete(id);
+		else this.#bound.set(id, next);
+		this.#updateCapture();
+	}
+	#register(id, binding, signature, definition, enabled) {
+		const callback = (event) => this.#handle(id, binding, signature, event);
+		const platform = this.#host.platform();
+		const options = {
+			preventDefault: false,
+			stopPropagation: false,
+			conflictBehavior: "allow",
+			enabled,
+			ignoreInputs: definition.ignoreInputs,
+			platform,
+			target: this.#target,
+			meta: { name: definition.title }
+		};
+		try {
+			const handle = isSequence(binding) ? getSequenceManager().register([...binding.sequence], callback, {
+				...options,
+				timeout: definition.sequenceTimeout ?? DEFAULT_SEQUENCE_TIMEOUT
+			}) : getHotkeyManager().register(binding, callback, {
+				...options,
+				requireReset: definition.requireReset === true
+			});
+			return {
+				signature,
+				binding,
+				config: registrationConfig(definition, platform),
+				handle,
+				steps: isSequence(binding) ? binding.sequence.map((step) => parseHotkey(step, platform)) : null,
+				enabled
+			};
+		} catch {
+			return null;
+		}
+	}
+	/** Listens ahead of TanStack's sequence manager while any sequence is bound. */
+	#updateCapture() {
+		const needed = [...this.#bound.values()].some((bindings) => bindings.some((bound) => bound.steps !== null));
+		if (needed && !this.#capture && typeof document !== "undefined") {
+			const target = this.#target ?? document;
+			const listener = (event) => this.#beforeSequences(event);
+			target.addEventListener("keydown", listener, true);
+			this.#capture = {
+				target,
+				listener
+			};
+		} else if (!needed && this.#capture) {
+			this.#capture.target.removeEventListener("keydown", this.#capture.listener, true);
+			this.#capture = null;
+		}
+	}
+	/**
+	* Runs in the capture phase, so it sees each sequence's progress before
+	* TanStack advances it, whatever order the managers' own listeners were
+	* attached in. Two things depend on that:
+	*
+	* - A step that advances a sequence without completing it prevents the
+	*   browser default, as the final step does (unless the command sets
+	*   `preventDefault: false`). Otherwise `Mod+K then Mod+S` could never be
+	*   finished: `Mod+K` would move focus to the browser's search bar first.
+	* - A key that continues a half-typed sequence belongs to that sequence.
+	*   With `G then C` and a chord `C` both bound, typing G, C used to run
+	*   both commands; now the chord waits unless the key breaks the sequence.
+	*/
+	#beforeSequences(event) {
+		if (event.isComposing || event.keyCode === 229) return;
+		if (isModifierKey(normalizeKeyName(event.key))) return;
+		const views = getSequenceManager().registrations.state;
+		const now = Date.now();
+		let prevent = false;
+		for (const [id, bindings] of this.#bound) for (const bound of bindings) {
+			const steps = bound.steps;
+			const view = steps && views.get(bound.handle.id);
+			if (!steps || !view || !view.options.enabled) continue;
+			if (view.options.ignoreInputs !== false && this.#isTyping(event)) continue;
+			const platform = view.options.platform;
+			const timeout = view.options.timeout ?? DEFAULT_SEQUENCE_TIMEOUT;
+			const matched = now - view.partialMatchLastKeyTime > timeout ? 0 : view.matchedStepCount;
+			const expected = steps[matched];
+			const first = steps[0];
+			let reached = 0;
+			if (expected && matchesKeyboardEvent(event, expected, platform)) reached = matched + 1;
+			else if (matched > 0 && first && matchesKeyboardEvent(event, first, platform)) reached = 1;
+			if (reached === 0) continue;
+			if (reached < steps.length) {
+				const step = steps[reached - 1];
+				if (!(!step?.ctrl && !step?.meta && this.#isTyping(event)) && this.#host.getDefinition(id)?.preventDefault !== false) prevent = true;
+				if (matched > 0) this.#continued.add(event);
+			} else if (this.#host.canRun(id, event)) this.#continued.add(event);
+		}
+		if (prevent) event.preventDefault();
+	}
+	#isTyping(event) {
+		return event.composedPath().some((node) => node !== this.#target && isEditableElement(node));
+	}
+	/**
+	* One keypress can reach several registrations (see `conflictBehavior`
+	* above), so every candidate asks the registry whether it won before doing
+	* anything observable. Arbitration comes before `preventDefault` on
+	* purpose: a losing command must leave the event exactly as it found it,
+	* or a command declaring `preventDefault: false` would still have the
+	* browser's default action cancelled by whichever rival happened to be
+	* registered alongside it.
+	*/
+	#handle(id, binding, signature, event) {
+		if (event.isComposing || event.keyCode === 229) return;
+		if (!isSequence(binding) && this.#continued.has(event)) return;
+		if (typesAltGraphCharacter(event, binding, this.#host.platform())) return;
+		const ran = this.#ran.get(event);
+		if (ran?.has(signature)) return;
+		if (!this.#host.canRun(id, event)) return;
+		if (!this.#host.claims(id, signature, event)) return;
+		const definition = this.#host.getDefinition(id);
+		if (!definition) return;
+		if (ran) ran.add(signature);
+		else this.#ran.set(event, /* @__PURE__ */ new Set([signature]));
+		if (definition.preventDefault !== false) event.preventDefault();
+		this.#host.execute(id, {
+			source: "keyboard",
+			event,
+			binding
+		});
+	}
+};
+function setEnabled(bound, enabled) {
+	if (bound.enabled === enabled) return;
+	bound.enabled = enabled;
+	bound.handle.setOptions({ enabled });
+}
+function hasProgress(bound) {
+	return (getSequenceManager().registrations.state.get(bound.handle.id)?.matchedStepCount ?? 0) > 0;
+}
+function registrationConfig(definition, platform) {
+	return [
+		platform,
+		String(definition.ignoreInputs),
+		definition.requireReset === true ? "1" : "0",
+		String(definition.sequenceTimeout ?? DEFAULT_SEQUENCE_TIMEOUT)
+	].join("|");
+}
+/** Mirrors TanStack's notion of a text field, which `ignoreInputs` refers to. */
+function isEditableElement(node) {
+	if (typeof HTMLElement === "undefined" || !(node instanceof HTMLElement)) return false;
+	if (node instanceof HTMLInputElement) {
+		const type = node.type.toLowerCase();
+		return type !== "button" && type !== "submit" && type !== "reset";
+	}
+	return node instanceof HTMLTextAreaElement || node instanceof HTMLSelectElement || node.isContentEditable === true;
+}
+/**
+* Whether the keypress types a character through AltGr rather than pressing
+* the bound shortcut. Windows reports AltGr as Control+Alt, and TanStack
+* falls back to the physical key when the character differs, so AltGr+Q —
+* `@` on a German layout — matched `Control+Alt+Q`, and AltGr+A — `ą` on a
+* Polish one — matched `Control+Alt+A`. Control chords fire inside text
+* fields, so the command ran and swallowed the character mid-sentence. When
+* AltGraph is down and the key produced a character other than the one the
+* binding names, the user is typing. macOS has no AltGr: Option+letter
+* shortcuts rely on that same physical-key fallback.
+*/
+function typesAltGraphCharacter(event, binding, platform) {
+	if (platform === "mac" || !event.getModifierState?.("AltGraph")) return false;
+	const produced = event.key;
+	if (produced !== "Dead" && !/^.$/u.test(produced)) return false;
+	const chord = isSequence(binding) ? binding.sequence.at(-1) : binding;
+	if (chord === void 0) return false;
+	const key = parseHotkey(chord, platform).key;
+	return key !== void 0 && produced.toUpperCase() !== key.toUpperCase();
+}
+//#endregion
+//#region src/ids.ts
+/**
+* Recovers the strict id type from the loose one the public API accepts.
+*
+* Lookups — `get`, `setEnabled`, `keymap.set` and the rest — take
+* `Id | (string & {})`, which keeps autocomplete for the registry's own ids
+* while still accepting ids that exist only at runtime: a command `add()`ed
+* later, a `data-command` attribute. Internally every map is keyed by `Id`,
+* and an id nothing registered simply misses, so narrowing it never lets a
+* wrong value in.
+*/
+function strictId(id) {
+	return id;
+}
+//#endregion
+//#region src/keymap.ts
+/** Keymap managing default bindings and user overrides. */
+const DEFAULT_STORAGE_KEY = "inklu.keys";
+const KEYMAP_VERSION = 1;
+/** Type guard narrowing a JSON value to a plain object (excludes arrays and `null`). */
+function isJsonObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Same keys on every platform. The keymap is user data that may travel
+* between machines, so `Mod+S` and `Control+S` stay distinct here even on
+* Windows, where they happen to coincide.
+*/
+function portableSignature(binding) {
+	return `${bindingSignature(binding, "mac")} ${bindingSignature(binding, "windows")}`;
+}
+var Keymap = class {
+	#defaults = /* @__PURE__ */ new Map();
+	#overrides = /* @__PURE__ */ new Map();
+	#listeners = /* @__PURE__ */ new Set();
+	#persistence;
+	#loaded = false;
+	constructor(persistence) {
+		this.#persistence = persistence;
+	}
+	/** Sets a command's default bindings. `null` leaves the command unbound. */
+	setDefault(loose, input) {
+		const id = strictId(loose);
+		const bindings = toBindings(input);
+		if (bindings.length === 0) this.#defaults.delete(id);
+		else this.#defaults.set(id, bindings);
+	}
+	/** Removes a command's default bindings, leaving overrides intact. */
+	clearDefault(loose) {
+		this.#defaults.delete(strictId(loose));
+	}
+	/** Checks whether a command has an active user override. */
+	isOverridden(loose) {
+		return this.#overrides.has(strictId(loose));
+	}
+	get(loose) {
+		const id = strictId(loose);
+		const defaults = this.#defaults.get(id) ?? [];
+		const override = this.#overrides.get(id);
+		if (!override) return defaults;
+		if (override.kind === "replace") return override.bindings;
+		return [...defaults, ...without(override.bindings, defaults)];
+	}
+	/** Replaces a command's bindings. Passing `null` unbinds it. */
+	set(loose, input) {
+		const id = strictId(loose);
+		this.load();
+		const bindings = input === null ? [] : toBindings(input);
+		const defaults = this.#defaults.get(id);
+		if (defaults && sameBindings(bindings, defaults)) {
+			if (!this.#overrides.delete(id)) return;
+		} else this.#overrides.set(id, {
+			kind: "replace",
+			bindings
+		});
+		this.#changed();
+	}
+	/** Adds an additional binding to a command. */
+	add(loose, input) {
+		const id = strictId(loose);
+		this.load();
+		const added = without(toBindings(input), this.get(id));
+		if (added.length === 0) return;
+		const override = this.#overrides.get(id);
+		this.#overrides.set(id, {
+			kind: override?.kind ?? "add",
+			bindings: [...override?.bindings ?? [], ...added]
+		});
+		this.#changed();
+	}
+	/** Resets user overrides to defaults for one command or all commands. */
+	reset(loose) {
+		this.load();
+		if (loose === void 0) {
+			if (this.#overrides.size === 0) return;
+			this.#overrides.clear();
+		} else if (!this.#overrides.delete(strictId(loose))) return;
+		this.#changed();
+	}
+	/** Exports user overrides as a serialized keymap object. */
+	export() {
+		return {
+			version: KEYMAP_VERSION,
+			overrides: Object.fromEntries(Array.from(this.#overrides, ([id, override]) => [id, serializeOverride(override)]))
+		};
+	}
+	/** Imports serialized user overrides and saves to storage. */
+	import(data) {
+		this.#loaded = true;
+		this.#read(data);
+		this.#changed();
+	}
+	/**
+	* Loads persisted overrides from storage, once. The registry calls this on
+	* its first mount; `set`, `add` and `reset` call it too, so an edit made
+	* before mount lands on top of the stored overrides instead of writing
+	* over them.
+	*/
+	load() {
+		if (this.#loaded) return;
+		this.#loaded = true;
+		const storage = this.#storage();
+		if (!storage) return;
+		try {
+			const raw = storage.getItem(this.#storageKey());
+			if (!raw) return;
+			this.#read(JSON.parse(raw));
+		} catch {
+			return;
+		}
+		this.#notify();
+	}
+	/**
+	* Follows edits other tabs make to the stored overrides, so rebinding a
+	* key in one tab reaches the rest instead of being overwritten by the next
+	* stale tab to save. Returns a function that stops watching.
+	*/
+	watch() {
+		if (!this.#persistence || typeof window === "undefined") return () => {};
+		const onStorage = (event) => {
+			if (event.key !== null && event.key !== this.#storageKey()) return;
+			this.#reload();
+		};
+		window.addEventListener("storage", onStorage);
+		return () => window.removeEventListener("storage", onStorage);
+	}
+	/** Subscribes to keymap changes. Returns an unsubscribe function. */
+	subscribe(listener) {
+		this.#listeners.add(listener);
+		return () => {
+			this.#listeners.delete(listener);
+		};
+	}
+	#reload() {
+		const storage = this.#storage();
+		if (!storage) return;
+		const before = JSON.stringify(this.export());
+		try {
+			const raw = storage.getItem(this.#storageKey());
+			if (raw) this.#read(JSON.parse(raw));
+			else this.#overrides.clear();
+		} catch {
+			return;
+		}
+		this.#loaded = true;
+		if (JSON.stringify(this.export()) !== before) this.#notify();
+	}
+	#read(data) {
+		const entries = storedOverrides(data);
+		if (!entries) return;
+		this.#overrides.clear();
+		for (const [id, value] of Object.entries(entries)) {
+			const override = deserializeOverride(value);
+			if (override) this.#overrides.set(strictId(id), override);
+		}
+	}
+	#changed() {
+		this.#persist();
+		this.#notify();
+	}
+	#notify() {
+		for (const listener of this.#listeners) listener();
+	}
+	#persist() {
+		const storage = this.#storage();
+		if (!storage) return;
+		try {
+			if (this.#overrides.size === 0) storage.removeItem(this.#storageKey());
+			else storage.setItem(this.#storageKey(), JSON.stringify(this.export()));
+		} catch {}
+	}
+	#storageKey() {
+		return this.#persistence?.key ?? DEFAULT_STORAGE_KEY;
+	}
+	#storage() {
+		try {
+			return this.#persistence?.storage() ?? null;
+		} catch {
+			return null;
+		}
+	}
+};
+/** `bindings` minus any already in `existing` or repeated, compared across platforms. */
+function without(bindings, existing) {
+	const known = new Set(existing.map(portableSignature));
+	return bindings.filter((binding) => {
+		const signature = portableSignature(binding);
+		if (known.has(signature)) return false;
+		known.add(signature);
+		return true;
+	});
+}
+/** Same bindings in the same order; the first is the one shortcuts display. */
+function sameBindings(a, b) {
+	return a.length === b.length && a.every((binding, index) => {
+		const other = b[index];
+		return other !== void 0 && portableSignature(binding) === portableSignature(other);
+	});
+}
+/** The overrides in stored data, or `null` if this release cannot read it. */
+function storedOverrides(data) {
+	if (!isJsonObject(data)) return null;
+	if (typeof data.version !== "number") return data;
+	if (data.version !== KEYMAP_VERSION) return null;
+	const overrides = data.overrides;
+	return overrides !== void 0 && isJsonObject(overrides) ? overrides : null;
+}
+function serializeOverride(override) {
+	const bindings = override.bindings.map(serializeBinding);
+	return override.kind === "replace" ? bindings : { add: bindings };
+}
+function deserializeOverride(value) {
+	if (Array.isArray(value)) {
+		const bindings = deserializeBindings(value);
+		return bindings && {
+			kind: "replace",
+			bindings
+		};
+	}
+	if (isJsonObject(value) && Array.isArray(value.add)) {
+		const bindings = deserializeBindings(value.add);
+		return bindings && bindings.length > 0 ? {
+			kind: "add",
+			bindings
+		} : null;
+	}
+	return null;
+}
+/**
+* `[]` is how an unbound command is stored. A non-empty list with nothing
+* usable in it is damage — hand edits, another version's format — and
+* reading it as "unbound" would silently strip the command of its default
+* shortcut, so it reads as `null` instead.
+*/
+function deserializeBindings(values) {
+	const bindings = values.map(deserializeBinding).filter((binding) => binding !== null);
+	return bindings.length === 0 && values.length > 0 ? null : bindings;
+}
+//#endregion
+//#region src/registry.ts
+/** Command registry managing command definitions, keymaps, scopes, and execution. */
+const EMPTY_PENDING = [];
+const SSR_PLATFORM = "windows";
+var CommandRegistry = class {
+	#stacks = /* @__PURE__ */ new Map();
+	#order = [];
+	#enabled = /* @__PURE__ */ new Map();
+	#keymap;
+	#scopes = new ScopeStack();
+	#binder;
+	#options;
+	#listeners = /* @__PURE__ */ new Set();
+	#pendingListeners = /* @__PURE__ */ new Set();
+	#pending = EMPTY_PENDING;
+	#pendingSubscription = null;
+	#snapshot = null;
+	#serverSnapshot = null;
+	#initial;
+	/** Stops following other tabs' keymap edits; set while mounted. */
+	#unwatch = null;
+	#pendingTimer = null;
+	#index = null;
+	#ownerIndex = null;
+	#mounts = 0;
+	#hydrated = false;
+	#barrier = false;
+	#singleKeys;
+	#verdicts = /* @__PURE__ */ new WeakMap();
+	constructor(definitions, options = {}) {
+		this.#options = options;
+		this.#singleKeys = options.singleKeyShortcuts !== false;
+		this.#keymap = new Keymap(options.persist);
+		this.#binder = new Binder({
+			getDefinition: (id) => this.#definition(id),
+			getBindings: (id) => this.#bindings(id),
+			canRun: (id, event) => this.#whyNotRun(id, "keyboard", event) === null,
+			isReachable: (id) => this.#isReachable(id),
+			claims: (id, signature, event) => this.#claims(id, signature, event),
+			platform: () => this.#platform(),
+			execute: (id, context) => {
+				this.#execute(id, context);
+			}
+		}, options.target);
+		this.#initial = Object.entries(definitions);
+		for (const [id, definition] of this.#initial) this.#push(id, definition);
+		this.#keymap.subscribe(() => this.#onKeymapChange());
+		this.#scopes.subscribe(() => this.#onScopeChange());
+		auditRegistry(this.#auditSource());
+	}
+	get keymap() {
+		return this.#keymap;
+	}
+	get(id) {
+		this.#snapshotList();
+		return this.#index?.get(strictId(id));
+	}
+	list() {
+		return this.#snapshotList();
+	}
+	serverList() {
+		if (this.#serverSnapshot) return this.#serverSnapshot;
+		const platform = this.#options.platform ?? SSR_PLATFORM;
+		const options = {
+			platform,
+			...this.#options.display
+		};
+		const singleKeys = this.#options.singleKeyShortcuts !== false;
+		this.#serverSnapshot = this.#initial.map(([id, definition]) => {
+			const bindings = toBindings(this.#defaultKeys(id, definition)).filter((binding) => singleKeys || !isSingleKeyBinding(binding, platform));
+			const enabled = definition.enabled !== false;
+			const global = definition.scope === void 0 || definition.scope === "*";
+			return describeCommand(id, definition, bindings, platform, options, {
+				enabled,
+				reachable: enabled && global,
+				overridden: false
+			});
+		});
+		return this.#serverSnapshot;
+	}
+	run(id, options = {}) {
+		const source = options.source ?? "api";
+		if (this.#whyNotRun(id, source, options.event) !== null) return false;
+		this.#execute(id, {
+			source,
+			event: options.event
+		});
+		return true;
+	}
+	canRun(id) {
+		return this.whyNotRun(id) === null;
+	}
+	whyNotRun(id) {
+		return this.#whyNotRun(strictId(id), "api");
+	}
+	setEnabled(loose, enabled) {
+		const id = strictId(loose);
+		if (!this.#stacks.has(id)) return;
+		if (this.#enabled.get(id) === enabled) return;
+		this.#enabled.set(id, enabled);
+		this.#binder.refreshEnabled();
+		this.#invalidate();
+	}
+	add(loose, definition) {
+		const id = strictId(loose);
+		const entry = this.#push(id, definition);
+		if (this.#mounts > 0) this.#binder.sync(id);
+		this.#invalidate();
+		auditAdded(this.#auditSource(), id);
+		let disposed = false;
+		return {
+			run: (options) => !disposed && this.run(id, options),
+			dispose: () => {
+				if (disposed) return;
+				disposed = true;
+				this.#pop(id, entry);
+			}
+		};
+	}
+	remove(loose) {
+		const id = strictId(loose);
+		if (!this.#stacks.has(id)) return;
+		this.#drop(id);
+		this.#invalidate();
+	}
+	pushScope(name, options) {
+		return this.#scopes.push(name, options);
+	}
+	conflicts(binding, options = {}) {
+		const platform = this.#platform();
+		const candidates = toBindings(binding);
+		const signatures = new Set(candidates.map((entry) => bindingSignature(entry, platform)));
+		const conflicts = [];
+		for (const id of this.#order) {
+			if (id === options.ignore) continue;
+			const scope = this.#definition(id)?.scope;
+			if (!scopesOverlap(scope, options.scope)) continue;
+			for (const existing of this.#bindings(id)) {
+				const kind = signatures.has(bindingSignature(existing, platform)) ? "exact" : candidates.some((candidate) => isPrefixCollision(candidate, existing, platform)) ? "prefix" : null;
+				if (kind === null) continue;
+				const display = formatBinding(existing, this.#displayOptions());
+				conflicts.push({
+					id,
+					binding: existing,
+					kind,
+					display,
+					scope
+				});
+			}
+		}
+		return conflicts;
+	}
+	display(id) {
+		const binding = this.#bindings(strictId(id))[0];
+		return binding ? formatBinding(binding, this.#displayOptions()) : "";
+	}
+	tokens(id) {
+		const binding = this.#bindings(strictId(id))[0];
+		return binding ? bindingTokens(binding, this.#displayOptions()) : [];
+	}
+	get singleKeyShortcuts() {
+		return this.#singleKeys;
+	}
+	setSingleKeyShortcuts(enabled) {
+		if (this.#singleKeys === enabled) return;
+		this.#singleKeys = enabled;
+		if (this.#mounts > 0) for (const id of this.#order) this.#binder.sync(id);
+		this.#invalidate();
+	}
+	mount() {
+		this.#mounts++;
+		if (this.#mounts === 1) {
+			this.#hydrated = true;
+			this.#keymap.load();
+			this.#unwatch = this.#keymap.watch();
+			for (const id of this.#order) this.#binder.sync(id);
+			this.#invalidate();
+		}
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			if (this.#mounts === 0) return;
+			this.#mounts--;
+			if (this.#mounts === 0) this.#unmount();
+		};
+	}
+	pending() {
+		return this.#pending;
+	}
+	subscribePending(listener) {
+		this.#pendingListeners.add(listener);
+		if (this.#pendingListeners.size === 1) this.#watchPending();
+		return () => {
+			this.#pendingListeners.delete(listener);
+			if (this.#pendingListeners.size > 0) return;
+			this.#unwatchPending();
+		};
+	}
+	subscribe(listener) {
+		this.#listeners.add(listener);
+		return () => {
+			this.#listeners.delete(listener);
+		};
+	}
+	destroy() {
+		this.#mounts = 0;
+		this.#unmount();
+		this.#stacks.clear();
+		this.#order = [];
+		this.#enabled.clear();
+		this.#scopes.clear();
+		this.#listeners.clear();
+		this.#pendingListeners.clear();
+		this.#unwatchPending();
+		this.#initial = [];
+		this.#serverSnapshot = null;
+		this.#invalidate();
+	}
+	#unmount() {
+		this.#binder.destroy();
+		this.#unwatch?.();
+		this.#unwatch = null;
+	}
+	#onScopeChange() {
+		const barrier = this.#scopes.hasBarrier();
+		this.#binder.refreshEnabled();
+		if (barrier && !this.#barrier) this.#binder.resetSequences();
+		this.#barrier = barrier;
+		this.#invalidate();
+	}
+	#watchPending() {
+		const store = getSequenceManager().registrations;
+		const read = () => {
+			this.#clearPendingTimer();
+			const { pending, expires } = this.#readPending(store.state);
+			if (expires !== null) this.#pendingTimer = setTimeout(read, Math.max(0, expires - Date.now()) + 1);
+			if (samePending(pending, this.#pending)) return;
+			this.#pending = pending;
+			for (const listener of this.#pendingListeners) listener();
+		};
+		this.#pendingSubscription = store.subscribe(read);
+		read();
+	}
+	#unwatchPending() {
+		this.#pendingSubscription?.unsubscribe();
+		this.#pendingSubscription = null;
+		this.#clearPendingTimer();
+		this.#pending = EMPTY_PENDING;
+	}
+	#clearPendingTimer() {
+		if (this.#pendingTimer === null) return;
+		clearTimeout(this.#pendingTimer);
+		this.#pendingTimer = null;
+	}
+	/** Sequences in progress, and when the first of them times out. */
+	#readPending(state) {
+		const options = this.#displayOptions();
+		const pending = [];
+		const now = Date.now();
+		let expires = null;
+		for (const { id, binding, registrationId } of this.#binder.sequences()) {
+			const view = state.get(registrationId);
+			if (!view?.options.enabled) continue;
+			const matched = view.matchedStepCount;
+			if (matched === 0 || matched >= binding.sequence.length) continue;
+			const deadline = view.partialMatchLastKeyTime + (view.options.timeout ?? DEFAULT_SEQUENCE_TIMEOUT);
+			if (now > deadline) continue;
+			expires = expires === null ? deadline : Math.min(expires, deadline);
+			pending.push({
+				id,
+				binding,
+				matched,
+				total: binding.sequence.length,
+				remaining: binding.sequence.slice(matched).map((step) => formatBinding(step, options))
+			});
+		}
+		return {
+			pending: pending.length === 0 ? EMPTY_PENDING : pending,
+			expires
+		};
+	}
+	/**
+	* Bindings in effect: the keymap's, minus single-key ones while those are
+	* switched off. Everything that binds, displays or compares keys reads
+	* this, so a suppressed shortcut is not advertised either.
+	*/
+	#bindings(id) {
+		const bindings = this.#keymap.get(id);
+		if (this.#singleKeys) return bindings;
+		const platform = this.#platform();
+		return bindings.filter((binding) => !isSingleKeyBinding(binding, platform));
+	}
+	/**
+	* `source` and `event` describe what asked, so a throwing guard is
+	* reported as the keypress (or click) that evaluated it rather than as an
+	* API call. With an event the verdict is cached for that event.
+	*/
+	#whyNotRun(id, source, event) {
+		let cache;
+		if (event) {
+			cache = this.#verdicts.get(event);
+			if (cache?.has(id)) return cache.get(id) ?? null;
+		}
+		const verdict = this.#evaluate(id, source, event);
+		if (event) {
+			if (!cache) {
+				cache = /* @__PURE__ */ new Map();
+				this.#verdicts.set(event, cache);
+			}
+			cache.set(id, verdict);
+		}
+		return verdict;
+	}
+	#evaluate(id, source, event) {
+		const definition = this.#definition(id);
+		if (!definition) return "unknown";
+		if (!(this.#enabled.get(id) ?? false)) return "disabled";
+		if (!this.#scopes.isActive(definition.scope)) return "out-of-scope";
+		if (!definition.when) return null;
+		try {
+			return definition.when() === false ? "guarded" : null;
+		} catch (error) {
+			this.#reportError(toError(error), {
+				id,
+				source,
+				event,
+				commands: this
+			});
+			return "guarded";
+		}
+	}
+	#definition(id) {
+		const stack = this.#stacks.get(id);
+		return stack?.[stack.length - 1]?.definition;
+	}
+	#push(id, definition) {
+		let stack = this.#stacks.get(id);
+		if (!stack) {
+			stack = [];
+			this.#stacks.set(id, stack);
+			this.#order.push(id);
+		}
+		const entry = { definition };
+		stack.push(entry);
+		this.#applyTop(id);
+		return entry;
+	}
+	#pop(id, entry) {
+		const stack = this.#stacks.get(id);
+		if (!stack) return;
+		const index = stack.indexOf(entry);
+		if (index === -1) return;
+		stack.splice(index, 1);
+		if (stack.length === 0) this.#drop(id);
+		else {
+			this.#applyTop(id);
+			if (this.#mounts > 0) this.#binder.sync(id);
+		}
+		this.#invalidate();
+	}
+	#applyTop(id) {
+		const definition = this.#definition(id);
+		if (!definition) return;
+		this.#enabled.set(id, definition.enabled !== false);
+		this.#keymap.setDefault(id, this.#defaultKeys(id, definition));
+	}
+	/**
+	* A command's default keys: the app's `options.bindings` entry if it has
+	* one, else the definition's own. `hasOwn`, not `??`: a `null` entry
+	* deliberately ships the command unbound, and `??` would read that as
+	* "absent" and restore the very default the app asked to drop.
+	*/
+	#defaultKeys(id, definition) {
+		const overrides = this.#options.bindings;
+		return overrides && Object.hasOwn(overrides, id) ? overrides[id] : definition.keys;
+	}
+	#drop(id) {
+		this.#stacks.delete(id);
+		const index = this.#order.indexOf(id);
+		if (index !== -1) this.#order.splice(index, 1);
+		this.#enabled.delete(id);
+		this.#keymap.clearDefault(id);
+		this.#binder.release(id);
+	}
+	#isReachable(id) {
+		if (!(this.#enabled.get(id) ?? false)) return false;
+		return this.#scopes.isActive(this.#definition(id)?.scope);
+	}
+	/**
+	* Whether `id` wins a keypress on a binding it shares, by the ranking in
+	* `arbitration.ts`. Guards run live here rather than in the ranking, so a
+	* winner whose `when()` currently returns false steps aside instead of
+	* swallowing the keypress.
+	*/
+	#claims(id, signature, event) {
+		const candidates = this.#owners().get(signature);
+		if (!candidates || candidates.length < 2) return true;
+		for (const candidate of candidates) {
+			if (candidate !== id && this.#whyNotRun(candidate, "keyboard", event) !== null) continue;
+			return candidate === id;
+		}
+		return false;
+	}
+	/** Binding signature → command ids that share it, ranked by `#claims`. */
+	#owners() {
+		this.#ownerIndex ??= rankOwners({
+			ids: this.#order,
+			scope: (id) => this.#definition(id)?.scope,
+			bindings: (id) => this.#bindings(id),
+			platform: this.#platform()
+		});
+		return this.#ownerIndex;
+	}
+	#execute(id, context) {
+		const definition = this.#definition(id);
+		if (!definition) return;
+		const full = {
+			id,
+			...context,
+			commands: this
+		};
+		if (this.#options.onRun) try {
+			this.#options.onRun(full);
+		} catch (error) {
+			this.#reportError(toError(error), full);
+		}
+		try {
+			const result = definition.run(full);
+			if (result instanceof Promise) result.catch((cause) => this.#reportError(toError(cause), full));
+		} catch (error) {
+			this.#reportError(toError(error), full);
+		}
+	}
+	#reportError(error, context) {
+		if (this.#options.onError) {
+			this.#options.onError(error, context);
+			return;
+		}
+		console.error(`[@inklu/keys] command "${context.id}" failed`, error);
+	}
+	#onKeymapChange() {
+		if (this.#mounts > 0) for (const id of this.#order) this.#binder.sync(id);
+		this.#invalidate();
+	}
+	#platform() {
+		return this.#options.platform ?? (this.#hydrated ? detectPlatform() : SSR_PLATFORM);
+	}
+	#displayOptions() {
+		return {
+			platform: this.#platform(),
+			...this.#options.display
+		};
+	}
+	#snapshotList() {
+		if (this.#snapshot) return this.#snapshot;
+		const platform = this.#platform();
+		const options = this.#displayOptions();
+		const commands = [];
+		const index = /* @__PURE__ */ new Map();
+		for (const id of this.#order) {
+			const definition = this.#definition(id);
+			if (!definition) continue;
+			const command = describeCommand(id, definition, this.#bindings(id), platform, options, {
+				enabled: this.#enabled.get(id) ?? false,
+				reachable: this.#isReachable(id),
+				overridden: this.#keymap.isOverridden(id)
+			});
+			commands.push(command);
+			index.set(id, command);
+		}
+		this.#snapshot = commands;
+		this.#index = index;
+		return commands;
+	}
+	#invalidate() {
+		this.#snapshot = null;
+		this.#index = null;
+		this.#ownerIndex = null;
+		for (const listener of this.#listeners) listener();
+	}
+	#auditSource() {
+		return {
+			ids: this.#order,
+			scope: (id) => this.#definition(id)?.scope,
+			bindings: (id) => this.#bindings(id),
+			declared: (id) => this.#keymap.get(id),
+			isRegistered: (id) => this.#stacks.has(strictId(id)),
+			overrides: this.#options.bindings,
+			conflicts: (binding, options) => this.conflicts(binding, options),
+			platform: this.#platform(),
+			display: this.#displayOptions()
+		};
+	}
+};
+function describeCommand(id, definition, source, platform, options, state) {
+	const bindings = [...source];
+	return {
+		id,
+		title: definition.title,
+		description: definition.description,
+		group: definition.group,
+		keywords: definition.keywords ?? [],
+		hidden: definition.hidden === true,
+		scope: definition.scope,
+		bindings,
+		display: bindings.map((binding) => formatBinding(binding, options)),
+		tokens: bindings.map((binding) => bindingTokens(binding, options)),
+		aria: bindings.map((binding) => ariaKeyShortcuts(binding, platform)).filter((value) => value.length > 0).join(" "),
+		spoken: bindings.map((binding) => spokenBinding(binding, platform)).join(" or "),
+		...state
+	};
+}
+/** Normalizes an arbitrary thrown value into a real `Error` at the catch boundary. */
+function toError(cause) {
+	return cause instanceof Error ? cause : new Error(String(cause));
+}
+function samePending(a, b) {
+	if (a.length !== b.length) return false;
+	return a.every((entry, index) => {
+		const other = b[index];
+		return other !== void 0 && entry.id === other.id && entry.matched === other.matched;
+	});
+}
+/**
+* Creates a command registry.
+*
+* @example
+* ```ts
+* export const commands = createCommands({
+*   "palette.open": {
+*     title: "Open command palette",
+*     keys: "Mod+K",
+*     run: () => setPaletteOpen(true),
+*   },
+*   "nav.inbox": {
+*     title: "Go to inbox",
+*     keys: seq("G", "I"),
+*     run: () => navigate("/inbox"),
+*   },
+* });
+* ```
+*/
+function createCommands(definitions, options) {
+	return new CommandRegistry(definitions, options);
+}
+//#endregion
+//#region src/search.ts
+/**
+* Filters commands for a search query, as a command palette does, leaving
+* out `hidden` ones. Every word of the query must appear somewhere in the
+* command — title, description, group, keywords, id or displayed shortcut —
+* in any order. Title matches come first: titles starting with the query,
+* then titles containing every word, then the rest; each tier keeps the
+* list's own order. An empty query returns every visible command.
+*
+* @example
+* ```ts
+* const results = matchCommands(commands.list(), "go inbox");
+* ```
+*/
+function matchCommands(commands, query) {
+	const visible = commands.filter((command) => !command.hidden);
+	const needle = query.trim().toLowerCase();
+	if (!needle) return visible;
+	const terms = needle.split(/\s+/);
+	const ranked = [];
+	for (const command of visible) {
+		const title = command.title.toLowerCase();
+		const text = [
+			title,
+			command.description,
+			command.group,
+			command.id,
+			...command.keywords,
+			...command.display
+		].join("\n").toLowerCase();
+		if (!terms.every((term) => text.includes(term))) continue;
+		const rank = title.startsWith(needle) ? 0 : terms.every((term) => title.includes(term)) ? 1 : 2;
+		ranked.push({
+			command,
+			rank
+		});
+	}
+	return ranked.sort((a, b) => a.rank - b.rank).map(({ command }) => command);
+}
+//#endregion
+export { ariaKeyShortcuts as a, spokenBinding as c, seq as d, toBindings as f, createRebinder as i, bindingSignature as l, createCommands as n, bindingTokens as o, validateBinding as p, ALWAYS_SCOPE as r, formatBinding as s, matchCommands as t, isSingleKeyBinding as u };