@inklu/keys 1.0.0

package/dist/src-B305icXC.js

@@ -0,0 +1,981 @@
+import { HotkeyRecorder, HotkeySequenceRecorder, detectPlatform, formatForDisplay, getHotkeyManager, getSequenceManager, normalizeHotkey, validateHotkey } from "@tanstack/hotkeys";
+//#region src/bindings.ts
+/** Comparing, validating and serializing hotkey bindings. */
+/**
+* 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. */
+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)) {
+			if (candidate.sequence.length > 0) bindings.push({ sequence: [...candidate.sequence] });
+			continue;
+		}
+		const trimmed = String(candidate).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)}`;
+}
+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 (typeof value === "string") {
+		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 TOKEN_SEPARATOR = "\0";
+/** 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) => formatForDisplay(step, options)).join(" ");
+	return formatForDisplay(binding, options);
+}
+/** Splits a binding into display tokens for rendering `<kbd>` elements. */
+function bindingTokens(binding, options) {
+	if (isSequence(binding)) return binding.sequence.map((step) => formatForDisplay(step, options));
+	return formatForDisplay(binding, {
+		...options,
+		separatorToken: TOKEN_SEPARATOR
+	}).split(TOKEN_SEPARATOR).map((token) => token.trim()).filter((token) => token.length > 0);
+}
+/** Generates an `aria-keyshortcuts` attribute string for a binding. */
+function ariaKeyShortcuts(binding, platform) {
+	if (isSequence(binding)) return "";
+	try {
+		return resolveMod(normalizeHotkey(binding, 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();
+		notify({
+			recording: false,
+			binding: null,
+			steps: NO_STEPS,
+			conflicts: []
+		});
+		options.onClear?.();
+	};
+	const recorder = options.mode === "sequence" ? new HotkeySequenceRecorder({
+		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({
+		ignoreInputs: options.ignoreInputs ?? true,
+		onRecord: (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 });
+			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/binder.ts
+/** Bridge connecting commands to underlying hotkey event listeners. */
+var Binder = class {
+	#host;
+	#target;
+	#bound = /* @__PURE__ */ new Map();
+	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);
+		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) {
+				reusable.delete(signature);
+				kept.setEnabled(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.unregister();
+		if (next.length === 0) this.#bound.delete(id);
+		else this.#bound.set(id, next);
+	}
+	/** Updates enabled state for all active registrations without re-registering. */
+	refreshEnabled() {
+		for (const [id, bindings] of this.#bound) {
+			const enabled = this.#host.isReachable(id);
+			for (const bound of bindings) bound.setEnabled(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.sequenceId === null || !isSequence(bound.binding)) continue;
+			entries.push({
+				id,
+				binding: bound.binding,
+				registrationId: bound.sequenceId
+			});
+		}
+		return entries;
+	}
+	/** Removes all registrations for a specific command. */
+	release(id) {
+		const bindings = this.#bound.get(id);
+		if (!bindings) return;
+		for (const bound of bindings) bound.unregister();
+		this.#bound.delete(id);
+	}
+	/** Removes all registrations. */
+	destroy() {
+		for (const bindings of this.#bound.values()) for (const bound of bindings) bound.unregister();
+		this.#bound.clear();
+	}
+	#register(id, binding, signature, definition, enabled) {
+		const callback = (event) => this.#handle(id, binding, event);
+		const options = {
+			preventDefault: false,
+			stopPropagation: false,
+			conflictBehavior: "allow",
+			enabled,
+			ignoreInputs: definition.ignoreInputs,
+			platform: this.#host.platform(),
+			target: this.#target,
+			meta: { name: definition.title }
+		};
+		try {
+			const handle = isSequence(binding) ? getSequenceManager().register([...binding.sequence], callback, {
+				...options,
+				timeout: definition.sequenceTimeout
+			}) : getHotkeyManager().register(binding, callback, {
+				...options,
+				requireReset: definition.requireReset === true
+			});
+			return {
+				signature,
+				binding,
+				sequenceId: isSequence(binding) ? handle.id : null,
+				setEnabled: (value) => handle.setOptions({ enabled: value }),
+				unregister: () => handle.unregister()
+			};
+		} catch {
+			return null;
+		}
+	}
+	#handle(id, binding, event) {
+		if (!this.#host.canRun(id)) return;
+		const definition = this.#host.getDefinition(id);
+		if (!definition) return;
+		if (definition.preventDefault !== false) event.preventDefault();
+		this.#host.execute(id, {
+			source: "keyboard",
+			event,
+			binding
+		});
+	}
+};
+//#endregion
+//#region src/keymap.ts
+/** Keymap managing default bindings and user overrides. */
+const DEFAULT_STORAGE_KEY = "inklu.keys";
+var Keymap = class {
+	#defaults = /* @__PURE__ */ new Map();
+	#overrides = /* @__PURE__ */ new Map();
+	#listeners = /* @__PURE__ */ new Set();
+	#persistence;
+	constructor(persistence) {
+		this.#persistence = persistence;
+	}
+	/** Sets a command's default bindings. */
+	setDefault(loose, input) {
+		const id = 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(loose);
+	}
+	/** Checks whether a command has an active user override. */
+	isOverridden(loose) {
+		return this.#overrides.has(loose);
+	}
+	get(loose) {
+		const id = loose;
+		return this.#overrides.get(id) ?? this.#defaults.get(id) ?? [];
+	}
+	/** Sets a user binding override for a command. Passing `null` unbinds it. */
+	set(loose, input) {
+		this.#overrides.set(loose, input === null ? [] : toBindings(input));
+		this.#changed();
+	}
+	/** Adds an additional binding override for a command. */
+	add(loose, input) {
+		const id = loose;
+		this.#overrides.set(id, [...this.get(id), ...toBindings(input)]);
+		this.#changed();
+	}
+	/** Resets user overrides to defaults for one command or all commands. */
+	reset(loose) {
+		const id = loose;
+		if (id === void 0) {
+			if (this.#overrides.size === 0) return;
+			this.#overrides.clear();
+		} else if (!this.#overrides.delete(id)) return;
+		this.#changed();
+	}
+	/** Exports user overrides as a serialized keymap object. */
+	export() {
+		const data = {};
+		for (const [id, bindings] of this.#overrides) data[id] = bindings.map(serializeBinding);
+		return data;
+	}
+	/** Imports serialized user overrides and saves to storage. */
+	import(data) {
+		this.#read(data);
+		this.#changed();
+	}
+	/** Loads persisted overrides from storage. */
+	load() {
+		const storage = this.#storage();
+		if (!storage) return;
+		try {
+			const raw = storage.getItem(this.#storageKey());
+			if (!raw) return;
+			this.#read(JSON.parse(raw));
+			for (const listener of this.#listeners) listener();
+		} catch {}
+	}
+	/** Subscribes to keymap changes. Returns an unsubscribe function. */
+	subscribe(listener) {
+		this.#listeners.add(listener);
+		return () => {
+			this.#listeners.delete(listener);
+		};
+	}
+	#read(data) {
+		if (typeof data !== "object" || data === null) return;
+		this.#overrides.clear();
+		for (const [id, value] of Object.entries(data)) {
+			if (!Array.isArray(value)) continue;
+			const bindings = value.map(deserializeBinding).filter((binding) => binding !== null);
+			this.#overrides.set(id, bindings);
+		}
+	}
+	#changed() {
+		this.#persist();
+		for (const listener of this.#listeners) listener();
+	}
+	#persist() {
+		const storage = this.#storage();
+		if (!storage) return;
+		try {
+			const data = this.export();
+			if (Object.keys(data).length === 0) storage.removeItem(this.#storageKey());
+			else storage.setItem(this.#storageKey(), JSON.stringify(data));
+		} catch {}
+	}
+	#storageKey() {
+		return this.#persistence?.key ?? DEFAULT_STORAGE_KEY;
+	}
+	#storage() {
+		try {
+			return this.#persistence?.storage() ?? null;
+		} catch {
+			return null;
+		}
+	}
+};
+//#endregion
+//#region src/scopes.ts
+/** Wildcard scope identifier for commands that remain active across exclusive scopes. */
+const ALWAYS_SCOPE = "*";
+/** 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 entry = {
+			name,
+			exclusive: options.exclusive === true
+		};
+		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 true;
+		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/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;
+	#index = null;
+	#mounts = 0;
+	#hydrated = false;
+	#barrier = false;
+	constructor(definitions, options = {}) {
+		this.#options = options;
+		this.#keymap = new Keymap(options.persist);
+		this.#binder = new Binder({
+			getDefinition: (id) => this.#definition(id),
+			getBindings: (id) => this.#keymap.get(id),
+			canRun: (id) => this.canRun(id),
+			isReachable: (id) => this.#isReachable(id),
+			platform: () => this.#platform(),
+			execute: (id, context) => {
+				this.#execute(id, context);
+			}
+		}, options.target);
+		for (const [id, definition] of Object.entries(definitions)) this.#push(id, definition);
+		this.#keymap.load();
+		this.#keymap.subscribe(() => this.#onKeymapChange());
+		this.#scopes.subscribe(() => this.#onScopeChange());
+		this.#audit();
+	}
+	get keymap() {
+		return this.#keymap;
+	}
+	get(id) {
+		this.#snapshotList();
+		return this.#index?.get(id);
+	}
+	list() {
+		return this.#snapshotList();
+	}
+	run(id, options = {}) {
+		if (!this.canRun(id)) return false;
+		this.#execute(id, {
+			source: options.source ?? "api",
+			event: options.event
+		});
+		return true;
+	}
+	canRun(id) {
+		return this.whyNotRun(id) === null;
+	}
+	whyNotRun(loose) {
+		const id = loose;
+		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(error, {
+				id,
+				source: "api",
+				commands: this
+			});
+			return "guarded";
+		}
+	}
+	setEnabled(loose, enabled) {
+		const id = 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 = loose;
+		const entry = this.#push(id, definition);
+		if (this.#mounts > 0) this.#binder.sync(id);
+		this.#invalidate();
+		this.#auditAdded(id);
+		return {
+			run: (options) => this.run(id, options),
+			dispose: () => this.#pop(id, entry)
+		};
+	}
+	remove(loose) {
+		const id = 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 signatures = new Set(toBindings(binding).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.#keymap.get(id)) {
+				if (!signatures.has(bindingSignature(existing, platform))) continue;
+				const display = formatBinding(existing, this.#displayOptions());
+				conflicts.push({
+					id,
+					binding: existing,
+					display,
+					scope
+				});
+			}
+		}
+		return conflicts;
+	}
+	display(id) {
+		const binding = this.#keymap.get(id)[0];
+		return binding ? formatBinding(binding, this.#displayOptions()) : "";
+	}
+	tokens(id) {
+		const binding = this.#keymap.get(id)[0];
+		return binding ? bindingTokens(binding, this.#displayOptions()) : [];
+	}
+	mount() {
+		this.#mounts++;
+		if (this.#mounts === 1) {
+			this.#hydrated = true;
+			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.#binder.destroy();
+		};
+	}
+	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.#pendingSubscription?.unsubscribe();
+			this.#pendingSubscription = null;
+			this.#pending = EMPTY_PENDING;
+		};
+	}
+	subscribe(listener) {
+		this.#listeners.add(listener);
+		return () => {
+			this.#listeners.delete(listener);
+		};
+	}
+	destroy() {
+		this.#mounts = 0;
+		this.#binder.destroy();
+		this.#stacks.clear();
+		this.#order = [];
+		this.#enabled.clear();
+		this.#scopes.clear();
+		this.#listeners.clear();
+		this.#pendingListeners.clear();
+		this.#pendingSubscription?.unsubscribe();
+		this.#pendingSubscription = null;
+		this.#pending = EMPTY_PENDING;
+		this.#invalidate();
+	}
+	#onScopeChange() {
+		const barrier = this.#scopes.hasBarrier();
+		this.#binder.refreshEnabled();
+		if (barrier && !this.#barrier) getSequenceManager().resetAll();
+		this.#barrier = barrier;
+		this.#invalidate();
+	}
+	#watchPending() {
+		const store = getSequenceManager().registrations;
+		const read = () => {
+			const next = this.#readPending(store.state);
+			if (samePending(next, this.#pending)) return;
+			this.#pending = next;
+			for (const listener of this.#pendingListeners) listener();
+		};
+		this.#pendingSubscription = store.subscribe(read);
+		read();
+	}
+	#readPending(state) {
+		const options = this.#displayOptions();
+		const pending = [];
+		for (const { id, binding, registrationId } of this.#binder.sequences()) {
+			const matched = state.get(registrationId)?.matchedStepCount ?? 0;
+			if (matched === 0 || matched >= binding.sequence.length) continue;
+			pending.push({
+				id,
+				binding,
+				matched,
+				total: binding.sequence.length,
+				remaining: binding.sequence.slice(matched).map((step) => formatBinding(step, options))
+			});
+		}
+		return pending.length === 0 ? EMPTY_PENDING : pending;
+	}
+	#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, 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);
+	}
+	#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(error, full);
+		}
+		try {
+			const result = definition.run(full);
+			if (result instanceof Promise) result.catch((error) => this.#reportError(error, full));
+		} catch (error) {
+			this.#reportError(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 bindings = [...this.#keymap.get(id)];
+			const command = {
+				id,
+				title: definition.title,
+				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(" "),
+				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;
+		for (const listener of this.#listeners) listener();
+	}
+	#warnAboutConflicts() {
+		const seen = /* @__PURE__ */ new Map();
+		const collisions = [];
+		for (const id of this.#order) {
+			const scope = this.#definition(id)?.scope;
+			for (const binding of this.#keymap.get(id)) {
+				const key = `${scope ?? ""}::${bindingSignature(binding, this.#platform())}`;
+				const owner = seen.get(key);
+				if (owner === void 0) {
+					seen.set(key, id);
+					continue;
+				}
+				collisions.push(`${formatBinding(binding, this.#displayOptions())} — "${owner}" and "${id}"`);
+			}
+		}
+		if (collisions.length > 0) console.warn(`[@inklu/keys] ${collisions.length} conflicting binding(s):\n  ${collisions.join("\n  ")}`);
+	}
+	#warnAboutBindings(id) {
+		for (const binding of this.#keymap.get(id)) {
+			const { valid, errors } = validateBinding(binding);
+			if (valid) continue;
+			const resolved = formatBinding(binding, this.#displayOptions());
+			console.warn(`[@inklu/keys] "${id}" has an unrecognized binding ${describeBinding(binding)}, which resolves to "${resolved}". ${errors.join("; ")}.`);
+		}
+	}
+	#audit() {
+		if (!isDevelopment()) return;
+		for (const id of this.#order) this.#warnAboutBindings(id);
+		this.#warnAboutConflicts();
+	}
+	#auditAdded(id) {
+		if (!isDevelopment()) return;
+		this.#warnAboutBindings(id);
+		const scope = this.#definition(id)?.scope;
+		for (const conflict of this.conflicts(this.#keymap.get(id), {
+			ignore: id,
+			scope
+		})) console.warn(`[@inklu/keys] "${id}" binds ${conflict.display}, which "${conflict.id}" already uses.`);
+	}
+};
+function describeBinding(binding) {
+	return typeof binding === "string" ? `"${binding}"` : `"${binding.sequence.join(" ")}"`;
+}
+function isDevelopment() {
+	const environment = globalThis.process?.env?.NODE_ENV;
+	return environment !== void 0 && environment !== "production";
+}
+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;
+	});
+}
+function scopesOverlap(a, b) {
+	if (a === void 0 || b === void 0) return true;
+	if (a === "*" || b === "*") return true;
+	return a === b;
+}
+/**
+* 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
+export { bindingTokens as a, seq as c, ariaKeyShortcuts as i, toBindings as l, ALWAYS_SCOPE as n, formatBinding as o, createRebinder as r, bindingSignature as s, createCommands as t, validateBinding as u };