@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/js-heap.ts

@@ -0,0 +1,71 @@
+/**
+ * THE JS HEAP READING — the editor's one browser-side memory signal, read by
+ * the tab census (`tab-census.ts`: the heartbeat's sample, the death line's
+ * quote) and by the Frame debugger's tile (`@volter/editor-game`). A browser
+ * property, not a scene property (M1 kept it out of the engine's
+ * render-memory on purpose), and Chromium-only: feature-detected, with the
+ * REASON returned when the global is absent — never a fabricated 0.
+ */
+export interface JsHeapReading {
+  readonly usedBytes: number;
+  readonly totalBytes: number;
+  /**
+   * `jsHeapSizeLimit` — the CEILING this renderer process may allocate to,
+   * which is the only one of the three that says how close to a heap death
+   * the tab is (`totalBytes` is merely what it has claimed so far). Null when
+   * the browser exposes the other two and not this one; the tab census reads
+   * it, and reads null as null.
+   */
+  readonly limitBytes: number | null;
+}
+
+export interface JsHeapUnavailable {
+  /** The honest reason the reading is absent (printed to the user). */
+  readonly unavailable: string;
+}
+
+/** True when the reading is present (vs. the unavailable-reason branch). */
+export function isJsHeapReading(
+  reading: JsHeapReading | JsHeapUnavailable,
+): reading is JsHeapReading {
+  return !('unavailable' in reading);
+}
+
+/**
+ * Read the JS heap via the Chromium-only `performance.memory` global — the one
+ * editor-side memory signal (M1 kept it OUT of the engine's render-memory on
+ * purpose: it is a browser property, not a scene property). Feature-detected:
+ * when the global is absent (Firefox/Safari, or a locked-down Chromium), the
+ * REASON is returned so the tile prints it, never a fabricated 0. `perf` is
+ * injectable so the test can drive both branches deterministically.
+ */
+export function readJsHeap(
+  perf: Performance | undefined = globalThis.performance,
+): JsHeapReading | JsHeapUnavailable {
+  const memory = (
+    perf as unknown as
+      | {
+          memory?: {
+            usedJSHeapSize?: number;
+            totalJSHeapSize?: number;
+            jsHeapSizeLimit?: number;
+          };
+        }
+      | undefined
+  )?.memory;
+  if (
+    !memory ||
+    typeof memory.usedJSHeapSize !== 'number' ||
+    typeof memory.totalJSHeapSize !== 'number'
+  ) {
+    return {
+      unavailable:
+        'performance.memory is unavailable — it is a non-standard Chromium-only API, not exposed by this browser.',
+    };
+  }
+  return {
+    usedBytes: memory.usedJSHeapSize,
+    totalBytes: memory.totalJSHeapSize,
+    limitBytes: typeof memory.jsHeapSizeLimit === 'number' ? memory.jsHeapSizeLimit : null,
+  };
+}

package/src/kit/key-actions.ts

@@ -0,0 +1,91 @@
+/**
+ * THE EDITOR'S KEY ACTIONS — every action a chord can reach, as DATA.
+ *
+ * THERE IS ONE KEYBOARD AND IT IS VS CODE'S (ARCHITECTURE-CORE §The core is
+ * Code-OSS rule 3). The editor installs no `keydown` dispatcher of its own;
+ * what it publishes is this table, and the frame turns each entry into a
+ * `volter.<id>` command with a `when` clause over our panes' context keys
+ * (`scripts/workbench/generate-keymaps.mjs` writes one keybinding rule per
+ * (action, chord, keymap) into a built-in extension, read from this repo's own
+ * keymap tables — so a chord is written in ONE place whichever keyboard is
+ * driving).
+ *
+ * WHY, measured: with two listeners on one page, `1,1,1,2,2,2` typed into
+ * Monaco arrived as `,,,,,`, the file saved as `BoxGeometry(,,,,,)`, and a
+ * `Control+W` meant for the workbench opened Edit Mode's Inset tool.
+ *
+ * An action's BODY is written once, in `editor-hotkeys.ts`'s `bind()` call —
+ * the same call that fills this table also fills the binding row — so a
+ * handler cannot exist for one keyboard and not the other.
+ */ import type { EditorKeyActionId } from '@volter/sdk/looks';
+
+export type KeyActionScope = 'stage' | 'panel' | 'global';
+
+export interface KeyActionEntry {
+  readonly id: EditorKeyActionId;
+  /** Run the action. The event is the host dispatcher's; the frame has none. */
+  readonly run: (event?: KeyboardEvent) => void;
+  readonly scope: KeyActionScope;
+  /**
+   * The action's own runtime gate, where it can be asked without an event —
+   * the play-state and clipboard-ownership conditions. A gate that reads the
+   * EVENT (undo/redo's editable-target test) is not lifted here: under the
+   * frame the focus condition it approximates is a `when` clause, and under
+   * the host the dispatcher still applies its own `when`.
+   */
+  readonly enabled?: () => boolean;
+}
+
+const actions = new Map<EditorKeyActionId, KeyActionEntry>();
+let actionsVersion = 0;
+const actionListeners = new Set<() => void>();
+
+function emitActions(): void {
+  actionsVersion++;
+  for (const listener of actionListeners) listener();
+}
+
+/**
+ * Record what one action DOES. Last registration wins: the shell and viewport
+ * binding sets rebuild on every keymap switch (`registerKeymapBindings`), and
+ * a rebuild re-registers the same ids with fresh closures over the same store.
+ * Returns the removal, which only fires if this entry is still the live one.
+ */
+export function registerKeyAction(entry: KeyActionEntry): () => void {
+  actions.set(entry.id, entry);
+  emitActions();
+  return () => {
+    if (actions.get(entry.id) !== entry) return;
+    actions.delete(entry.id);
+    emitActions();
+  };
+}
+
+/** Every action the editor currently has a handler for. */
+export function registeredKeyActions(): readonly KeyActionEntry[] {
+  return [...actions.values()];
+}
+
+export function keyActionsVersion(): number {
+  return actionsVersion;
+}
+
+export function subscribeKeyActions(listener: () => void): () => void {
+  actionListeners.add(listener);
+  return () => actionListeners.delete(listener);
+}
+
+/**
+ * Run one action by id — the frame's door. `false` means the editor has no
+ * handler for it right now (the viewport set is registered only while a three
+ * stage is mounted) or its own gate refused; the frame's command answers the
+ * same, so a keybinding that reaches a dead action is visible rather than
+ * silent.
+ */
+export function invokeKeyAction(id: EditorKeyActionId): boolean {
+  const entry = actions.get(id);
+  if (!entry) return false;
+  if (entry.enabled && !entry.enabled()) return false;
+  entry.run();
+  return true;
+}

package/src/kit/keymap-presets.ts

@@ -0,0 +1,428 @@
+import type { EditorKeyActionId, KeyChord, KeymapContribution, KeymapNavigation } from '@volter/sdk/looks';
+import { editorConsole } from '@volter/sdk/kit/editor-console';
+import {
+  adapterSettings,
+  projectSettings,
+  subscribeSettings,
+  updatePreferenceSettings,
+  updateProjectSettings,
+  userSettings,
+} from './settings-store';
+
+export type { EditorKeyActionId, KeyChord } from '@volter/sdk/looks';
+/**
+ * KEYMAPS — the binding table behind every editor keyboard action.
+ *
+ * The ruling (docs/ARCHITECTURE-CORE.md §Editor chrome, the "Workspaces are
+ * task-named layout memories" bullet, final sentence): *"Keymaps are
+ * orthogonal to workspaces: a `keymap` setting selects the binding table
+ * (`volter` default; `blender` — G/R/S, A, Alt+A, `.` frame) through one
+ * indirection at the action-registry/hotkey seam."*
+ *
+ * ONE INDIRECTION means exactly this: nothing in the editor spells a literal
+ * key for a keyboard action any more. `editor-hotkeys.ts` builds its
+ * `HotkeyBinding`s from {@link keyChordsFor}, and every place that PRINTS a
+ * shortcut — the command palette (via `action-registry.ts`), the viewport
+ * toolstrip tooltips, the snap transient hint —
+ * renders {@link shortcutFor} over the same table. Switch the keymap and the
+ * chrome tells the truth on the next paint, with no reload.
+ *
+ * The two axes this module is deliberately NOT: it is not a workspace (that is
+ * `workspace-presets.ts` — layout, keyed per project) and not an appearance
+ * preference (`theme-preference.ts`). A keymap is a per-user input preference,
+ * persisted the way that module persists palette/material: one settings
+ * key, lazily read, written on change, broadcast to `useSyncExternalStore`
+ * subscribers, and simply falling back to the default when unreadable —
+ * nothing a user authored is at stake in a stored preference.
+ *
+ * WHAT THIS DOES NOT GOVERN — the boundary, stated once: this table is the
+ * EDITOR's own chrome bindings, consumed by `hotkeys.ts`'s single `keydown`
+ * dispatcher on the editor's window. Play-mode input isolation is a different
+ * mechanism entirely and is untouched by a keymap switch: the engine's
+ * realm gate, `gated-globals.ts`'s lexical
+ * `window`/`document` shadow over project modules decide whether GAME code
+ * hears a key. A game never reads this table, and no keymap entry can widen or
+ * narrow what a running game receives.
+ */
+
+/** Any registered keymap's id: the editor's own `volter`, or one a package
+ *  contributes (`@volter/sdk/looks`, `KeymapContribution`). */
+export type EditorKeymapId = string;
+
+export interface EditorKeymapDescriptor {
+  readonly id: EditorKeymapId;
+  readonly title: string;
+  readonly description: string;
+}
+
+/** The editor's OWN keymap, the one every project has. Every other keymap is
+ *  a package's contribution (Blender's ships with `@volter/editor-blender`). */
+const BUILT_IN_KEYMAPS: readonly EditorKeymapDescriptor[] = Object.freeze([
+  {
+    id: 'volter',
+    title: 'volter',
+    description: "The editor's own bindings: W/E/R gizmo modes, Ctrl+A select all, F frames.",
+  },
+] satisfies readonly EditorKeymapDescriptor[]);
+
+interface ContributedKeymap {
+  readonly descriptor: EditorKeymapDescriptor;
+  readonly table: EditorKeymapTable;
+  readonly navigation: KeymapNavigation | null;
+}
+const contributedKeymaps = new Map<string, ContributedKeymap>();
+let registryVersion = 0;
+
+/** Built-ins first, then contributions in registration order — the switch
+ *  surfaces (View menu, palette) enumerate this. */
+export function editorKeymaps(): readonly EditorKeymapDescriptor[] {
+  return [
+    ...BUILT_IN_KEYMAPS,
+    ...[...contributedKeymaps.values()].map((entry) => entry.descriptor),
+  ];
+}
+
+export function editorKeymapsVersion(): number {
+  return registryVersion;
+}
+
+/**
+ * Register a package's keymap (`workspace.keymap` contribution). The table is
+ * the editor's own bindings with the contribution's chords over them, so a
+ * keymap declares only where it differs. Returns the unregister. A duplicate
+ * id throws — ids are the `keymap` setting's values.
+ */
+export function registerContributedKeymap(contribution: KeymapContribution): () => void {
+  if (
+    BUILT_IN_KEYMAPS.some((entry) => entry.id === contribution.id) ||
+    contributedKeymaps.has(contribution.id)
+  )
+    throw new Error(
+      `registerContributedKeymap: keymap "${contribution.id}" is already registered.`,
+    );
+  const entry: ContributedKeymap = {
+    descriptor: {
+      id: contribution.id,
+      title: contribution.title,
+      description: contribution.description,
+    },
+    table: Object.freeze({ ...VOLTER_KEYMAP, ...contribution.bindings }) as EditorKeymapTable,
+    navigation: contribution.navigation ?? null,
+  };
+  contributedKeymaps.set(contribution.id, entry);
+  registryVersion++;
+  // A stored preference this contribution satisfies applies now, not on the
+  // next reload: the cache re-reads the setting against the wider registry.
+  cachedKeymap = null;
+  emit();
+  return () => {
+    if (contributedKeymaps.get(contribution.id) !== entry) return;
+    contributedKeymaps.delete(contribution.id);
+    registryVersion++;
+    cachedKeymap = null;
+    emit();
+  };
+}
+
+export function isEditorKeymapId(value: unknown): value is EditorKeymapId {
+  return (
+    typeof value === 'string' &&
+    (BUILT_IN_KEYMAPS.some((entry) => entry.id === value) || contributedKeymaps.has(value))
+  );
+}
+
+export type EditorKeymapTable = Readonly<Record<EditorKeyActionId, readonly KeyChord[]>>;
+
+/**
+ * The volter table reproduces the bindings the editor shipped before keymaps
+ * existed, chord for chord. It is the regression bar: any change here is a
+ * change to the default editor, not to a keymap.
+ */
+const VOLTER_KEYMAP: EditorKeymapTable = Object.freeze({
+  'edit.undo': [{ key: 'z', mod: true }],
+  // Ctrl+Y mirrors Ctrl+Shift+Z (Windows convention).
+  'edit.redo': [
+    { key: 'z', mod: true, shift: true },
+    { key: 'y', mod: true },
+  ],
+  'edit.copy': [{ key: 'c', mod: true }],
+  'edit.cut': [{ key: 'x', mod: true }],
+  'edit.paste': [{ key: 'v', mod: true }],
+  'edit.duplicate': [{ key: 'd', mod: true }],
+  'edit.group': [{ key: 'g', mod: true }],
+  'edit.wrap': [{ key: 'g', mod: true, alt: true }],
+  'edit.unwrap': [{ key: 'g', mod: true, shift: true }],
+  'edit.selectAll': [{ key: 'a', mod: true }],
+  // No dedicated chord: Escape is the volter deselect, and it carries the
+  // scope-exit semantics too (`edit.exitScopeOrDeselect`). An empty chord list
+  // registers no binding; the printed hint falls back to Escape's.
+  'edit.deselectAll': [],
+  'edit.save': [{ key: 's', mod: true }],
+  'edit.delete': [{ key: 'delete' }, { key: 'backspace' }],
+  'edit.enterScope': [{ key: 'enter' }],
+  'edit.exitScopeOrDeselect': [{ key: 'escape' }],
+  'edit.nudgeUp': [{ key: 'arrowup' }],
+  'edit.nudgeUpCoarse': [{ key: 'arrowup', shift: true }],
+  'edit.nudgeDown': [{ key: 'arrowdown' }],
+  'edit.nudgeDownCoarse': [{ key: 'arrowdown', shift: true }],
+  'edit.nudgeLeft': [{ key: 'arrowleft' }],
+  'edit.nudgeLeftCoarse': [{ key: 'arrowleft', shift: true }],
+  'edit.nudgeRight': [{ key: 'arrowright' }],
+  'edit.nudgeRightCoarse': [{ key: 'arrowright', shift: true }],
+  'view.resetPan': [{ key: '0', mod: true }],
+  'view.commandPalette': [{ key: 'k', mod: true }],
+  'view.toggleConsole': [{ key: '`' }],
+  'view.focusMode': [{ key: 'f', mod: true, shift: true }],
+  // Blender's own workspace cycle keys, and free in this registry.
+  'workspace.cycleNext': [{ key: 'pagedown', mod: true }],
+  'workspace.cyclePrevious': [{ key: 'pageup', mod: true }],
+  // Q, beside W/E/R: Godot's 2D Select (its 4.7.1 shortcut `canvas_item_editor/select_mode`)
+  // and Unreal's Select both sit there. The Blender look keeps Select on Blender's own `W`.
+  'transform.select': [{ key: 'q' }],
+  'transform.combined': [{ key: 't' }],
+  'transform.translate': [{ key: 'w' }],
+  'transform.rotate': [{ key: 'e' }],
+  'transform.scale': [{ key: 'r' }],
+  'viewport.toggleSnap': [{ key: 's', shift: true }],
+  'viewport.frameSelection': [{ key: 'f' }],
+  'viewport.cyclePivot': [{ key: '.' }],
+  // A 2D view's Pan and Ruler modes, on Godot's own keys (its 4.7.1 shortcuts
+  // `canvas_item_editor/pan_mode` G and `ruler_mode` M).
+  'canvas.panMode': [{ key: 'g' }],
+  'canvas.rulerMode': [{ key: 'm' }],
+  // Godot's View › Grid › Toggle Grid, Command+' (its 4.7.1 menu shortcut).
+  'canvas.toggleGrid': [{ key: "'", mod: true }],
+  'viewport.vertexSnapHold': [{ key: 'v' }],
+  'viewport.snapToFloor': [{ key: '', code: 'PageDown' }],
+  'view.top': [{ key: '', code: 'Numpad7' }],
+  'view.front': [{ key: '', code: 'Numpad1' }],
+  'view.right': [{ key: '', code: 'Numpad3' }],
+  'view.bottom': [],
+  'view.back': [],
+  'view.left': [],
+  'view.orbitLeft': [],
+  'view.orbitRight': [],
+  'view.orbitUp': [],
+  'view.orbitDown': [],
+  'view.opposite': [],
+  'view.rollLeft': [],
+  'view.rollRight': [],
+  'view.all': [],
+  'view.zoomIn': [],
+  'view.zoomOut': [],
+  'view.perspective': [{ key: '', code: 'Numpad5' }],
+  'view.projection': [],
+  'view.camera': [{ key: '', code: 'Numpad0' }],
+} satisfies EditorKeymapTable);
+
+// ---------------------------------------------------------------------------
+// The setting
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_EDITOR_KEYMAP: EditorKeymapId = 'volter';
+
+let cachedKeymap: EditorKeymapId | null = null;
+let settingsSyncInstalled = false;
+const listeners = new Set<() => void>();
+
+function emit(): void {
+  for (const listener of listeners) listener();
+}
+
+/** The editor's own keymap ids — the ones that exist in every project. */
+function isBuiltInKeymapId(value: unknown): boolean {
+  return typeof value === 'string' && BUILT_IN_KEYMAPS.some((entry) => entry.id === value);
+}
+
+/** What the PROJECT selects: its adapter's declaration, its own settings over it. */
+function projectScopedKeymap(): unknown {
+  return projectSettings().keymap ?? adapterSettings().keymap;
+}
+
+/**
+ * A keymap a PACKAGE contributes is project-scoped: it exists only where that
+ * package is declared, so only the project may select it — its adapter
+ * (`editor: { keymap: blenderKeymap }`) or its own `.volter/settings.json`. The
+ * USER layer chooses among the editor's own, because a cross-project default
+ * naming a skew's bindings is how a models project's G/R/S reached a game
+ * project that merely happens to declare the same package.
+ */
+function readStoredKeymap(): EditorKeymapId {
+  const scoped = projectScopedKeymap();
+  if (isEditorKeymapId(scoped)) return scoped;
+  const preferred = userSettings().keymap;
+  return isBuiltInKeymapId(preferred) ? (preferred as EditorKeymapId) : DEFAULT_EDITOR_KEYMAP;
+}
+
+const saidUnavailable = new Set<string>();
+/**
+ * Say, once per id, that the STORED keymap is one nothing in this project
+ * contributes, so a models project opened without its Blender package
+ * explains the W/E/R it is showing. Called by the loader AFTER a contribution
+ * pass has registered what the project's packages ship — asked at boot it
+ * would warn about every keymap a package is about to contribute (measured
+ * 2026-09-17: "blender is not available" on a project whose mesh package
+ * registered it a moment later).
+ */
+export function reportUnavailableKeymap(): void {
+  const stored = projectScopedKeymap();
+  if (typeof stored !== 'string' || stored === DEFAULT_EDITOR_KEYMAP) return;
+  if (isEditorKeymapId(stored) || saidUnavailable.has(stored)) return;
+  saidUnavailable.add(stored);
+  editorConsole.warn(
+    `Keymap "${stored}" is not available in this project: no declared package contributes it ` +
+      `(a package ships one as a \`workspace.keymap\` contribution). Using "${DEFAULT_EDITOR_KEYMAP}".`,
+    'editor',
+  );
+}
+
+/** The setting is `keymap` in the settings layers (`settings-store.ts`); a
+ *  load finishing or a project's own override becoming active must not leave
+ *  this module's cache lying. Installed on first read so the module has no
+ *  load-time side effect. */
+function ensureSettingsSync(): void {
+  if (settingsSyncInstalled) return;
+  settingsSyncInstalled = true;
+  subscribeSettings(() => {
+    const next = readStoredKeymap();
+    if (next === cachedKeymap) return;
+    cachedKeymap = next;
+    emit();
+  });
+}
+
+/** Current keymap id (`useSyncExternalStore`-shaped snapshot). */
+export function activeEditorKeymap(): EditorKeymapId {
+  ensureSettingsSync();
+  cachedKeymap ??= readStoredKeymap();
+  return cachedKeymap;
+}
+
+/**
+ * Switch keymaps. Live: every binding registration re-derives from the new
+ * table on this call (`editor-hotkeys.ts`) and every printed hint re-renders,
+ * so there is no reload and no restart. Choosing one of the editor's OWN
+ * keymaps writes where the key is declared; choosing a package's writes the
+ * PROJECT layer, because that is the only layer a contributed keymap is read
+ * from (see {@link readStoredKeymap}) — a gesture must land somewhere it wins.
+ */
+export function setEditorKeymapPreference(id: EditorKeymapId): void {
+  if (activeEditorKeymap() === id) return;
+  cachedKeymap = id;
+  if (isBuiltInKeymapId(id)) updatePreferenceSettings({ keymap: id });
+  else updateProjectSettings({ keymap: id });
+  emit();
+}
+
+export function subscribeEditorKeymap(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function __resetEditorKeymapForTest(): void {
+  cachedKeymap = null;
+  listeners.clear();
+}
+
+// ---------------------------------------------------------------------------
+// The one lookup
+// ---------------------------------------------------------------------------
+
+/** The active table's chords for one action. Empty means deliberately unbound. */
+export function keyChordsFor(action: EditorKeyActionId): readonly KeyChord[] {
+  return keymapTable(activeEditorKeymap())[action];
+}
+
+/** The active keymap's viewport mouse (`KeymapContribution.navigation`), the editor's own when
+ *  it states none: orbit on the right button. */
+export function activeKeymapNavigation(): KeymapNavigation {
+  return contributedKeymaps.get(activeEditorKeymap())?.navigation ?? { orbit: 'right' };
+}
+
+/** A named table, for a surface that must show a keymap it is not running.
+ *  An unregistered id answers the editor's own table. */
+export function keymapTable(id: EditorKeymapId): EditorKeymapTable {
+  return contributedKeymaps.get(id)?.table ?? VOLTER_KEYMAP;
+}
+
+// ---------------------------------------------------------------------------
+// Display
+// ---------------------------------------------------------------------------
+
+function isMacPlatform(): boolean {
+  return typeof navigator !== 'undefined' && navigator.platform.includes('Mac');
+}
+
+/** Named keys whose label is neither the raw `key` nor its uppercase form. */
+const KEY_LABELS: Readonly<Record<string, string>> = {
+  delete: 'Del',
+  backspace: 'Backspace',
+  escape: 'Esc',
+  enter: 'Enter',
+  pagedown: 'PgDn',
+  pageup: 'PgUp',
+  arrowup: '↑',
+  arrowdown: '↓',
+  arrowleft: '←',
+  arrowright: '→',
+  ' ': 'Space',
+  tab: 'Tab',
+};
+
+const CODE_LABELS: Readonly<Record<string, string>> = {
+  Numpad0: 'Num0',
+  Numpad1: 'Num1',
+  Numpad2: 'Num2',
+  Numpad3: 'Num3',
+  Numpad4: 'Num4',
+  Numpad5: 'Num5',
+  Numpad6: 'Num6',
+  Numpad7: 'Num7',
+  Numpad8: 'Num8',
+  Numpad9: 'Num9',
+  NumpadDecimal: 'Num.',
+  PageDown: 'PgDn',
+  PageUp: 'PgUp',
+  End: 'End',
+  KeyG: 'G',
+  KeyH: 'H',
+  KeyJ: 'J',
+  KeyK: 'K',
+};
+
+function keyLabel(chord: KeyChord): string {
+  if (chord.code) return CODE_LABELS[chord.code] ?? chord.code;
+  return KEY_LABELS[chord.key] ?? (chord.key.length === 1 ? chord.key.toUpperCase() : chord.key);
+}
+
+/**
+ * Render one chord the way the editor's chrome has always rendered them —
+ * BOTH existing conventions preserved verbatim, because changing a printed
+ * string is a visible regression: a mod-prefixed chord reads `⌘⇧Z` / `Ctrl+⇧Z`
+ * (the command palette's shape), while a modless chord spells its modifiers
+ * out, `Shift+S` (the toolstrip's shape).
+ */
+export function formatChord(chord: KeyChord): string {
+  const label = keyLabel(chord);
+  if (chord.mod) {
+    const mod = isMacPlatform() ? '⌘' : 'Ctrl+';
+    return `${chord.ctrl && isMacPlatform() ? '⌃' : ''}${mod}${chord.alt ? '⌥' : ''}${chord.shift ? '⇧' : ''}${label}`;
+  }
+  const parts: string[] = [];
+  if (chord.ctrl) parts.push('Ctrl');
+  if (chord.alt) parts.push('Alt');
+  if (chord.shift) parts.push('Shift');
+  parts.push(label);
+  return parts.join('+');
+}
+
+/**
+ * The printed hint for an action under the ACTIVE keymap — the first chord,
+ * which every table lists in "the one to teach" order. `undefined` when the
+ * action is deliberately unbound, so a caller can fall back or omit the hint
+ * rather than print a lie.
+ */
+export function shortcutFor(action: EditorKeyActionId): string | undefined {
+  const chord = keyChordsFor(action)[0];
+  return chord ? formatChord(chord) : undefined;
+}

package/src/kit/layout-policy.ts

@@ -0,0 +1,31 @@
+/** Presentation chosen by mounted layout code. No game or website names live here. */
+import type { WorkspaceArrangement } from '@volter/sdk/layout-arrangements';
+import { activeProjectKey } from '@volter/sdk/kit/active-project';
+export interface LayoutPolicy {
+  readonly immersivePlay?: boolean;
+  readonly playUtilities?: readonly string[];
+  readonly arrangement?: WorkspaceArrangement;
+}
+let owner: string | null = null;
+let policy: LayoutPolicy | null = null;
+const listeners = new Set<() => void>();
+export function layoutPolicy(): LayoutPolicy | null {
+  return owner === activeProjectKey() ? policy : null;
+}
+export function subscribeLayoutPolicy(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+export function installLayoutPolicy(next: LayoutPolicy): () => void {
+  owner = activeProjectKey();
+  policy = next;
+  for (const listener of listeners) listener();
+  return () => {
+    if (policy !== next) return;
+    policy = null;
+    owner = null;
+    for (const listener of listeners) listener();
+  };
+}