@vgai/editor 0.2.0

package/src/editor-console.ts

@@ -0,0 +1,194 @@
+import { connectEvents } from './editor-api';
+import { getEditorMode } from './editor-mode';
+
+export type ConsoleLevel = 'info' | 'warn' | 'error';
+
+export interface ConsoleEntry {
+  id: number;
+  timestamp: number;
+  level: ConsoleLevel;
+  message: string;
+  source?: string;
+  subsystem?: string;
+  metadata?: Record<string, unknown>;
+  count: number;
+}
+
+const MAX_ENTRIES = 1000;
+
+class EditorConsole {
+  private _entries: ConsoleEntry[] = [];
+  private _listeners = new Set<() => void>();
+  private _nextId = 0;
+  private _version = 0;
+  private _sink: ((entry: ConsoleEntry) => void) | null = null;
+
+  /** Register (or clear) a callback invoked for every console entry. */
+  setSink(fn: ((entry: ConsoleEntry) => void) | null): void {
+    this._sink = fn;
+  }
+
+  counts = { info: 0, warn: 0, error: 0 };
+
+  log(message: string, source?: string): void {
+    this._push('info', message, source);
+  }
+
+  warn(message: string, source?: string): void {
+    this._push('warn', message, source);
+  }
+
+  error(message: string, source?: string): void {
+    this._push('error', message, source);
+  }
+
+  /** Log with structured metadata (used by the engine logger). */
+  logStructured(
+    level: ConsoleLevel,
+    message: string,
+    source: string,
+    subsystem?: string,
+    metadata?: Record<string, unknown>,
+  ): void {
+    this._push(level, message, source, subsystem, metadata);
+  }
+
+  clear(): void {
+    this._entries = [];
+    this.counts = { info: 0, warn: 0, error: 0 };
+    this._notify();
+  }
+
+  getEntries(): readonly ConsoleEntry[] {
+    return this._entries;
+  }
+
+  // useSyncExternalStore compatible
+  subscribe = (cb: () => void): (() => void) => {
+    this._listeners.add(cb);
+    return () => this._listeners.delete(cb);
+  };
+
+  getSnapshot = (): number => this._version;
+
+  private _push(
+    level: ConsoleLevel,
+    message: string,
+    source?: string,
+    subsystem?: string,
+    metadata?: Record<string, unknown>,
+  ): void {
+    // Collapse identical consecutive messages
+    const last = this._entries[this._entries.length - 1];
+    if (last && last.level === level && last.message === message && last.source === source) {
+      last.count++;
+      last.timestamp = Date.now();
+      this._sink?.(last);
+      this._notify();
+      return;
+    }
+
+    const entry: ConsoleEntry = {
+      id: this._nextId++,
+      timestamp: Date.now(),
+      level,
+      message,
+      count: 1,
+    };
+    if (source) entry.source = source;
+    if (subsystem) entry.subsystem = subsystem;
+    if (metadata) entry.metadata = metadata;
+    this._entries.push(entry);
+    this.counts[level]++;
+    this._sink?.(entry);
+
+    // Cap at MAX_ENTRIES, drop oldest
+    if (this._entries.length > MAX_ENTRIES) {
+      const removed = this._entries.shift()!;
+      this.counts[removed.level] = Math.max(0, this.counts[removed.level] - 1);
+    }
+
+    this._notify();
+  }
+
+  private _notify(): void {
+    this._version++;
+    for (const fn of this._listeners) fn();
+  }
+}
+
+export const editorConsole = new EditorConsole();
+
+// Test-only hook (e2e) — the window mirror `design/24-scene-ui.md` A4(f)
+// anticipates: direct read access to console entries without DOM-scraping
+// `ConsolePanel` (which has no per-entry testids). Same ad-hoc `window.__vgai*`
+// convention as every other dev-only hook in `test-window.ts`.
+(window as unknown as { __vgaiEditorConsole?: EditorConsole })['__vgaiEditorConsole'] =
+  editorConsole;
+
+/**
+ * Listen for `console-bridge` postMessage events from game iframes (or self)
+ * and pipe them into the editor console.
+ */
+const BRIDGE_LEVEL_MAP: Record<string, ConsoleLevel> = {
+  log: 'info',
+  warn: 'warn',
+  error: 'error',
+};
+
+/** LogLevel string → ConsoleLevel for engine-log messages. */
+const ENGINE_LEVEL_MAP: Record<string, ConsoleLevel> = {
+  trace: 'info',
+  debug: 'info',
+  info: 'info',
+  warn: 'warn',
+  error: 'error',
+  fatal: 'error',
+};
+
+window.addEventListener('message', (e: MessageEvent) => {
+  // Structured engine-log messages (from engine logger)
+  if (e.data?.type === 'engine-log') {
+    const level = ENGINE_LEVEL_MAP[e.data.level];
+    if (!level) return;
+    editorConsole.logStructured(level, e.data.message, 'engine', e.data.subsystem, e.data.metadata);
+    return;
+  }
+
+  // Plain console-bridge messages (from game code)
+  if (e.data?.type === 'console-bridge') {
+    const level = BRIDGE_LEVEL_MAP[e.data.level];
+    if (!level) return;
+    editorConsole[level === 'info' ? 'log' : level](e.data.message, 'engine');
+  }
+});
+
+/**
+ * Connect to the editor SSE endpoint and pipe `server-log` events
+ * into the editor console tagged with source 'server'.
+ */
+export function connectServerLogs(): () => void {
+  // Phase A cleanup: browser mode has no Node dev server, so `/__editor/events`
+  // does not exist — an unconditional `EventSource` here would auto-retry
+  // against a dead endpoint forever (the same anti-pattern A2 already fixed
+  // for the CLI/asset/scene SSE consumers via `getEditorMode() === 'browser'`
+  // guards; this one was missed). There is no browser-mode server-log source
+  // to bridge from, so this is a clean skip, not a routed replacement.
+  if (getEditorMode() === 'browser') {
+    return () => {};
+  }
+  const source = connectEvents();
+
+  source.addEventListener('server-log', (e: MessageEvent) => {
+    try {
+      const data = JSON.parse(e.data) as { level: string; message: string };
+      const level = BRIDGE_LEVEL_MAP[data.level];
+      if (!level) return;
+      editorConsole[level === 'info' ? 'log' : level](data.message, 'server');
+    } catch {
+      /* ignore malformed events */
+    }
+  });
+
+  return () => source.close();
+}

package/src/editor-hotkeys.ts

@@ -0,0 +1,441 @@
+import {
+  collectAllNodeIds,
+  getActiveAuthoring,
+  hasAuthoringOverride,
+} from './authoring/active-adapter';
+import { timelineRedo, timelineUndo } from './authoring/undo-timeline';
+import { resetWorldPan } from './authoring/world-pan-state';
+import {
+  boxEditForId,
+  computeArrowNudgePatch,
+  readSpacingValues,
+  rectForId,
+} from './components/world-overlay-gestures';
+import type { EditorStore } from './editor-store';
+import type { EditorViewport } from './editor-viewport';
+import { installHotkeys, registerHotkeys, setActiveScope } from './hotkeys';
+
+/**
+ * D4 (spec27 §6 D4, §8 "Keyboard / undo / pan-zoom" row) — RECONCILED by the
+ * `overlay-panzoom` unit (see `docs/unified-world-editor/27-visual-react-
+ * editing.md` §1 D-E's own reconciliation note and `GOLDEN-GATE.md`).
+ *
+ * Space-pan is BUILT: `WorldSelectionOverlay.tsx`'s own Space-held +
+ * pointer-drag handling (its `spaceHeldRef`/`panDragRef`), writing the shared
+ * `world-pan-state.ts` singleton, which `design-time-layers.ts` applies to
+ * every world-layer host IN LOCKSTEP with the overlay's own wrapper — a pure
+ * CSS `transform: translate()` on both. Not registered here in
+ * `editor-hotkeys.ts`'s `registerHotkeys` array because that registry is a
+ * single-fire-per-keydown dispatcher with no "held" concept (see
+ * `hotkeys.ts`); Space-pan needs a literal hold state, so it follows the
+ * SAME precedent this file's own vertex-snap `V`-key handling below already
+ * set (a raw `window` keydown/keyup pair) — just owned by the overlay
+ * component instead of this file, since the gesture IS a pointer-drag over
+ * the overlay's own interaction layer, not a stateless action like
+ * duplicate/delete/nudge above.
+ *
+ * Zoom-fit/selection is a stated EXCLUDE — evidence checked (not assumed):
+ * the 3D viewport (`ViewportPanel.tsx`/`editor-viewport.ts`) already has a
+ * real zoom substrate (Three.js `OrbitControls`, numpad view presets), so
+ * zoom-fit there is pure duplication, not a gap. The react/DOM world
+ * surface's `RectProvider.rect(id)` is `getBoundingClientRect()`-derived and
+ * host-relative (`react-world-authoring-adapter.ts`'s `toHostRelative`) —
+ * UNLIKE pan (a pure translation, which cancels out of that subtraction with
+ * zero consumer changes, per `world-pan-state.ts`'s own soundness doc
+ * comment), a host `scale()` bakes the zoom factor into every rect AND every
+ * screen-space gesture delta (`toHostLocal`), so it would require an
+ * explicit zoom-aware conversion at all ~14 host-relative chrome consumers
+ * (selection/hover box, 8 handles, rotate, labels, spacing bands, measure
+ * lines, snap guides, badges, parent outline, drag-ghost, reorder marker,
+ * empty-container hints, align-toolbar anchor, marquee) and the 3
+ * screen-delta gesture patches (`computeResizePatch`/`computeMovePatch`/
+ * `computeSpacingPatch`) — a foundation rebase against the ~2360-test unit
+ * suite + the full 27x e2e series (all pinned at the implicit `scale=1`
+ * frame) that is disproportionate to one keyboard-row affordance the
+ * visual-edit reference itself only had live in its own demo host, not its
+ * reusable library. No dead keybinding is registered for it.
+ */
+
+// The five action functions below (`duplicateSelection` … `nudgeSelection`)
+// are exported for two reasons: `registerEditorHotkeys` wires them to their
+// keybindings below, AND `editor-hotkeys.test.ts` unit-tests the
+// capability-gate behavior (structure/boxEdit absent -> no-op) directly
+// against them, without needing a full `EditorViewport`/canvas fixture.
+
+/**
+ * D4 (spec27 §6 D4 "Ctrl+D duplicate, Del/Backspace delete — route through
+ * adapter.structure.* (capability-gated)"): the pre-D4 `'d'`/`'delete'`/
+ * `'backspace'` bindings below called the FIRST-PARTY-only `store.
+ * duplicateEntity`/`store.deleteEntities` directly — a silent no-op for a
+ * react-world/ingest/scene-UI selection (those ids aren't in `store`'s own
+ * `SceneEntity` map). This keeps the first-party path'S existing batched-
+ * undo behavior (`store.deleteEntities` pushes ONE undo entry for the whole
+ * selection; looping the contract's per-id `structure.remove` would instead
+ * push N) byte-identical, and ADDS the override path via `adapter.structure`
+ * (capability-gated — a no-op when absent, e.g. the ingested `react-dom`
+ * adapter, spec:308-309). `store.selectedEntityIds` is the shared,
+ * adapter-routed selection set either way (every adapter's own
+ * `selection.set` funnels into it) — only the ACTION differs by path.
+ */
+export function duplicateSelection(store: EditorStore): void {
+  if (store.selectedEntityIds.size === 0) return;
+  if (hasAuthoringOverride()) {
+    const structure = getActiveAuthoring(store).structure;
+    if (!structure) return;
+    for (const id of store.selectedEntityIds) structure.duplicate(id);
+  } else {
+    for (const id of store.selectedEntityIds) store.duplicateEntity(id);
+  }
+}
+
+/**
+ * D4.R2 (spec27 §6 D4 reopen) — a multi-node override delete prefers the
+ * batched `structure.removeMany` (ONE undo entry for the whole selection,
+ * matching the first-party `store.deleteEntities` batched-undo semantics
+ * below) when the active adapter implements it; falls back to the per-id
+ * `structure.remove` loop for any adapter that doesn't (N undo entries).
+ * `await`ed the same way `remove` is (harmless no-op for a synchronous/
+ * in-memory implementer) — see `StructureProvider.removeMany`'s doc comment.
+ *
+ * SOURCE-CORRUPTION FIX (bug-panel reopen, post-D4.R2) + DELETE-ORDER-
+ * RESIDUAL FIX (bug-panel follow-up, post-50f90a6d): the per-id fallback loop
+ * used to fire `structure.remove(id)` for every id in RAW selection order —
+ * document/top-first, the same order a marquee/DFS walk produces — with NO
+ * `await` between iterations. For an adapter whose per-op target offset is
+ * resolved from an index that is only refreshed by a real reparse (never
+ * between same-file writes — `ReactWorldAuthoringAdapter`'s `OidStore.index`),
+ * that is a real, default-gesture-reachable source-corruption hazard:
+ * deleting an EARLIER element first shifts every LATER element's still-stale
+ * `{line, col}` out from under it, and firing every write in the same tick
+ * can race the underlying network request, letting a later write silently
+ * clobber an earlier one. Both mechanisms are fixed for the fallback loop,
+ * together (see the CORRECTNESS INVARIANT comment on
+ * `ReactWorldAuthoringAdapter.structure`'s per-id `remove` for the full
+ * soundness argument, including its own remaining caveat):
+ *   1. sort `ids` into REVERSE DOCUMENT ORDER (bottom-most/deepest first) —
+ *      derived from the SAME DFS pre-order `collectAllNodeIds` walks (the
+ *      marquee/select-all candidate order), reversed, so a selected
+ *      descendant is always deleted before a selected ancestor;
+ *   2. `await` each `structure.remove(id)` before starting the next, so
+ *      write N only ever begins once write N-1 has landed on disk.
+ * A synchronous/in-memory `remove` (e.g. `UIAuthoringAdapter`'s) is
+ * unaffected — awaiting a non-promise return is a harmless no-op, and its own
+ * `removeMany` batches instead of ever reaching this loop. This fallback loop
+ * is sound ONLY when `collectAllNodeIds`' walk order matches true SOURCE
+ * order — `ReactWorldAuthoringAdapter` now implements `removeMany` (a single
+ * shared-snapshot batched delete, order-independent by construction) exactly
+ * so THIS loop is never reached for it; it stays here, documented and tested,
+ * as the honest degrade for any override adapter that has no batched delete.
+ */
+export async function deleteSelection(store: EditorStore): Promise<void> {
+  if (store.selectedEntityIds.size === 0) return;
+  if (hasAuthoringOverride()) {
+    const adapter = getActiveAuthoring(store);
+    const structure = adapter.structure;
+    if (!structure) return;
+    const ids = [...store.selectedEntityIds];
+    if (structure.removeMany) {
+      await structure.removeMany(ids);
+    } else {
+      // Reverse DOCUMENT order (bottom-most/deepest first) — see this
+      // function's own doc comment. `collectAllNodeIds` walks the adapter's
+      // hierarchy in the same DFS pre-order (parent-before-child, top-first)
+      // a marquee/select-all uses; an id outside that walk (should not
+      // happen — every selected id came FROM this adapter's own hierarchy)
+      // sorts last (rank -1) as a defensive fallback, never a throw.
+      const rank = new Map(collectAllNodeIds(adapter).map((id, i) => [id, i]));
+      const ordered = [...ids].sort((a, b) => (rank.get(b) ?? -1) - (rank.get(a) ?? -1));
+      for (const id of ordered) await structure.remove(id);
+    }
+  } else {
+    store.deleteEntities([...store.selectedEntityIds]);
+  }
+}
+
+/** D4 — `Ctrl+Alt+G` wrap / `Ctrl+Shift+G` unwrap (spec §6 D4, §5 "wrap/
+ *  unwrap ... via `structure.*`"): no first-party equivalent exists (a 3D
+ *  entity can't be "wrapped"), so this is override-only, capability-gated on
+ *  the OPTIONAL `structure.wrap`/`structure.unwrap` (absent for the
+ *  ingested `react-dom` adapter and the first-party threejs adapter alike —
+ *  both correctly no-op). Applies to every selected id, same multi-select
+ *  loop `duplicateSelection`/`deleteSelection` use. */
+export function wrapSelection(store: EditorStore): void {
+  if (store.selectedEntityIds.size === 0) return;
+  const structure = getActiveAuthoring(store).structure;
+  if (!structure?.wrap) return;
+  for (const id of store.selectedEntityIds) structure.wrap(id);
+}
+
+export function unwrapSelection(store: EditorStore): void {
+  if (store.selectedEntityIds.size === 0) return;
+  const structure = getActiveAuthoring(store).structure;
+  if (!structure?.unwrap) return;
+  for (const id of store.selectedEntityIds) structure.unwrap(id);
+}
+
+/**
+ * D4.c (spec §6 D4 "arrow-nudge (↑↓←→, Shift=×10) ... writes margins/
+ * offsets"): nudges every currently-selected id whose owner exposes
+ * `boxEdit` (capability-gated — silently skips ids that don't, e.g. a 3D
+ * entity or an ingested-world node with no spatial write path). Position/
+ * margin math is the pure, independently-tested `computeArrowNudgePatch`
+ * (`world-overlay-gestures.ts`); this function only resolves the per-id
+ * rect/position/margin inputs it needs and brackets the write in a single
+ * `begin`/`apply`/`end` (one undo step per nudged node, per B1/D-1).
+ */
+export function nudgeSelection(store: EditorStore, dx: number, dy: number): void {
+  if (store.selectedEntityIds.size === 0) return;
+  const adapter = getActiveAuthoring(store);
+  for (const id of store.selectedEntityIds) {
+    const boxEdit = boxEditForId(adapter, id);
+    if (!boxEdit) continue;
+    const rect = rectForId(adapter, id);
+    if (!rect) continue;
+    const position = adapter.inspector?.get(id, 'style.position');
+    const isPositioned = position === 'absolute' || position === 'fixed';
+    const spacing = readSpacingValues(adapter, id);
+    const patch = computeArrowNudgePatch(dx, dy, isPositioned, rect, {
+      left: spacing.marginLeft,
+      top: spacing.marginTop,
+    });
+    if (Object.keys(patch).length === 0) continue;
+    boxEdit.begin(id);
+    boxEdit.apply(id, patch);
+    boxEdit.end(id);
+  }
+}
+
+/**
+ * Register all standard editor hotkeys. Returns a dispose function that removes them.
+ * Call once when the viewport is created.
+ */
+export function registerEditorHotkeys(
+  store: EditorStore,
+  viewport: EditorViewport,
+  canvas: HTMLCanvasElement,
+): () => void {
+  const unregister = registerHotkeys([
+    // --- Global (fire regardless of active panel) ---
+    // Undo/redo (T3.2 slice 2): dispatch through the editor-global undo TIMELINE,
+    // NOT `hasAuthoringOverride() ? adapter : store` — the timeline pops whichever
+    // adapter (first-party store / ingest / UI) recorded the MOST RECENT op,
+    // globally, regardless of which one is currently active (docs/
+    // PERSISTENCE-PROVIDER-DESIGN.md §3). Ctrl+Y mirrors Ctrl+Shift+Z (Windows
+    // convention) — see `undo-timeline.ts`.
+    {
+      key: 'z',
+      mod: true,
+      shift: true,
+      scope: 'global',
+      action: () => timelineRedo(),
+    },
+    {
+      key: 'y',
+      mod: true,
+      scope: 'global',
+      action: () => timelineRedo(),
+    },
+    {
+      key: 'z',
+      mod: true,
+      scope: 'global',
+      action: () => timelineUndo(),
+    },
+    {
+      key: 'c',
+      mod: true,
+      scope: 'global',
+      action: () => {
+        if (store.selectedEntityIds.size > 0) store.copyEntities();
+      },
+    },
+    {
+      key: 'x',
+      mod: true,
+      scope: 'global',
+      action: () => {
+        if (store.selectedEntityIds.size > 0) store.cutEntities();
+      },
+    },
+    {
+      key: 'v',
+      mod: true,
+      scope: 'global',
+      action: () => {
+        if (store.hasClipboard) store.pasteEntities();
+      },
+    },
+    {
+      key: 'd',
+      mod: true,
+      scope: 'global',
+      action: () => duplicateSelection(store),
+    },
+    // D4 — wrap/unwrap (override-only, capability-gated — see
+    // `wrapSelection`/`unwrapSelection`'s doc comments).
+    {
+      key: 'g',
+      mod: true,
+      alt: true,
+      scope: 'global',
+      action: () => wrapSelection(store),
+    },
+    {
+      key: 'g',
+      mod: true,
+      shift: true,
+      scope: 'global',
+      action: () => unwrapSelection(store),
+    },
+    // D4 — arrow-nudge (↑↓←→, Shift=×10 — see `nudgeSelection`'s doc comment).
+    { key: 'arrowup', scope: 'global', action: () => nudgeSelection(store, 0, -1) },
+    { key: 'arrowup', shift: true, scope: 'global', action: () => nudgeSelection(store, 0, -10) },
+    { key: 'arrowdown', scope: 'global', action: () => nudgeSelection(store, 0, 1) },
+    { key: 'arrowdown', shift: true, scope: 'global', action: () => nudgeSelection(store, 0, 10) },
+    { key: 'arrowleft', scope: 'global', action: () => nudgeSelection(store, -1, 0) },
+    { key: 'arrowleft', shift: true, scope: 'global', action: () => nudgeSelection(store, -10, 0) },
+    { key: 'arrowright', scope: 'global', action: () => nudgeSelection(store, 1, 0) },
+    {
+      key: 'arrowright',
+      shift: true,
+      scope: 'global',
+      action: () => nudgeSelection(store, 10, 0),
+    },
+    {
+      key: 'a',
+      mod: true,
+      scope: 'global',
+      action: () => {
+        if (hasAuthoringOverride()) {
+          const a = getActiveAuthoring(store);
+          a.selection?.set(collectAllNodeIds(a)); // select all ingested nodes
+        } else store.selectAll();
+      },
+    },
+    { key: 's', mod: true, scope: 'global', action: () => void store.saveNow() },
+    // D4 (spec27 §8 "space-pan" row) — Ctrl+0, the conventional "reset
+    // zoom/pan to 100%" shortcut (browsers/design tools alike), resets the
+    // DOM/react overlay's shared pan translate (`world-pan-state.ts`) back to
+    // `(0, 0)`. A no-op when already at rest or when the active surface has
+    // no pan-capable world (there is nothing for it to affect either way —
+    // `resetWorldPan()` itself no-ops at `(0,0)`).
+    { key: '0', mod: true, scope: 'global', action: () => resetWorldPan() },
+    {
+      key: 'delete',
+      scope: 'global',
+      action: () => void deleteSelection(store),
+    },
+    {
+      key: 'backspace',
+      scope: 'global',
+      action: () => void deleteSelection(store),
+    },
+    {
+      key: 'escape',
+      scope: 'global',
+      // While playing, Escape is owned by play-mode (stop on Escape) — don't also
+      // clear the editor selection out from under the running game.
+      action: () => {
+        if (store.playState === 'stopped') store.select(null);
+      },
+    },
+    {
+      key: 'k',
+      mod: true,
+      scope: 'global',
+      action: () => store.toggleCommandPalette(),
+    },
+    {
+      key: '`',
+      scope: 'global',
+      action: () => window.dispatchEvent(new CustomEvent('editor:toggle-console')),
+    },
+
+    // --- Viewport-scoped (only when viewport/canvas is active) ---
+    {
+      key: 'w',
+      scope: 'viewport',
+      action: () => {
+        if (!viewport.isFlying) store.setTransformMode('translate');
+      },
+    },
+    {
+      key: 'e',
+      scope: 'viewport',
+      action: () => {
+        if (!viewport.isFlying) store.setTransformMode('rotate');
+      },
+    },
+    {
+      key: 'r',
+      scope: 'viewport',
+      action: () => {
+        if (!viewport.isFlying) store.setTransformMode('scale');
+      },
+    },
+    {
+      key: 'f',
+      scope: 'viewport',
+      action: () => store.focusOnSelection(),
+    },
+    {
+      key: 'l',
+      scope: 'viewport',
+      action: () => {
+        if (store.selectedEntityIds.size > 0)
+          for (const id of store.selectedEntityIds) store.toggleLocked(id);
+      },
+    },
+    {
+      key: '.',
+      scope: 'viewport',
+      action: () => {
+        const pivotModes = ['active-element', 'median-point', 'individual-origins'] as const;
+        const idx = pivotModes.indexOf(store.pivotMode);
+        store.setPivotMode(pivotModes[(idx + 1) % pivotModes.length]!);
+      },
+    },
+    { code: 'Numpad7', key: '', scope: 'viewport', action: () => viewport.setViewPreset('top') },
+    { code: 'Numpad1', key: '', scope: 'viewport', action: () => viewport.setViewPreset('front') },
+    {
+      code: 'Numpad3',
+      key: '',
+      scope: 'viewport',
+      action: () => viewport.setViewPreset('right'),
+    },
+    {
+      code: 'Numpad5',
+      key: '',
+      scope: 'viewport',
+      action: () => viewport.setViewPreset('perspective'),
+    },
+  ]);
+
+  const onPointerDown = () => setActiveScope('viewport');
+  canvas.addEventListener('pointerdown', onPointerDown);
+  installHotkeys();
+
+  // Vertex snap: hold V to activate
+  const onKeyDown = (e: KeyboardEvent) => {
+    if (e.key === 'v' && !e.metaKey && !e.ctrlKey && !e.repeat) {
+      if (e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement) return;
+      store.setVertexSnapActive(true);
+      viewport.activateVertexSnap();
+    }
+  };
+  const onKeyUp = (e: KeyboardEvent) => {
+    if (e.key === 'v' && !e.metaKey && !e.ctrlKey) {
+      store.setVertexSnapActive(false);
+      viewport.deactivateVertexSnap();
+    }
+  };
+  window.addEventListener('keydown', onKeyDown);
+  window.addEventListener('keyup', onKeyUp);
+
+  return () => {
+    unregister();
+    canvas.removeEventListener('pointerdown', onPointerDown);
+    window.removeEventListener('keydown', onKeyDown);
+    window.removeEventListener('keyup', onKeyUp);
+  };
+}

package/src/editor-layers.ts

@@ -0,0 +1,2 @@
+/** Layer used for editor-only infrastructure (grid, gizmos, helpers, editor lights). */
+export const EDITOR_LAYER = 31;

package/src/editor-mode.ts

@@ -0,0 +1,28 @@
+/**
+ * Build mode — server-first vs browser-first.
+ *
+ * Two first-class build profiles, distinguished by Vite's `import.meta.env.MODE`
+ * (reliably injected in BOTH dev and build — unlike custom `define`s, which are
+ * not statically replaced by the dev middleware server):
+ *   - 'browser' — the static build (`npm run build:web` → `--mode web`, e.g.
+ *     GitHub Pages). No server; storage defaults to the in-browser OPFS VFS,
+ *     with a seeded Starter and an opt-in "Open folder" (File System Access).
+ *   - 'server'  — everything else: the installed app + `npm run dev`. Assumes a
+ *     Node backend; storage defaults to `HttpStorage` (edits the on-disk project).
+ *
+ * Both share one codebase; only the default backend + first-run behavior differ.
+ */
+
+declare const __VGAI_PROJECT_PATH__: string;
+
+export type EditorMode = 'server' | 'browser';
+
+/** The active build mode. `--mode web` → browser-first; dev/prod → server-first. */
+export function getEditorMode(): EditorMode {
+  return import.meta.env.MODE === 'web' ? 'browser' : 'server';
+}
+
+/** Absolute project root injected by the dev/prod server (empty in browser mode). */
+export function getProjectDefinePath(): string {
+  return typeof __VGAI_PROJECT_PATH__ !== 'undefined' ? __VGAI_PROJECT_PATH__ : '';
+}