@vgai/editor 0.2.0

package/server/session-registry.ts

@@ -0,0 +1,93 @@
+/**
+ * Editor session registry — the file-backed ledger of live editor dev servers
+ * (D12, docs/EDITOR-FIRST-DEV.md). Written by THIS package (dev.ts registers
+ * on listen, re-registers on project switch, unregisters on shutdown); read by
+ * the vgai CLI (its own light reader in packages/vgai-cli/src/editor-sessions.ts —
+ * the CLI deliberately has no editor-package dependency, so the FILE FORMAT
+ * here is the contract: keep the two in sync).
+ *
+ * Format: `~/.vgai/editor-sessions.json`, a JSON array of EditorSession.
+ * Entries are best-effort — every reader must PID-liveness-filter (a crashed
+ * server can't unregister itself), and writers sweep dead entries on write.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export interface EditorSession {
+  /** Canonical project root currently open, or null when none. */
+  project: string | null;
+  port: number;
+  /** PID of the dev-server process (dev.ts's own process.pid). */
+  pid: number;
+  /** ISO timestamp of server start. */
+  startedAt: string;
+}
+
+const REGISTRY_DIR = join(homedir(), '.vgai');
+const REGISTRY_FILE = join(REGISTRY_DIR, 'editor-sessions.json');
+
+export function sessionRegistryPath(): string {
+  return REGISTRY_FILE;
+}
+
+function isSession(v: unknown): v is EditorSession {
+  if (typeof v !== 'object' || v === null) return false;
+  const s = v as Record<string, unknown>;
+  return (
+    (typeof s['project'] === 'string' || s['project'] === null) &&
+    typeof s['port'] === 'number' &&
+    typeof s['pid'] === 'number' &&
+    typeof s['startedAt'] === 'string'
+  );
+}
+
+export function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** All recorded sessions, unvalidated beyond shape (callers liveness-filter). */
+export function readSessions(): EditorSession[] {
+  try {
+    const raw: unknown = JSON.parse(readFileSync(REGISTRY_FILE, 'utf8'));
+    return Array.isArray(raw) ? raw.filter(isSession) : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Sessions whose server process is still alive. */
+export function liveSessions(): EditorSession[] {
+  return readSessions().filter((s) => pidAlive(s.pid));
+}
+
+/**
+ * Record (or refresh) this process's session. Sweeps dead entries and any
+ * stale claim on the same port while it's here.
+ */
+export function registerSession(session: EditorSession): void {
+  try {
+    mkdirSync(REGISTRY_DIR, { recursive: true });
+    const rest = readSessions().filter(
+      (s) => s.pid !== session.pid && s.port !== session.port && pidAlive(s.pid),
+    );
+    writeFileSync(REGISTRY_FILE, `${JSON.stringify([...rest, session], null, 2)}\n`);
+  } catch {
+    // Registry is best-effort — never let bookkeeping kill the server.
+  }
+}
+
+export function unregisterSession(pid: number): void {
+  try {
+    const rest = readSessions().filter((s) => s.pid !== pid);
+    writeFileSync(REGISTRY_FILE, `${JSON.stringify(rest, null, 2)}\n`);
+  } catch {
+    // Best-effort (see registerSession).
+  }
+}

package/src/EditorContext.tsx

@@ -0,0 +1,87 @@
+import { createContext, type ReactNode, Suspense, useContext, useEffect, useRef } from 'react';
+import { connectCommandListener } from './command-listener';
+import { EditorStore } from './editor-store';
+import { initProject } from './initial-scene';
+import { type InteractiveEditScope, InteractiveEditScopeContext } from './interactive-edit-scope';
+
+export interface EditorStats {
+  fps: number;
+  frameTime: number;
+  drawCalls: number;
+  triangles: number;
+  cameraPosition: { x: number; y: number; z: number };
+  cameraTarget: { x: number; y: number; z: number };
+}
+
+interface EditorContextValue {
+  store: EditorStore;
+  stats: EditorStats;
+  initPromise: Promise<void>;
+}
+
+const EditorContext = createContext<EditorContextValue | null>(null);
+
+export function EditorProvider({ children }: { children: ReactNode }) {
+  const storeRef = useRef<EditorStore | null>(null);
+  if (!storeRef.current) storeRef.current = new EditorStore();
+
+  const statsRef = useRef<EditorStats | null>(null);
+  if (!statsRef.current) {
+    statsRef.current = {
+      fps: 0,
+      frameTime: 0,
+      drawCalls: 0,
+      triangles: 0,
+      cameraPosition: { x: 0, y: 0, z: 0 },
+      cameraTarget: { x: 0, y: 0, z: 0 },
+    };
+  }
+
+  const initRef = useRef<Promise<void> | null>(null);
+  if (!initRef.current) {
+    initRef.current = initProject();
+  }
+
+  // The shallow undo-gesture seam the shared widget kit consumes instead of
+  // this (deep) context — see interactive-edit-scope.ts's doc comment (W3).
+  const editScopeRef = useRef<InteractiveEditScope | null>(null);
+  if (!editScopeRef.current) {
+    const store = storeRef.current;
+    editScopeRef.current = {
+      begin: () => store.beginInteractiveEdit(),
+      end: () => store.endInteractiveEdit(),
+    };
+  }
+
+  useEffect(() => {
+    return connectCommandListener(storeRef.current!);
+  }, []);
+
+  return (
+    <EditorContext.Provider
+      value={{ store: storeRef.current, stats: statsRef.current, initPromise: initRef.current }}
+    >
+      <InteractiveEditScopeContext.Provider value={editScopeRef.current}>
+        <Suspense>{children}</Suspense>
+      </InteractiveEditScopeContext.Provider>
+    </EditorContext.Provider>
+  );
+}
+
+export function useEditorStore(): EditorStore {
+  const ctx = useContext(EditorContext);
+  if (!ctx) throw new Error('useEditorStore must be used within <EditorProvider>');
+  return ctx.store;
+}
+
+export function useEditorStats(): EditorStats {
+  const ctx = useContext(EditorContext);
+  if (!ctx) throw new Error('useEditorStats must be used within <EditorProvider>');
+  return ctx.stats;
+}
+
+export function useEditorInit(): Promise<void> {
+  const ctx = useContext(EditorContext);
+  if (!ctx) throw new Error('useEditorInit must be used within <EditorProvider>');
+  return ctx.initPromise;
+}

package/src/achieved-tier.ts

@@ -0,0 +1,126 @@
+/**
+ * Achieved-tier verification — T3.4 slice 1 (docs/ADAPTER-AUTHORING-DESIGN.md
+ * §1.C). A `{ module }` adapter self-certifies its `capabilities.{local,hosted}`
+ * tier at manifest-author time (the loader requires it explicitly — there is no
+ * derivable ceiling, `packages/engine/src/manifest/load.ts`'s `resolveCapabilities`).
+ * Nothing checks that self-certification against reality UNTIL NOW: this module
+ * computes the tier a `MountedGame` ACTUALLY reaches, straight from the
+ * `AuthoringAdapter` surface it returned from `mount()`, and logs a shortfall
+ * loudly (never silently) when achieved < declared.
+ *
+ * The three-band mapping (§1.C, "roughly: full authoring incl.
+ * transforms+inspector+persistence -> first-party reach; hierarchy-only ->
+ * shared-tier reach; no authoring -> opaque-embed reach") is made exact here:
+ *
+ *   - no `authoring` at all                                -> 'opaque-embed'
+ *     (docs/CAPABILITY-TIERS.md §b: "None — embed + lifecycle only ... no
+ *     reachable scene to capture").
+ *   - `authoring` present, but missing `transforms`, `inspector`, OR
+ *     `persistence`                                         -> 'shared'
+ *     (§b: "Full — in-realm capture + editing" is `shared`'s row; a partial
+ *     authoring surface still reaches in-realm editing on whatever it DOES
+ *     provide, so it is not honestly opaque, but it has not earned the
+ *     `first-party` floor's full round-trip either).
+ *   - `authoring` with ALL of `transforms`+`inspector`+`persistence`
+ *                                                            -> 'first-party'
+ *     (§b: "Full — native SceneEntity + gizmo ... .vscn is the source of
+ *     truth" — a module adapter obviously has no `.vscn`, but this is the
+ *     ceiling band a custom adapter can claim: full editing + full
+ *     persistence route, mirrored for a non-first-party mount).
+ *
+ * `docs/achieved-tier-doc-pin.test.ts`-style coverage lives in
+ * `packages/engine/test/capability-tiers-achieved-mapping-doc-pin.test.ts`,
+ * pinning this banding's tier names + the doc's per-tier "Inspector / gizmo
+ * editing" language against this file, the same way
+ * `capability-tiers-doc-pin.test.ts` pins the ceiling table.
+ */
+
+import type { MountedGame } from '@engine/adapter';
+import type { Tier } from '@engine/manifest/schema';
+
+// Deliberately NO import of `./editor-console` here: that module touches
+// `window` unconditionally at its top level (a house rule this file must
+// respect — `adapter-resolver.ts`, this module's first caller, is imported
+// by headless Node/vitest suites with no `window` stub, e.g.
+// `adapter-resolver.test.ts`/`adapter-resolver-pixi.test.ts`). This module
+// stays a PURE computation + message-formatting library; callers that already
+// own an `editorConsole` import (or a browser environment) do the actual
+// logging (see `adapter-resolver.ts`'s `withAchievedTierCheck` and
+// `ingest-mode.ts`'s embed-only retrofit).
+
+/** The exact three achieved bands this slice's check can produce. */
+export type AchievedTier = Extract<Tier, 'first-party' | 'shared' | 'opaque-embed'>;
+
+/** Total order over `Tier` — same ranking as `CAPABILITY_CEILINGS`'s consumer
+ *  (docs/CAPABILITY-TIERS.md §a: `first-party > shared ~= deduped >
+ *  iframe-reachable > opaque-embed > unsupported`). Duplicated (not imported)
+ *  because `packages/engine/src/manifest/load.ts`'s `TIER_RANK` is module-private. */
+const TIER_RANK: Record<Tier, number> = {
+  'first-party': 5,
+  shared: 4,
+  deduped: 4,
+  'iframe-reachable': 3,
+  'opaque-embed': 2,
+  unsupported: 1,
+};
+
+/**
+ * Compute the ACHIEVED tier from a mounted game's actual `authoring` surface
+ * (§1.C's exact banding — see this file's doc comment). Pure function of the
+ * `MountedGame` shape; does not itself log — call {@link reportTierShortfall}
+ * with the result to get the structured log this slice's AC requires.
+ */
+export function computeAchievedTier(mounted: Pick<MountedGame, 'authoring'>): AchievedTier {
+  const { authoring } = mounted;
+  if (!authoring) return 'opaque-embed';
+  if (authoring.transforms && authoring.inspector && authoring.persistence) return 'first-party';
+  return 'shared';
+}
+
+/**
+ * Structured shortfall payload — ONE shape, greppable, used by BOTH the
+ * module-adapter achieved-tier check (adapter-resolver.ts) and the ingest
+ * embed-only degradation retrofit (ingest-mode.ts's
+ * `enterIngestModeWithGame`), per §1.C: "mirroring the ingest `embedOnly`
+ * precedent but carrying the actual enum values ... the existing embed-only
+ * fallback gains the same structured tier log." A no-op (`null`) when
+ * `achieved` is not below `declared` (over-claiming survives silently right
+ * up until it's caught — under-claiming, including exact matches, is never
+ * reported as a shortfall).
+ */
+export interface TierShortfallReport {
+  worldId: string;
+  declaredTier: Tier;
+  achievedTier: Tier;
+}
+
+/** Greppable prefix shared by every shortfall log line this slice produces. */
+export const TIER_SHORTFALL_PREFIX = 'tier-shortfall';
+
+/**
+ * Compute the shortfall report (or `null` if there is none) — pure, no
+ * logging. `formatTierShortfallMessage` turns a non-null report into the ONE
+ * log-line shape; callers own the actual `editorConsole.warn(...)` call (see
+ * this file's doc comment for why the logging call isn't made HERE).
+ */
+export function computeTierShortfall(
+  worldId: string,
+  declared: Tier,
+  achieved: Tier,
+): TierShortfallReport | null {
+  const achievedRank: number = TIER_RANK[achieved];
+  const declaredRank: number = TIER_RANK[declared];
+  if (achievedRank >= declaredRank) return null;
+  return { worldId, declaredTier: declared, achievedTier: achieved };
+}
+
+/** The one shared message shape: `tier-shortfall world "<id>" declared "<X>"
+ *  but only achieved "<Y>" ... tier-shortfall {"worldId":...}` (greppable on
+ *  the `tier-shortfall` prefix, JSON-parseable on the trailing payload). */
+export function formatTierShortfallMessage(report: TierShortfallReport): string {
+  return (
+    `${TIER_SHORTFALL_PREFIX} world "${report.worldId}" declared "${report.declaredTier}" but ` +
+    `only achieved "${report.achievedTier}" — mounting at the achieved tier ` +
+    `(docs/ADAPTER-AUTHORING-DESIGN.md §1.C). ${TIER_SHORTFALL_PREFIX} ${JSON.stringify(report)}`
+  );
+}

package/src/action-registry.ts

@@ -0,0 +1,268 @@
+import { timelineRedo, timelineUndo } from './authoring/undo-timeline';
+import type { EditorStore } from './editor-store';
+
+export interface EditorAction {
+  id: string;
+  label: string;
+  category: 'action' | 'entity' | 'asset';
+  shortcut?: string;
+  execute: () => void;
+}
+
+const RECENT_KEY = 'editor:recent-actions';
+const MAX_RECENT = 10;
+
+export function getRecentActionIds(): string[] {
+  try {
+    return JSON.parse(localStorage.getItem(RECENT_KEY) ?? '[]') as string[];
+  } catch {
+    return [];
+  }
+}
+
+export function pushRecentAction(id: string): void {
+  const recent = getRecentActionIds().filter((r) => r !== id);
+  recent.unshift(id);
+  if (recent.length > MAX_RECENT) recent.length = MAX_RECENT;
+  localStorage.setItem(RECENT_KEY, JSON.stringify(recent));
+}
+
+/** Build the static list of editor command actions. */
+export function buildStaticActions(store: EditorStore): EditorAction[] {
+  const isMac = navigator.platform.includes('Mac');
+  const mod = isMac ? '\u2318' : 'Ctrl+';
+
+  return [
+    {
+      id: 'editor.undo',
+      label: 'Undo',
+      category: 'action',
+      shortcut: `${mod}Z`,
+      // T3.2 slice 2: through the editor-global timeline, NOT `store.undo()`
+      // directly \u2014 same reasoning as the Ctrl+Z hotkey (docs/
+      // PERSISTENCE-PROVIDER-DESIGN.md \u00A73): whichever adapter (first-party/
+      // ingest/UI) recorded the most recent op, not always the first-party store.
+      execute: () => timelineUndo(),
+    },
+    {
+      id: 'editor.redo',
+      label: 'Redo',
+      category: 'action',
+      shortcut: `${mod}\u21E7Z`,
+      execute: () => timelineRedo(),
+    },
+    {
+      id: 'editor.copy',
+      label: 'Copy',
+      category: 'action',
+      shortcut: `${mod}C`,
+      execute: () => {
+        if (store.selectedEntityIds.size > 0) store.copyEntities();
+      },
+    },
+    {
+      id: 'editor.cut',
+      label: 'Cut',
+      category: 'action',
+      shortcut: `${mod}X`,
+      execute: () => {
+        if (store.selectedEntityIds.size > 0) store.cutEntities();
+      },
+    },
+    {
+      id: 'editor.paste',
+      label: 'Paste',
+      category: 'action',
+      shortcut: `${mod}V`,
+      execute: () => {
+        if (store.hasClipboard) store.pasteEntities();
+      },
+    },
+    {
+      id: 'editor.duplicate',
+      label: 'Duplicate',
+      category: 'action',
+      shortcut: `${mod}D`,
+      execute: () => {
+        for (const id of store.selectedEntityIds) store.duplicateEntity(id);
+      },
+    },
+    {
+      id: 'editor.delete',
+      label: 'Delete Selected',
+      category: 'action',
+      shortcut: 'Del',
+      execute: () => {
+        if (store.selectedEntityIds.size > 0) store.deleteEntities([...store.selectedEntityIds]);
+      },
+    },
+    {
+      id: 'editor.select-all',
+      label: 'Select All',
+      category: 'action',
+      shortcut: `${mod}A`,
+      execute: () => store.selectAll(),
+    },
+    {
+      id: 'editor.deselect',
+      label: 'Deselect All',
+      category: 'action',
+      shortcut: 'Esc',
+      execute: () => store.select(null),
+    },
+    {
+      id: 'mode.translate',
+      label: 'Translate Mode',
+      category: 'action',
+      shortcut: 'W',
+      execute: () => store.setTransformMode('translate'),
+    },
+    {
+      id: 'mode.rotate',
+      label: 'Rotate Mode',
+      category: 'action',
+      shortcut: 'E',
+      execute: () => store.setTransformMode('rotate'),
+    },
+    {
+      id: 'mode.scale',
+      label: 'Scale Mode',
+      category: 'action',
+      shortcut: 'R',
+      execute: () => store.setTransformMode('scale'),
+    },
+    {
+      id: 'mode.world',
+      label: 'World Space',
+      category: 'action',
+      execute: () => store.setTransformSpace('world'),
+    },
+    {
+      id: 'mode.local',
+      label: 'Local Space',
+      category: 'action',
+      execute: () => store.setTransformSpace('local'),
+    },
+    {
+      id: 'toggle.grid',
+      label: 'Toggle Grid',
+      category: 'action',
+      execute: () => store.toggleGrid(),
+    },
+    {
+      id: 'toggle.helpers',
+      label: 'Toggle Helpers',
+      category: 'action',
+      execute: () => store.toggleHelpers(),
+    },
+    {
+      id: 'toggle.stats',
+      label: 'Toggle Stats Overlay',
+      category: 'action',
+      execute: () => store.toggleStats(),
+    },
+    {
+      id: 'toggle.snap',
+      label: 'Toggle Snap',
+      category: 'action',
+      execute: () => store.toggleSnap(),
+    },
+    {
+      id: 'toggle.surface-snap',
+      label: 'Toggle Surface Snap',
+      category: 'action',
+      execute: () => store.toggleSnapToSurface(),
+    },
+    {
+      id: 'shading.solid',
+      label: 'Solid Shading',
+      category: 'action',
+      execute: () => store.setShadingMode('solid'),
+    },
+    {
+      id: 'shading.wireframe',
+      label: 'Wireframe Shading',
+      category: 'action',
+      execute: () => store.setShadingMode('wireframe'),
+    },
+    {
+      id: 'shading.unlit',
+      label: 'Unlit Shading',
+      category: 'action',
+      execute: () => store.setShadingMode('unlit'),
+    },
+    {
+      id: 'view.top',
+      label: 'Top View',
+      category: 'action',
+      shortcut: 'Num7',
+      execute: () => store.setViewPreset('top'),
+    },
+    {
+      id: 'view.front',
+      label: 'Front View',
+      category: 'action',
+      shortcut: 'Num1',
+      execute: () => store.setViewPreset('front'),
+    },
+    {
+      id: 'view.right',
+      label: 'Right View',
+      category: 'action',
+      shortcut: 'Num3',
+      execute: () => store.setViewPreset('right'),
+    },
+    {
+      id: 'view.perspective',
+      label: 'Perspective View',
+      category: 'action',
+      shortcut: 'Num5',
+      execute: () => store.setViewPreset('perspective'),
+    },
+    {
+      id: 'focus.selected',
+      label: 'Focus Selected',
+      category: 'action',
+      shortcut: 'F',
+      execute: () => store.focusOnSelection(),
+    },
+    {
+      id: 'toggle.console',
+      label: 'Toggle Console',
+      category: 'action',
+      shortcut: '`',
+      execute: () => {
+        window.dispatchEvent(new CustomEvent('editor:toggle-console'));
+      },
+    },
+    {
+      id: 'build.web',
+      label: 'Build for Web (itch.io)',
+      category: 'action',
+      execute: () => {
+        window.dispatchEvent(new CustomEvent('editor:show-build-tab'));
+      },
+    },
+    {
+      id: 'build.steam',
+      label: 'Build for Desktop (Steam)',
+      category: 'action',
+      execute: () => {
+        window.dispatchEvent(new CustomEvent('editor:show-build-tab'));
+      },
+    },
+  ];
+}
+
+/** Build dynamic entity actions from the current scene. */
+export function buildEntityActions(store: EditorStore): EditorAction[] {
+  return store.allEntities().map((entity) => ({
+    id: `entity:${entity.id}`,
+    label: entity.name,
+    category: 'entity' as const,
+    execute: () => {
+      store.select(entity.id!);
+      store.focusOnEntity(entity.id!);
+    },
+  }));
+}