@volter/editor-core 0.5.57

package/src/hmr-registration-group.ts

@@ -0,0 +1,67 @@
+/**
+ * Owns a module's registry contributions across Vite Fast Refresh.
+ *
+ * A module-local `registered` boolean is not sufficient: Vite may reload the
+ * contributor without reloading the registry (duplicates), or reload the
+ * registry without reloading the contributor (missing entries). Tracking the
+ * unregister callbacks in `import.meta.hot.data` gives the contribution one
+ * explicit lifetime and keeps strict duplicate-id checks meaningful.
+ */
+
+export interface HmrRegistrationContext {
+  readonly data?: Record<string, unknown>;
+  dispose(callback: (data: Record<string, unknown>) => void): void;
+}
+
+export interface HmrRegistrationGroup {
+  ensure(register: (track: (unregister: () => void) => void) => void): void;
+  reset(): void;
+}
+
+interface PersistedRegistrationGroup {
+  dispose(): void;
+}
+
+export function createHmrRegistrationGroup(
+  hot: HmrRegistrationContext | undefined,
+  key: string,
+): HmrRegistrationGroup {
+  const persistedKey = `vgai:registration-group:${key}`;
+  // Test runners and non-Vite hosts can expose a partial `import.meta.hot`
+  // shim without `data`. In that case the group still owns its local
+  // registrations, but there is no cross-refresh persistence to maintain.
+  const hotData = hot?.data;
+  const previous = hotData?.[persistedKey] as PersistedRegistrationGroup | undefined;
+  previous?.dispose();
+
+  let active = false;
+  let unregisters: Array<() => void> = [];
+
+  const reset = () => {
+    active = false;
+    const owned = unregisters;
+    unregisters = [];
+    for (let i = owned.length - 1; i >= 0; i--) owned[i]!();
+  };
+
+  const group: HmrRegistrationGroup = {
+    ensure(register) {
+      if (active) return;
+      active = true;
+      try {
+        register((unregister) => unregisters.push(unregister));
+      } catch (error) {
+        reset();
+        throw error;
+      }
+    },
+    reset,
+  };
+
+  if (hotData) {
+    hotData[persistedKey] = { dispose: reset } satisfies PersistedRegistrationGroup;
+    hot.dispose(reset);
+  }
+
+  return group;
+}

package/src/hmr-stable-react-context.ts

@@ -0,0 +1,23 @@
+import { type Context, createContext } from 'react';
+
+/**
+ * Preserve a React context object across Vite module replacement.
+ *
+ * A provider from the previous module generation can remain mounted while a
+ * freshly imported consumer renders. If both generations call
+ * `createContext()`, the consumer observes a different context and falsely
+ * reports that it is outside the provider. Vite keeps `import.meta.hot.data`
+ * for exactly this kind of module-local state handoff.
+ */
+export function createHmrStableReactContext<T>(
+  hotData: Record<string, unknown> | undefined,
+  key: string,
+  defaultValue: T,
+): Context<T> {
+  const existing = hotData?.[key];
+  if (existing) return existing as Context<T>;
+
+  const context = createContext(defaultValue);
+  if (hotData) hotData[key] = context;
+  return context;
+}

package/src/hotkeys.ts

@@ -0,0 +1,188 @@
+let _installed = false;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type HotkeyScope =
+  | 'viewport'
+  | 'hierarchy'
+  | 'inspector'
+  | 'asset-browser'
+  | 'workspace'
+  | 'global';
+
+const HOTKEY_SCOPES = new Set<HotkeyScope>([
+  'viewport',
+  'hierarchy',
+  'inspector',
+  'asset-browser',
+  'workspace',
+  '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(s) this binding belongs to. `'global'` bindings fire regardless of panel focus. */
+  scope: HotkeyScope | readonly HotkeyScope[];
+  /** Action to execute when the binding matches. */
+  action: (e: KeyboardEvent) => void;
+  /** Optional runtime gate. When it returns false, the binding yields to the
+   * browser and does not call preventDefault(). Use this for commands whose
+   * shortcut overlaps native behavior, such as Copy with a DOM text selection. */
+  when?: (e: KeyboardEvent) => boolean;
+  /** Allow this binding while a form control/contenteditable owns focus.
+   * Reserved for commands such as Save that are expected inside editors. */
+  allowInEditable?: boolean;
+  /** Human-readable label for menus / tooltips. */
+  label?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Active scope (which panel was last interacted with)
+// ---------------------------------------------------------------------------
+
+let _activeScope: HotkeyScope = 'viewport';
+
+const ACTIVE_SCOPE_DATA_KEY = 'editorActiveHotkeyScope';
+
+export function getActiveScope(): HotkeyScope {
+  const shared = document.documentElement.dataset[ACTIVE_SCOPE_DATA_KEY];
+  if (shared && HOTKEY_SCOPES.has(shared as HotkeyScope)) return shared as HotkeyScope;
+  return _activeScope;
+}
+
+export function setActiveScope(scope: HotkeyScope): void {
+  _activeScope = scope;
+  // Vite can temporarily retain both pre- and post-HMR module instances.
+  // The editor shell is the durable ownership authority, so mirror the value
+  // onto the shared document rather than trusting one module-local singleton.
+  document.documentElement.dataset[ACTIVE_SCOPE_DATA_KEY] = scope;
+}
+
+/** True when a DOM target belongs to a native text-editing surface. Shared
+ * by the global dispatcher and panel-local handlers so bubbled Backspace,
+ * Delete, and clipboard shortcuts cannot mutate editor state while typing. */
+/**
+ * Fields that COMMIT PER KEYSTROKE — the inspector's numeric transform/prop
+ * inputs — carry no meaningful native text-undo: they are controlled inputs
+ * whose value is re-rendered from committed state, so the browser's own
+ * Cmd+Z is a dead key inside them. Marking one with this attribute lets the
+ * app's undo/redo bindings fire while it holds focus (measured 2026-08-27:
+ * after typing a transform value, undo silently did nothing until the field
+ * was blurred). Everything else keeps the editable guard — a rename box or a
+ * chat composer must keep native text undo.
+ */
+export const APP_UNDO_PASSTHROUGH_ATTR = 'data-editor-app-undo';
+
+/** True when `target` sits inside a field that opted into app undo/redo. */
+export function allowsAppUndoWhileEditable(target: EventTarget | null): boolean {
+  return target instanceof Element && target.closest(`[${APP_UNDO_PASSTHROUGH_ATTR}]`) !== null;
+}
+
+export function isEditableTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof Element)) return false;
+  if (
+    target instanceof HTMLInputElement ||
+    target instanceof HTMLTextAreaElement ||
+    target instanceof HTMLSelectElement
+  ) {
+    return true;
+  }
+  if (target instanceof HTMLElement && target.isContentEditable) return true;
+  return Boolean(target.closest('[contenteditable]:not([contenteditable="false"])'));
+}
+
+function scopeFromOwnershipEvent(event: Event): HotkeyScope | null {
+  for (const target of event.composedPath()) {
+    if (!(target instanceof HTMLElement)) continue;
+    // A layout host moves focus through internal navigation sentinels that
+    // sit directly under the shell. A focusin on that infrastructure must not
+    // erase the concrete panel established by the preceding pointerdown.
+    // Pointerdown still uses the fallback, so genuinely clicking unclaimed
+    // chrome neutralizes authoring commands as intended.
+    if (event.type === 'focusin' && target.hasAttribute('data-editor-hotkey-fallback')) continue;
+    const candidate = target.dataset['editorHotkeyScope'];
+    if (candidate && HOTKEY_SCOPES.has(candidate as HotkeyScope)) {
+      return candidate as HotkeyScope;
+    }
+  }
+  return null;
+}
+
+function handleOwnershipEvent(event: Event): void {
+  const scope = scopeFromOwnershipEvent(event);
+  if (scope) setActiveScope(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);
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Play-mode bare-key yield (owner ruling, 2026-08-30)
+// ---------------------------------------------------------------------------
+
+/**
+ * While Play runs and the GAME holds the keyboard, bare-key shell bindings
+ * yield — W/E/R belong to the game, not the transform gizmo — and ⌘/Ctrl
+ * chords stay the editor's (undo, save, palette). The predicate lives with
+ * play-mode (which owns play/tab state); this module stays dependency-free
+ * and just asks. Registered null ⇒ no yield (editor-only sessions, tests).
+ */
+/**
+ * Attach the scope-ownership listeners. Call once at startup.
+ *
+ * THERE IS NO KEYDOWN LISTENER HERE, and that is the whole shape of this
+ * module: VS Code's keybinding service is the one keyboard, and every editor
+ * action reaches it as a `vgai.<id>` command with a `when` clause over our
+ * panes' context keys (`scripts/workbench/generate-keymaps.mjs` writes one rule per
+ * (action, chord, keymap) into a built-in extension). A second window-level
+ * listener here would be the second owner the ruling forbids — and it was
+ * measured as exactly that: `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.
+ *
+ * The SCOPE listeners are still ours and still needed: `getActiveScope()` is
+ * read by panel chrome as well as by the frame's `when` clauses, and they
+ * consume no keys. Ownership is captured before React's panel-local bubble
+ * handlers run, so the closest declarative scope in the composed path wins and
+ * the shell's `workspace` marker is a safe neutral fallback.
+ */
+export function installHotkeys(): void {
+  if (_installed) return;
+  window.addEventListener('pointerdown', handleOwnershipEvent, true);
+  window.addEventListener('focusin', handleOwnershipEvent, true);
+  _installed = true;
+}
+
+/** Detach the scope-ownership listeners. */
+export function uninstallHotkeys(): void {
+  window.removeEventListener('pointerdown', handleOwnershipEvent, true);
+  window.removeEventListener('focusin', handleOwnershipEvent, true);
+  _installed = false;
+}

package/src/inference-diagnostics.ts

@@ -0,0 +1,69 @@
+/**
+ * THE FALLBACK RUNG IS LOUD.
+ *
+ * ARCHITECTURE-CORE §The editor protocol, "Zero inference": the runtime answers
+ * a question by reading a declaration, walking ground truth, or diagnosing
+ * declared-vs-measured drift — loudly. A few editor surfaces still end in a
+ * text heuristic when no declaration reaches them: the inspector's widget type
+ * for a prop whose component declares nothing usable, and a design token's
+ * category when neither its name nor its value settles it.
+ *
+ * Those heuristics stay (a guessed widget still beats a blank row), but they
+ * stop being SILENT. A silent guess is indistinguishable from a declaration
+ * that worked, so nobody ever learns which rows are load-bearing and which are
+ * the editor improvising — and the guess is exactly the thing an author could
+ * have stated. Reporting names the file, the subject, and what was guessed, so
+ * the fix is one edit away.
+ *
+ * It goes to the editor's OWN Console panel, not `window.console`: the editor's
+ * doors answer questions about the editor. Warn-once per (where, what, guess),
+ * because inspector rows rebuild on every selection and a per-frame repeat
+ * would be noise rather than a signal.
+ */
+
+import { editorConsole } from './editor-console';
+
+const warned = new Set<string>();
+
+/**
+ * The warn-once key for one (where, what, guess) triple.
+ *
+ * `JSON.stringify` of the tuple rather than a joined string: the three parts are
+ * free text, so any plain separator (`:`, `|`) can appear inside one of them and
+ * collapse two distinct guesses into one key. JSON quotes and escapes each part,
+ * which makes the encoding unambiguous — and keeps this module PLAIN TEXT. The
+ * separator this replaced was a raw NUL byte typed into the source literal,
+ * which made git classify the whole file as BINARY (`Bin 0 -> 2281 bytes`, no
+ * reviewable diff, no `.gitattributes` text normalization) while rendering as an
+ * innocent space in every editor — so the next person to touch the line would
+ * have deleted the separator without ever seeing it.
+ */
+function warnKey(where: string, what: string, guess: string): string {
+  return JSON.stringify([where, what, guess]);
+}
+
+/**
+ * Report that a widget/category was GUESSED from text because no declaration
+ * covered it.
+ *
+ * @param where  Project-relative file (or other addressable location).
+ * @param what   The subject inside it — a prop name, a token name.
+ * @param guess  What the heuristic settled on, in the vocabulary the reader
+ *               sees on screen.
+ */
+export function warnGuessedFromText(where: string, what: string, guess: string): void {
+  const key = warnKey(where, what, guess);
+  if (warned.has(key)) return;
+  warned.add(key);
+  editorConsole.warn(
+    `No declaration covers \`${what}\` in ${where}, so the editor GUESSED \`${guess}\` from its ` +
+      'text. Declare it (a typed prop on the component, a token value that states its own kind) ' +
+      'and the editor reads the declaration instead of a heuristic.',
+    'inspector',
+  );
+}
+
+/** Test seam: forget what has already been reported. */
+export function __resetInferenceDiagnosticsForTest(): void {
+  warned.clear();
+}

package/src/initial-project.ts

@@ -0,0 +1,80 @@
+/**
+ * Editor project bootstrap: detect the open project before the editor builds
+ * anything.
+ */
+
+import { editorConsole } from './editor-console';
+import { detectServerProject, getCurrentProject } from './project-manager';
+
+/**
+ * Resolves once the boot-time project bootstrap has SETTLED (either outcome).
+ *
+ * The gate is OPEN until {@link bootstrapProject} arms it (`_projectBootstrap`
+ * starts resolved), and that is deliberate: a closed-until-armed initial value
+ * has no non-hanging form — nothing can prove a bootstrap will ever arrive, so
+ * any caller in a context that never boots the editor would wait forever.
+ * The safety comes from an ordering invariant one level up instead:
+ * `EditorProvider` calls `bootstrapProject()` in its RENDER BODY, so every
+ * descendant lifecycle — Play's binding on the store's arrival, the `?play=1`
+ * autoplay effect, `connectCommandListener`'s `vgai play` relay — observes an
+ * already-armed gate, and `DefaultEditorLayout` additionally SUSPENDS on the
+ * same promise via `use(useEditorInit())`. Moving that call into a `useEffect`
+ * would break this silently (effects run child-first), which is why the
+ * invariant is pinned by `test/editor-boot-gate-arming.test.tsx`.
+ */
+export function projectBootstrapSettled(): Promise<void> {
+  return _projectBootstrap;
+}
+
+let _projectBootstrap: Promise<void> = Promise.resolve();
+
+/**
+ * The editor's boot-time project bootstrap: detect the project.
+ * Tracked by `projectBootstrapSettled()` so play-mode (and any
+ * other caller that must not observe a half-booted editor) can await it.
+ *
+ * Settlement tracker only — this caller still observes its OWN failure through
+ * the returned promise (same convention as play-mode's `_enterQueue`).
+ */
+export function bootstrapProject(): Promise<void> {
+  const run = bootstrapProjectInner();
+  _projectBootstrap = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  return run;
+}
+
+async function bootstrapProjectInner(): Promise<void> {
+  await initProject();
+}
+
+/** Detect the active project and log the result.
+ *
+ * The only fallback detection left is ASKING THE SESSION: a local
+ * editor server holds which project is open, so there is nothing else to
+ * consult. This used to read `getProjectPathFromURL()` first, which on the
+ * HOSTED build handed an example ID to `openProject()` as if it were a
+ * filesystem path — reachable only if AppRoot had not already resolved the
+ * project, which is why it never bit. Both halves are gone with the param.
+ */
+export async function initProject(): Promise<void> {
+  // If the project manager already has a project (AppRoot resolved one),
+  // just log it and return — no need to re-detect.
+  const existing = getCurrentProject();
+  if (existing) {
+    editorConsole.log(`Opened project: ${existing.config.name}`, 'project');
+    return;
+  }
+
+  // Hosted has no server to ask; AppRoot's `detectProject` owns that surface.
+
+  try {
+    const project = await detectServerProject();
+    if (project) {
+      editorConsole.log(`Opened project: ${project.config.name}`, 'project');
+    }
+  } catch {
+    // No server project — run without a project
+  }
+}