@vgai/editor 0.2.0

package/src/handle-system.ts

@@ -0,0 +1,221 @@
+import type { SceneEntity } from '@engine/scene/scene-types';
+import * as THREE from 'three';
+import { EDITOR_LAYER } from './editor-layers';
+
+// ---------------------------------------------------------------------------
+// Handle definition
+// ---------------------------------------------------------------------------
+
+export interface HandleDef {
+  /** Unique handle ID within the entity, e.g. 'light-distance' */
+  id: string;
+  /** The entity ID this handle belongs to */
+  entityId: string;
+  /** Compute the handle's world position from the current entity state */
+  getWorldPosition: (entityObj: THREE.Object3D, entity: SceneEntity) => THREE.Vector3;
+  /** Called during drag — mutates the entity descriptor directly. */
+  onDrag: (newWorldPos: THREE.Vector3, entityObj: THREE.Object3D, entity: SceneEntity) => void;
+  /** Handle color (default yellow) */
+  color?: number;
+}
+
+export interface HandleMesh extends THREE.Mesh {
+  userData: {
+    editorHandle: true;
+    handleDef: HandleDef;
+  };
+}
+
+const HANDLE_COLOR = 0xffaa00;
+const HANDLE_HOVER_COLOR = 0xffffff;
+
+const handleGeo = new THREE.SphereGeometry(1, 10, 10);
+
+/** Create a handle mesh for a given definition. */
+export function createHandleMesh(def: HandleDef): HandleMesh {
+  const mat = new THREE.MeshBasicMaterial({
+    color: def.color ?? HANDLE_COLOR,
+    depthTest: false,
+    transparent: true,
+    opacity: 0.85,
+  });
+  const mesh = new THREE.Mesh(handleGeo, mat) as unknown as HandleMesh;
+  mesh.renderOrder = 998;
+  mesh.layers.set(EDITOR_LAYER);
+  mesh.userData = { editorHandle: true, handleDef: def };
+  return mesh;
+}
+
+/** Set a handle mesh to its hovered state. */
+export function setHandleHovered(mesh: HandleMesh, hovered: boolean): void {
+  const mat = mesh.material as THREE.MeshBasicMaterial;
+  mat.color.setHex(hovered ? HANDLE_HOVER_COLOR : (mesh.userData.handleDef.color ?? HANDLE_COLOR));
+}
+
+/** Scale a handle to maintain constant screen size. */
+export function scaleHandle(mesh: THREE.Mesh, camera: THREE.Camera): void {
+  const dist = mesh.position.distanceTo(camera.position);
+  const s = dist * 0.012;
+  mesh.scale.setScalar(s);
+}
+
+// ---------------------------------------------------------------------------
+// Handle definitions per entity type
+// ---------------------------------------------------------------------------
+
+/** Create handle definitions for an entity. Returns empty array if no handles apply. */
+export function createHandleDefs(entity: SceneEntity): HandleDef[] {
+  const defs: HandleDef[] = [];
+  const eid = entity.id!;
+
+  // -- Point light distance --
+  if (entity.light?.type === 'point' && entity.light.distance) {
+    defs.push({
+      id: 'light-distance',
+      entityId: eid,
+      getWorldPosition: (obj) => {
+        const local = new THREE.Vector3(entity.light!.distance ?? 5, 0, 0);
+        return local.applyMatrix4(obj.matrixWorld);
+      },
+      onDrag: (newWorld, obj, ent) => {
+        const inv = obj.matrixWorld.clone().invert();
+        const local = newWorld.clone().applyMatrix4(inv);
+        const dist = Math.max(0.1, local.length());
+        ent.light!.distance = Math.round(dist * 100) / 100;
+      },
+    });
+  }
+
+  // -- Spot light distance + angle --
+  if (entity.light?.type === 'spot') {
+    const dist = entity.light.distance ?? 10;
+    if (dist > 0) {
+      defs.push({
+        id: 'spot-distance',
+        entityId: eid,
+        getWorldPosition: (obj) => {
+          const local = new THREE.Vector3(0, 0, -(entity.light!.distance ?? 10));
+          return local.applyMatrix4(obj.matrixWorld);
+        },
+        onDrag: (newWorld, obj, ent) => {
+          const inv = obj.matrixWorld.clone().invert();
+          const local = newWorld.clone().applyMatrix4(inv);
+          ent.light!.distance = Math.max(0.1, Math.round(Math.abs(local.z) * 100) / 100);
+        },
+      });
+    }
+    defs.push({
+      id: 'spot-angle',
+      entityId: eid,
+      color: 0xff8844,
+      getWorldPosition: (obj) => {
+        const angle = entity.light!.angle ?? Math.PI / 6;
+        const d = entity.light!.distance ?? 10;
+        const r = Math.tan(angle) * d;
+        const local = new THREE.Vector3(r, 0, -d);
+        return local.applyMatrix4(obj.matrixWorld);
+      },
+      onDrag: (newWorld, obj, ent) => {
+        const inv = obj.matrixWorld.clone().invert();
+        const local = newWorld.clone().applyMatrix4(inv);
+        const d = Math.abs(local.z) || 0.1;
+        const r = Math.abs(local.x);
+        const angle = Math.atan2(r, d);
+        ent.light!.angle = Math.max(
+          0.01,
+          Math.min(Math.PI / 2 - 0.01, Math.round(angle * 1000) / 1000),
+        );
+      },
+    });
+  }
+
+  // -- Audio source ref/max distance --
+  if (entity.audio?.spatial !== false && entity.audio) {
+    defs.push({
+      id: 'audio-refDistance',
+      entityId: eid,
+      color: 0x44bbff,
+      getWorldPosition: (obj) => {
+        const local = new THREE.Vector3(entity.audio!.refDistance ?? 1, 0, 0);
+        return local.applyMatrix4(obj.matrixWorld);
+      },
+      onDrag: (newWorld, obj, ent) => {
+        const inv = obj.matrixWorld.clone().invert();
+        const local = newWorld.clone().applyMatrix4(inv);
+        ent.audio!.refDistance = Math.max(0.01, Math.round(local.length() * 100) / 100);
+      },
+    });
+    if ((entity.audio.maxDistance ?? 10000) < 10000) {
+      defs.push({
+        id: 'audio-maxDistance',
+        entityId: eid,
+        color: 0x2277aa,
+        getWorldPosition: (obj) => {
+          const local = new THREE.Vector3(entity.audio!.maxDistance ?? 100, 0, 0);
+          return local.applyMatrix4(obj.matrixWorld);
+        },
+        onDrag: (newWorld, obj, ent) => {
+          const inv = obj.matrixWorld.clone().invert();
+          const local = newWorld.clone().applyMatrix4(inv);
+          ent.audio!.maxDistance = Math.max(
+            (ent.audio!.refDistance ?? 1) + 0.1,
+            Math.round(local.length() * 100) / 100,
+          );
+        },
+      });
+    }
+  }
+
+  // -- Camera FOV --
+  if (entity.camera?.type === 'perspective') {
+    defs.push({
+      id: 'camera-fov',
+      entityId: eid,
+      color: 0xcccc44,
+      getWorldPosition: (obj) => {
+        const fov = entity.camera!.fov ?? 60;
+        const halfRad = THREE.MathUtils.degToRad(fov / 2);
+        const d = 3; // fixed forward distance for the handle
+        const y = Math.tan(halfRad) * d;
+        const local = new THREE.Vector3(0, y, -d);
+        return local.applyMatrix4(obj.matrixWorld);
+      },
+      onDrag: (newWorld, obj, ent) => {
+        const inv = obj.matrixWorld.clone().invert();
+        const local = newWorld.clone().applyMatrix4(inv);
+        const d = Math.abs(local.z) || 0.1;
+        const y = Math.abs(local.y);
+        const halfRad = Math.atan2(y, d);
+        const fov = THREE.MathUtils.radToDeg(halfRad) * 2;
+        ent.camera!.fov = Math.max(5, Math.min(170, Math.round(fov * 10) / 10));
+      },
+    });
+  }
+
+  // -- Spline control points --
+  if (entity.spline && entity.spline.points.length >= 2) {
+    for (let i = 0; i < entity.spline.points.length; i++) {
+      defs.push({
+        id: `spline-point-${i}`,
+        entityId: eid,
+        color: 0x00ccff,
+        getWorldPosition: (obj) => {
+          const p = entity.spline!.points[i]!;
+          const local = new THREE.Vector3(p[0], p[1], p[2]);
+          return local.applyMatrix4(obj.matrixWorld);
+        },
+        onDrag: (newWorld, obj, ent) => {
+          const inv = obj.matrixWorld.clone().invert();
+          const local = newWorld.clone().applyMatrix4(inv);
+          ent.spline!.points[i] = [
+            Math.round(local.x * 1000) / 1000,
+            Math.round(local.y * 1000) / 1000,
+            Math.round(local.z * 1000) / 1000,
+          ];
+        },
+      });
+    }
+  }
+
+  return defs;
+}

package/src/hierarchy-menu-registry.ts

@@ -0,0 +1,70 @@
+/**
+ * Hierarchy context-menu contribution registry (A2,
+ * docs/unified-world-editor/26-unified-editor-spec.md §2 A2) — the escape
+ * hatch for first-party-only row actions that are NOT YET contract-expressible
+ * through `StructureProvider`/`InspectorProvider` (prefab unpack/open/save-as
+ * today; a future tag-search or similar joins the same seam). `GameHierarchy`
+ * (the contract-only shell) calls {@link getHierarchyMenuItems} and appends
+ * whatever comes back to its own Rename/Duplicate/Show-Hide/Lock/Delete items
+ * — it never branches on WHICH registration fired, keeping Rule Zero intact
+ * (the shell still speaks only the `AuthoringAdapter` contract; only the
+ * REGISTRATION module, e.g. `authoring/first-party-hierarchy-menu.ts`, is
+ * allowed to reach into store internals).
+ *
+ * PERMANENT adapter-module contribution seam (blessed by C2, docs/unified-
+ * world-editor/26-unified-editor-spec.md §4 C2 — the same status as C2's own
+ * `inspector-section-registry.ts`): first-party affordances that aren't (yet,
+ * or ever) contract-expressible register through here instead of the
+ * contract-only shell branching on adapter identity. If a given affordance
+ * later becomes contract-expressible, its OWN registration is removed at
+ * that point — the registry mechanism itself is not temporary.
+ */
+
+import type { EditorStore } from './editor-store';
+
+export interface HierarchyMenuContext {
+  /** The row's node id (an `EditorNode.id` — format-neutral, not a `SceneEntity` id). */
+  readonly nodeId: string;
+  readonly store: EditorStore;
+}
+
+export interface HierarchyMenuItem {
+  readonly label: string;
+  readonly action: () => void;
+  readonly color?: string;
+}
+
+type Matcher = (ctx: HierarchyMenuContext) => boolean;
+type ItemsFactory = (ctx: HierarchyMenuContext) => HierarchyMenuItem[];
+
+interface Registration {
+  readonly match: Matcher;
+  readonly items: ItemsFactory;
+}
+
+const registrations: Registration[] = [];
+
+/**
+ * Register a set of first-party (or other non-contract) hierarchy context-menu
+ * items. `match` decides whether this registration applies to a given row;
+ * `items` builds the actual entries when it does (called only when `match`
+ * returns true). Returns an unregister function.
+ */
+export function registerHierarchyMenuItems(match: Matcher, items: ItemsFactory): () => void {
+  const reg: Registration = { match, items };
+  registrations.push(reg);
+  return () => {
+    const idx = registrations.indexOf(reg);
+    if (idx >= 0) registrations.splice(idx, 1);
+  };
+}
+
+/** Every registered item that applies to `ctx`, in registration order. */
+export function getHierarchyMenuItems(ctx: HierarchyMenuContext): HierarchyMenuItem[] {
+  return registrations.filter((r) => r.match(ctx)).flatMap((r) => r.items(ctx));
+}
+
+/** Test-only reset (mirrors `undo-timeline.ts`'s `__resetUndoTimelineForTest`). */
+export function __resetHierarchyMenuRegistryForTest(): void {
+  registrations.length = 0;
+}

package/src/hierarchy-rows.ts

@@ -0,0 +1,73 @@
+/**
+ * Pure row-flattening for the hierarchy tree (no React) — extracted so the
+ * child-cap logic is unit-testable without rendering the panel.
+ */
+
+import type { SceneEntity } from '@engine/scene/scene-types';
+
+/** Max children shown per parent before a "… N more" row (when capping is on). */
+export const CHILD_CAP = 20;
+export const MORE_ID_PREFIX = '__more__:';
+
+export interface TreeRow {
+  entity: SceneEntity;
+  depth: number;
+  parentId: string | null;
+  childIndex: number;
+  hasChildren: boolean;
+  isOpen: boolean;
+  /** Present on a synthetic "… N more" row that reveals capped siblings. */
+  more?: { parentKey: string; hidden: number };
+}
+
+/** Stable key for a parent's child-limit bookkeeping (root uses a sentinel). */
+export function parentKeyOf(parentId: string | null): string {
+  return parentId ?? '__root__';
+}
+
+/**
+ * Flatten a `SceneEntity` tree into display rows, honoring collapsed nodes and
+ * (when `capEnabled`) a per-parent child cap with a synthetic "… N more" row.
+ * `expanded` maps a parent key → how many children it has been asked to reveal.
+ */
+export function flattenVisibleRows(
+  entities: SceneEntity[],
+  closedIds: Set<string>,
+  expanded: Map<string, number>,
+  capEnabled: boolean,
+  parentId: string | null = null,
+  depth = 0,
+): TreeRow[] {
+  const rows: TreeRow[] = [];
+  const parentKey = parentKeyOf(parentId);
+  // Cap each sibling list so a huge live scene graph (play mode) doesn't dump
+  // thousands of rows at once. A "… N more" row reveals the next page on click.
+  const limit = capEnabled
+    ? Math.max(CHILD_CAP, expanded.get(parentKey) ?? CHILD_CAP)
+    : Number.POSITIVE_INFINITY;
+  const shown = Math.min(entities.length, limit);
+  for (let i = 0; i < shown; i++) {
+    const entity = entities[i]!;
+    const id = entity.id!;
+    const hasChildren = (entity.children?.length ?? 0) > 0;
+    const isOpen = hasChildren && !closedIds.has(id);
+    rows.push({ entity, depth, parentId, childIndex: i, hasChildren, isOpen });
+    if (isOpen && entity.children) {
+      rows.push(
+        ...flattenVisibleRows(entity.children, closedIds, expanded, capEnabled, id, depth + 1),
+      );
+    }
+  }
+  if (entities.length > shown) {
+    rows.push({
+      entity: { id: `${MORE_ID_PREFIX}${parentKey}`, name: '' } as SceneEntity,
+      depth,
+      parentId,
+      childIndex: shown,
+      hasChildren: false,
+      isOpen: false,
+      more: { parentKey, hidden: entities.length - shown },
+    });
+  }
+  return rows;
+}

package/src/hosted-example.ts

@@ -0,0 +1,160 @@
+/**
+ * Hosted-example routing — the static/browser build's `?project=<exampleId>`
+ * deep-link scheme (docs/EXAMPLES-AS-PROJECTS-DESIGN.md §H, Track H).
+ *
+ * In the hosted editor every `examples/<id>/` project is staged at
+ * `/examples/<id>/` by the web build (`vite-plugin-example-assets.ts` copies
+ * `public/*` plus the `vgai.game.json` manifest) and its code ships inside the
+ * pre-bundled project scripts, dispatched by `EditorPreview.exampleId`
+ * (`browser-play-entry.ts`). This module supplies the routing glue between
+ * those two existing seams:
+ *
+ *  - `openExampleProject(id)` — resolve `?project=<id>` to an ActiveProject by
+ *    fetching the staged manifest; namespaces ALL relative asset resolution
+ *    (editor-side prefab/material/scene fetches included) via `setAssetPrefix`.
+ *  - `exampleDispatchFor(...)` — the play-mode decision: dispatch the bundled
+ *    example setup, or play the OPEN scene generically but keep the example's
+ *    asset prefix (`?scene=` override within the project).
+ *  - `legacyPoolSearch(...)` — rewrite pre-Track-H `?scene=/examples/scenes/…`
+ *    pool links (the deleted flat scene pool) onto the project scheme, so
+ *    published lesson URLs and bookmarks keep working.
+ *
+ * Example projects open READ-ONLY: their scenes load with no save path, which
+ * makes autosave an inert no-op (see `editor-store.ts`) — edits are in-memory
+ * for the session. To keep changes, scaffold the example into a real project
+ * (`create-vgai-project <name> --example <id>`).
+ */
+
+import { setAssetPrefix } from '@engine/loader';
+import { GameManifestSchema } from '@engine/manifest/schema';
+import type { ActiveProject } from './project-manager';
+
+/** Folder-name shape shared by every `examples/<id>/` — also a path-safety gate. */
+const EXAMPLE_ID_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+/** Fetch + validate the staged manifest for a bundled example and derive the
+ *  ActiveProject the rest of the editor consumes. Throws on unknown id /
+ *  missing staging / invalid manifest — the caller decides the fallback. */
+export async function openExampleProject(exampleId: string): Promise<ActiveProject> {
+  if (!EXAMPLE_ID_RE.test(exampleId)) {
+    throw new Error(`Invalid example id "${exampleId}"`);
+  }
+  const manifestUrl = `/examples/${exampleId}/vgai.game.json`;
+  const res = await fetch(manifestUrl);
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} fetching ${manifestUrl} — not a bundled example?`);
+  }
+  const manifest = GameManifestSchema.parse(await res.json());
+
+  // Namespace relative asset resolution to this example's staged public/ —
+  // the same prefix `browser-play-entry.ts` sets at play dispatch, applied
+  // here so EDITOR-side fetches (scenes, prefabs, .mat files via
+  // `resolveUrl`) resolve against the project too.
+  setAssetPrefix(`/examples/${exampleId}/`);
+
+  return {
+    rootPath: `/examples/${exampleId}`,
+    config: {
+      name: manifest.name,
+      defaultScene: manifest.worlds[0]?.scene ?? null,
+      ...(manifest.resolution ? { resolution: manifest.resolution } : {}),
+    },
+    exampleId,
+  };
+}
+
+/**
+ * The play-mode routing decision for a hosted example project — pure, so it is
+ * unit-testable without booting play mode. Returns the EditorPreview fields to
+ * spread into the preview object:
+ *
+ *  - `{ exampleId }` — the project's shipped game: dispatch the bundled setup
+ *    (its own registry + gameplay systems; it loads its own manifest scene).
+ *  - `{ assetPrefix }` — a `?scene=` override inside the project (e.g.
+ *    feature-scenes' unmounted extras): play the editor's OPEN scene through
+ *    the generic loader, but keep asset refs resolving into the example.
+ *  - `{}` — not an example project, or the user opened a VFS scene of their
+ *    own (savePath set): today's generic behavior, root prefix.
+ */
+export function exampleDispatchFor(
+  exampleId: string | undefined,
+  savePath: string | null,
+  hasSceneOverride: boolean,
+): { exampleId?: string; assetPrefix?: string } {
+  if (!exampleId || savePath !== null) return {};
+  if (hasSceneOverride) return { assetPrefix: `/examples/${exampleId}/` };
+  return { exampleId };
+}
+
+// ---------------------------------------------------------------------------
+// Legacy flat-pool links (`?scene=/examples/scenes/<name>.vscn.json`)
+// ---------------------------------------------------------------------------
+
+/** Pool scenes that live in the scene-only `feature-scenes` project now. */
+const FEATURE_SCENES_POOL = new Set([
+  'instanced-grid', // feature-scenes' manifest default — no scene override needed
+  'learn-skybox',
+  'ocean',
+  'particles',
+  'terrain',
+  'water-shader',
+]);
+
+/** Pool scenes whose example folder name differs from the scene file name. */
+const RENAMED_POOL: Record<string, string> = {
+  arena: 'third-person-arena',
+};
+
+/** Pool scenes whose name IS their example id (verified on disk by
+ *  `hosted-example-routing.test.ts` — every target's manifest + scene exist). */
+const IDENTITY_POOL = new Set([
+  'editor-tutorial',
+  'fps',
+  'ik',
+  'learn-joints',
+  'learn-matfiles',
+  'learn-splines',
+  'learn-triggers',
+  'littlest-tokyo',
+  'rts',
+  'third-person',
+  'vehicle',
+]);
+
+/** Map a legacy pool scene name to its `?project=` route, or null if unknown. */
+export function legacyPoolRoute(name: string): { project: string; scene?: string } | null {
+  if (FEATURE_SCENES_POOL.has(name)) {
+    return name === 'instanced-grid'
+      ? { project: 'feature-scenes' }
+      : { project: 'feature-scenes', scene: `scenes/${name}.vscn.json` };
+  }
+  const project = RENAMED_POOL[name] ?? (IDENTITY_POOL.has(name) ? name : null);
+  return project ? { project } : null;
+}
+
+/**
+ * Rewrite a legacy pool deep link's search string onto the project scheme.
+ * Returns the new search string (other params preserved), or null when the
+ * URL is not a known legacy pool link (leave it alone).
+ */
+export function legacyPoolSearch(search: string): string | null {
+  const params = new URLSearchParams(search);
+  const scene = params.get('scene');
+  if (!scene || params.get('project')) return null;
+  const m = /^\/examples\/scenes\/([a-z0-9-]+)\.vscn\.json$/.exec(scene);
+  if (!m || m[1] === undefined) return null;
+  const route = legacyPoolRoute(m[1]);
+  if (!route) return null;
+  params.delete('scene');
+  params.set('project', route.project);
+  if (route.scene) params.set('scene', route.scene);
+  return `?${params.toString()}`;
+}
+
+/** Apply the legacy rewrite to the live URL (history.replaceState, no reload). */
+export function applyLegacyPoolRedirect(): void {
+  const rewritten = legacyPoolSearch(window.location.search);
+  if (rewritten !== null) {
+    window.history.replaceState(null, '', `${window.location.pathname}${rewritten}`);
+  }
+}

package/src/hotkeys.ts

@@ -0,0 +1,142 @@
+import { useEffect } from 'react';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type HotkeyScope = 'viewport' | 'hierarchy' | 'inspector' | 'asset-browser' | 'global';
+
+export interface HotkeyBinding {
+  /** The key to match (`e.key`, lowercase). Ignored when `code` is set. */
+  key: string;
+  /** Match on `e.code` instead of `e.key` (for numpad keys). */
+  code?: string;
+  /** Require Ctrl (Win/Linux) or Cmd (Mac). */
+  mod?: boolean;
+  /** Require Shift. */
+  shift?: boolean;
+  /** Require Alt/Option (D4 — `wrap`'s `Ctrl+Alt+G`). */
+  alt?: boolean;
+  /** Scope this binding belongs to. `'global'` bindings fire regardless of panel focus. */
+  scope: HotkeyScope;
+  /** Action to execute when the binding matches. */
+  action: (e: KeyboardEvent) => void;
+  /** Human-readable label for menus / tooltips. */
+  label?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Active scope (which panel was last interacted with)
+// ---------------------------------------------------------------------------
+
+let _activeScope: HotkeyScope = 'viewport';
+
+export function getActiveScope(): HotkeyScope {
+  return _activeScope;
+}
+
+export function setActiveScope(scope: HotkeyScope): void {
+  _activeScope = scope;
+}
+
+// ---------------------------------------------------------------------------
+// Binding registry
+// ---------------------------------------------------------------------------
+
+const _bindings: HotkeyBinding[] = [];
+
+/**
+ * Register hotkey bindings. Returns a dispose function that removes them.
+ */
+export function registerHotkeys(bindings: HotkeyBinding[]): () => void {
+  _bindings.push(...bindings);
+  return () => {
+    for (const b of bindings) {
+      const idx = _bindings.indexOf(b);
+      if (idx >= 0) _bindings.splice(idx, 1);
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+
+function handleKeyDown(e: KeyboardEvent): void {
+  // Skip when typing in form inputs — D4 (spec27 §6 D4 "each shortcut fires
+  // only when not typing") widens this to `[contenteditable]` too (no
+  // in-repo editor uses one today — `WorldTextEditor`/`GameHierarchy`'s
+  // rename both use a real `<textarea>`/`<input>`, already covered above —
+  // but the guard should hold for a future contentEditable surface without
+  // needing another fix here).
+  if (
+    e.target instanceof HTMLInputElement ||
+    e.target instanceof HTMLTextAreaElement ||
+    e.target instanceof HTMLSelectElement ||
+    (e.target instanceof HTMLElement && e.target.isContentEditable)
+  )
+    return;
+
+  const mod = e.metaKey || e.ctrlKey;
+  const key = e.key.toLowerCase();
+  const code = e.code;
+  const scope = _activeScope;
+
+  // Check scoped bindings first, then global
+  const passes: HotkeyScope[] = scope === 'global' ? ['global'] : [scope, 'global'];
+
+  for (const pass of passes) {
+    for (const b of _bindings) {
+      if (b.scope !== pass) continue;
+
+      const keyMatch = b.code ? b.code === code : b.key === key;
+      if (!keyMatch) continue;
+      if ((b.mod ?? false) !== mod) continue;
+      if ((b.shift ?? false) !== e.shiftKey) continue;
+      if ((b.alt ?? false) !== e.altKey) continue;
+
+      e.preventDefault();
+      b.action(e);
+      return;
+    }
+  }
+}
+
+let _installed = false;
+
+/** Attach the global keydown listener. Call once at startup. */
+export function installHotkeys(): void {
+  if (_installed) return;
+  window.addEventListener('keydown', handleKeyDown);
+  _installed = true;
+}
+
+/** Detach the global keydown listener. */
+export function uninstallHotkeys(): void {
+  window.removeEventListener('keydown', handleKeyDown);
+  _installed = false;
+}
+
+/**
+ * True once this shared hotkey system is installed (the real editor's
+ * `registerEditorHotkeys`/`installHotkeys`, called when the viewport mounts).
+ * `false` in a standalone surface that never mounts a viewport (e.g. the UI-editor
+ * harness) — used so a panel that has its OWN local keydown handling (T3.2 slice
+ * 2: `UIEditor.tsx`'s undo/redo) can tell whether THIS system will already
+ * dispatch the key, and skip acting itself rather than double-dispatching.
+ */
+export function isHotkeysInstalled(): boolean {
+  return _installed;
+}
+
+// ---------------------------------------------------------------------------
+// React hook for panel-local shortcuts
+// ---------------------------------------------------------------------------
+
+/**
+ * Register hotkey bindings for the lifetime of a component.
+ * Pass a stable array (defined outside render or wrapped in useMemo).
+ */
+export function useHotkeys(bindings: HotkeyBinding[]): void {
+  useEffect(() => registerHotkeys(bindings), [bindings]);
+}