hotkey-router 0.2.3 → 0.3.0

package/dist/types/hotkey-router.d.ts

@@ -0,0 +1,196 @@
+declare namespace _default {
+    export { init };
+    export { destroy };
+    export { setTarget };
+    export { bind };
+    export { unbind };
+    export { registerPlugin };
+    export { unregisterPlugin };
+    export { onBind };
+    export { pause };
+    export { resume };
+    export { ignoreInput };
+    export { trigger };
+    export { parseHotkey };
+    export { comboFromEvent };
+}
+export default _default;
+/**
+ * Handler invoked when a bound hotkey fires. Receives the underlying
+ * `KeyboardEvent` (real one from the DOM, or a synthetic one produced by
+ * {@link trigger}).
+ */
+export type HotkeyHandler = (e: KeyboardEvent) => void;
+/**
+ * Optional per-binding behavior modifiers. See the inline comment on
+ * `normalizeOptions` for the canonical list.
+ */
+export type BindOptions = {
+    preventDefault?: boolean;
+    stopPropagation?: boolean;
+    stopImmediatePropagation?: boolean;
+    repeat?: boolean;
+    once?: boolean;
+    when?: (e: KeyboardEvent) => boolean;
+    allowIn?: (e: KeyboardEvent) => boolean;
+    priority?: number;
+    capture?: boolean;
+    altGraph?: boolean;
+    composing?: boolean;
+};
+/**
+ * Return value of {@link bind}: callable to unbind, plus `id` (the unique
+ * binding id used internally) and `hotkey` (the original input string).
+ */
+export type BindOff = (() => boolean) & {
+    id: number;
+    hotkey: string;
+};
+/**
+ * Payload passed to subscribers registered via {@link onBind} after each
+ * successful bind.
+ */
+export type BindEvent = {
+    combo: ReturnType<typeof parseHotkey>["combo"];
+    raw: string;
+    options: BindOptions;
+    plugin: string | null;
+    id: number;
+};
+/**
+ * Plugin shape accepted by {@link registerPlugin}: a map from hotkey
+ * strings to either a handler or a `[handler, options]` tuple.
+ */
+export type HotkeyMap = Record<string, HotkeyHandler | [HotkeyHandler, BindOptions]>;
+/**
+ * Initialize the router by attaching `keydown`/`keyup` listeners to a target.
+ * Re-initializes cleanly if already running (calls {@link destroy} first).
+ * Auto-runs on `window` at module-load time in browser environments.
+ *
+ * `capture: true` handles every binding in the capture phase. With the
+ * default (`false`), bindings run in the bubble phase except those bound
+ * with `{ capture: true }`, which a second, capture-phase listener handles:
+ * they see the key before the page's own listeners and can stop it.
+ *
+ * @param {{ target?: EventTarget, capture?: boolean }} [opts]
+ * @returns {void}
+ */
+declare function init({ target, capture }?: {
+    target?: EventTarget;
+    capture?: boolean;
+}): void;
+/**
+ * Tear down listeners and clear all bindings + plugins. Bind-hook
+ * subscribers ({@link onBind}) deliberately survive — consumer
+ * extensions should install once and live across `init`/`destroy` cycles.
+ *
+ * @returns {void}
+ */
+declare function destroy(): void;
+/**
+ * Replace the default target (used by {@link init} when no `target` is
+ * provided). Useful for iframes and tests. Does NOT auto-rebind existing
+ * listeners — call {@link destroy} + {@link init} to re-attach.
+ *
+ * @param {EventTarget | null} target
+ * @returns {void}
+ */
+declare function setTarget(target: EventTarget | null): void;
+/**
+ * Bind a hotkey combo string to a handler.
+ *
+ * @param {string} hotkeyStr      e.g. `'ctrl+shift+k'`, `'meta+slash'`, `'alt+code:KeyX'`
+ * @param {HotkeyHandler} handler
+ * @param {string | null} [plugin]  optional plugin/namespace tag for bulk cleanup
+ * @param {BindOptions} [options]
+ * @returns {BindOff} unbind function with `id` + `hotkey` props
+ */
+declare function bind(hotkeyStr: string, handler: HotkeyHandler, plugin?: string | null, options?: BindOptions): BindOff;
+/**
+ * Remove bindings for a combo string. Omit `handler` to remove all bindings
+ * for the combo/type; pass a specific handler to remove just that one.
+ *
+ * @param {string} hotkeyStr
+ * @param {HotkeyHandler} [handler]
+ * @returns {void}
+ */
+declare function unbind(hotkeyStr: string, handler?: HotkeyHandler): void;
+/**
+ * Register a named plugin that bulk-binds a {@link HotkeyMap}. All bindings
+ * are tagged with the plugin name so {@link unregisterPlugin} can clean them
+ * up together without touching other plugins' bindings.
+ *
+ * @param {string} name        plugin name (must be unique)
+ * @param {HotkeyMap} hotkeyMap
+ * @returns {() => void} unregister fn for this plugin
+ */
+declare function registerPlugin(name: string, hotkeyMap: HotkeyMap): () => void;
+/**
+ * Remove all bindings owned by the named plugin. Silent no-op if no such
+ * plugin is registered.
+ *
+ * @param {string} name
+ * @returns {void}
+ */
+declare function unregisterPlugin(name: string): void;
+/**
+ * Subscribe to {@link bind} events. The hook is called after each successful
+ * bind with a {@link BindEvent} payload.
+ *
+ * @param {(info: BindEvent) => void} hook
+ * @returns {() => void} unsubscribe
+ */
+declare function onBind(hook: (info: BindEvent) => void): () => void;
+/** Pause dispatch — bindings stay registered but no handlers fire. @returns {void} */
+declare function pause(): void;
+/** Resume dispatch after a {@link pause}. @returns {void} */
+declare function resume(): void;
+/**
+ * Toggle whether handlers fire when the event target is an editable element
+ * (input/textarea/contenteditable). Default `true`. Override per-binding via
+ * `options.allowIn`.
+ *
+ * @param {boolean} [value]
+ * @returns {void}
+ */
+declare function ignoreInput(value?: boolean): void;
+/**
+ * Programmatically fire any bindings for `hotkeyStr`. Used by tests and
+ * automation; not a typical app-runtime path. Returns `true` if a binding
+ * was found and invoked, `false` otherwise.
+ *
+ * @param {string} hotkeyStr
+ * @param {{ type?: 'keydown' | 'keyup' }} [opts]
+ * @returns {boolean}
+ */
+declare function trigger(hotkeyStr: string, { type: forcedType }?: {
+    type?: "keydown" | "keyup";
+}): boolean;
+export function parseHotkey(hotkeyStr: any): {
+    combo: {
+        ctrl: boolean;
+        shift: boolean;
+        alt: boolean;
+        meta: boolean;
+        key: any;
+        code: any;
+        bareModifier: any;
+    };
+    type: string;
+    raw: any;
+};
+/**
+ * The hotkey string for a keyboard event, for a "press your keys" recorder.
+ * Physical by default (`ctrl+shift+code:Period`), so the binding survives
+ * keyboard layouts. With `useMod`, the platform's primary modifier (Cmd on
+ * macOS, Ctrl elsewhere) is written as `mod`. Returns null for a bare
+ * modifier press (the user hasn't pressed the base key yet).
+ *
+ * @param {KeyboardEvent} e
+ * @param {{ physical?: boolean, useMod?: boolean }} [opts]
+ * @returns {string | null}
+ */
+export function comboFromEvent(e: KeyboardEvent, { physical, useMod }?: {
+    physical?: boolean;
+    useMod?: boolean;
+}): string | null;

package/dist/types/reservations.d.ts

@@ -0,0 +1,80 @@
+export function detectPlatform(nav?: Navigator): "mac" | "windows" | "linux";
+export function detectBrowser(nav?: Navigator): "edge" | "firefox" | "chrome" | "safari";
+export function lookupKeyFromCombo(combo: any): string;
+/**
+ * @typedef {'mac' | 'windows' | 'linux'} Platform
+ * @typedef {'chrome' | 'firefox' | 'safari' | 'edge'} Browser
+ * @typedef {'hard' | 'hard-fullscreen' | 'soft' | 'soft-warn'} Severity
+ *
+ * @typedef {{
+ *   source: 'browser' | 'system',
+ *   platform: Platform,
+ *   browser: Browser | undefined,
+ *   lookupKey: string,
+ *   action: string,
+ *   severity: Severity
+ * }} Reservation
+ */
+/**
+ * Look up whether a parsed hotkey combo is reserved by the host platform
+ * or browser. Returns `null` when not reserved or when the data table
+ * hasn't loaded.
+ *
+ * @param {object | null} combo  parsed combo from `hotkey-router`'s `parseHotkey`
+ * @param {{ platform?: Platform, browser?: Browser }} [opts]
+ * @returns {Reservation | null}
+ */
+export function lookupReservation(combo: object | null, { platform, browser }?: {
+    platform?: Platform;
+    browser?: Browser;
+}): Reservation | null;
+/** @param {Severity | string} severity @returns {boolean} */
+export function severityIsHard(severity: Severity | string): boolean;
+/** @param {Severity | string} severity @returns {boolean} */
+export function severityIsSoft(severity: Severity | string): boolean;
+/**
+ * Render a console-friendly warning string for a reservation.
+ *
+ * @param {Reservation} reservation
+ * @param {string} rawHotkey
+ * @returns {string}
+ */
+export function formatReservationWarning(reservation: Reservation, rawHotkey: string): string;
+/**
+ * Emit a reservation warning via the given console (or the global `console`
+ * by default). Hard reservations log via `warn`; soft ones via `info`.
+ *
+ * @param {Reservation} reservation
+ * @param {string} rawHotkey
+ * @param {Console} [console_]
+ * @returns {void}
+ */
+export function emitReservationWarning(reservation: Reservation, rawHotkey: string, console_?: Console): void;
+/**
+ * @param {object} hotkeys  a hotkey-router default-export instance
+ * @param {{
+ *   platform?: Platform,
+ *   browser?: Browser,
+ *   console?: Console
+ * }} [opts]
+ * @returns {() => void} uninstall function
+ */
+export function installReservationWarnings(hotkeys: object, opts?: {
+    platform?: Platform;
+    browser?: Browser;
+    console?: Console;
+}): () => void;
+export const SCHEMA_VERSION: any;
+export const DATA_GENERATED: any;
+export { HOTKEY_DATA };
+export type Platform = "mac" | "windows" | "linux";
+export type Browser = "chrome" | "firefox" | "safari" | "edge";
+export type Severity = "hard" | "hard-fullscreen" | "soft" | "soft-warn";
+export type Reservation = {
+    source: "browser" | "system";
+    platform: Platform;
+    browser: Browser | undefined;
+    lookupKey: string;
+    action: string;
+    severity: Severity;
+};

package/dist/types/sites.d.ts

@@ -0,0 +1,109 @@
+/** @typedef {'mac' | 'windows' | 'linux' | 'chromeos'} SitePlatform */
+/**
+ * @param {Navigator | null} [nav]
+ * @returns {SitePlatform | null}
+ */
+export function detectSitePlatform(nav?: Navigator | null): SitePlatform | null;
+/**
+ * Parse a hotkey string (`mod+shift+code:Period`, `ctrl+alt+,`) into modifier
+ * flags and a canonical base key name (`period`), resolving `mod` for the
+ * platform. Shared with validate.js.
+ *
+ * @param {string} str
+ * @param {SitePlatform} platform
+ * @returns {{ ctrl: boolean, meta: boolean, alt: boolean, shift: boolean, base: string | null }}
+ */
+export function parseComboString(str: string, platform: SitePlatform): {
+    ctrl: boolean;
+    meta: boolean;
+    alt: boolean;
+    shift: boolean;
+    base: string | null;
+};
+/**
+ * The canonical lookup key for a combo on a platform (`ctrl+shift+period`).
+ * Accepts a hotkey string or a parsed combo from hotkey-router (`onBind`).
+ *
+ * @param {string | { ctrl?: boolean, meta?: boolean, alt?: boolean, shift?: boolean, key?: string, code?: string }} combo
+ * @param {SitePlatform} [platform]
+ * @returns {string | null}
+ */
+export function siteLookupKey(combo: string | {
+    ctrl?: boolean;
+    meta?: boolean;
+    alt?: boolean;
+    shift?: boolean;
+    key?: string;
+    code?: string;
+}, platform?: SitePlatform): string | null;
+/**
+ * The researched sites whose hosts (and path prefixes, when listed) match a
+ * URL. Defaults to the current page.
+ *
+ * @param {string | URL} [url]
+ * @returns {Array<object>}
+ */
+export function matchSites(url?: string | URL): Array<object>;
+/**
+ * @typedef {{
+ *   siteId: string,
+ *   siteName: string,
+ *   action: string,
+ *   verified: boolean,
+ *   lookupKey: string
+ * }} SiteConflict
+ *
+ * Sources for each row are in data/site-hotkeys.json (look it up by siteId).
+ */
+/**
+ * The shortcuts on the page (or a given URL) that use the same chord.
+ *
+ * @param {string | object} combo  hotkey string or parsed combo
+ * @param {{ url?: string | URL, platform?: SitePlatform, verifiedOnly?: boolean }} [opts]
+ * @returns {SiteConflict[]}
+ */
+export function lookupSiteConflicts(combo: string | object, { url, platform, verifiedOnly }?: {
+    url?: string | URL;
+    platform?: SitePlatform;
+    verifiedOnly?: boolean;
+}): SiteConflict[];
+/**
+ * A `when()` gate for a binding: true on sites that don't use the chord;
+ * on sites that do, true only while `engaged(e)` says the user is focused
+ * on the app. Conflicts are looked up once per page URL.
+ *
+ * @param {string | object} combo  the binding's hotkey string (or parsed combo)
+ * @param {{
+ *   engaged: (e?: KeyboardEvent) => boolean,
+ *   url?: () => string,
+ *   platform?: SitePlatform,
+ *   verifiedOnly?: boolean,
+ *   onYield?: (conflicts: SiteConflict[], e?: KeyboardEvent) => void
+ * }} opts
+ * @returns {(e?: KeyboardEvent) => boolean}
+ */
+export function siteAware(combo: string | object, { engaged, url, platform, verifiedOnly, onYield }?: {
+    engaged: (e?: KeyboardEvent) => boolean;
+    url?: () => string;
+    platform?: SitePlatform;
+    verifiedOnly?: boolean;
+    onYield?: (conflicts: SiteConflict[], e?: KeyboardEvent) => void;
+}): (e?: KeyboardEvent) => boolean;
+/**
+ * All researched sites, compact form: `{ id, name, hosts, pathPrefixes,
+ * shortcuts: [windows, mac, chromeos, action, verified][] }`.
+ */
+export function listSites(): any;
+export const SITE_DATA_RESEARCHED: any;
+export const SITE_SCHEMA_VERSION: any;
+export type SitePlatform = "mac" | "windows" | "linux" | "chromeos";
+/**
+ * Sources for each row are in data/site-hotkeys.json (look it up by siteId).
+ */
+export type SiteConflict = {
+    siteId: string;
+    siteName: string;
+    action: string;
+    verified: boolean;
+    lookupKey: string;
+};

package/dist/types/validate.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @typedef {{
+ *   code: 'invalid' | 'no-key' | 'no-modifier' | 'alt-only' | 'needs-primary' |
+ *         'too-few-modifiers' | 'taken' | 'reserved' | 'reserved-soft' |
+ *         'altgr' | 'site-conflict',
+ *   severity: 'error' | 'warning',
+ *   message: string,
+ *   platforms?: string[],
+ *   details?: object
+ * }} ComboReason
+ */
+/**
+ * @param {string} combo  hotkey string, e.g. `mod+shift+code:Period`
+ * @param {{
+ *   platforms?: Array<'mac' | 'windows' | 'linux'>,
+ *   browsers?: Array<'chrome' | 'firefox' | 'edge' | 'safari'>,
+ *   requirePrimary?: boolean,  // must include Ctrl (Cmd on macOS)
+ *   minModifiers?: number,     // default 1
+ *   taken?: string[],          // combos the app already uses
+ *   sites?: boolean,           // warn about sites that use the keys (default true)
+ * }} [opts]
+ * @returns {{ ok: boolean, reasons: ComboReason[], lookupKeys: Record<string, string> }}
+ */
+export function validateCombo(combo: string, { platforms, browsers, requirePrimary, minModifiers, taken, sites, }?: {
+    platforms?: Array<"mac" | "windows" | "linux">;
+    browsers?: Array<"chrome" | "firefox" | "edge" | "safari">;
+    requirePrimary?: boolean;
+    minModifiers?: number;
+    taken?: string[];
+    sites?: boolean;
+}): {
+    ok: boolean;
+    reasons: ComboReason[];
+    lookupKeys: Record<string, string>;
+};
+export type ComboReason = {
+    code: "invalid" | "no-key" | "no-modifier" | "alt-only" | "needs-primary" | "too-few-modifiers" | "taken" | "reserved" | "reserved-soft" | "altgr" | "site-conflict";
+    severity: "error" | "warning";
+    message: string;
+    platforms?: string[];
+    details?: object;
+};

package/dist/validate.js

@@ -0,0 +1,106 @@
+// hotkey-router v0.3.0 | SEE LICENSE IN LICENSE
+
+
+// validate.js
+import { lookupReservation, severityIsHard } from "./reservations.js";
+import { parseComboString, listSites } from "./sites.js";
+var ALL_PLATFORMS = ["mac", "windows", "linux"];
+var ALL_BROWSERS = ["chrome", "firefox", "edge", "safari"];
+var PLATFORM_LABEL = { mac: "macOS", windows: "Windows", linux: "Linux" };
+var BROWSER_LABEL = { chrome: "Chrome", firefox: "Firefox", edge: "Edge", safari: "Safari" };
+var SITE_COL = { windows: 0, mac: 1, linux: 0 };
+function validateCombo(combo, {
+  platforms = ALL_PLATFORMS,
+  browsers = ALL_BROWSERS,
+  requirePrimary = false,
+  minModifiers = 1,
+  taken = [],
+  sites = true
+} = {}) {
+  const reasons = [];
+  const lookupKeys = {};
+  const add = (reason) => {
+    const same = reasons.find((r) => r.code === reason.code && r.message === reason.message);
+    if (same) {
+      for (const p of reason.platforms || []) if (!same.platforms?.includes(p)) same.platforms = [...same.platforms || [], p];
+      return;
+    }
+    reasons.push(reason);
+  };
+  if (typeof combo !== "string" || !combo.trim()) {
+    return { ok: false, reasons: [{ code: "invalid", severity: "error", message: "No keys were recorded." }], lookupKeys };
+  }
+  for (const platform of platforms) {
+    let parsed;
+    try {
+      parsed = parseComboString(combo, platform);
+    } catch {
+      parsed = null;
+    }
+    if (!parsed) {
+      add({ code: "invalid", severity: "error", message: "These keys could not be read.", platforms: [platform] });
+      continue;
+    }
+    if (!parsed.base) {
+      add({ code: "no-key", severity: "error", message: "Add a key to the modifiers, for example a letter or punctuation key.", platforms: [platform] });
+      continue;
+    }
+    const mods = ["ctrl", "meta", "alt", "shift"].filter((m) => parsed[m]);
+    const key = [...mods, parsed.base].join("+");
+    lookupKeys[platform] = key;
+    if (mods.length === 0) {
+      add({ code: "no-modifier", severity: "error", message: "Use at least one modifier (Ctrl, Alt, Shift or Cmd), or the key would fire while typing.", platforms: [platform] });
+    }
+    if (platform !== "mac" && mods.length === 1 && parsed.alt) {
+      add({ code: "alt-only", severity: "error", message: "Alt on its own moves focus to the browser menu when released. Add Ctrl or Shift.", platforms: [platform] });
+    }
+    const primary = platform === "mac" ? parsed.meta : parsed.ctrl;
+    if (requirePrimary && !primary) {
+      add({ code: "needs-primary", severity: "error", message: `Include ${platform === "mac" ? "Cmd" : "Ctrl"}.`, platforms: [platform] });
+    }
+    if (mods.length > 0 && mods.length < minModifiers) {
+      add({ code: "too-few-modifiers", severity: "error", message: `Use at least ${minModifiers} modifiers together.`, platforms: [platform] });
+    }
+    for (const other of taken) {
+      let otherKey = null;
+      try {
+        const o = parseComboString(other, platform);
+        if (o?.base) otherKey = [...["ctrl", "meta", "alt", "shift"].filter((m) => o[m]), o.base].join("+");
+      } catch {
+      }
+      if (otherKey === key) {
+        add({ code: "taken", severity: "error", message: "These keys are already used for something else here.", platforms: [platform], details: { combo: other } });
+      }
+    }
+    const shape = { ctrl: parsed.ctrl, meta: parsed.meta, alt: parsed.alt, shift: parsed.shift, key: parsed.base, code: null, bareModifier: null };
+    for (const browser of browsers) {
+      if (platform !== "mac" && browser === "safari") continue;
+      const hit = lookupReservation(shape, { platform, browser });
+      if (!hit) continue;
+      const where = hit.source === "system" ? PLATFORM_LABEL[platform] : `${BROWSER_LABEL[browser]} on ${PLATFORM_LABEL[platform]}`;
+      if (severityIsHard(hit.severity)) {
+        add({ code: "reserved", severity: "error", message: `${where} uses these keys (${hit.action}), so a page never sees them.`, platforms: [platform], details: { browser, action: hit.action } });
+      } else {
+        add({ code: "reserved-soft", severity: "warning", message: `${where} uses these keys in some situations (${hit.action}).`, platforms: [platform], details: { browser, action: hit.action, severity: hit.severity } });
+      }
+    }
+    if (platform === "windows" && parsed.ctrl && parsed.alt && !parsed.meta) {
+      add({ code: "altgr", severity: "warning", message: "On some keyboard layouts Ctrl+Alt acts as AltGr and types characters; those keystrokes are skipped.", platforms: [platform] });
+    }
+    if (sites) {
+      const col = SITE_COL[platform];
+      const names = [];
+      for (const site of listSites()) {
+        if (site.shortcuts.some((row) => row[col] === key)) names.push(site.name);
+      }
+      if (names.length) {
+        add({ code: "site-conflict", severity: "warning", message: `Also used by ${names.join(", ")}.`, platforms: [platform], details: { sites: names } });
+      }
+    }
+  }
+  return { ok: !reasons.some((r) => r.severity === "error"), reasons, lookupKeys };
+}
+export {
+  validateCombo
+};
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../validate.js"],
+  "sourcesContent": ["// validate.js\n// Check a hotkey before an app saves it, e.g. from a \"press your keys\"\n// recorder. Returns plain-language reasons the app can show as they are.\n//\n//   import { comboFromEvent } from 'hotkey-router'\n//   import { validateCombo } from 'hotkey-router/validate'\n//\n//   const combo = comboFromEvent(e, { useMod: true })   // 'mod+shift+code:Period'\n//   const { ok, reasons } = validateCombo(combo, { requirePrimary: true, minModifiers: 2 })\n//\n// Errors make `ok` false (the combo would not work, or breaks a rule the\n// app asked for). Warnings leave `ok` true (it works, with a caveat worth\n// telling the user: AltGr on some layouts, sites that use the same keys).\n//\n// Data: data/browser-hotkeys.json (keys the browser or OS take before the\n// page sees them) and data/site-hotkeys.runtime.json (keys popular sites use).\n\nimport { lookupReservation, severityIsHard } from './reservations.js'\nimport { parseComboString, listSites } from './sites.js'\n\nconst ALL_PLATFORMS = ['mac', 'windows', 'linux']\nconst ALL_BROWSERS = ['chrome', 'firefox', 'edge', 'safari']\nconst PLATFORM_LABEL = { mac: 'macOS', windows: 'Windows', linux: 'Linux' }\nconst BROWSER_LABEL = { chrome: 'Chrome', firefox: 'Firefox', edge: 'Edge', safari: 'Safari' }\n// Runtime site rows: [windows, mac, chromeos, action, verified]\nconst SITE_COL = { windows: 0, mac: 1, linux: 0 }\n\n/**\n * @typedef {{\n *   code: 'invalid' | 'no-key' | 'no-modifier' | 'alt-only' | 'needs-primary' |\n *         'too-few-modifiers' | 'taken' | 'reserved' | 'reserved-soft' |\n *         'altgr' | 'site-conflict',\n *   severity: 'error' | 'warning',\n *   message: string,\n *   platforms?: string[],\n *   details?: object\n * }} ComboReason\n */\n\n/**\n * @param {string} combo  hotkey string, e.g. `mod+shift+code:Period`\n * @param {{\n *   platforms?: Array<'mac' | 'windows' | 'linux'>,\n *   browsers?: Array<'chrome' | 'firefox' | 'edge' | 'safari'>,\n *   requirePrimary?: boolean,  // must include Ctrl (Cmd on macOS)\n *   minModifiers?: number,     // default 1\n *   taken?: string[],          // combos the app already uses\n *   sites?: boolean,           // warn about sites that use the keys (default true)\n * }} [opts]\n * @returns {{ ok: boolean, reasons: ComboReason[], lookupKeys: Record<string, string> }}\n */\nexport function validateCombo(combo, {\n  platforms = ALL_PLATFORMS,\n  browsers = ALL_BROWSERS,\n  requirePrimary = false,\n  minModifiers = 1,\n  taken = [],\n  sites = true,\n} = {}) {\n  /** @type {ComboReason[]} */\n  const reasons = []\n  const lookupKeys = {}\n  const add = (reason) => {\n    const same = reasons.find((r) => r.code === reason.code && r.message === reason.message)\n    if (same) {\n      for (const p of reason.platforms || []) if (!same.platforms?.includes(p)) same.platforms = [...(same.platforms || []), p]\n      return\n    }\n    reasons.push(reason)\n  }\n\n  if (typeof combo !== 'string' || !combo.trim()) {\n    return { ok: false, reasons: [{ code: 'invalid', severity: 'error', message: 'No keys were recorded.' }], lookupKeys }\n  }\n\n  for (const platform of platforms) {\n    let parsed\n    try {\n      parsed = parseComboString(combo, platform)\n    } catch {\n      parsed = null\n    }\n    if (!parsed) {\n      add({ code: 'invalid', severity: 'error', message: 'These keys could not be read.', platforms: [platform] })\n      continue\n    }\n    if (!parsed.base) {\n      add({ code: 'no-key', severity: 'error', message: 'Add a key to the modifiers, for example a letter or punctuation key.', platforms: [platform] })\n      continue\n    }\n    const mods = ['ctrl', 'meta', 'alt', 'shift'].filter((m) => parsed[m])\n    const key = [...mods, parsed.base].join('+')\n    lookupKeys[platform] = key\n\n    if (mods.length === 0) {\n      add({ code: 'no-modifier', severity: 'error', message: 'Use at least one modifier (Ctrl, Alt, Shift or Cmd), or the key would fire while typing.', platforms: [platform] })\n    }\n    if (platform !== 'mac' && mods.length === 1 && parsed.alt) {\n      add({ code: 'alt-only', severity: 'error', message: 'Alt on its own moves focus to the browser menu when released. Add Ctrl or Shift.', platforms: [platform] })\n    }\n    const primary = platform === 'mac' ? parsed.meta : parsed.ctrl\n    if (requirePrimary && !primary) {\n      add({ code: 'needs-primary', severity: 'error', message: `Include ${platform === 'mac' ? 'Cmd' : 'Ctrl'}.`, platforms: [platform] })\n    }\n    if (mods.length > 0 && mods.length < minModifiers) {\n      add({ code: 'too-few-modifiers', severity: 'error', message: `Use at least ${minModifiers} modifiers together.`, platforms: [platform] })\n    }\n\n    for (const other of taken) {\n      let otherKey = null\n      try {\n        const o = parseComboString(other, platform)\n        if (o?.base) otherKey = [...['ctrl', 'meta', 'alt', 'shift'].filter((m) => o[m]), o.base].join('+')\n      } catch { /* ignore unreadable entries */ }\n      if (otherKey === key) {\n        add({ code: 'taken', severity: 'error', message: 'These keys are already used for something else here.', platforms: [platform], details: { combo: other } })\n      }\n    }\n\n    const shape = { ctrl: parsed.ctrl, meta: parsed.meta, alt: parsed.alt, shift: parsed.shift, key: parsed.base, code: null, bareModifier: null }\n    for (const browser of browsers) {\n      if (platform !== 'mac' && browser === 'safari') continue\n      const hit = lookupReservation(shape, { platform, browser })\n      if (!hit) continue\n      const where = hit.source === 'system' ? PLATFORM_LABEL[platform] : `${BROWSER_LABEL[browser]} on ${PLATFORM_LABEL[platform]}`\n      if (severityIsHard(hit.severity)) {\n        add({ code: 'reserved', severity: 'error', message: `${where} uses these keys (${hit.action}), so a page never sees them.`, platforms: [platform], details: { browser, action: hit.action } })\n      } else {\n        add({ code: 'reserved-soft', severity: 'warning', message: `${where} uses these keys in some situations (${hit.action}).`, platforms: [platform], details: { browser, action: hit.action, severity: hit.severity } })\n      }\n    }\n\n    if (platform === 'windows' && parsed.ctrl && parsed.alt && !parsed.meta) {\n      add({ code: 'altgr', severity: 'warning', message: 'On some keyboard layouts Ctrl+Alt acts as AltGr and types characters; those keystrokes are skipped.', platforms: [platform] })\n    }\n\n    if (sites) {\n      const col = SITE_COL[platform]\n      const names = []\n      for (const site of listSites()) {\n        if (site.shortcuts.some((row) => row[col] === key)) names.push(site.name)\n      }\n      if (names.length) {\n        add({ code: 'site-conflict', severity: 'warning', message: `Also used by ${names.join(', ')}.`, platforms: [platform], details: { sites: names } })\n      }\n    }\n  }\n\n  return { ok: !reasons.some((r) => r.severity === 'error'), reasons, lookupKeys }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hotkey-router",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "A tiny, deterministic keyboard routing engine for modern web apps.",
   "type": "module",
   "author": "WATT3D <WATT3D@protonmail.com>",
@@ -29,7 +29,17 @@
       "types": "./dist/types/reservations.d.ts",
       "import": "./dist/reservations.js"
     },
-    "./data/browser-hotkeys.json": "./data/browser-hotkeys.json"
+    "./sites": {
+      "types": "./dist/types/sites.d.ts",
+      "import": "./dist/sites.js"
+    },
+    "./validate": {
+      "types": "./dist/types/validate.d.ts",
+      "import": "./dist/validate.js"
+    },
+    "./data/browser-hotkeys.json": "./data/browser-hotkeys.json",
+    "./data/site-hotkeys.json": "./data/site-hotkeys.json",
+    "./data/site-hotkeys.runtime.json": "./data/site-hotkeys.runtime.json"
   },
   "sideEffects": false,
   "files": [
@@ -43,21 +53,22 @@
   "scripts": {
     "build": "node build.js",
     "build:types": "tsc -p tsconfig.types.json",
-    "prepare": "node build.js",
-    "prepublishOnly": "node build.js && npm run build:types",
+    "prepare": "node build.js && npm run build:types",
+    "prepublishOnly": "npm test",
     "test": "vitest run --environment jsdom",
     "test:watch": "vitest --environment jsdom",
     "scrape:diff": "node scripts/scrape-reservations.mjs",
-    "scrape:apply": "node scripts/scrape-reservations.mjs --apply"
+    "scrape:apply": "node scripts/scrape-reservations.mjs --apply",
+    "sites:build": "node scripts/build-site-hotkeys.cjs"
   },
   "devDependencies": {
-    "esbuild": "^0.21.0",
+    "esbuild": "^0.28.1",
     "jsdom": "^24.0.0",
     "typescript": "^5.9.3",
     "vitest": "^3.1.2"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=18"
   },
   "repository": {
     "type": "git",