FE-1560: Add a command registry with a host-provided palette contract

[kube]

Summary

Before this PR, Petrinaut's user-invocable actions lived only in the keyboard handler and on toolbar buttons. Nothing enumerated them, so a host could not render a command palette over the editor, and the headless instance had no way to expose actions such as auto-layout to a host UI.

Adds a command registry the host owns. Components declare commands with a hook that registers and unregisters them, the headless instance registers its own imperatively, and the host renders the list and runs entries by id. Petrinaut ships no palette; a Storybook story and the demo website carry reference palettes.

9457.mp4

Links

• Ticket FE-1560
• Docs Command registry
• Docs Command registry usage manual
• Docs React commands
• Docs README › Commands and the palette

Changes

Core

• createCommandRegistry in @hashintel/petrinaut-core, the core.command-registry layer

  register replaces by id in place and returns a disposer that is inert once the id was re-registered.
  list returns one snapshot until the set changes, execute runs an entry by id, subscribe notifies on changes.

• combineCommandRegistries merges several registries into one read view

  For a host palette fed by its own registry plus one per embedded component. Writes stay on the sources.

React bindings

• CommandRegistryProvider, useCommand, useCommands, useCommandRegistry, and formatShortcutKeys from @hashintel/petrinaut/react, the react.commands layer

  Provider takes a host registry or creates one.
  useCommands is a useSyncExternalStore snapshot for palettes.
  formatShortcutKeys turns mod+shift+z into platform-aware keycap labels.

• useCommand registers while mounted and its when option holds

  Re-registers only when the id, label, category, keywords, or shortcut change and reads the latest run through a ref, so palettes are not notified on every render.
  No-op outside a provider.

• Wrapping the editor in the provider is the only wiring a host needs

Editor

• Editor registers a starter set from a null-rendering EditorCommands leaf

  Undo and Redo when the handle provides history, Select and Pan tools, Add place, Add transition, and auto-layout in edit mode when not read-only, search, left sidebar and bottom panel toggles.
  Leaf keeps the undo/redo context subscription off the EditorView tree.
  shortcut strings are display metadata; the keyboard handler still binds the keys.

• Redundant width-initializing effect removed from PropertiesPanel

  Its dependency is stable only under the React Compiler, so without the compiler it looped with "Maximum update depth exceeded".
  Provider already seeds the width.

Host examples

• Storybook story Commands / Command palette with a palette over host commands and over the full editor
• Demo website ⌘K palette registering a demo-owned command beside Petrinaut's

  HASH app untouched.

Review fixes

• Auto-layout registers from EditorCommands through the mode-aware usePetrinautCommands

  Nothing writes to the registry during render, and the command follows edit mode and the active subnet.

• PropertiesPanel reads its width from the editor store only

  Removes the local width state that disagreed with the persisted value after a reload.

• useCommands passes a server snapshot to useSyncExternalStore
• formatShortcutKeys returns no keycaps for an empty shortcut
• Example palettes close on Escape from any element inside them
• Sidebar toggle keeps a static label, so it holds its palette position

Known issues

• Registry does not dispatch keys

  Consume-contract shortcut work reads chords from it when it lands.

Next steps

• Bridge the zero-argument entries of instance.commands into the registry
• Rework the HASH app's command palette against this registry

Test coverage

• command-registry.test.ts:

  Register, list, execute, in-place replacement, snapshot stability and notifications, inert disposer after replacement, and combineCommandRegistries.

• command-registry.test.tsx:

  Registration lifecycle, the when flip, latest run without re-notification, no-provider no-op, and useCommands live snapshots.

• format-shortcut.test.ts:

  Apple and generic keycap labels, and the empty shortcut.

How to test

• Open Petrinaut preview on Vercel
• Press ⌘K or Ctrl+K
• Expect Petrinaut's commands and the demo's "Create a new empty net" in one list
• Type "place", Enter
• Expect the canvas tool switched to Add place
• Press ⌘K again, type "undo"
• Expect Undo and Redo listed with keycaps

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hash	Ready	Preview	Sep 3, 2026 5:02pm UTC
petrinaut	Ready	Preview	Sep 3, 2026 5:02pm UTC
petrinaut-docs	Ready	Preview	Sep 3, 2026 5:02pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Sep 3, 2026 5:02pm UTC

[cursor]

PR Summary

Low Risk
Additive public API and optional provider wiring; command runs delegate to existing editor handlers. The PropertiesPanel change fixes a render loop rather than altering editing semantics.

Overview
Introduces a command registry so hosts can render their own command palettes over Petrinaut. Core adds createCommandRegistry() and combineCommandRegistries() with stable snapshots, in-place id replacement, and safe disposers. @hashintel/petrinaut/react exposes CommandRegistryProvider, useCommand (optional when), useCommands, useCommandRegistry, and display-only formatShortcutKeys.

The editor registers undo/redo, canvas tools, auto-layout, search, and panel toggles via a null-rendering EditorCommands leaf so palette metadata stays out of the main view tree; shortcuts remain editor-bound, not registry-bound. Petrinaut does not ship a palette—Storybook and the demo site add reference ⌘K/Ctrl+K palettes that list useCommands() and call execute(id).

The demo wraps the editor in CommandRegistryProvider and registers a host command (new empty net). PropertiesPanel now uses propertiesPanelWidth from editor context directly and drops a width-sync effect that could cause maximum update depth errors without the React Compiler.

^{Reviewed by Cursor Bugbot for commit dd48015. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5b2f371. Configure here.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 61.05%. Comparing base (27b32c4) to head (dd48015).
⚠️ Report is 34 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9457      +/-   ##
==========================================
+ Coverage   61.03%   61.05%   +0.02%     
==========================================
  Files        1449     1449              
  Lines      144693   144718      +25     
  Branches     6692     6695       +3     
==========================================
+ Hits        88307    88356      +49     
+ Misses      55282    55254      -28     
- Partials     1104     1108       +4     

Flag	Coverage Δ
apps.hash-api	15.41% <ø> (+0.73%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.