@notis_ai/cli 0.2.18 → 0.2.19

package/dist/sdk/src/words/format.ts

@@ -0,0 +1,136 @@
+/**
+ * How keys read on screen (toolkit spec 2.2), matching the review deck:
+ * - Mac: glyphs in ctrl, alt, shift, cmd order, then the key ("⇧E", "⌘A").
+ * - Elsewhere: names joined by "+" ("Ctrl+A"); French says "Maj" for Shift.
+ * - Sequences join with "then" / "puis"; alternatives with "or" / "ou".
+ */
+
+import { keyList, parseKeySpec, type Chord } from './keys';
+import type { KeySpec, Locale, Platform, Words } from './types';
+
+export interface FormatKeyOptions {
+  platform: Platform;
+  locale: Locale;
+}
+
+export const KEY_JOIN_WORDS: Readonly<{ then: Words; or: Words }> = Object.freeze({
+  then: { en: 'then', fr: 'puis' },
+  or: { en: 'or', fr: 'ou' },
+});
+
+const MAC_GLYPH = { ctrl: '⌃', alt: '⌥', shift: '⇧', mod: '⌘' } as const;
+
+function keyName(key: string, mac: boolean, fr: boolean): string {
+  switch (key) {
+    case 'enter': return mac ? '↵' : fr ? 'Entrée' : 'Enter';
+    // French says Échap on every computer, as the Portal does.
+    case 'escape': return fr ? 'Échap' : 'Esc';
+    case 'space': return fr ? 'Espace' : 'Space';
+    case 'arrowdown': return '↓';
+    case 'arrowup': return '↑';
+    case 'arrowleft': return '←';
+    case 'arrowright': return '→';
+    case 'tab': return 'Tab';
+    case 'backspace': return mac ? '⌫' : fr ? 'Retour arrière' : 'Backspace';
+    case 'delete': return mac ? '⌦' : fr ? 'Suppr' : 'Delete';
+    case 'insert': return fr ? 'Inser' : 'Insert';
+    case 'home': return fr ? 'Début' : 'Home';
+    case 'end': return fr ? 'Fin' : 'End';
+    case 'pagedown': return fr ? 'Pg suiv' : 'PgDn';
+    case 'pageup': return fr ? 'Pg préc' : 'PgUp';
+    default:
+      if (key.length === 1) return key.toUpperCase();
+      return key[0]!.toUpperCase() + key.slice(1);
+  }
+}
+
+/** One chord as shown on a single keycap. */
+export function formatChord(chord: Chord, { platform, locale }: FormatKeyOptions): string {
+  const mac = platform === 'mac';
+  const fr = locale === 'fr';
+  if (mac) {
+    const glyphs = (['ctrl', 'alt', 'shift', 'mod'] as const).filter((m) => chord[m]).map((m) => MAC_GLYPH[m]).join('');
+    return glyphs + keyName(chord.key, mac, fr);
+  }
+  const names: string[] = [];
+  if (chord.mod || chord.ctrl) names.push('Ctrl');
+  if (chord.alt) names.push('Alt');
+  if (chord.shift) names.push(fr ? 'Maj' : 'Shift');
+  return [...names, keyName(chord.key, mac, fr)].join('+');
+}
+
+/**
+ * Keycap parts: one entry per alternative, each a list of caps (one per sequence step).
+ * `[['⇧E']]`, `[['G', 'I']]`, `[['J'], ['↓']]`.
+ */
+export function formatKeyParts(spec: KeySpec | readonly KeySpec[], options: FormatKeyOptions): string[][] {
+  return keyList(spec).map((one) => parseKeySpec(one).map((chord) => formatChord(chord, options)));
+}
+
+/** The whole spec as one string: "J or ↓", "G then I", "⇧E". */
+export function formatKey(spec: KeySpec | readonly KeySpec[], options: FormatKeyOptions): string {
+  const then = ` ${KEY_JOIN_WORDS.then[options.locale]} `;
+  const or = ` ${KEY_JOIN_WORDS.or[options.locale]} `;
+  return formatKeyParts(spec, options).map((caps) => caps.join(then)).join(or);
+}
+
+const ARIA_KEY: Readonly<Record<string, string>> = {
+  escape: 'Escape', enter: 'Enter', tab: 'Tab', space: 'Space', backspace: 'Backspace', delete: 'Delete',
+  insert: 'Insert', arrowup: 'ArrowUp', arrowdown: 'ArrowDown', arrowleft: 'ArrowLeft', arrowright: 'ArrowRight',
+  home: 'Home', end: 'End', pageup: 'PageUp', pagedown: 'PageDown',
+};
+
+/** Value for the `aria-keyshortcuts` attribute ("Shift+E J ArrowDown"). Sequences are left out (ARIA has no syntax). */
+export function toAriaKeyShortcuts(spec: KeySpec | readonly KeySpec[], platform: Platform): string {
+  return keyList(spec)
+    .map((one) => parseKeySpec(one))
+    .filter((chords) => chords.length === 1)
+    .map(([chord]) => {
+      const parts: string[] = [];
+      if (chord!.mod) parts.push(platform === 'mac' ? 'Meta' : 'Control');
+      if (chord!.ctrl && !(chord!.mod && platform !== 'mac')) parts.push('Control');
+      if (chord!.alt) parts.push('Alt');
+      if (chord!.shift) parts.push('Shift');
+      const key = chord!.key;
+      parts.push(ARIA_KEY[key] ?? (key.length === 1 ? key.toUpperCase() : key[0]!.toUpperCase() + key.slice(1)));
+      return parts.join('+');
+    })
+    .join(' ');
+}
+
+const SPOKEN_KEY: Readonly<Record<string, Words>> = Object.freeze({
+  enter: { en: 'Enter', fr: 'Entrée' },
+  escape: { en: 'Escape', fr: 'Échap' },
+  space: { en: 'Space', fr: 'Espace' },
+  arrowdown: { en: 'Down arrow', fr: 'Flèche bas' },
+  arrowup: { en: 'Up arrow', fr: 'Flèche haut' },
+  arrowleft: { en: 'Left arrow', fr: 'Flèche gauche' },
+  arrowright: { en: 'Right arrow', fr: 'Flèche droite' },
+  backspace: { en: 'Backspace', fr: 'Retour arrière' },
+  delete: { en: 'Delete', fr: 'Suppr' },
+  pagedown: { en: 'Page down', fr: 'Page suivante' },
+  pageup: { en: 'Page up', fr: 'Page précédente' },
+});
+
+const SPOKEN_MOD = Object.freeze({
+  ctrl: { en: 'Control', fr: 'Contrôle' },
+  alt: { mac: { en: 'Option', fr: 'Option' }, other: { en: 'Alt', fr: 'Alt' } },
+  shift: { en: 'Shift', fr: 'Maj' },
+  mod: { mac: { en: 'Command', fr: 'Commande' }, other: { en: 'Control', fr: 'Contrôle' } },
+});
+
+/** Words for screen readers: glyphs spelled out ("Command A", "G then I"). Used for the Keycap sr-only label. */
+export function formatKeySpoken(spec: KeySpec | readonly KeySpec[], { platform, locale }: FormatKeyOptions): string {
+  const then = ` ${KEY_JOIN_WORDS.then[locale]} `;
+  const or = ` ${KEY_JOIN_WORDS.or[locale]} `;
+  const chordWords = (chord: Chord): string => {
+    const parts: string[] = [];
+    if (chord.ctrl && !(chord.mod && platform !== 'mac')) parts.push(SPOKEN_MOD.ctrl[locale]);
+    if (chord.alt) parts.push(SPOKEN_MOD.alt[platform][locale]);
+    if (chord.shift) parts.push(SPOKEN_MOD.shift[locale]);
+    if (chord.mod) parts.push(SPOKEN_MOD.mod[platform][locale]);
+    parts.push(SPOKEN_KEY[chord.key]?.[locale] ?? keyName(chord.key, false, locale === 'fr'));
+    return parts.join(' ');
+  };
+  return keyList(spec).map((one) => parseKeySpec(one).map(chordWords).join(then)).join(or);
+}

package/dist/sdk/src/words/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @notis/sdk/words: pure toolkit vocabulary. No React, no DOM, no state; bundled into each Space and read by the
+ * CLI design check and the server. Action catalogue, shell words, key specs, the default key map, `formatKey`,
+ * host-reserved keys and `checkClashes`.
+ */
+
+export * from './types';
+export * from './keys';
+export * from './format';
+export * from './actions';
+export * from './shell';
+export * from './keymap';
+export * from './clashes';

package/dist/sdk/src/words/keymap.ts

@@ -0,0 +1,72 @@
+/**
+ * The default key map (toolkit spec 3). Pieces register these ids with these keys and words, so the ? sheet reads
+ * the same in every Space and on every Notis page. Action keys come from the catalogue (`STANDARD_ACTIONS`).
+ */
+
+import type { KeySpec, Scope, Words } from './types';
+
+export interface KeymapEntry {
+  id: string;
+  keys: readonly KeySpec[];
+  scope: Scope;
+  label: Words;
+  /** Registered by the Notis host, never by a Space. */
+  host?: boolean;
+  /** Manager only for now (spec 6.10). */
+  managerOnly?: boolean;
+  /** Fires while the key is held (J/K stepping). */
+  repeat?: boolean;
+  /** Not listed in the help sheet. */
+  hidden?: boolean;
+}
+
+const entry = (id: string, keys: KeySpec[], scope: Scope, en: string, fr: string, extra: Partial<KeymapEntry> = {}):
+  KeymapEntry => Object.freeze({ id, keys: Object.freeze(keys), scope, label: Object.freeze({ en, fr }), ...extra });
+
+export const DEFAULT_KEYMAP = Object.freeze({
+  // Lists (collection scope).
+  'list.next': entry('list.next', ['j', 'arrowdown'], 'collection', 'Next item', 'Élément suivant', { repeat: true }),
+  'list.prev': entry('list.prev', ['k', 'arrowup'], 'collection', 'Previous item', 'Élément précédent', { repeat: true }),
+  'list.extendDown': entry('list.extendDown', ['shift+j', 'shift+arrowdown'], 'collection',
+    'Extend selection down', 'Étendre la sélection vers le bas', { repeat: true }),
+  'list.extendUp': entry('list.extendUp', ['shift+k', 'shift+arrowup'], 'collection',
+    'Extend selection up', 'Étendre la sélection vers le haut', { repeat: true }),
+  'list.open': entry('list.open', ['enter', 'o'], 'collection', 'Open', 'Ouvrir'),
+  'list.toggleSelect': entry('list.toggleSelect', ['x'], 'collection', 'Select', 'Sélectionner'),
+  'list.selectAll': entry('list.selectAll', ['mod+a'], 'collection', 'Select all', 'Tout sélectionner'),
+  // A calendar or a timeline (collection scope): [ and ] step its period only while focus is inside the view, so
+  // elsewhere on the page they stay the Tabs' view keys; T works while the view shows.
+  'period.prev': entry('period.prev', ['['], 'collection', 'Previous period', 'Période précédente'),
+  'period.next': entry('period.next', [']'], 'collection', 'Next period', 'Période suivante'),
+  'period.today': entry('period.today', ['t'], 'collection', 'Today', 'Aujourd’hui'),
+  // Route scope.
+  undo: entry('undo', ['z', 'mod+z'], 'route', 'Undo', 'Annuler'),
+  // Tabs: switch the whole content to the previous or next view.
+  'view.prev': entry('view.prev', ['['], 'route', 'Previous view', 'Vue précédente'),
+  'view.next': entry('view.next', [']'], 'route', 'Next view', 'Vue suivante'),
+  // Host (app scope).
+  'host.help': entry('host.help', ['?'], 'app', 'Show keyboard shortcuts', 'Afficher les raccourcis clavier',
+    { host: true }),
+  'host.escape': entry('host.escape', ['escape'], 'app', 'Close, then go back', 'Fermer, puis revenir',
+    { host: true }),
+  'host.search': entry('host.search', ['/'], 'app', 'Search', 'Rechercher', { host: true }),
+  'host.newChat': entry('host.newChat', ['c'], 'app', 'New conversation', 'Nouvelle conversation', { host: true }),
+  'host.call': entry('host.call', ['shift+c'], 'app', 'Open voice call', 'Ouvrir l’appel vocal', { host: true }),
+  'host.toggleSidebar': entry('host.toggleSidebar', ['mod+s'], 'app', 'Toggle sidebar',
+    'Afficher ou masquer la barre latérale', { host: true }),
+  'host.voiceMessage': entry('host.voiceMessage', ['mod+d'], 'app', 'Voice message', 'Message vocal', { host: true }),
+  'host.modelMenu': entry('host.modelMenu', ['alt+p'], 'app', 'Model menu', 'Menu du modèle', { host: true }),
+  'host.speedMenu': entry('host.speedMenu', ['alt+s'], 'app', 'Speed menu', 'Menu de vitesse', { host: true }),
+  'host.toggleVoiceCall': entry('host.toggleVoiceCall', ['shift+tab'], 'app', 'Toggle voice call in panel',
+    'Afficher ou masquer l’appel vocal dans le panneau', { host: true }),
+  'host.commandMenu': entry('host.commandMenu', ['mod+k'], 'app', 'Command menu', 'Menu des commandes',
+    { host: true }),
+  'host.goInbox': entry('host.goInbox', ['g i'], 'app', 'Go to Inbox', 'Aller à l’Inbox',
+    { host: true, managerOnly: true }),
+  'host.goStarred': entry('host.goStarred', ['g s'], 'app', 'Go to Starred', 'Aller aux Favoris',
+    { host: true, managerOnly: true }),
+  'host.goDone': entry('host.goDone', ['g d'], 'app', 'Go to Done', 'Aller à Terminé',
+    { host: true, managerOnly: true }),
+}) satisfies Readonly<Record<string, KeymapEntry>>;
+
+export type KeymapId = keyof typeof DEFAULT_KEYMAP;

package/dist/sdk/src/words/keys.ts

@@ -0,0 +1,297 @@
+/**
+ * Key specs: parsing, canonical forms and matching against a plain keyboard event.
+ * Pure: `matchKey` takes `{ key, code, metaKey, ctrlKey, altKey, shiftKey }`, not a DOM event.
+ *
+ * Rules (toolkit spec 2.1):
+ * - Letters and symbols match on `event.key`, so they follow the keyboard layout (`#` and `?` work on AZERTY).
+ * - Any chord with Alt matches on `event.code`, because Option on a Mac changes `event.key` (Option+P gives "π").
+ * - `mod` is Cmd on a Mac and Ctrl elsewhere.
+ */
+
+import type { KeySpec, Platform } from './types';
+
+export interface Chord {
+  /** Normalized key: a lowercase letter, a digit, a symbol, or a named key ('escape', 'arrowdown', ...). */
+  key: string;
+  mod: boolean;
+  ctrl: boolean;
+  alt: boolean;
+  shift: boolean;
+}
+
+/** One alternative: a single chord, or a sequence of chords ('g i'). */
+export type ChordSequence = Chord[];
+
+/** The fields of a KeyboardEvent the matcher reads. */
+export interface KeyEventLike {
+  key: string;
+  code?: string;
+  metaKey?: boolean;
+  ctrlKey?: boolean;
+  altKey?: boolean;
+  shiftKey?: boolean;
+}
+
+const KEY_ALIASES: Readonly<Record<string, string>> = {
+  esc: 'escape',
+  return: 'enter',
+  up: 'arrowup',
+  down: 'arrowdown',
+  left: 'arrowleft',
+  right: 'arrowright',
+  del: 'delete',
+  spacebar: 'space',
+  ' ': 'space',
+  plus: '+',
+  pgup: 'pageup',
+  pgdn: 'pagedown',
+};
+
+const MOD_ALIASES: Readonly<Record<string, keyof Omit<Chord, 'key'>>> = {
+  mod: 'mod',
+  cmd: 'mod',
+  command: 'mod',
+  meta: 'mod',
+  ctrl: 'ctrl',
+  control: 'ctrl',
+  alt: 'alt',
+  option: 'alt',
+  opt: 'alt',
+  shift: 'shift',
+};
+
+export const NAMED_KEYS: ReadonlySet<string> = new Set([
+  'escape', 'enter', 'tab', 'space', 'backspace', 'delete', 'insert',
+  'arrowup', 'arrowdown', 'arrowleft', 'arrowright',
+  'home', 'end', 'pageup', 'pagedown',
+  'f1', 'f2', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9', 'f10', 'f11', 'f12',
+]);
+
+/** US physical key of each symbol, for Alt chords (matched on `event.code`). */
+const SYMBOL_CODES: Readonly<Record<string, { code: string; shift: boolean }>> = {
+  '/': { code: 'Slash', shift: false }, '?': { code: 'Slash', shift: true },
+  '[': { code: 'BracketLeft', shift: false }, '{': { code: 'BracketLeft', shift: true },
+  ']': { code: 'BracketRight', shift: false }, '}': { code: 'BracketRight', shift: true },
+  ',': { code: 'Comma', shift: false }, '<': { code: 'Comma', shift: true },
+  '.': { code: 'Period', shift: false }, '>': { code: 'Period', shift: true },
+  ';': { code: 'Semicolon', shift: false }, ':': { code: 'Semicolon', shift: true },
+  "'": { code: 'Quote', shift: false }, '"': { code: 'Quote', shift: true },
+  '`': { code: 'Backquote', shift: false }, '~': { code: 'Backquote', shift: true },
+  '-': { code: 'Minus', shift: false }, '_': { code: 'Minus', shift: true },
+  '=': { code: 'Equal', shift: false }, '+': { code: 'Equal', shift: true },
+  '\\': { code: 'Backslash', shift: false }, '|': { code: 'Backslash', shift: true },
+  '!': { code: 'Digit1', shift: true }, '@': { code: 'Digit2', shift: true },
+  '#': { code: 'Digit3', shift: true }, '$': { code: 'Digit4', shift: true },
+  '%': { code: 'Digit5', shift: true }, '^': { code: 'Digit6', shift: true },
+  '&': { code: 'Digit7', shift: true }, '*': { code: 'Digit8', shift: true },
+  '(': { code: 'Digit9', shift: true }, ')': { code: 'Digit0', shift: true },
+};
+
+const NAMED_CODES: Readonly<Record<string, readonly string[]>> = {
+  escape: ['Escape'], enter: ['Enter', 'NumpadEnter'], tab: ['Tab'], space: ['Space'],
+  backspace: ['Backspace'], delete: ['Delete'], insert: ['Insert'],
+  arrowup: ['ArrowUp'], arrowdown: ['ArrowDown'], arrowleft: ['ArrowLeft'], arrowright: ['ArrowRight'],
+  home: ['Home'], end: ['End'], pageup: ['PageUp'], pagedown: ['PageDown'],
+};
+
+export function isLetterKey(key: string): boolean {
+  return /^[a-z]$/.test(key);
+}
+
+export function isDigitKey(key: string): boolean {
+  return /^[0-9]$/.test(key);
+}
+
+/** A printable key that is neither a letter nor a digit ('#', '?', '[', ...). */
+export function isSymbolKey(key: string): boolean {
+  return key.length === 1 && !isLetterKey(key) && !isDigitKey(key);
+}
+
+function normalizeKeyName(raw: string): string {
+  if (raw.length === 1) {
+    const lower = raw.toLowerCase();
+    return KEY_ALIASES[raw] ?? lower;
+  }
+  const lower = raw.toLowerCase();
+  return KEY_ALIASES[lower] ?? lower;
+}
+
+export class KeySpecError extends Error {
+  constructor(spec: string, reason: string) {
+    super(`Invalid key spec "${spec}": ${reason}`);
+    this.name = 'KeySpecError';
+  }
+}
+
+function parseChord(step: string, spec: string): Chord {
+  const chord: Chord = { key: '', mod: false, ctrl: false, alt: false, shift: false };
+  let parts: string[];
+  if (step === '+') parts = ['+'];
+  else if (step.endsWith('++')) parts = [...step.slice(0, -2).split('+'), '+'];
+  else parts = step.split('+');
+  const rawKey = parts.pop() ?? '';
+  if (!rawKey) throw new KeySpecError(spec, 'missing key');
+  for (const part of parts) {
+    const modifier = MOD_ALIASES[part.toLowerCase()];
+    if (!modifier) throw new KeySpecError(spec, `unknown modifier "${part}"`);
+    chord[modifier] = true;
+  }
+  const key = normalizeKeyName(rawKey);
+  if (key.length !== 1 && !NAMED_KEYS.has(key)) throw new KeySpecError(spec, `unknown key "${rawKey}"`);
+  chord.key = key;
+  // A symbol already says whether Shift is down ('?' is Shift+/ on a US keyboard, a plain key elsewhere).
+  if (isSymbolKey(key) && !chord.alt) chord.shift = false;
+  return chord;
+}
+
+const parseCache = new Map<string, ChordSequence>();
+
+/** 'g i' gives two chords; 'shift+e' one. Throws KeySpecError on an unknown key or modifier. */
+export function parseKeySpec(spec: KeySpec): ChordSequence {
+  const cached = parseCache.get(spec);
+  if (cached) return cached;
+  const trimmed = spec.trim();
+  if (!trimmed) throw new KeySpecError(spec, 'empty');
+  const steps = trimmed === '+' ? ['+'] : trimmed.split(/\s+/);
+  const parsed = steps.map((step) => parseChord(step, spec));
+  parseCache.set(spec, parsed);
+  return parsed;
+}
+
+export function isValidKeySpec(spec: KeySpec): boolean {
+  try { parseKeySpec(spec); return true; } catch { return false; }
+}
+
+export function isSequenceSpec(spec: KeySpec): boolean {
+  return parseKeySpec(spec).length > 1;
+}
+
+/** Alternatives as a list. */
+export function keyList(keys: KeySpec | readonly KeySpec[] | null | undefined): KeySpec[] {
+  if (keys == null) return [];
+  return typeof keys === 'string' ? [keys] : [...keys];
+}
+
+function chordToString(chord: Chord, platform: Platform): string {
+  const mod = chord.mod || (platform === 'other' && chord.ctrl);
+  const ctrl = platform === 'mac' && chord.ctrl;
+  const parts: string[] = [];
+  if (mod) parts.push('mod');
+  if (ctrl) parts.push('ctrl');
+  if (chord.alt) parts.push('alt');
+  if (chord.shift) parts.push('shift');
+  parts.push(chord.key);
+  return parts.join('+');
+}
+
+/** One normalized string per spec, for comparing keys ('Shift+E' and 'shift+e' are the same). */
+export function canonicalKey(spec: KeySpec, platform: Platform = 'mac'): string {
+  return parseKeySpec(spec).map((chord) => chordToString(chord, platform)).join(' ');
+}
+
+/** Codes a chord's key sits on, for Alt chords. */
+function codesFor(chord: Chord): { codes: string[]; shift: boolean | null } {
+  const { key } = chord;
+  if (isLetterKey(key)) return { codes: [`Key${key.toUpperCase()}`], shift: null };
+  if (isDigitKey(key)) return { codes: [`Digit${key}`, `Numpad${key}`], shift: null };
+  const named = NAMED_CODES[key];
+  if (named) return { codes: [...named], shift: null };
+  const symbol = SYMBOL_CODES[key];
+  if (symbol) return { codes: [symbol.code], shift: symbol.shift };
+  return { codes: [], shift: null };
+}
+
+function normalizedEventKey(key: string): string {
+  if (key === ' ' || key === 'Spacebar') return 'space';
+  if (key === 'Esc') return 'escape';
+  if (key === 'Up' || key === 'Down' || key === 'Left' || key === 'Right') return `arrow${key.toLowerCase()}`;
+  if (key === 'Del') return 'delete';
+  return key.length === 1 ? key.toLowerCase() : key.toLowerCase();
+}
+
+/** Does this event press this chord? */
+export function matchChord(event: KeyEventLike, chord: Chord, platform: Platform): boolean {
+  const meta = !!event.metaKey;
+  const ctrl = !!event.ctrlKey;
+  const alt = !!event.altKey;
+  const shift = !!event.shiftKey;
+  const wantMeta = platform === 'mac' ? chord.mod : false;
+  const wantCtrl = platform === 'mac' ? chord.ctrl : chord.mod || chord.ctrl;
+
+  if (chord.alt) {
+    // Physical key: Option changes event.key on a Mac.
+    if (!alt || meta !== wantMeta || ctrl !== wantCtrl) return false;
+    const { codes, shift: symbolShift } = codesFor(chord);
+    if (!event.code || !codes.includes(event.code)) return false;
+    const wantShift = symbolShift ?? chord.shift;
+    return shift === wantShift;
+  }
+
+  const key = normalizedEventKey(event.key ?? '');
+
+  if (isSymbolKey(chord.key)) {
+    if (key !== chord.key) return false;
+    // Layouts put symbols behind Shift, Option (Mac) or AltGr (Ctrl+Alt elsewhere): those do not count.
+    if (meta !== wantMeta) return false;
+    if (platform === 'other') {
+      if (wantCtrl) return ctrl;
+      return !ctrl || alt;
+    }
+    return ctrl === wantCtrl;
+  }
+
+  if (alt || meta !== wantMeta || ctrl !== wantCtrl) return false;
+
+  if (isLetterKey(chord.key)) {
+    if (shift !== chord.shift) return false;
+    if (key === chord.key) return true;
+    // Non-Latin layouts (Cyrillic, Greek...): the letter is not on event.key, so fall back to the physical key.
+    // Only for letters outside a-z: a Latin layout that moves keys (AZERTY's comma on KeyM) keeps event.key.
+    const foreignLetter = key.length === 1 && /\p{L}/u.test(key) && !/^[a-z]$/.test(key);
+    return foreignLetter && event.code === `Key${chord.key.toUpperCase()}`;
+  }
+
+  if (isDigitKey(chord.key)) {
+    // Shift may be needed to type a digit (AZERTY), so it does not count.
+    return key === chord.key;
+  }
+
+  return key === chord.key && shift === chord.shift;
+}
+
+/** Does this event press this single-chord spec (or the first step of a sequence when `firstStep`)? */
+export function matchKey(event: KeyEventLike, spec: KeySpec, platform: Platform, firstStep = false): boolean {
+  let chords: ChordSequence;
+  try { chords = parseKeySpec(spec); } catch { return false; }
+  if (chords.length > 1 && !firstStep) return false;
+  return matchChord(event, chords[0]!, platform);
+}
+
+/** Pure modifier keys never start or finish a chord. */
+export function isModifierOnlyKey(key: string): boolean {
+  return key === 'Shift' || key === 'Control' || key === 'Alt' || key === 'Meta' || key === 'AltGraph'
+    || key === 'CapsLock' || key === 'OS' || key === 'Fn' || key === 'Hyper' || key === 'Super';
+}
+
+/**
+ * Keys the Notis host owns. A Space may not bind them (toolkit spec 2.1, clash rule 1).
+ * '?' help sheet, '/' search, 'c' new chat, 'shift+c' call, the rest host chrome.
+ */
+export const HOST_RESERVED_KEYS: readonly KeySpec[] = Object.freeze([
+  '/', 'c', 'shift+c', 'shift+tab', 'mod+s', 'mod+d', 'alt+p', 'alt+s', '?', 'escape', 'mod+k',
+]);
+
+const reservedCanonical = {
+  mac: new Set(HOST_RESERVED_KEYS.map((spec) => canonicalKey(spec, 'mac'))),
+  other: new Set(HOST_RESERVED_KEYS.map((spec) => canonicalKey(spec, 'other'))),
+};
+
+/** True when the spec is host-reserved on either platform, or starts with a reserved key ('escape x'). */
+export function isHostReserved(spec: KeySpec): boolean {
+  for (const platform of ['mac', 'other'] as const) {
+    const canonical = canonicalKey(spec, platform);
+    const first = canonical.split(' ')[0]!;
+    if (reservedCanonical[platform].has(canonical) || reservedCanonical[platform].has(first)) return true;
+  }
+  return false;
+}

package/dist/sdk/src/words/shell.ts

@@ -0,0 +1,46 @@
+/** Shell words shared by every toolkit piece (toolkit spec 2.7). French uses tu and a narrow no-break space before ":". */
+
+import { fillWords, type Words } from './types';
+
+export const SHELL_WORDS = Object.freeze({
+  open: { en: 'Open', fr: 'Ouvrir' },
+  back: { en: 'Back', fr: 'Retour' },
+  close: { en: 'Close', fr: 'Fermer' },
+  previous: { en: 'Previous', fr: 'Précédent' },
+  next: { en: 'Next', fr: 'Suivant' },
+  more: { en: 'More', fr: 'Plus' },
+  clear: { en: 'Clear', fr: 'Effacer' },
+  removeNamed: { en: 'Remove {name}', fr: 'Retirer {name}' },
+  savingNamed: { en: 'Saving {name}', fr: 'Enregistrement de {name}' },
+  clearSelection: { en: 'Clear selection', fr: 'Effacer la sélection' },
+  undo: { en: 'Undo', fr: 'Annuler' },
+  select: { en: 'Select', fr: 'Sélectionner' },
+  selectAll: { en: 'Select all', fr: 'Tout sélectionner' },
+  extendSelection: { en: 'Extend selection', fr: 'Étendre la sélection' },
+  closeThenClear: { en: 'Close, then clear selection', fr: 'Fermer, puis effacer la sélection' },
+  showShortcuts: { en: 'Show shortcuts', fr: 'Afficher les raccourcis' },
+  search: { en: 'Search', fr: 'Rechercher' },
+  tryAgain: { en: 'Try again', fr: 'Réessayer' },
+  selectedOne: { en: '1 selected', fr: '1 sélectionné' },
+  selectedMany: { en: '{n} selected', fr: '{n} sélectionnés' },
+  sidePeek: { en: 'Side peek', fr: 'Aperçu latéral' },
+  centerPeek: { en: 'Center peek', fr: 'Aperçu centré' },
+  fullPage: { en: 'Full page', fr: 'Pleine page' },
+  openAs: { en: 'Open as', fr: 'Ouvrir en' },
+}) satisfies Readonly<Record<string, Words>>;
+
+export type ShellWordId = keyof typeof SHELL_WORDS;
+
+/** "1 selected" / "{n} selected", count filled in. */
+export function selectedCount(n: number): Words {
+  return n === 1 ? SHELL_WORDS.selectedOne : fillWords(SHELL_WORDS.selectedMany, { n });
+}
+
+/** Words of the keyboard help sheet and the engine (toolkit spec 2.1). */
+export const HELP_WORDS = Object.freeze({
+  title: { en: 'Keyboard shortcuts', fr: 'Raccourcis clavier' },
+  groupSpace: { en: 'This Space', fr: 'Ce Space' },
+  groupNotis: { en: 'Notis', fr: 'Notis' },
+  close: { en: 'Close', fr: 'Fermer' },
+  empty: { en: 'No shortcuts here.', fr: 'Aucun raccourci ici.' },
+}) satisfies Readonly<Record<string, Words>>;

package/dist/sdk/src/words/types.ts

@@ -0,0 +1,65 @@
+/** Shared vocabulary of the toolkit. Pure: no React, no DOM. */
+
+export type Locale = 'en' | 'fr';
+export type Platform = 'mac' | 'other';
+
+/** Every user-facing string the toolkit shows, in both languages. */
+export type Words = { en: string; fr: string };
+
+/** 'j', 'shift+j', 'mod+a', 'g i' (one key, then another), '#', '?'. */
+export type KeySpec = string;
+
+/** Keyboard scopes, lowest to highest. A higher scope is asked first. */
+export type Scope = 'app' | 'route' | 'collection' | 'detail' | 'modal';
+
+export const SCOPE_ORDER: Readonly<Record<Scope, number>> = Object.freeze({
+  app: 0,
+  route: 100,
+  collection: 200,
+  detail: 300,
+  modal: 400,
+});
+
+export const SCOPES: readonly Scope[] = Object.freeze(['app', 'route', 'collection', 'detail', 'modal'] as Scope[]);
+
+export function isScope(value: unknown): value is Scope {
+  return typeof value === 'string' && Object.prototype.hasOwnProperty.call(SCOPE_ORDER, value);
+}
+
+export function isWords(value: unknown): value is Words {
+  return !!value && typeof value === 'object'
+    && typeof (value as Words).en === 'string' && typeof (value as Words).fr === 'string';
+}
+
+/** The string for a locale. A plain string is returned as is (Space code may pass its own words). */
+export function pick(words: Words | string, locale: Locale): string {
+  if (typeof words === 'string') return words;
+  return locale === 'fr' ? words.fr : words.en;
+}
+
+/** Replaces `{name}` placeholders. Unknown names stay as written. */
+export function interpolate(template: string, vars: Readonly<Record<string, string | number>>): string {
+  return template.replace(/\{(\w+)\}/g, (whole, name: string) =>
+    Object.prototype.hasOwnProperty.call(vars, name) ? String(vars[name]) : whole);
+}
+
+/** Fills the same placeholders in both languages. */
+export function fillWords(words: Words, vars: Readonly<Record<string, string | number>>): Words {
+  return { en: interpolate(words.en, vars), fr: interpolate(words.fr, vars) };
+}
+
+/** Shorthand for a Words pair. */
+export function w(en: string, fr: string): Words {
+  return { en, fr };
+}
+
+/** Narrow no-break space, used in French before `:` `?` `!` `;`. */
+export const NNBSP = ' ';
+
+/**
+ * "Label: value" (an accessible name such as "Status: Done"). French puts the narrow no-break space before the
+ * colon: "Statut : Terminé".
+ */
+export function labelValue(label: string, value: string, locale: Locale): string {
+  return locale === 'fr' ? `${label}${NNBSP}: ${value}` : `${label}: ${value}`;
+}