PSA/ee/docs/plans/2026-05-18-keyboard-shortcuts-shared-system/SCRATCHPAD.md

Scratchpad — Shared Keyboard Shortcuts System

• Plan slug: 2026-05-18-keyboard-shortcuts-shared-system
• Created: 2026-05-18
• Source design doc: .ai/keyboard-shortcuts-shared-system-plan.md

What This Is

Working memory for the shared keyboard shortcuts effort. Append discoveries and decisions; update earlier notes when a decision changes.

Decisions

• (2026-05-18) Scope = all 6 phases incl. chord/sequence engine and visible kbd hints + aria-keyshortcuts. (User answer.)
• (2026-05-18) i18n = English + all 8 production languages (en, fr, es, de, nl, it, pl, pt) translated in this plan, + pseudo xx/yy regenerated, + validate-translations.cjs must pass. (User answer.)
• (2026-05-18) mod+k = stays global search; asset command palette rescoped to page-scoped assets.commandPalette with a non-mod+k default. (User answer; settles the source-doc open question, hard prereq for P2.)
• (2026-05-18) Matcher = dual matching: code-kind tokens → event.code + exact modifier set; char-kind tokens (e.g. ?) → event.key produced char. Rationale: fixes macOS Option-as-dead-key (event.key becomes Dead/˜) and international layouts (Cyrillic/German mod+s).
• (2026-05-18) Persist deltas only in platform-neutral syntax; resolve mod/platform per device at runtime; drop a user value that equals the current platform default. Never persist resolved (cmd+/ctrl+) bindings.
• (2026-05-18) Respect event.defaultPrevented (reversed from original source draft) so the global system does not double-fire against ~40 component-local arrow/Enter handlers.
• (2026-05-18) Engine lives in packages/ui/src/keyboard-shortcuts/*, kept dependency-light; preference wiring lives in the MSP wrapper via useUserPreference (@alga-psa/user-composition/hooks).
• (2026-05-19) Dependency-boundary guard (group architecture-guard, F005-F007/T012-T014, placed right after scaffold so it lands before persistence). Engine persists ONLY via a ShortcutStorage interface (F005) + default in-memory adapter (F006); provider takes an injected storage (F043); the useUserPreference adapter lives in server and is injected (F140 reworded). Rationale: importing useUserPreference into packages/ui creates ui → user-composition → ui, a NEW cycle that fails .github/workflows/circular-deps.yml (not in known-cycles.json). Guard (F007) + T012 (no forbidden imports) + T013 (nx graph no new cycle) enforce it. Repo also has eslint-plugin-custom-rules/ no-feature-to-feature-imports (CI error).
• (2026-05-18) i18n namespace = new msp/keyboard-shortcuts (action labels, groups, help, settings-panel chrome). Settings tab label goes in existing msp/settings. Action labelKey/groupKey are i18n keys from Phase 1 (no raw strings, no Phase-6 retrofit).
• (2026-05-18) Settings UI = new tab in SettingsPage.tsx baseTabContent, component KeyboardShortcutsSettings.tsx, preference-backed (immediate debounced save, no explicit Save button), shared components only.
• (2026-05-18) Commit policy = one commit per commitGroup (not per item). Every feature/test carries a commitGroup; 15 groups: scaffold, parser, matcher, registry, sequence, radix-escape, action-catalog, global-migration, panels-drawers, editors, persistence, settings-ui, help-a11y, i18n, regression → ≈15 commits. Commit a group only when all its items are implemented:true. Message form: <type>(<group>): summary [ids].
• (2026-05-19) Added 3 net-new groups from manual-test feedback: page-actions (page-scoped page.create/page.save registered per page; default create = c, NOT mod+n — Ctrl/⌘+N is a browser new-window accelerator not reliably interceptable, esp. Chrome/Windows; mod+n is an opt-in alternate with a caveat), dialog-a11y (every page's create dialog keyboard-only: focus-on-open, trap, mod+Enter submit, Escape, SR roles), command-palette (Spotlight on mod+k — resolves the old open decision; record search now lives inside the palette; asset palette stays mod+shift+k). Palette grammar = TeamCity-derived (see PRD Appendix: field:value + aliases, quoted phrases, -/NOT, */?, prefix+OR default, AND in-field, $magic, sigils > # @ /). Parser is a pure module under the same FR30 boundary guard. F300-F353 / T300-T349.
• (2026-05-19) Code review caught a severe wiring gap: customization is cosmetic. Provider accepts storage?/disabledActionIds? but MspLayoutClient passes neither (falls back to in-memory). Dispatch (collectSingleChord/Sequence) resolves from normalizeDefaultBindings, never resolveActionBindings; display.tsx uses getDefaultBindingsForPlatform only. So a rebind persists + shows in the settings Effective column but does nothing; old default still fires; disabled list never reaches dispatch; hints/aria stay on defaults. Root cause: no integration test. Every piece had a green unit/contract test in isolation; the architecture-guard checked the import boundary but nothing checked the functional wiring → F043/F140/F142/F146/F185/F186 were flipped true on unit-green. Corrective: reopened those 6 (commitGroup→customization-wiring), added F360-F366 (inject storage at mount; provider = single source; dispatch via resolveActionBindings; merge disabled; context resolver; settings consumes context) + T360-T364 including T360, the end-to-end test that would have caught it. FR34 added: unit-green is NOT sufficient to mark FR19/20/23/26 done.
• Process lesson: any "engine + adapter + UI" feature needs one integration test across the seam before its features can be marked done; isolated unit tests passing is a false signal.

Discoveries / Constraints

• (2026-05-19) GAP found in manual test: catalog.ts defined navigation.goTickets/goAssets/goClients (sequence g t/a/c) but no component registered handlers → g t was a silent no-op. Source plan had nav as "illustrative"; sequence group built the engine only. Fixed: registered the 3 nav actions in DefaultLayout.tsx with router.push (navigation commitGroup, F095 impl, T095 e2e pending).
• (2026-05-18) ~50 files use keydown/onKeyDown; only window/document-level handlers are in scope. Component-local widget handlers (DatePicker, SearchableSelect, TagInput, comboboxes, Radix internals) stay as-is.
• (2026-05-18) Two DrawerContexts: server/src/context/DrawerContext.tsx AND packages/ui/src/context/DrawerContext.tsx — migrate together or they fight.
• (2026-05-18) Alt+ArrowLeft/Right (TicketNavigation, DrawerContext) = browser Back/Forward on Windows/Linux → change record nav default to [/].
• (2026-05-18) DefaultLayout.tsx:215/229 mod+l/mod+ArrowUp gated on aiAssistantAvailable (early-return before preventDefault) — preserve via the registry enabled flag.
• (2026-05-18) AssetDashboardClient.tsx:285 window mod+k listener = the conflict source; remove on rescope.
• (2026-05-18) Radix Dialog/Drawer Escape is managed via onEscapeKeyDown + stopPropagation and ModalityContext/InsideDialogContext nesting fix (see global memory). Escape actions must integrate, not add a competing window listener.
• (2026-05-18) Settings shell: server/src/components/settings/SettingsPage.tsx → CustomTabs + UnsavedChangesProvider; tabs are a hard-coded baseTabContent array ({id,label,icon,content}); add a tab there.
• (2026-05-18) Settings panel analogs: server/src/components/settings/general/ExperimentalFeaturesSettings.tsx (toggle list), GeneralSettings.tsx (Table of items with controls).
• (2026-05-18) Shared component import paths: @alga-psa/ui/components/{Card,Table,Button,Switch,Dialog,ConfirmationDialog,LoadingIndicator,Alert,Input,Label,CustomSelect}; feedback via react-hot-toast + @alga-psa/ui/lib/errorHandling#handleError. Button variants: default|destructive|outline|ghost|soft; every interactive element needs an id.
• (2026-05-18) i18n: i18next + react-i18next. Client hook useTranslation('namespace') from @alga-psa/ui/lib/i18n/client; server getServerTranslation/getServerLocale from @alga-psa/ui/lib/i18n/serverOnly. Locale files server/public/locales/{lang}/{namespace}.json (nested JSON, dot keys). Languages: en, fr, es, de, nl, it, pl, pt (+ xx, yy pseudo).
• (2026-05-18) i18n workflow: add EN keys → mirror to 7 langs → regenerate pseudo (node scripts/generate-pseudo-locales.cjs) → validate (node scripts/validate-translations.cjs) → register namespace in ROUTE_NAMESPACES (packages/core/src/lib/i18n/config.ts).
• (2026-05-18) useUserPreference already does default→localStorage→server, 500ms debounce, hydration-mismatch avoidance, skipServerFetch/ isUserLoggedIn unauth path — it is THE persistence impl, not re-invented.
• (2026-05-18) Plan-folder convention: docs/plans/YYYY-MM-DD-<slug>/ with PRD.md/features.json/tests.json/SCRATCHPAD.md (matches docs/plans/2026-05-13-threaded-comments/).

Commands / Runbooks

• Pseudo-locales: node scripts/generate-pseudo-locales.cjs
• Validate translations: node scripts/validate-translations.cjs
• Pseudo QA: switch locale to xx (expect 11111…) or yy (55555…) to confirm all strings are extracted.

Links / References

• Source: .ai/keyboard-shortcuts-shared-system-plan.md
• Engine target: packages/ui/src/keyboard-shortcuts/*
• Settings shell: server/src/components/settings/SettingsPage.tsx
• Persistence: packages/user-composition/src/hooks/useUserPreference.ts
• i18n config: packages/core/src/lib/i18n/config.ts
• Locale root: server/public/locales/
• Global memory: Radix Dialog nesting / ModalityContext escape fix.

Work Log

• (2026-05-19) Completed scaffold group F001-F004/T026. Added packages/ui/src/keyboard-shortcuts/ with a barrel, core public types (ShortcutAction, scopes, binding descriptors, parse result, persisted shortcut blob), and client-only platform detection helpers. Added package exports and a tsup entry for @alga-psa/ui/keyboard-shortcuts. Detection now returns null when window is absent so SSR/node paths do not inspect navigator; useClientPlatform resolves after mount.
• (2026-05-19) Verification for scaffold: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/platform.test.ts from packages/ui passed (3 tests).
• (2026-05-19) Completed parser group F010-F019/T001-T011. Added parser.ts with typed-result parseBinding and parseSequence. Supported physical code tokens for letters, digits, F1-F12, named navigation keys, and brackets; glyphs like ? parse as character tokens. Modifier normalization is deterministic (mod, ctrl, meta, alt, shift), and literal ctrl/meta remain distinct from neutral mod.
• (2026-05-19) Verification for parser: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/parser.test.ts from packages/ui passed (27 tests).
• (2026-05-19) Completed matcher group F020-F025/T020-T025. Added matcher.ts with platform-time mod resolution, exact modifier matching for code tokens, produced-character matching for char tokens with Shift ignored only as the glyph-producing modifier, and AltGraph protection. Tests cover mac/other mod, macOS Option dead-key behavior, international-layout physical-code matching, and AltGr false-positive prevention.
• (2026-05-19) Verification for matcher: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/matcher.test.ts from packages/ui passed (6 tests).
• (2026-05-19) Completed registry group F030-F042/T030-T044/T234. Added ShortcutRegistry, normalizeDefaultBindings, and a client KeyboardShortcutsProvider with one capture-phase document listener. Hooks now register actions, scopes, and active regions without adding listeners. Dispatch skips defaultPrevented, honors enabled/disabled gates, suppresses editable targets unless opted in, filters by active scopes, uses priority then most-local active scope, and reports residual ties through onConflict.
• (2026-05-19) Route-change clearing is represented in the UI package by a provider routeKey prop so MSP can pass pathname later without coupling the package to Next routing. Active-region gating covers selection.* and unmodified single-letter page actions.
• (2026-05-19) Verification for registry: npx vitest run --config vitest.config.ts src/keyboard-shortcuts from packages/ui passed (57 tests). npx tsc --noEmit -p packages/ui/tsconfig.json passed.
• (2026-05-19) PRD/checklist was updated outside my prior commits with new FR30 dependency-boundary requirements and a late F043 storage-adapter item. Moved that late item from the already-committed registry group to a new architecture-boundary group to preserve the one-commit-per-group rule, and added F044/T045-T047 to cover the boundary guard and CI path.
• (2026-05-19) Completed architecture-boundary group F043-F044/T045-T047. Added ShortcutStorage, default in-memory storage, provider injection via storage prop/context, and useShortcutStorage. Added scripts/guard-keyboard-shortcuts-boundary.mjs plus a package script and circular-deps workflow step. The guard blocks imports from @alga-psa/user-composition and feature packages in packages/ui/src/keyboard-shortcuts, and delegates graph checks to scripts/check-circular-deps.mjs --baseline .github/known-cycles.json when --graph is supplied.
• (2026-05-19) Verification for architecture-boundary: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/storage.test.tsx from packages/ui passed (2 tests); node --test scripts/tests/guard-keyboard-shortcuts-boundary.test.mjs passed (2 tests); npm run guard:keyboard-shortcuts-boundary passed; npx tsc --noEmit -p packages/ui/tsconfig.json passed.
• (2026-05-19) Completed sequence group F050-F054/T050-T054. The provider now evaluates sequence actions through the same delegated listener, with a configurable sequenceTimeoutMs (default 1000ms). Sequence buffers reset on timeout, non-match, scope push/pop, route change, and editable targets. Prefixes do not block single-chord actions; a full sequence prevents default only when its handler reports handled.
• (2026-05-19) Verification for sequence: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/sequence.test.tsx src/keyboard-shortcuts/provider.test.tsx from packages/ui passed (24 tests); npx tsc --noEmit -p packages/ui/tsconfig.json passed.
• (2026-05-19) Completed radix-escape group F060-F062/T060-T062. Added a ref-counted Radix Escape owner bridge (useRadixEscapeOwner) and wired shared Dialog/Drawer to mark ownership while open. The provider skips Escape dispatch while any Radix owner exists, so document-capture shortcuts cannot race Radix onEscapeKeyDown or nested stopPropagation. When no Radix owner exists, panel.close/Escape actions still dispatch normally.
• (2026-05-19) Verification for radix-escape: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/escape.test.tsx src/keyboard-shortcuts/provider.test.tsx from packages/ui passed (22 tests); npx tsc --noEmit -p packages/ui/tsconfig.json passed.
• (2026-05-19) Completed action-catalog group F070-F071/T070-T071. Added catalog.ts with stable metadata entries for global, AI, page, selection, navigation sequence, assets, dialog/panel/drawer, record, and editor actions. Each entry carries labelKey/groupKey, scope, priority, defaults, and flags like sequence/allowInEditable; editor.redo resolves to mod+shift+z on mac and ctrl+y/ctrl+shift+z elsewhere.
• (2026-05-19) Verification for action-catalog: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/catalog.test.ts from packages/ui passed (2 tests); npx tsc --noEmit -p packages/ui/tsconfig.json passed.
• (2026-05-19) Completed global-migration group F080-F090/T080-T089/T230. Mounted KeyboardShortcutsProvider in MspLayoutClient around the MSP product shells (not auth/client portal). Migrated global.search out of SearchPalette's window listener; migrated global.toggleChat and ai.quickAsk out of DefaultLayout's window listener while preserving aiAssistantAvailable gates; registered global.openShortcuts and global.quickCreate; and rescoped the assets palette to page-scoped assets.commandPalette on mod+shift+k.
• (2026-05-19) Temporary note: global.openShortcuts currently opens a minimal placeholder dialog in DefaultLayout; the full shared help dialog remains owned by the later help-a11y group. global.quickCreate opens the ticket quick-create dialog by default.
• (2026-05-19) Verification for global-migration: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/global-migration.contract.test.ts from packages/ui passed (5 tests); npx tsc --noEmit -p packages/ui/tsconfig.json passed; npx tsc --noEmit -p packages/assets/tsconfig.json passed; npm run typecheck --workspace server passed. Attempting direct server layout Vitest files hit an existing Vitest 4/coverage-v8 3.2.4 harness error before tests executed (Cannot read properties of undefined (reading 'fetchCache')).
• (2026-05-19) Completed panels-drawers group F100-F108/T100-T107. Both server/src/context/DrawerContext.tsx and packages/ui/src/context/DrawerContext.tsx now register panel.close, drawer.historyBack, and drawer.historyForward; both push panel scope only while open. TicketNavigation now registers record.previous/next on [/] and removed its Alt+Arrow window listener. The catalog keeps Alt+ArrowLeft/Right only in OPTIONAL_ALTERNATE_BINDINGS.
• (2026-05-19) Verification for panels-drawers: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/panels-drawers.contract.test.ts src/keyboard-shortcuts/provider.test.tsx src/keyboard-shortcuts/catalog.test.ts from packages/ui passed (25 tests); npx tsc --noEmit -p packages/ui/tsconfig.json passed; npx tsc --noEmit -p packages/tickets/tsconfig.json passed; npm run typecheck --workspace server passed.
• (2026-05-19) Completed editors group F120-F124/T120-T124. Invoice designer useDesignerShortcuts.ts now pushes editor scope and registers undo, redo, delete selection, cancel, and arrow-move actions instead of a window keydown listener. TextEditor pushes editor scope and marks the BlockNote root with data-keyboard-shortcuts-editor-root="true" but does not register undo/redo, so BlockNote internal editing shortcuts remain local. Search did not find a separate workflow-designer window-level shortcut hook to migrate in this group.
• (2026-05-19) Verification for editors: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/editors.contract.test.ts src/keyboard-shortcuts/catalog.test.ts from packages/ui passed (5 tests); npx tsc --noEmit -p packages/ui/tsconfig.json passed; npx tsc --noEmit -p packages/billing/tsconfig.json passed.
• (2026-05-19) Completed persistence group F140-F147/T140-T150. Added dependency-free preference utilities under packages/ui for keyboard_shortcuts_v1, version migration, neutral delta storage, override/default resolution, drop-equals-default, disabled action ids, and hostile/reserved combo advisories. Added the MSP bridge hook server/src/hooks/useKeyboardShortcutPreferenceStorage.ts, which uses useUserPreference with localStorage and skipServerFetch support.
• (2026-05-19) Verification for persistence: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/preferences.test.ts src/keyboard-shortcuts/persistence-bridge.contract.test.ts from packages/ui passed (6 tests); npx tsc --noEmit -p packages/ui/tsconfig.json passed; npm run typecheck --workspace server passed.
• (2026-05-19) Completed settings-ui group F160-F172/T160-T174. Added KeyboardShortcutsSettings as a settings tab with shared Card/Table/Switch/ Button/LoadingIndicator/ConfirmationDialog components. The panel lists catalog actions by group, captures bindings inline, writes preference deltas immediately through useKeyboardShortcutPreferenceStorage, supports disable, reset one, reset all, and conflict confirmation, and uses toast/handleError.
• (2026-05-19) Verification for settings-ui: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/settings-ui.contract.test.ts from packages/ui passed (3 tests); npm run typecheck --workspace server passed.
• (2026-05-19) Completed help-a11y group F180-F187/T180-T187. Added shared Kbd, ShortcutHint, shortcut formatting, aria-keyshortcuts conversion, and ShortcutHelpDialog. The search input now exposes aria-keyshortcuts and a visible hint, and global.openShortcuts renders the shared help dialog instead of the temporary placeholder.
• (2026-05-19) Verification for help-a11y: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/display.test.tsx from packages/ui passed (3 tests); npx tsc --noEmit -p packages/ui/tsconfig.json passed; npm run typecheck --workspace server passed.

Open Questions

• Final assets.commandPalette default binding after rescope (confirm in P2).
• Whether any editor action needs allowInEditable exceptions beyond designer canvases (confirm in P4 against useDesignerShortcuts.ts).
• Exact set of controls to receive visible kbd hints / aria-keyshortcuts (curate during P6 — avoid hint clutter).

2026-05-19 — i18n group implementation

• F200: Implemented in commitGroup i18n. Added the keyboard-shortcuts namespace, settings tab key, route preload, pseudo-locale generation support, and localized platform/advisory/help/settings/action strings as applicable.
• F201: Implemented in commitGroup i18n. Added the keyboard-shortcuts namespace, settings tab key, route preload, pseudo-locale generation support, and localized platform/advisory/help/settings/action strings as applicable.
• F202: Implemented in commitGroup i18n. Added the keyboard-shortcuts namespace, settings tab key, route preload, pseudo-locale generation support, and localized platform/advisory/help/settings/action strings as applicable.
• F203: Implemented in commitGroup i18n. Added the keyboard-shortcuts namespace, settings tab key, route preload, pseudo-locale generation support, and localized platform/advisory/help/settings/action strings as applicable.
• F204: Implemented in commitGroup i18n. Added the keyboard-shortcuts namespace, settings tab key, route preload, pseudo-locale generation support, and localized platform/advisory/help/settings/action strings as applicable.
• F205: Implemented in commitGroup i18n. Added the keyboard-shortcuts namespace, settings tab key, route preload, pseudo-locale generation support, and localized platform/advisory/help/settings/action strings as applicable.
• F206: Implemented in commitGroup i18n. Added the keyboard-shortcuts namespace, settings tab key, route preload, pseudo-locale generation support, and localized platform/advisory/help/settings/action strings as applicable.
• F207: Implemented in commitGroup i18n. Added the keyboard-shortcuts namespace, settings tab key, route preload, pseudo-locale generation support, and localized platform/advisory/help/settings/action strings as applicable.
• F208: Implemented in commitGroup i18n. Added the keyboard-shortcuts namespace, settings tab key, route preload, pseudo-locale generation support, and localized platform/advisory/help/settings/action strings as applicable.
• F209: Implemented in commitGroup i18n. Added the keyboard-shortcuts namespace, settings tab key, route preload, pseudo-locale generation support, and localized platform/advisory/help/settings/action strings as applicable.
• F210: Implemented in commitGroup i18n. Added the keyboard-shortcuts namespace, settings tab key, route preload, pseudo-locale generation support, and localized platform/advisory/help/settings/action strings as applicable.
• F211: Implemented in commitGroup i18n. Added the keyboard-shortcuts namespace, settings tab key, route preload, pseudo-locale generation support, and localized platform/advisory/help/settings/action strings as applicable.
• F212: Implemented in commitGroup i18n. Added the keyboard-shortcuts namespace, settings tab key, route preload, pseudo-locale generation support, and localized platform/advisory/help/settings/action strings as applicable.
• F213: Implemented in commitGroup i18n. Added the keyboard-shortcuts namespace, settings tab key, route preload, pseudo-locale generation support, and localized platform/advisory/help/settings/action strings as applicable.
• F214: Implemented in commitGroup i18n. Added the keyboard-shortcuts namespace, settings tab key, route preload, pseudo-locale generation support, and localized platform/advisory/help/settings/action strings as applicable.
• F215: Implemented in commitGroup i18n. Added the keyboard-shortcuts namespace, settings tab key, route preload, pseudo-locale generation support, and localized platform/advisory/help/settings/action strings as applicable.
• F216: Implemented in commitGroup i18n. Added the keyboard-shortcuts namespace, settings tab key, route preload, pseudo-locale generation support, and localized platform/advisory/help/settings/action strings as applicable.
• T200: Verified in commitGroup i18n via the keyboard shortcuts i18n contract test plus pseudo-locale generation and validate-translations.cjs.
• T201: Verified in commitGroup i18n via the keyboard shortcuts i18n contract test plus pseudo-locale generation and validate-translations.cjs.
• T202: Verified in commitGroup i18n via the keyboard shortcuts i18n contract test plus pseudo-locale generation and validate-translations.cjs.
• T203: Verified in commitGroup i18n via the keyboard shortcuts i18n contract test plus pseudo-locale generation and validate-translations.cjs.
• T204: Verified in commitGroup i18n via the keyboard shortcuts i18n contract test plus pseudo-locale generation and validate-translations.cjs.
• T205: Verified in commitGroup i18n via the keyboard shortcuts i18n contract test plus pseudo-locale generation and validate-translations.cjs.
• T206: Verified in commitGroup i18n via the keyboard shortcuts i18n contract test plus pseudo-locale generation and validate-translations.cjs.
• T207: Verified in commitGroup i18n via the keyboard shortcuts i18n contract test plus pseudo-locale generation and validate-translations.cjs.
• T208: Verified in commitGroup i18n via the keyboard shortcuts i18n contract test plus pseudo-locale generation and validate-translations.cjs.
• T209: Verified in commitGroup i18n via the keyboard shortcuts i18n contract test plus pseudo-locale generation and validate-translations.cjs.
• Checks: node scripts/validate-translations.cjs passed with pre-existing Polish plural warnings only; npx vitest run --config vitest.config.ts src/keyboard-shortcuts/i18n.contract.test.ts src/keyboard-shortcuts/display.test.tsx passed; npx tsc --noEmit -p packages/ui/tsconfig.json passed.
• Additional check: npm run typecheck --workspace server passed for i18n wiring.

2026-05-19 — architecture-guard checklist reconciliation

• F005: Verified existing ShortcutStorage adapter/default memory storage/dependency guard implementation and marked complete under the current architecture-guard checklist ids.
• F006: Verified existing ShortcutStorage adapter/default memory storage/dependency guard implementation and marked complete under the current architecture-guard checklist ids.
• F007: Verified existing ShortcutStorage adapter/default memory storage/dependency guard implementation and marked complete under the current architecture-guard checklist ids.
• T012: Verified with guard/storage tests and Nx graph baseline check; marked complete under the current architecture-guard checklist ids.
• T013: Verified with guard/storage tests and Nx graph baseline check; marked complete under the current architecture-guard checklist ids.
• T014: Verified with guard/storage tests and Nx graph baseline check; marked complete under the current architecture-guard checklist ids.
• Checks: node --test scripts/tests/guard-keyboard-shortcuts-boundary.test.mjs, npx vitest run --config vitest.config.ts src/keyboard-shortcuts/storage.test.tsx, and npx nx graph --file=/tmp/project-graph.json && node scripts/guard-keyboard-shortcuts-boundary.mjs --graph /tmp/project-graph.json passed.

2026-05-19 — regression group implementation

• F230: Added final regression contract coverage asserting migrated legacy shortcut listeners remain removed after replacement actions are present.
• F231: Added SSR/client-only regression coverage for platform-sensitive shortcut components and navigator access ordering.
• F232: Added regression coverage proving DatePicker, SearchableSelect, AsyncSearchableSelect, TagInput, and TagInputInline keep local onKeyDown handling and do not register shared shortcut actions.
• T231: Covered by regression.contract.test.ts widget-local assertions.
• T232: Covered by regression.contract.test.ts client-only/platform assertions plus existing platform.test.ts.
• T233: Covered by regression.contract.test.ts migrated legacy-listener assertions plus phase contract tests.
• Checks: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/regression.contract.test.ts src/keyboard-shortcuts/global-migration.contract.test.ts src/keyboard-shortcuts/panels-drawers.contract.test.ts src/keyboard-shortcuts/editors.contract.test.ts src/keyboard-shortcuts/platform.test.ts passed; npx tsc --noEmit -p packages/ui/tsconfig.json passed.

2026-05-19 — Gap analysis (post-implementation review) → commitGroup gap-hardening

A full end-to-end read of the branch surfaced structural gaps. Finding #1 was already captured by the prior customization-wiring group (F360-F366 / T360-T364, FR34) — verified, not re-added. The remaining three findings are added as F367-F373 / T365-T373 under commitGroup gap-hardening (FR35/FR36/FR37). The loop should not commit this group until all of its items are implemented: true (one-commit-per-group rule).

• (FR35, F367-F369/T365-T366) Catalog is not the source of truth. catalog.ts carries scope/priority/bindings, but registration sites hand-author ShortcutAction literals. Concrete divergence: only useDesignerShortcuts sets priority: 60; DefaultLayout, both DrawerContext, SearchPalette, TicketNavigation, AssetDashboardClient omit priority so the provider uses ?? 0, contradicting catalog.ts DEFAULT_PRIORITY (panel 40 / page 20 / editor 60). The settings UI/help show catalog priorities; dispatch uses different ones. Fix = a catalog-derived factory (id + handler only) + a drift guard (unit + extend guard-keyboard-shortcuts-boundary.mjs). This is distinct from FR30 (import boundary), which the guard already enforces correctly.

• (FR36, F370-F371/T367-T368) Active-region gating is a no-op. DefaultLayout calls useShortcutActiveRegion(true) unconditionally, so activeRegionsRef is always non-empty while the MSP shell is mounted → requiresActiveRegion() never gates anything. global.quickCreate (c), selection.next (j), selection.previous (k) fire on any non-editable focus app-wide, the opposite of FR10's intent. Fix = register an active region only from genuine roving-focus list/selection containers via a shared wrapper/hook.

• (FR37, F372-F373/T369-T373) Contract tests are source greps, not behavioral. Every *.contract.test.ts (global-migration, panels-drawers, editors, persistence-bridge, settings-ui, regression, i18n) is readFileSync + .toContain('...'). They assert code exists, never that it works — which is why findings #1-#3 shipped "green". T360-T364 already add behavioral coverage for the customization path; gap-hardening converts the remaining grep suites to behavioral and adds a meta test-guard so a new grep-only contract test fails CI.

• Uncommitted working tree at review time: DefaultLayout.tsx carries the F095 nav handlers (legit, not yet committed); features.json/tests.json have incidental \uXXXX escape churn from a JSON re-serializer (the new gap-hardening items are authored in plain ASCII to avoid adding to it). These are pre-existing and out of scope for gap-hardening — flag for the branch owner, do not bundle into this group's commit.

2026-05-19 — navigation group verification

• T095: Added packages/ui/src/keyboard-shortcuts/navigation.test.tsx to exercise the catalogued navigation.goTickets/goAssets/goClients sequence actions through KeyboardShortcutsProvider. The test verifies g t, g a, and g c dispatch to their handlers and that the same sequence is suppressed while typing in an input.

2026-05-19 — customization-wiring group implementation

• F043/F140/F142/F146/F185/F186/F360-F366: Connected the preference adapter end-to-end. MspLayoutClient now injects useKeyboardShortcutPreferenceStorage into KeyboardShortcutsProvider; the provider loads the persisted blob, keeps it as reactive context state, resolves dispatch through resolveActionBindings, merges preferences.disabled, and exposes resolved bindings plus set/disable/reset mutators. ShortcutHint, useAriaKeyShortcuts, ShortcutHelpDialog, and KeyboardShortcutsSettings now read the same provider-owned source instead of separate defaults/preference hooks.
• T360-T363: Added packages/ui/src/keyboard-shortcuts/customization-wiring.test.tsx. The test covers rebind -> new combo dispatches and old default stops, Effective + ShortcutHint + aria-keyshortcuts update, disable stops dispatch and hides help, reset-one/reset-all live-update, and persisted storage loads before dispatch.
• T364/checks: npx nx graph --file=/tmp/project-graph.json && node scripts/guard-keyboard-shortcuts-boundary.mjs --graph /tmp/project-graph.json passed. Focused tests passed: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/customization-wiring.test.tsx src/keyboard-shortcuts/provider.test.tsx src/keyboard-shortcuts/storage.test.tsx src/keyboard-shortcuts/display.test.tsx src/keyboard-shortcuts/settings-ui.contract.test.ts src/keyboard-shortcuts/persistence-bridge.contract.test.ts src/keyboard-shortcuts/global-migration.contract.test.ts. Type checks passed: npx tsc --noEmit -p packages/ui/tsconfig.json and npm run typecheck --workspace server.

2026-05-19 — page-actions group implementation

• F300-F302/F310: Added page.create to the catalog with default c, kept mod+n only as an optional alternate with a browser-owned new-window caveat, and added shared usePageCreateShortcut/usePageSaveShortcut helpers in packages/ui/src/keyboard-shortcuts/page-actions.ts. Page-scoped actions are now suppressed when panel/dialog/editor scope is active, in addition to the existing editable-target suppression.
• F303-F308: Wired page create shortcuts to existing create controls: TicketingDashboard (ticket), Clients (client), Contacts (contact), InteractionsFeed (interaction), Projects (project), and AssetDashboardClient (asset).
• F309: Wired page save to primary editable Save controls found in this pass: ClientDetails (handleSave) and ticket TicketInfo (handleSaveChanges). I did not find a route-level project-detail Save equivalent; project detail appears to save scoped phase/task edits through local controls.
• F311/T304: Added actions.page.create label/description to en/fr/es/de/nl/it/pl/pt and regenerated xx/yy pseudo-locales.
• Tests/checks: Added page-actions.test.tsx for catalog/default/optional alternate behavior, create/save dispatch, editable suppression, and panel-scope suppression. Added page-actions.source.test.ts to smoke the page component wiring. Passed: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/page-actions.test.tsx src/keyboard-shortcuts/page-actions.source.test.ts src/keyboard-shortcuts/provider.test.tsx src/keyboard-shortcuts/catalog.test.ts src/keyboard-shortcuts/i18n.contract.test.ts; node scripts/validate-translations.cjs (pre-existing Polish plural warnings only); npx tsc --noEmit -p packages/ui/tsconfig.json; npx tsc --noEmit -p packages/tickets/tsconfig.json; npx tsc --noEmit -p packages/clients/tsconfig.json; npx tsc --noEmit -p packages/projects/tsconfig.json; npx tsc --noEmit -p packages/assets/tsconfig.json; and npm run typecheck --workspace server.

2026-05-19 — dialog-a11y group implementation

• F320-F324/F330: Moved the shared create-dialog keyboard contract into packages/ui/src/components/Dialog.tsx: store/restore invoker focus, focus the first focusable field on open when no custom onOpenAutoFocus is supplied, keep Radix modal focus trapping enabled, and submit the first form on Ctrl/Cmd+Enter even from textarea/editor-like fields. Escape remains routed through the existing Radix owner bridge.
• F325-F329: Removed disableFocusTrap from Create Ticket, Create Client, Create Contact, Create Project, and Create Asset dialogs. Create Interaction was already on the focus-trapped shared Dialog path.
• T320-T326: Added dialog-a11y.test.tsx for first-field focus, invoker focus restore, Escape close, and mod+Enter form submit. Added dialog-a11y.source.test.ts to smoke that all create dialogs use shared Dialog, keep forms, and no longer opt out of focus trapping.
• Checks passed: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/dialog-a11y.test.tsx src/keyboard-shortcuts/dialog-a11y.source.test.ts src/keyboard-shortcuts/escape.test.tsx; npx tsc --noEmit -p packages/ui/tsconfig.json; npx tsc --noEmit -p packages/tickets/tsconfig.json; npx tsc --noEmit -p packages/clients/tsconfig.json; npx tsc --noEmit -p packages/projects/tsconfig.json; npx tsc --noEmit -p packages/assets/tsconfig.json; and npm run typecheck --workspace server.

2026-05-19 — command-palette group implementation

• F340-F353: Implemented the command palette overlay opened by global.search (mod+k) from SearchPalette. The overlay merges navigation menu entries, catalog shortcut actions, and existing record typeahead search; supports keyboard navigation/activation, Escape close, localStorage frequency boosts, accessible combobox/listbox roles, live result counts, visible mod+k hint, and in-palette syntax help.
• F343-F347: Added pure UI-decoupled packages/ui/src/keyboard-shortcuts/command-palette-query.ts parser with field aliases, sigils, quoted phrases, exclusion, wildcards, fuzzy suffixes, OR/AND metadata, and $mine/$recent/$open aliases.
• F350/F352: Added command palette chrome/syntax/type labels across en/fr/es/de/nl/it/pl/pt, regenerated pseudo locales, and added a shortcut help-dialog link to the palette syntax affordance.
• T340-T349: Covered by parser unit tests, command palette source wiring smoke, translation validation, server/UI typecheck, and the existing keyboard shortcut dependency-boundary/graph guard.
• Checks passed: npx vitest run --config vitest.config.ts src/keyboard-shortcuts/command-palette-query.test.ts src/keyboard-shortcuts/command-palette.source.test.ts; npx tsc --noEmit -p packages/ui/tsconfig.json; npm run typecheck --workspace server; node scripts/generate-pseudo-locales.cjs; node scripts/validate-translations.cjs (pre-existing Polish plural warnings only); and npx nx graph --file=/tmp/project-graph.json && node scripts/guard-keyboard-shortcuts-boundary.mjs --graph /tmp/project-graph.json.

2026-05-19 — gap-hardening group implementation

• F367-F369: Added catalog-derived createShortcutAction and useCatalogShortcut, then migrated SearchPalette, DefaultLayout, both DrawerContexts, TicketNavigation, AssetDashboardClient, and invoice designer shortcuts away from hand-authored metadata. The boundary guard now also checks these registration sites for hand-authored shortcut metadata and unknown catalog IDs.
• F370-F371: Removed the unconditional useShortcutActiveRegion(true) from DefaultLayout. Added shared ShortcutActiveRegion, which registers an active region only while focus is within the real list region, and applied it to ticket/client/contact/interaction/project/asset list surfaces.
• F372-F373: Added behavioral gap-hardening coverage for global, panel, editor, active-region, and settings preference behavior; added a contract-test guard so grep-only contract tests must carry behavioral coverage. Existing source smoke tests were updated to assert the catalog-hook wiring rather than stale metadata literals.
• Checks passed: npx vitest run --config vitest.config.ts src/keyboard-shortcuts; node --test scripts/tests/guard-keyboard-shortcuts-contract-tests.test.mjs scripts/tests/guard-keyboard-shortcuts-boundary.test.mjs; node scripts/guard-keyboard-shortcuts-contract-tests.mjs; npx tsc --noEmit -p packages/ui/tsconfig.json; npx tsc --noEmit -p packages/tickets/tsconfig.json; npx tsc --noEmit -p packages/clients/tsconfig.json; npx tsc --noEmit -p packages/assets/tsconfig.json; npx tsc --noEmit -p packages/projects/tsconfig.json; npx tsc --noEmit -p packages/billing/tsconfig.json; npm run typecheck --workspace server; and npx nx graph --file=/tmp/project-graph.json && node scripts/guard-keyboard-shortcuts-boundary.mjs --graph /tmp/project-graph.json && node scripts/guard-keyboard-shortcuts-contract-tests.mjs.

2026-05-20 — shortcuts-ui-redesign (Profile move + visual keyboard cheatsheet)

Built directly (not via loop) because the work is high-fidelity visual + judgment-heavy and the loop has no signal for either. Source: design handoff in ~/Downloads/design_handoff_keyboard_shortcuts/ (variation-c is canonical).

• Root cause of "no nav tab" turned out NOT to be the AlgaDesk allowlist (user is on full PSA). The real cause: SettingsPage.tsx does not render the tab strip itself — the settings nav is driven by the Sidebar in settings mode (Sidebar.tsx:111, DefaultLayout.tsx:52), a separate curated menu that never got a keyboard-shortcuts entry. The content route worked, but there was nothing to click. settings-ui.contract.test.ts was a grep that only asserted the id/icon/<Component/> strings were present in SettingsPage source, never that the nav surfaced it — another FR37-class miss the gap-hardening group didn't cover (it converted engine contract tests, not the server-side settings one).
• Decision: move to Profile sub-tab (matches per-user preference convention; uses real <CustomTabs tabs={tabContent}> so the tab strip appears immediately; sidesteps any allowlist). Added entry to UserProfile.tsx tabContent, deleted KeyboardShortcutsSettings.tsx and its SettingsPage registration + Keyboard lucide import. Added 'keyboard-shortcuts' to BASE_PROFILE_TABS (calendarAvailability.ts) so /msp/profile?tab=keyboard-shortcuts deep-links.
• Engine: extended PersistedShortcuts to v2 with profile: string and a v1→v2 migration; SHORTCUT_PROFILES ships default / vim / emacs with parser-valid neutral single-chord deltas keyed by real catalog ids. Multi-chord emacs sequences (mod+x mod+s) were deliberately NOT assigned to non-sequence actions (page.save etc.) — they would parse-fail and silently never dispatch. Resolution = user override → profile delta → platform default, inside resolveActionBindings so dispatch + hints + ARIA + panel all read the same effective binding. setActionBindingsDelta now drops overrides equal to the profile baseline, so per-action reset returns to the active profile (not raw factory). Provider exposes profile + setProfile; useKeyboardShortcutPreferences includes them. Vim/Emacs deltas are best-guess pending team confirmation (open Q in handoff).
• Panel: server/src/components/keyboard-shortcuts/KeyboardShortcutsPanel.tsx recreates variation-c using product CSS vars (--color-primary-*, --color-card, --radius-md, --font-mono — globals.css already defines these) + Radix-based ConfirmationDialog/Switch/LoadingIndicator. Real keydown capture via window-level capture-phase listener with stopImmediatePropagation so the provider dispatch doesn't double-fire during rebind. Conflict UX = prompt-to-reassign (the new binding takes over, the previous owner is left unbound) per user decision. Override scope = per-account only (useUserPreference); per-device deferred. Unmappable keys (?, Escape, Delete, sequences) route to the chord rail instead of disappearing — improvement over the prototype.
• Tests: added profiles.test.ts (7 behavioral cases for the profile layer). Rewrote settings-ui.contract.test.ts to assert the new placement + panel wiring (with @behavioralCoverage linking the real behavioral suites). Updated i18n.contract.test.ts to assert profile.tabs.keyboardShortcuts in en/msp/profile.json and that SettingsPage no longer references the removed tab. Added the key to all production+pseudo locales for parity and ran generate-pseudo-locales.cjs + validate-translations.cjs (0 errors, 8 pre-existing Polish plural warnings).
• Verification: npx vitest run --config vitest.config.ts src/keyboard-shortcuts → 29 files / 137 tests pass; npx tsc --noEmit -p packages/ui/tsconfig.json clean; npm run typecheck --workspace server clean; node scripts/guard-keyboard-shortcuts-boundary.mjs OK; meta contract-test guard OK; node scripts/validate-translations.cjs PASSED.
• Follow-up (F386/T386, implemented:false): translate panel chrome strings (settings.*, profiles.*, legend.*, settings.chords.*, settings.conflict.*, settings.actions.*) into the 7 non-EN production locales; today the panel falls back via t(..., { defaultValue }) outside EN. Per-device override scope from the handoff is also deferred.
• Visual QA: not driven here. Browser/conduit QA pending with the user; the prototype's prototype/index.html is the side-by-side reference.