@inklu/keys 2.0.2 → 2.2.0

package/dist/src-TaZw4V61.mjs

@@ -0,0 +1,1797 @@
+//#region src/chord.ts
+/** The platform, as `navigator` reports it. `"other"` where there is none. */
+function detectPlatform() {
+	if (typeof navigator === "undefined") return "other";
+	return /mac/i.test(`${navigator.platform} ${navigator.userAgent}`) ? "mac" : "other";
+}
+/** Named keys in the `Key` type, as `KeyboardEvent.key` spells them. Other names still work. */
+const NAMED_KEYS = [
+	"ArrowUp",
+	"ArrowDown",
+	"ArrowLeft",
+	"ArrowRight",
+	"Home",
+	"End",
+	"PageUp",
+	"PageDown",
+	"Enter",
+	"Escape",
+	"Space",
+	"Tab",
+	"Backspace",
+	"Delete",
+	"Insert",
+	"CapsLock",
+	"ContextMenu",
+	"PrintScreen",
+	"ScrollLock",
+	"Pause",
+	"NumLock",
+	"Help",
+	"Clear",
+	"MediaPlayPause",
+	"MediaStop",
+	"MediaTrackNext",
+	"MediaTrackPrevious",
+	"AudioVolumeUp",
+	"AudioVolumeDown",
+	"AudioVolumeMute",
+	"BrowserBack",
+	"BrowserForward",
+	"BrowserRefresh",
+	"BrowserSearch",
+	"BrowserHome"
+];
+const MODIFIERS = [
+	"Control",
+	"Alt",
+	"Shift",
+	"Meta"
+];
+const PHYSICAL = /^\[([A-Za-z][A-Za-z0-9]*)\]$/;
+const FUNCTION_KEY = /^F([1-9]|1\d|2[0-4])$/;
+const LETTER = /^\p{Letter}$/u;
+const LATIN_LETTER = /^\p{Script_Extensions=Latin}$/u;
+/** Splits on `+`. The plus key itself is written last: `+` alone, or `Control++`. */
+function split(chord) {
+	const plusKey = chord === "+" || chord.endsWith("++");
+	const parts = (plusKey ? chord.slice(0, -1) : chord).split("+");
+	if (plusKey) parts[parts.length - 1] = "+";
+	return parts.map((part) => part.trim());
+}
+/** One spelling per key: letters upper-cased, the space bar by name. */
+function keyName$1(key) {
+	if (key === " ") return "Space";
+	if (!LETTER.test(key)) return key;
+	const upper = key.toUpperCase();
+	return upper.length === 1 ? upper : key;
+}
+/** The key a keypress produced. Empty for the keyless events browser autofill dispatches. */
+function pressedKey(event) {
+	return keyName$1(String(event.key ?? "").normalize("NFC"));
+}
+function isOneCharacter(key) {
+	return Array.from(key).length === 1;
+}
+/** Reads a chord, or says why it cannot be read. */
+function read(chord, platform) {
+	if (chord.trim() === "") return "Chord cannot be empty";
+	const parts = split(chord);
+	const key = parts.pop() ?? "";
+	if (key === "" || parts.includes("")) return "Invalid chord: empty part";
+	if (parts.includes("Mod") && (parts.includes("Control") || parts.includes("Meta"))) return "Mod already stands for Control or Meta: write one or the other";
+	const held = /* @__PURE__ */ new Set();
+	for (const part of parts) {
+		const name = part === "Mod" ? platform === "mac" ? "Meta" : "Control" : part;
+		const modifier = MODIFIERS.find((candidate) => candidate === name);
+		if (!modifier) return `Unknown modifier: '${part}'`;
+		if (held.has(modifier)) return `Repeated modifier: '${part}'`;
+		held.add(modifier);
+	}
+	const code = PHYSICAL.exec(key)?.[1];
+	if (code === void 0 && key.length > 1 && (key.startsWith("[") || key.endsWith("]"))) return "Invalid physical key: use a bracketed KeyboardEvent.code, such as [KeyS]";
+	return {
+		ctrl: held.has("Control"),
+		alt: held.has("Alt"),
+		shift: held.has("Shift"),
+		meta: held.has("Meta"),
+		...code === void 0 ? { key: keyName$1(key) } : { code }
+	};
+}
+/** Parses a chord for a platform, or returns `null` for one that cannot be read. */
+function parseChord(chord, platform) {
+	const result = read(chord, platform);
+	return typeof result === "string" ? null : result;
+}
+/** Whether a string is a chord this package can read. */
+function isChord(text) {
+	return parseChord(text, "mac") !== null;
+}
+/** A chord's `errors` (it will never fire) and `warnings` (a key name this package does not know). */
+function validateChord(chord) {
+	const result = read(chord, "mac");
+	if (typeof result === "string") return {
+		errors: [result],
+		warnings: []
+	};
+	const key = result.key;
+	return {
+		errors: [],
+		warnings: key === void 0 || isOneCharacter(key) || FUNCTION_KEY.test(key) || NAMED_KEYS.some((name) => name === key) ? [] : [`Unknown key: '${key}'. Key names are KeyboardEvent.key values, such as Escape.`]
+	};
+}
+/** Writes a parsed chord as text. Given a platform, its primary modifier is written `Mod`. */
+function writeChord(chord, mod) {
+	const portable = mod !== void 0 && (mod === "mac" ? chord.meta && !chord.ctrl : chord.ctrl && !chord.meta);
+	const parts = portable ? ["Mod"] : [];
+	if (chord.ctrl && !portable) parts.push("Control");
+	if (chord.alt) parts.push("Alt");
+	if (chord.shift) parts.push("Shift");
+	if (chord.meta && !portable) parts.push("Meta");
+	parts.push(chord.code === void 0 ? chord.key ?? "" : `[${chord.code}]`);
+	return parts.join("+");
+}
+/** Whether a chord types a character: a one-character key with no Control, Alt or Meta. */
+function typesCharacter(chord) {
+	if (chord.ctrl || chord.alt || chord.meta) return false;
+	return isOneCharacter(chord.key ?? keyAtCode(chord.code ?? "") ?? "");
+}
+const MODIFIER_KEYS = /* @__PURE__ */ new Set([
+	...MODIFIERS,
+	"AltGraph",
+	"OS",
+	"Fn",
+	"Hyper",
+	"Super",
+	"Symbol"
+]);
+/** Whether a `KeyboardEvent.key` is a modifier on its own. */
+function isModifierKey(key) {
+	return MODIFIER_KEYS.has(key);
+}
+/** Whether AltGr is down. Windows reports it as Control+Alt, though a character is being typed. */
+function hasAltGraph(event, platform) {
+	return platform !== "mac" && event.getModifierState?.("AltGraph") === true;
+}
+/** The punctuation keys of the conventional (US) layout, by `KeyboardEvent.code`. */
+const PUNCTUATION_CODES = {
+	Backquote: "`",
+	Backslash: "\\",
+	BracketLeft: "[",
+	BracketRight: "]",
+	Comma: ",",
+	Equal: "=",
+	Minus: "-",
+	Period: ".",
+	Quote: "'",
+	Semicolon: ";",
+	Slash: "/"
+};
+/** The key a `KeyboardEvent.code` sits on in the conventional (US) layout. */
+function keyAtCode(code) {
+	if (/^Key[A-Z]$/.test(code)) return code.slice(3);
+	if (/^Digit[0-9]$/.test(code)) return code.slice(5);
+	return code === "Space" ? code : PUNCTUATION_CODES[code];
+}
+/** A chord with its key by name: a physical key becomes the key at its position, or its `code`. */
+function namedChord(chord) {
+	const key = chord.key ?? keyAtCode(chord.code ?? "") ?? chord.code ?? "";
+	return {
+		...chord,
+		key,
+		code: void 0
+	};
+}
+/** `KeyboardEvent.key` values that name neither a character nor a key. */
+const NO_KEY = /* @__PURE__ */ new Set([
+	"",
+	"Dead",
+	"Unidentified",
+	"Process"
+]);
+const isAscii = (key) => /^[\x21-\x7e]$/.test(key);
+/** A one-character key that is not a letter: a digit or a symbol. */
+const isSymbol = (key) => isOneCharacter(key) && !LETTER.test(key);
+/** A key known by name rather than by a character, such as `Enter`. */
+const isNamed = (key) => !isOneCharacter(key) && !NO_KEY.has(key);
+/**
+* The key at a keypress's position on the US layout, where position may stand
+* in for what the layout produced:
+*
+* - on the digit row, always (`Mod+1` on AZERTY, `Shift+2` on a US keyboard);
+* - on a letter key that typed another script, or that macOS Option altered;
+* - on a punctuation key likewise, and while Shift or Alt is held.
+*
+* Never for a Latin letter, a named key, or under AltGr.
+*/
+function positionKey(event, key, altGraph) {
+	if (altGraph || /^[A-Z]$/.test(key) || isNamed(key)) return void 0;
+	const code = event.code;
+	if (/^Digit[0-9]$/.test(code)) return code.slice(5);
+	if (LATIN_LETTER.test(key) && !event.altKey) return void 0;
+	if (/^Key[A-Z]$/.test(code)) return isAscii(key) ? void 0 : code.slice(3);
+	return isAscii(key) && !event.shiftKey && !event.altKey ? void 0 : PUNCTUATION_CODES[code];
+}
+/**
+* Whether a keypress is this chord. A physical chord (`[KeyK]`) compares
+* position only. A logical one matches the key produced, where modifiers that
+* only typed a symbol need not be named (`?` is Shift+/ on a US keyboard), or
+* else the key's position where `positionKey` allows.
+*
+* Follows the matcher in TanStack Hotkeys (MIT).
+*/
+function matchesChord(event, chord, platform) {
+	const altGraph = hasAltGraph(event, platform);
+	if (altGraph && (chord.ctrl || chord.alt)) return false;
+	const alt = !altGraph && event.altKey;
+	const modifiersMatch = (typing) => (!altGraph && event.ctrlKey) === chord.ctrl && event.metaKey === chord.meta && (alt === chord.alt || typing && alt && platform === "mac") && (event.shiftKey === chord.shift || typing && event.shiftKey);
+	if (chord.code !== void 0) return event.code === chord.code && modifiersMatch(false);
+	const key = pressedKey(event);
+	if (key === chord.key) return modifiersMatch(isSymbol(key));
+	return positionKey(event, key, altGraph) === chord.key && modifiersMatch(false);
+}
+/**
+* The chord a keypress expresses, for recording a shortcut, or `null` for a
+* modifier on its own or a key with no name. It records what `matchesChord`
+* then matches: the character typed (`?`, not `Shift+/`), else the key's
+* position, with the primary modifier written `Mod`.
+*/
+function readChord(event, platform) {
+	if (isModifierKey(event.key)) return null;
+	const pressed = pressedKey(event);
+	const altGraph = hasAltGraph(event, platform);
+	const position = positionKey(event, pressed, altGraph);
+	const key = altGraph || isNamed(pressed) || isAscii(pressed) || LATIN_LETTER.test(pressed) && !event.altKey || position === void 0 ? pressed : position;
+	if (NO_KEY.has(key)) return null;
+	const typed = key === pressed && isSymbol(key);
+	const alt = !altGraph && event.altKey;
+	const chord = writeChord({
+		ctrl: !altGraph && event.ctrlKey,
+		alt: alt && !(typed && platform === "mac"),
+		shift: event.shiftKey && !typed,
+		meta: event.metaKey,
+		key
+	}, platform);
+	return isChord(chord) ? chord : null;
+}
+//#endregion
+//#region src/bindings.ts
+/** Bindings: a chord or a sequence of them. Comparing, validating and serializing. */
+/**
+* Creates a sequence binding from ordered chords.
+*
+* @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;
+}
+/** The chords of a binding, in order: one for a chord, several for a sequence. */
+function stepsOf(binding) {
+	return isSequence(binding) ? binding.sequence : [binding];
+}
+/** Normalizes a binding input into an array of bindings. A one-step sequence becomes a chord. */
+function toBindings(input) {
+	if (input == null) return [];
+	const candidates = isList(input) ? input : [input];
+	const bindings = [];
+	for (const candidate of candidates) {
+		if (candidate == null) continue;
+		const [first, ...rest] = stepsOf(candidate);
+		if (first === void 0) continue;
+		if (rest.length > 0) bindings.push({ sequence: [first, ...rest] });
+		else if (first.trim() !== "") bindings.push(first);
+	}
+	return bindings;
+}
+function isList(input) {
+	return Array.isArray(input);
+}
+/** The side of `{ mac, other }` keys that applies on a platform. Keys that do not differ pass through. */
+function keysFor(keys, platform) {
+	if (keys == null || !isPerPlatform(keys)) return keys;
+	return platform === "mac" ? keys.mac : keys.other;
+}
+function isPerPlatform(keys) {
+	return typeof keys === "object" && !Array.isArray(keys) && !("sequence" in keys);
+}
+/** Generates a normalized signature for binding comparison and conflict detection. */
+function bindingSignature(binding, platform) {
+	const steps = canonicalSteps(binding, platform);
+	return isSequence(binding) ? `seq:${steps.join(" ")}` : `chord:${steps.join(" ")}`;
+}
+/** Whether one binding is a strict prefix of the other, like chord `G` against `G then I`. */
+function isPrefixCollision(a, b, platform) {
+	const left = canonicalSteps(a, platform);
+	const right = canonicalSteps(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]);
+}
+/** Every step parsed for a platform, or `null` if any of them cannot be read. */
+function parseBinding(binding, platform) {
+	const steps = [];
+	for (const step of stepsOf(binding)) {
+		const parsed = parseChord(step, platform);
+		if (!parsed) return null;
+		steps.push(parsed);
+	}
+	return steps;
+}
+/** Each step in one spelling, so equivalent chords compare equal. One that cannot be read stays as written. */
+function canonicalSteps(binding, platform = detectPlatform()) {
+	return stepsOf(binding).map((step) => {
+		const parsed = parseChord(step, platform);
+		return parsed ? writeChord(parsed) : step;
+	});
+}
+/**
+* Whether every step is a printable character with no Control, Alt or Meta:
+* the "character key shortcuts" WCAG 2.1.4 lets users turn off.
+*/
+function isSingleKeyBinding(binding) {
+	return parseBinding(binding, "mac")?.every(typesCharacter) === true;
+}
+/** A binding's syntax `errors` (it will never fire) and `warnings`, for the development audit. */
+function validateBinding(binding) {
+	const results = stepsOf(binding).map(validateChord);
+	return {
+		errors: results.flatMap((result) => result.errors),
+		warnings: results.flatMap((result) => result.warnings)
+	};
+}
+//#endregion
+//#region src/display.ts
+/** Writing a binding for people: on screen, in `aria-keyshortcuts`, and read aloud. */
+const MODIFIER_LABELS = {
+	symbols: [
+		"⌃",
+		"⌥",
+		"⇧",
+		"⌘"
+	],
+	mac: [
+		"Control",
+		"Option",
+		"Shift",
+		"Cmd"
+	],
+	other: [
+		"Ctrl",
+		"Alt",
+		"Shift",
+		"Meta"
+	]
+};
+/** The abbreviated modifier labels, in full, for reading aloud. */
+const SPOKEN_MODIFIERS = {
+	Ctrl: "Control",
+	Cmd: "Command"
+};
+const KEY_LABELS = {
+	Enter: [
+		"↩",
+		"Enter",
+		"Return",
+		"Enter"
+	],
+	Backspace: [
+		"⌫",
+		"Backspace",
+		"Delete",
+		"Backspace"
+	],
+	Delete: [
+		"⌦",
+		"Del",
+		"Forward Delete",
+		"Delete"
+	],
+	Tab: [
+		"⇥",
+		"Tab",
+		"Tab"
+	],
+	Escape: [
+		"⎋",
+		"Esc",
+		"Escape"
+	],
+	ArrowUp: [
+		"↑",
+		"↑",
+		"Up Arrow"
+	],
+	ArrowDown: [
+		"↓",
+		"↓",
+		"Down Arrow"
+	],
+	ArrowLeft: [
+		"←",
+		"←",
+		"Left Arrow"
+	],
+	ArrowRight: [
+		"→",
+		"→",
+		"Right Arrow"
+	],
+	Home: [
+		"↖",
+		"Home",
+		"Home"
+	],
+	End: [
+		"↘",
+		"End",
+		"End"
+	],
+	PageUp: [
+		"⇞",
+		"PgUp",
+		"Page Up"
+	],
+	PageDown: [
+		"⇟",
+		"PgDn",
+		"Page Down"
+	],
+	"+": [
+		"+",
+		"Plus",
+		"Plus"
+	]
+};
+/** Names for the keys whose character is hard to tell apart in running text, or to hear. */
+const PUNCTUATION_NAMES = {
+	"`": "Backquote",
+	"\\": "Backslash",
+	"[": "Left Bracket",
+	"]": "Right Bracket",
+	",": "Comma",
+	"=": "Equal",
+	"-": "Minus",
+	".": "Period",
+	";": "Semicolon",
+	"/": "Slash",
+	"?": "Question Mark"
+};
+const spaced = (name) => name.replace(/([a-z])([A-Z])/g, "$1 $2");
+/**
+* Formats a binding the way its platform writes shortcuts: `⇧⌘S` on a Mac,
+* `Ctrl+Shift+S` elsewhere. The steps of a sequence are set apart by a space.
+*/
+function formatBinding(binding, options) {
+	return stepsOf(binding).map((step) => formatChord(step, options)).join(" ");
+}
+/**
+* Splits a binding into display tokens for rendering `<kbd>` elements: one
+* per key of a chord, one per step of a sequence.
+*/
+function bindingTokens(binding, options) {
+	if (isSequence(binding)) return binding.sequence.map((step) => formatChord(step, options));
+	return chordTokens(binding, options);
+}
+function formatChord(chord, options) {
+	return chordTokens(chord, options).join(usesModifierSymbols(options) ? "" : "+");
+}
+function usesModifierSymbols(options) {
+	return (options?.platform ?? detectPlatform()) === "mac" && options?.useSymbols !== false;
+}
+function chordTokens(chord, options) {
+	const platform = options?.platform ?? detectPlatform();
+	const parsed = parseChord(chord, platform);
+	if (!parsed) return [chord];
+	const labels = MODIFIER_LABELS[usesModifierSymbols(options) ? "symbols" : platform];
+	return [...heldLabels(parsed, labels), keyLabel(parsed, platform, options?.useSymbols !== false)];
+}
+function heldLabels(chord, labels) {
+	const held = [
+		chord.ctrl,
+		chord.alt,
+		chord.shift,
+		chord.meta
+	];
+	return labels.filter((_, index) => held[index]);
+}
+function keyLabel(chord, platform, symbols) {
+	const mac = platform === "mac";
+	const label = (key) => symbols ? KEY_LABELS[key]?.[mac ? 0 : 1] ?? key : keyName(key, mac);
+	if (chord.code?.startsWith("Numpad")) return `Numpad ${spaced(label(chord.code.slice(6)))}`;
+	return label(namedChord(chord).key);
+}
+/** A key in words: `"Return"`, `"Up Arrow"`, `"Comma"`, `"Caps Lock"`. */
+function keyName(key, mac) {
+	const label = KEY_LABELS[key];
+	if (label) return (mac ? void 0 : label[3]) ?? label[2];
+	return PUNCTUATION_NAMES[key] ?? spaced(key);
+}
+/**
+* Phrases a binding for a screen reader: `"Command K"` for a chord,
+* `"G then I"` for a sequence, which `aria-keyshortcuts` cannot express.
+*/
+function spokenBinding(binding, platform = detectPlatform()) {
+	return stepsOf(binding).map((step) => {
+		const parsed = parseChord(step, platform);
+		if (!parsed) return step;
+		return [...heldLabels(parsed, MODIFIER_LABELS[platform]).map((label) => SPOKEN_MODIFIERS[label] ?? label), keyName(namedChord(parsed).key, platform === "mac")].join(" ");
+	}).join(" then ");
+}
+/**
+* The `aria-keyshortcuts` value for a chord, as in `"Meta+K"`. Empty for a
+* sequence and for a chord that cannot be read.
+*/
+function ariaKeyShortcuts(binding, platform = detectPlatform()) {
+	const parsed = isSequence(binding) ? null : parseChord(binding, platform);
+	if (!parsed) return "";
+	const chord = namedChord(parsed);
+	return writeChord(chord.key === "+" ? {
+		...chord,
+		key: "Plus"
+	} : chord);
+}
+//#endregion
+//#region src/keymap.ts
+/** Keymap: default bindings, and the user's overrides on top of them. */
+/** A signature that holds on every platform, so `Mod+S` and `Control+S` stay distinct. */
+function portableSignature(binding) {
+	return `${bindingSignature(binding, "mac")} ${bindingSignature(binding, "other")}`;
+}
+var Keymap = class {
+	#defaults = /* @__PURE__ */ new Map();
+	#overrides = /* @__PURE__ */ new Map();
+	#listeners = /* @__PURE__ */ new Set();
+	#store;
+	#loaded = false;
+	constructor(store) {
+		this.#store = store;
+	}
+	/** Sets a command's default bindings. `null` leaves the command unbound. */
+	setDefault(id, input) {
+		const bindings = toBindings(input);
+		if (bindings.length === 0) this.#defaults.delete(id);
+		else this.#defaults.set(id, bindings);
+	}
+	/** Checks whether a command has an active user override. */
+	isOverridden(id) {
+		return this.#overrides.has(id);
+	}
+	/** The user's overrides, for a store or an export to write out. */
+	get overrides() {
+		return this.#overrides;
+	}
+	get(id) {
+		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)];
+	}
+	set(id, input) {
+		this.#load();
+		const bindings = input === null ? [] : toBindings(input);
+		if (sameBindings(bindings, this.#defaults.get(id) ?? [])) {
+			if (!this.#overrides.delete(id)) return;
+		} else this.#overrides.set(id, {
+			kind: "replace",
+			bindings
+		});
+		this.#changed();
+	}
+	add(id, input) {
+		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();
+	}
+	reset(id) {
+		this.#load();
+		if (id === void 0) {
+			if (this.#overrides.size === 0) return;
+			this.#overrides.clear();
+		} else if (!this.#overrides.delete(id)) return;
+		this.#changed();
+	}
+	/** Replaces every override and saves, as an import does. */
+	replace(overrides) {
+		this.#loaded = true;
+		this.#overrides = overrides;
+		this.#changed();
+	}
+	/**
+	* Takes the stored overrides, telling subscribers if they differ from the
+	* ones in memory, and returns whether they did. Each mount starts with it,
+	* which catches up on what other tabs stored while nothing was listening.
+	*/
+	sync() {
+		this.#loaded = true;
+		const stored = this.#store?.read();
+		if (!stored) return false;
+		const before = JSON.stringify([...this.#overrides]);
+		this.#overrides = stored;
+		if (JSON.stringify([...stored]) === before) return false;
+		this.#notify();
+		return true;
+	}
+	/** Follows edits other tabs make to the stored overrides. Returns a function that stops. */
+	watch() {
+		return this.#store?.watch(() => this.sync()) ?? (() => {});
+	}
+	/** Subscribes to keymap changes. Returns an unsubscribe function. */
+	subscribe(listener) {
+		this.#listeners.add(listener);
+		return () => {
+			this.#listeners.delete(listener);
+		};
+	}
+	/** Before an edit: stored overrides load first, once, so the edit lands on top of them. */
+	#load() {
+		if (!this.#loaded) this.sync();
+	}
+	#changed() {
+		this.#store?.write(this.#overrides);
+		this.#notify();
+	}
+	#notify() {
+		for (const listener of this.#listeners) listener();
+	}
+};
+/** `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);
+	});
+}
+//#endregion
+//#region src/persist.ts
+/** Keeping a keymap between visits: Web Storage, and export and import as JSON. */
+const VERSION = 1;
+/**
+* Keeps user overrides in Web Storage under `key`, and follows edits made in
+* other tabs. `storage` is only called in the browser; return
+* `sessionStorage` or an object of your own to keep them somewhere else.
+*
+* @example
+* ```ts
+* createCommands(definitions, { persist: webStorage("my-app.keys") });
+* ```
+*/
+function webStorage(key = "inklu.keys", storage = () => localStorage) {
+	const open = () => {
+		try {
+			return storage();
+		} catch {
+			return null;
+		}
+	};
+	return {
+		read() {
+			const area = open();
+			if (!area) return null;
+			try {
+				const raw = area.getItem(key);
+				return raw ? parseKeymap(JSON.parse(raw)) : /* @__PURE__ */ new Map();
+			} catch {
+				return null;
+			}
+		},
+		write(overrides) {
+			try {
+				if (overrides.size === 0) open()?.removeItem(key);
+				else open()?.setItem(key, JSON.stringify(serializeKeymap(overrides)));
+			} catch {}
+		},
+		watch(onChange) {
+			if (typeof window === "undefined") return () => {};
+			const onStorage = (event) => {
+				if (event.key === null || event.key === key) onChange();
+			};
+			window.addEventListener("storage", onStorage);
+			return () => window.removeEventListener("storage", onStorage);
+		}
+	};
+}
+/** A registry's user overrides as JSON-safe data, for your own storage or another device. */
+function exportKeymap(commands) {
+	return serializeKeymap(keymapOf(commands).overrides);
+}
+/**
+* Replaces a registry's user overrides with exported data, and saves them.
+* Data in another format changes nothing.
+*/
+function importKeymap(commands, data) {
+	const overrides = parseKeymap(data);
+	if (overrides) keymapOf(commands).replace(overrides);
+}
+function keymapOf({ keymap }) {
+	if (keymap instanceof Keymap) return keymap;
+	throw new TypeError("[@inklu/keys] not a registry made by createCommands");
+}
+function serializeKeymap(overrides) {
+	return {
+		version: VERSION,
+		overrides: Object.fromEntries(Array.from(overrides, ([id, { kind, bindings }]) => {
+			const list = bindings.map((binding) => isSequence(binding) ? [...binding.sequence] : binding);
+			return [id, kind === "replace" ? list : { add: list }];
+		}))
+	};
+}
+/** The overrides in stored data, or `null` for data in another format. */
+function parseKeymap(data) {
+	const stored = isObject(data) && data.version === VERSION ? data.overrides : void 0;
+	if (stored === void 0 || !isObject(stored)) return null;
+	const overrides = /* @__PURE__ */ new Map();
+	for (const [id, value] of Object.entries(stored)) {
+		const override = parseOverride(value);
+		if (override) overrides.set(id, override);
+	}
+	return overrides;
+}
+function parseOverride(value) {
+	if (Array.isArray(value)) {
+		const bindings = parseBindings(value);
+		return bindings && {
+			kind: "replace",
+			bindings
+		};
+	}
+	if (isObject(value) && Array.isArray(value.add)) {
+		const bindings = parseBindings(value.add);
+		return bindings && bindings.length > 0 ? {
+			kind: "add",
+			bindings
+		} : null;
+	}
+	return null;
+}
+/**
+* Reads a stored list. `[]` is an unbound command; a non-empty list with
+* nothing usable in it is damage, and reads as `null`.
+*/
+function parseBindings(values) {
+	const bindings = values.map(parseStoredBinding).filter((binding) => binding !== null);
+	return bindings.length === 0 && values.length > 0 ? null : bindings;
+}
+/** A stored chord (a string) or sequence (a list of them), or `null` if it cannot be read. */
+function parseStoredBinding(value) {
+	if (typeof value === "string") return isChord(value) ? value : null;
+	if (!Array.isArray(value)) return null;
+	const steps = [];
+	for (const step of value) {
+		if (typeof step !== "string" || !isChord(step)) return null;
+		steps.push(step);
+	}
+	const [first, ...rest] = steps;
+	if (first === void 0) return null;
+	return rest.length === 0 ? first : { sequence: steps };
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/keys.ts
+/** The one keyboard listener: matches a keypress to bindings and runs the command that wins it. */
+const DEFAULT_SEQUENCE_TIMEOUT = 1e3;
+/** The longest delay `setTimeout` honours; a longer one fires at once. */
+const MAX_TIMER = 2 ** 31 - 1;
+const NO_PROGRESS = [];
+var KeyListener = class {
+	#host;
+	#target;
+	#attached = null;
+	#bound = null;
+	/** Whoever has taken the keyboard, the most recent last. See `capture`. */
+	#captures = [];
+	#spent = null;
+	#watchers = /* @__PURE__ */ new Set();
+	#progress = NO_PROGRESS;
+	#timer = null;
+	constructor(host, target) {
+		this.#host = host;
+		this.#target = target;
+	}
+	/** Starts listening. A no-op on the server. */
+	attach() {
+		if (this.#attached || typeof document === "undefined") return;
+		this.#attached = this.#target ?? document;
+		this.#attached.addEventListener("keydown", this.#onKeyDown);
+	}
+	/** Stops listening and abandons half-typed sequences. */
+	detach() {
+		this.#attached?.removeEventListener("keydown", this.#onKeyDown);
+		this.#attached = null;
+		this.refresh();
+	}
+	/** Stops listening for good, dropping the watchers and captures too. */
+	destroy() {
+		this.#watchers.clear();
+		for (let onKey = this.#captures.at(-1); onKey; onKey = this.#captures.at(-1)) this.#release(onKey);
+		this.detach();
+	}
+	/** Whether something has taken the keyboard, so no command's keys are live. */
+	get captured() {
+		return this.#captures.length > 0;
+	}
+	/** Hands every keypress to `onKey` until released, in the capture phase on the document. */
+	capture(onKey) {
+		if (typeof document === "undefined") return () => {};
+		this.#captures.push(onKey);
+		if (this.#captures.length === 1) document.addEventListener("keydown", this.#onCapture, true);
+		return () => this.#release(onKey);
+	}
+	#release(onKey) {
+		const index = this.#captures.lastIndexOf(onKey);
+		if (index === -1) return;
+		this.#captures.splice(index, 1);
+		if (this.#captures.length > 0) return;
+		document.removeEventListener("keydown", this.#onCapture, true);
+	}
+	/** Bindings or the platform changed: re-read them. Half-typed sequences start over. */
+	refresh() {
+		this.#bound = null;
+		this.#publish();
+	}
+	/** Reachability changed: a half-typed sequence that is no longer reachable starts over. */
+	prune() {
+		let changed = false;
+		for (const bound of this.#bound ?? []) {
+			if (bound.matched === 0 || this.#host.reachable(bound.id)) continue;
+			bound.matched = 0;
+			changed = true;
+		}
+		if (changed) this.#publish();
+	}
+	/** Half-typed sequences. Tracked only while something is watching. */
+	progress() {
+		return this.#progress;
+	}
+	/** Watches sequence progress. It is tracked, and timed, only while someone is watching. */
+	watch(listener) {
+		this.#watchers.add(listener);
+		if (this.#watchers.size === 1) this.#publish();
+		return () => {
+			this.#watchers.delete(listener);
+			if (this.#watchers.size === 0) this.#publish();
+		};
+	}
+	#bindings() {
+		if (this.#bound) return this.#bound;
+		const platform = this.#host.platform();
+		const bound = [];
+		this.#host.ids().forEach((id, order) => {
+			for (const binding of this.#host.bindings(id)) {
+				const steps = parseBinding(binding, platform);
+				if (!steps) continue;
+				const timeout = this.#host.definition(id)?.sequenceTimeout ?? DEFAULT_SEQUENCE_TIMEOUT;
+				bound.push({
+					id,
+					order,
+					binding,
+					steps,
+					timeout,
+					matched: 0,
+					at: 0
+				});
+			}
+		});
+		this.#bound = bound;
+		return bound;
+	}
+	#onCapture = (event) => {
+		const onKey = this.#captures.at(-1);
+		if (!onKey || isComposing(event)) return;
+		this.#spent = event;
+		onKey(event, readChord(event, this.#host.platform()));
+	};
+	#onKeyDown = (event) => {
+		if (isComposing(event) || this.captured) return;
+		if (this.#spent) {
+			if (event === this.#spent || event.repeat) return;
+			this.#spent = null;
+		}
+		if (isModifierKey(event.key)) return;
+		const platform = this.#host.platform();
+		const typing = isTyping(event, this.#target);
+		const now = Date.now();
+		const chords = [];
+		const sequences = [];
+		let continued = false;
+		let prevent = false;
+		let progressed = false;
+		for (const bound of this.#bindings()) {
+			const definition = this.#host.definition(bound.id);
+			const first = bound.steps[0];
+			if (!definition || !first || !this.#host.reachable(bound.id)) continue;
+			if (typing && (definition.ignoreInputs ?? ignoresInputs(first, platform))) continue;
+			if (bound.steps.length === 1) {
+				if (matchesChord(event, first, platform)) chords.push(bound);
+				continue;
+			}
+			if (event.repeat) continue;
+			const matched = now - bound.at > bound.timeout ? 0 : bound.matched;
+			const expected = bound.steps[matched];
+			let reached = 0;
+			if (expected && matchesChord(event, expected, platform)) reached = matched + 1;
+			else if (matched > 0 && matchesChord(event, first, platform)) reached = 1;
+			const next = reached === bound.steps.length ? 0 : reached;
+			if (next !== bound.matched) progressed = true;
+			bound.matched = next;
+			bound.at = now;
+			if (reached === 0) continue;
+			if (reached > 1) continued = true;
+			if (reached === bound.steps.length) {
+				sequences.push(bound);
+				continue;
+			}
+			const step = bound.steps[reached - 1];
+			if (!(typing && !step?.ctrl && !step?.meta) && definition.preventDefault !== false) prevent = true;
+		}
+		if (progressed) this.#publish();
+		if (continued) this.#spent = event;
+		const candidates = sequences.length > 0 ? sequences : continued ? [] : chords;
+		let winner;
+		for (const bound of candidates) if (!winner || this.#outranks(bound, winner)) winner = bound;
+		const definition = winner && this.#host.definition(winner.id);
+		if (!winner || !definition) {
+			if (prevent) event.preventDefault();
+			return;
+		}
+		if (prevent || definition.preventDefault !== false) event.preventDefault();
+		if (event.repeat && definition.repeat === false) return;
+		this.#host.run(winner.id, event, winner.binding);
+	};
+	#outranks(a, b) {
+		const depth = this.#host.depth(a.id) - this.#host.depth(b.id);
+		return depth === 0 ? a.order > b.order : depth > 0;
+	}
+	#publish = () => {
+		if (this.#timer !== null) clearTimeout(this.#timer);
+		this.#timer = null;
+		const progress = [];
+		let expires = null;
+		if (this.#watchers.size > 0) {
+			const now = Date.now();
+			for (const bound of this.#bound ?? []) {
+				if (bound.matched === 0 || !isSequence(bound.binding)) continue;
+				const deadline = bound.at + bound.timeout;
+				if (now > deadline) continue;
+				expires = expires === null ? deadline : Math.min(expires, deadline);
+				progress.push({
+					id: bound.id,
+					binding: bound.binding,
+					matched: bound.matched
+				});
+			}
+		}
+		const wait = expires === null ? Infinity : Math.max(0, expires - Date.now()) + 1;
+		if (wait < MAX_TIMER) this.#timer = setTimeout(this.#publish, wait);
+		if (progress.length === this.#progress.length && progress.every((entry, index) => {
+			const other = this.#progress[index];
+			return other?.binding === entry.binding && other.matched === entry.matched;
+		})) return;
+		this.#progress = progress.length === 0 ? NO_PROGRESS : progress;
+		for (const watcher of this.#watchers) watcher();
+	};
+};
+/**
+* Whether a keydown belongs to an IME composition. Some engines report it
+* only as `keyCode` 229 or the key `Process`.
+*/
+function isComposing(event) {
+	return event.isComposing || event.keyCode === 229 || event.key === "Process";
+}
+/**
+* Whether a binding stays quiet in a text field when its command does not
+* say: everything but Control/Meta chords and bare `Escape`, and also the
+* chords a field edits its own text with.
+*/
+function ignoresInputs(step, platform) {
+	if (step.key === "Escape" || step.code === "Escape") return false;
+	return !(step.ctrl || step.meta) || editsText(step, platform);
+}
+/** Keys that, with the primary modifier, move the caret or delete by word or by line. */
+const CARET_KEYS = /^(Backspace|Delete|Home|End|Arrow\w+)$/;
+/**
+* Whether a text field acts on a chord itself, on the platform's primary
+* modifier: select all, copy, cut, paste, undo and redo, and moving or
+* deleting by word or line.
+*/
+function editsText(step, platform) {
+	const mac = platform === "mac";
+	if (step.alt || step.ctrl === mac || step.meta !== mac) return false;
+	const key = namedChord(step).key;
+	if (key.length > 1) return CARET_KEYS.test(key);
+	return (step.shift ? "VZ" : mac ? "ACVXZ" : "ACVXYZ").includes(key);
+}
+/**
+* Whether a keypress lands in a field that takes text. `host`, the element
+* the listener sits on, does not count.
+*/
+function isTyping(event, host) {
+	return event.composedPath().some((node) => node !== host && isTextEntry(node));
+}
+/** ARIA roles of widgets that take typed keys the way their native counterparts do. */
+const TEXT_ENTRY_ROLES = /* @__PURE__ */ new Set([
+	"textbox",
+	"searchbox",
+	"combobox",
+	"spinbutton",
+	"slider"
+]);
+function isTextEntry(node) {
+	if (!(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 || !["false", null].includes(node.getAttribute("contenteditable")) || TEXT_ENTRY_ROLES.has(node.getAttribute("role") ?? "");
+}
+//#endregion
+//#region src/rebind.ts
+/** Controller for recording and applying hotkey rebindings. */
+const NO_STEPS = [];
+/**
+* Creates a rebinder for recording a command's keys. While it records, no
+* command runs. Escape cancels, Backspace removes the shortcut (or the last
+* step of a sequence), and Enter finishes a sequence.
+*
+* @example
+* ```ts
+* const rebinder = createRebinder(commands, "palette.open", {
+*   onRecord: (binding, conflicts) => showConflicts(conflicts),
+* });
+* rebinder.start();
+* ```
+*/
+function createRebinder(registry, id, options = {}) {
+	const sequence = options.mode === "sequence";
+	const listeners = /* @__PURE__ */ new Set();
+	let state = {
+		recording: false,
+		binding: null,
+		steps: NO_STEPS,
+		conflicts: []
+	};
+	let release = null;
+	let idle = null;
+	const set = (next) => {
+		state = next;
+		for (const listener of listeners) listener();
+	};
+	/** Gives the keyboard back. */
+	const end = () => {
+		release?.();
+		release = null;
+		if (idle !== null) clearTimeout(idle);
+		idle = null;
+	};
+	const record = (binding) => {
+		end();
+		const conflicts = registry.conflicts(binding, {
+			ignore: id,
+			scope: registry.get(id)?.scope
+		});
+		const blocked = conflicts.some((conflict) => conflict.kind === "reserved") || 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);
+		}
+		set({
+			recording: false,
+			binding,
+			steps: NO_STEPS,
+			conflicts
+		});
+		options.onRecord?.(binding, conflicts);
+	};
+	const cancel = () => {
+		end();
+		set({
+			...state,
+			recording: false,
+			steps: NO_STEPS
+		});
+		options.onCancel?.();
+	};
+	const clear = () => {
+		end();
+		if (options.apply !== false) registry.keymap.set(id, null);
+		set({
+			recording: false,
+			binding: null,
+			steps: NO_STEPS,
+			conflicts: []
+		});
+		options.onClear?.();
+	};
+	const commit = () => {
+		const [first, ...rest] = state.steps;
+		if (first === void 0) return;
+		record(rest.length === 0 ? first : { sequence: state.steps });
+	};
+	/** Sets the steps typed so far, and restarts the wait for the next one. */
+	const step = (steps) => {
+		if (idle !== null) clearTimeout(idle);
+		const wait = options.idleTimeout ?? 0;
+		idle = wait > 0 && steps.length > 0 ? setTimeout(commit, wait) : null;
+		set({
+			...state,
+			steps
+		});
+	};
+	const stop = () => {
+		if (!state.recording) return;
+		end();
+		set({
+			...state,
+			recording: false,
+			steps: NO_STEPS
+		});
+	};
+	const onKey = (event, chord) => {
+		if (options.ignoreInputs !== false && event.key !== "Escape" && isTyping(event)) return;
+		event.preventDefault();
+		event.stopPropagation();
+		if (event.repeat) return;
+		const bare = !event.ctrlKey && !event.altKey && !event.shiftKey && !event.metaKey;
+		if (bare && event.key === "Escape") return cancel();
+		if (bare && (event.key === "Backspace" || event.key === "Delete")) return state.steps.length === 0 ? clear() : step(state.steps.slice(0, -1));
+		if (sequence && bare && event.key === "Enter") return commit();
+		if (chord === null) return;
+		if (sequence) step([...state.steps, chord]);
+		else record(chord);
+	};
+	return {
+		start: () => {
+			if (state.recording) return;
+			release = registry.capture(onKey);
+			set({
+				recording: true,
+				binding: null,
+				steps: NO_STEPS,
+				conflicts: []
+			});
+		},
+		stop,
+		cancel: () => {
+			if (state.recording) cancel();
+		},
+		commit: () => {
+			if (state.recording && sequence) commit();
+		},
+		get state() {
+			return state;
+		},
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		destroy: () => {
+			stop();
+			listeners.clear();
+		}
+	};
+}
+//#endregion
+//#region src/reserved.ts
+/** Chords the browser or the operating system keeps for itself. */
+const chords = (list) => new Set(list.split(" "));
+const RESERVED = {
+	mac: chords("Meta+N Meta+T Meta+W Meta+Q Meta+H Meta+M Meta+Tab Meta+Space Shift+Meta+N Shift+Meta+T Shift+Meta+W Shift+Meta+Q Shift+Meta+Tab Shift+Meta+3 Shift+Meta+4 Shift+Meta+5 Control+Tab Control+Shift+Tab Control+Meta+Q"),
+	other: chords("Control+N Control+T Control+W Control+Shift+N Control+Shift+T Control+Shift+W Control+Tab Control+Shift+Tab Control+PageUp Control+PageDown Control+F4 Alt+F4 Alt+Tab Alt+Shift+Tab Alt+Space Control+Alt+Tab Control+Alt+Delete")
+};
+/** Whether any step of a binding is a chord the browser or OS reserves on a platform. */
+function isReserved(binding, platform) {
+	return (parseBinding(binding, platform) ?? []).some((chord) => {
+		const written = writeChord(namedChord(chord));
+		return platform === "mac" ? RESERVED.mac.has(written) : chord.meta || RESERVED.other.has(written);
+	});
+}
+/**
+* Whether commands in two scopes can be live together, so their bindings can
+* collide: a global or `"*"` command overlaps every scope, and two named
+* scopes only when they are the same.
+*/
+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 entry = {
+			name,
+			exclusive: options.exclusive === true
+		};
+		this.#entries.push(entry);
+		this.#notify();
+		return () => {
+			const index = this.#entries.indexOf(entry);
+			if (index === -1) return;
+			this.#entries.splice(index, 1);
+			this.#notify();
+		};
+	}
+	/**
+	* Whether the keys of commands in `scope` are live: the scope is open and
+	* no `exclusive` scope above it has claimed the keyboard.
+	*/
+	isActive(scope) {
+		if (scope === "*") return true;
+		const barrier = this.#barrierIndex();
+		if (barrier === -1) return this.isOpen(scope);
+		return scope !== void 0 && this.depth(scope) >= barrier;
+	}
+	/** Whether `scope` is open at all, barriers aside. This is what a direct `run()` checks. */
+	isOpen(scope) {
+		return scope === void 0 || scope === "*" || this.depth(scope) !== -1;
+	}
+	/** How far up the stack `scope` was last opened, or `-1` for a global or closed one. */
+	depth(scope) {
+		if (scope === void 0 || scope === "*") return -1;
+		for (let index = this.#entries.length - 1; index >= 0; index--) if (this.#entries[index]?.name === scope) return index;
+		return -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/audit.ts
+/** Development-only warnings about default bindings that cannot work as written. */
+const platformName = (platform) => platform === "mac" ? "macOS" : "Windows and Linux";
+/** A binding as the app wrote it, which is what there is to search the code for. */
+const written = (binding) => stepsOf(binding).join(" ");
+/**
+* Warns about bad syntax, keys the platform keeps or types with, unknown
+* overrides and collisions. Called behind a `NODE_ENV` check, so a production
+* build drops this module.
+*/
+function auditRegistry(source) {
+	const said = /* @__PURE__ */ new Set();
+	const warn = (message) => {
+		if (said.has(message)) return;
+		said.add(message);
+		console.warn(`[@inklu/keys] ${message}`);
+	};
+	/** Reserved bindings, and the platforms each is reserved on. */
+	const reserved = /* @__PURE__ */ new Map();
+	for (const platform of source.platforms) {
+		for (const id of source.ids) for (const binding of source.bindings(id, platform)) {
+			warnAboutBinding(id, binding, platform, warn);
+			if (!isReserved(binding, platform)) continue;
+			const subject = `"${id}" binds "${written(binding)}"`;
+			reserved.set(subject, (reserved.get(subject) ?? /* @__PURE__ */ new Set()).add(platformName(platform)));
+		}
+		warnAboutConflicts(source, platform, warn);
+	}
+	for (const [subject, platforms] of reserved) warn(`${subject}, which the browser or operating system keeps for itself on ${[...platforms].join(" and ")}, so it may never reach the page.`);
+	warnAboutUnknownOverrides(source, warn);
+}
+function warnAboutBinding(id, binding, platform, warn) {
+	const { errors, warnings } = validateBinding(binding);
+	if (errors.length > 0) {
+		warn(`"${id}" has an unrecognized binding "${written(binding)}", so it never fires. ${errors.join("; ")}.`);
+		return;
+	}
+	if (warnings.length > 0) warn(`"${id}" binds "${written(binding)}". ${warnings.join(" ")}`);
+	const held = (parseBinding(binding, platform) ?? []).filter((step) => step.ctrl && step.alt);
+	if (held.length === 0) return;
+	if (platform === "mac") warn(`"${id}" binds "${written(binding)}". Control+Option is the VoiceOver modifier on macOS, so screen reader users cannot press it.`);
+	else if (held.some((step) => typesCharacter({
+		...namedChord(step),
+		ctrl: false,
+		alt: false
+	}))) warn(`"${id}" binds "${written(binding)}". Control+Alt is AltGr on many Windows and Linux keyboard layouts, where it types a character instead. Give those platforms other keys with { mac, other }.`);
+}
+function warnAboutConflicts(source, platform, warn) {
+	const seen = /* @__PURE__ */ new Map();
+	const visited = [];
+	for (const id of source.ids) {
+		const scope = source.scope(id);
+		for (const binding of source.bindings(id, platform)) {
+			for (const other of visited) {
+				if (other.id === id || !scopesOverlap(other.scope, scope)) continue;
+				if (!isPrefixCollision(other.binding, binding, platform)) continue;
+				const [short, long] = stepsOf(other.binding).length < stepsOf(binding).length ? [other, {
+					id,
+					binding
+				}] : [{
+					id,
+					binding
+				}, other];
+				warn(`prefix collision: ${written(short.binding)} ("${short.id}") is a prefix of ${written(long.binding)} ("${long.id}"), so the shorter binding fires on the way to the longer one.`);
+			}
+			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;
+			}
+			warn(`shadowed binding: "${id}" and "${owner}" share ${written(binding)} in the same scope, so "${id}" takes the key whenever both have a handler.`);
+		}
+	}
+}
+/** Catches ids in `options.bindings` that TypeScript could not, as in plain JS. */
+function warnAboutUnknownOverrides(source, warn) {
+	if (!source.overrides) return;
+	const known = new Set(source.ids);
+	const unknown = Object.keys(source.overrides).filter((id) => !known.has(id));
+	if (unknown.length > 0) warn(`bindings override ${unknown.map((id) => `"${id}"`).join(", ")}, which ${unknown.length === 1 ? "is not a registered command" : "are not registered commands"}.`);
+}
+//#endregion
+//#region src/registry.ts
+/** Command registry: what an app can do, which keys do it, and where each is live. */
+const SSR_PLATFORM = "other";
+var CommandRegistry = class {
+	#definitions;
+	/** Handlers attached per command, the most recent last. */
+	#handlers = /* @__PURE__ */ new Map();
+	#keymap;
+	#scopes = new ScopeStack();
+	#keys;
+	#options;
+	#listeners = /* @__PURE__ */ new Set();
+	#snapshot = null;
+	/** What the snapshot is behind on: who is reachable, or the bindings too. */
+	#stale = "bindings";
+	#serverSnapshot = null;
+	#pending = null;
+	/** Stops following other tabs' keymap edits; set while mounted. */
+	#unwatch = null;
+	#mounts = 0;
+	#hydrated = false;
+	#singleKeys;
+	constructor(definitions, options = {}) {
+		this.#options = options;
+		this.#singleKeys = options.singleKeyShortcuts !== false;
+		this.#keymap = new Keymap(options.persist);
+		this.#definitions = /* @__PURE__ */ new Map();
+		for (const id in definitions) this.#definitions.set(id, definitions[id]);
+		this.#setDefaults();
+		this.#keys = new KeyListener({
+			ids: () => [...this.#definitions.keys()],
+			definition: (id) => this.#definitions.get(id),
+			bindings: (id) => this.#bindings(id),
+			reachable: (id) => this.#reachable(id),
+			depth: (id) => this.#scopes.depth(this.#definitions.get(id)?.scope),
+			platform: () => this.#platform(),
+			run: (id, event, binding) => this.#execute(id, {
+				source: "keyboard",
+				event,
+				binding
+			})
+		}, options.target);
+		this.#keymap.subscribe(() => this.#bindingsChanged());
+		this.#scopes.subscribe(() => this.#reachabilityChanged());
+		if (process.env.NODE_ENV !== "production") auditRegistry({
+			ids: [...this.#definitions.keys()],
+			scope: (id) => this.#definitions.get(id)?.scope,
+			bindings: (id, platform) => this.#defaultBindings(id, platform),
+			platforms: options.platform ? [options.platform] : ["mac", "other"],
+			overrides: options.bindings
+		});
+	}
+	get keymap() {
+		return this.#keymap;
+	}
+	get(id) {
+		return this.#snapshots().index.get(id);
+	}
+	list() {
+		return this.#snapshots().list;
+	}
+	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 = Array.from(this.#definitions, ([id, definition]) => {
+			const bindings = this.#defaultBindings(id, platform).filter((binding) => singleKeys || !isSingleKeyBinding(binding));
+			const global = definition.scope === void 0 || definition.scope === "*";
+			return describeCommand(id, definition, bindings, platform, options, {
+				reachable: definition.run !== void 0 && global,
+				overridden: false
+			});
+		});
+		return this.#serverSnapshot;
+	}
+	run(id, options = {}) {
+		if (this.whyNotRun(id) !== null) return false;
+		this.#execute(id, {
+			source: options.source ?? "api",
+			event: options.event
+		});
+		return true;
+	}
+	canRun(id) {
+		return this.whyNotRun(id) === null;
+	}
+	whyNotRun(id) {
+		const definition = this.#definitions.get(id);
+		if (!definition) return "unknown";
+		if (!this.#handler(id)) return "unhandled";
+		return this.#scopes.isOpen(definition.scope) ? null : "out-of-scope";
+	}
+	handle(id, run) {
+		if (!this.#definitions.has(id)) return () => {};
+		let handlers = this.#handlers.get(id);
+		if (!handlers) {
+			handlers = [];
+			this.#handlers.set(id, handlers);
+		}
+		const had = this.#handler(id) !== void 0;
+		handlers.push(run);
+		if (!had) this.#reachabilityChanged();
+		let disposed = false;
+		return () => {
+			if (disposed) return;
+			disposed = true;
+			const index = handlers.lastIndexOf(run);
+			if (index !== -1) handlers.splice(index, 1);
+			if (this.#handler(id) === void 0) this.#reachabilityChanged();
+		};
+	}
+	pushScope(name, options) {
+		return this.#scopes.push(name, options);
+	}
+	capture(onKey) {
+		const release = this.#keys.capture(onKey);
+		this.#reachabilityChanged();
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			release();
+			this.#reachabilityChanged();
+		};
+	}
+	conflicts(binding, options = {}) {
+		const platform = this.#platform();
+		const display = (entry) => formatBinding(entry, this.#displayOptions());
+		const candidates = toBindings(binding);
+		const signatures = new Set(candidates.map((entry) => bindingSignature(entry, platform)));
+		const conflicts = [];
+		for (const candidate of candidates) {
+			if (!isReserved(candidate, platform)) continue;
+			conflicts.push({
+				kind: "reserved",
+				binding: candidate,
+				display: display(candidate)
+			});
+		}
+		for (const [id, { scope }] of this.#definitions) {
+			if (id === options.ignore || !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;
+				conflicts.push({
+					kind,
+					id,
+					binding: existing,
+					display: display(existing),
+					scope
+				});
+			}
+		}
+		return conflicts;
+	}
+	pending() {
+		const from = this.#keys.progress();
+		if (this.#pending?.from !== from) {
+			const options = this.#displayOptions();
+			this.#pending = {
+				from,
+				list: from.map(({ id, binding, matched }) => ({
+					id,
+					binding,
+					matched,
+					total: binding.sequence.length,
+					remaining: binding.sequence.slice(matched).map((step) => formatBinding(step, options))
+				}))
+			};
+		}
+		return this.#pending.list;
+	}
+	subscribePending(listener) {
+		return this.#keys.watch(listener);
+	}
+	get singleKeyShortcuts() {
+		return this.#singleKeys;
+	}
+	setSingleKeyShortcuts(enabled) {
+		if (this.#singleKeys === enabled) return;
+		this.#singleKeys = enabled;
+		this.#bindingsChanged();
+	}
+	mount() {
+		this.#mounts++;
+		if (this.#mounts === 1) {
+			const rendered = this.#platform();
+			this.#hydrated = true;
+			const moved = this.#platform() !== rendered;
+			if (moved) this.#setDefaults();
+			this.#unwatch = this.#keymap.watch();
+			this.#keys.attach();
+			if (!this.#keymap.sync() && moved) this.#bindingsChanged();
+		}
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			if (this.#mounts === 0) return;
+			this.#mounts--;
+			if (this.#mounts === 0) this.#unmount();
+		};
+	}
+	subscribe(listener) {
+		this.#listeners.add(listener);
+		return () => {
+			this.#listeners.delete(listener);
+		};
+	}
+	destroy() {
+		this.#mounts = 0;
+		this.#unwatch?.();
+		this.#unwatch = null;
+		this.#keys.destroy();
+		this.#definitions.clear();
+		this.#handlers.clear();
+		this.#serverSnapshot = null;
+		this.#invalidate("bindings");
+		this.#listeners.clear();
+		this.#scopes.clear();
+	}
+	#unmount() {
+		this.#keys.detach();
+		this.#unwatch?.();
+		this.#unwatch = null;
+	}
+	/** The handler that runs: the one attached last, else the definition's own. */
+	#handler(id) {
+		return this.#handlers.get(id)?.at(-1) ?? this.#definitions.get(id)?.run;
+	}
+	#reachable(id) {
+		if (this.#keys.captured || !this.#handler(id)) return false;
+		return this.#scopes.isActive(this.#definitions.get(id)?.scope);
+	}
+	/** Bindings in effect: the keymap's, minus single-key ones while those are switched off. */
+	#bindings(id) {
+		const bindings = this.#keymap.get(id);
+		if (this.#singleKeys) return bindings;
+		return bindings.filter((binding) => !isSingleKeyBinding(binding));
+	}
+	/**
+	* A command's default bindings on a platform. An `options.bindings` entry
+	* wins over the definition's `keys`, and a `null` one means unbound.
+	*/
+	#defaultBindings(id, platform) {
+		const overrides = this.#options.bindings;
+		return toBindings(keysFor(overrides && Object.hasOwn(overrides, id) ? overrides[id] : this.#definitions.get(id)?.keys, platform));
+	}
+	/** Hands the keymap every command's defaults for the platform in effect. */
+	#setDefaults() {
+		const platform = this.#platform();
+		for (const id of this.#definitions.keys()) this.#keymap.setDefault(id, this.#defaultBindings(id, platform));
+	}
+	#execute(id, context) {
+		const run = this.#handler(id);
+		if (!run) 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 = 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);
+	}
+	#bindingsChanged() {
+		this.#keys.refresh();
+		this.#invalidate("bindings");
+	}
+	#reachabilityChanged() {
+		this.#keys.prune();
+		this.#invalidate("reachable");
+	}
+	#platform() {
+		return this.#options.platform ?? (this.#hydrated ? detectPlatform() : SSR_PLATFORM);
+	}
+	#displayOptions() {
+		return {
+			platform: this.#platform(),
+			...this.#options.display
+		};
+	}
+	/**
+	* The commands as they are now. A command that did not change keeps its
+	* object, and the list keeps its own while none did, so a subscriber can
+	* tell by identity whether it has anything to do.
+	*/
+	#snapshots() {
+		const previous = this.#snapshot;
+		if (previous && !this.#stale) return previous;
+		const kept = this.#stale === "reachable" ? previous?.index : void 0;
+		const platform = this.#platform();
+		const options = this.#displayOptions();
+		const list = [];
+		const index = /* @__PURE__ */ new Map();
+		let changed = !kept;
+		for (const [id, definition] of this.#definitions) {
+			const reachable = this.#reachable(id);
+			let command = kept?.get(id);
+			if (!command) command = describeCommand(id, definition, this.#bindings(id), platform, options, {
+				reachable,
+				overridden: this.#keymap.isOverridden(id)
+			});
+			else if (command.reachable !== reachable) {
+				command = {
+					...command,
+					reachable
+				};
+				changed = true;
+			}
+			list.push(command);
+			index.set(id, command);
+		}
+		this.#stale = null;
+		this.#snapshot = changed || !previous ? {
+			list,
+			index
+		} : previous;
+		return this.#snapshot;
+	}
+	#invalidate(stale) {
+		if (this.#stale !== "bindings") this.#stale = stale;
+		for (const listener of this.#listeners) listener();
+	}
+};
+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));
+}
+/**
+* Creates a command registry.
+*
+* @example
+* ```ts
+* export const commands = createCommands({
+*   "palette.open": { title: "Open command palette", keys: "Mod+K" },
+*   "nav.inbox": {
+*     title: "Go to inbox",
+*     keys: seq("G", "I"),
+*     run: () => router.navigate("/inbox"),
+*   },
+* });
+* ```
+*/
+function createCommands(definitions, options) {
+	return new CommandRegistry(definitions, options);
+}
+//#endregion
+//#region src/search.ts
+/**
+* Filters commands for a search query, leaving out `hidden` ones. Every word
+* must appear in the title, description, group, keywords, id or displayed
+* shortcut. Titles starting with the query come first, then titles containing
+* every word, then the rest. 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 { importKeymap as a, bindingTokens as c, isSingleKeyBinding as d, seq as f, exportKeymap as i, formatBinding as l, keyName$1 as m, createCommands as n, webStorage as o, isModifierKey as p, createRebinder as r, ariaKeyShortcuts as s, matchCommands as t, spokenBinding as u };