@vgai/editor 0.2.0

package/src/ingest/types.ts

@@ -0,0 +1,127 @@
+import type { ExtraDepsResolution2D } from '@engine/world2d/ingest2d';
+
+/**
+ * The `IngestGame` descriptor — the mountable shape `ingest-mode.ts`
+ * (`enterIngestModeWithGame`) and `authoring/ingest-game-adapter.ts`
+ * (`mountIngestGame`) consume, regardless of where it came from.
+ *
+ * T3.3 slice 3 (docs/CLI-ON-FOLDER-DESIGN.md §1E) moved this type out of the
+ * now-deleted `ingest/games/registry.ts` (the static `INGEST_GAMES` array) —
+ * it used to be registry-specific; now it is the common contract BOTH
+ * discovery frontends build: `ingest/discovery.ts`'s glob-based discovery of
+ * the in-tree fixture games under `ingest/games/<id>/vgai.game.json`, and
+ * `adapter-resolver.ts`'s `resolveIngestDescriptor`, which builds the same
+ * shape from an arbitrary manifest's `ingest-three` world (the CLI-on-folder
+ * route, for a game folder never registered in source).
+ *
+ * D-W1/D-W2 (docs/WAVE4-FTUE-HARDENING-DESIGN.md) add the PREBUILT-BUNDLE
+ * iframe-reachable fields (`bundleUrl`/`baseHref`/`assetBaseUrl`/`bodyHtml`/
+ * `extraDeps`) — the three-side mirror of `IngestGame2D`'s Track-P fields
+ * (`@engine/world2d/ingest2d.ts`) — and widen `embedHtml` to admit a LAZY
+ * thunk alongside its original plain-string form (see that field's own doc
+ * comment for why both shapes must keep working).
+ */
+export interface IngestGame {
+  /** Stable id (used by the launcher + conformance test; == the manifest world id). */
+  id: string;
+  /** Human label shown in the editor's "Ingest game" menu (== the manifest's game name). */
+  name: string;
+  /** One-line description (== the manifest world's optional `description`, or `''`). */
+  description: string;
+  /**
+   * Dynamically import + run the unmodified game module (shared-`three`/deduped path).
+   * Omitted for `embedHtml`/`iframeReachableSrc` games (opaque-embed/iframe-reachable).
+   */
+  load?: () => Promise<unknown>;
+  /**
+   * Self-contained HTML for an OPAQUE prebuilt bundle (its own inlined renderer,
+   * `three` unreachable). The host runs it in an iframe at the embed-only floor
+   * (Tier 0–1): hosted + sized + disposed, but its scene is NOT introspectable.
+   * Mutually exclusive with `load`. See docs/ADAPTER-ARCHITECTURE.md §2.3.
+   *
+   * Two shapes, both legal (D-W2, docs/WAVE4-FTUE-HARDENING-DESIGN.md):
+   *  - a plain `string` — the file's contents ALREADY READ (the in-tree
+   *    fixture glob route, `ingest/discovery.ts`, which Vite reads eagerly at
+   *    build/dev time via `import.meta.glob(..., { query: '?raw' })`); or
+   *  - a lazy `() => Promise<string>` thunk — a MANIFEST-DRIVEN external
+   *    folder (`adapter-resolver.ts`'s `resolveIngestDescriptor`), which reads
+   *    the declared `entryHtml` file's bytes through the
+   *    `/project-game-static/` route only when the game is actually mounted,
+   *    never eagerly at resolve time (mirrors `bundleUrl`'s own laziness).
+   * `enterIngestModeWithGame` (ingest-mode.ts) resolves either form to a
+   * plain string before handing it to `mountIngestGameEmbed`.
+   */
+  embedHtml?: string | (() => Promise<string>);
+  /**
+   * Source of a PREBUILT bundle whose `three` is REACHABLE. The host runs it in a
+   * same-origin iframe whose importmap resolves `three` to the HOST instance (blob
+   * re-export), captures its live scene in-realm, and edits it fully (tier 2–3).
+   * Mutually exclusive with `load`/`embedHtml`. See ingest-iframe-reachable-adapter.ts.
+   */
+  iframeReachableSrc?: string;
+  /** Capture timeout (ms) before degrading to embed-only — short for the
+   *  mismatched-three demo whose `three` is deliberately unreachable. */
+  captureTimeoutMs?: number;
+  /**
+   * Map of game-relative-path substring → served asset URL. The ingest adapter
+   * installs a `THREE.DefaultLoadingManager` URL modifier that rewrites any
+   * requested URL containing a key to its value.
+   */
+  assets?: Record<string, string>;
+  /**
+   * Element ids the game expects to already exist in the DOM (e.g. an FPS game's
+   * `#blocker`/`#instructions` overlay). The host creates hidden stub elements
+   * with these ids before running the game, so DOM-dependent games stay
+   * unmodified (study §4D).
+   */
+  domStubs?: string[];
+  /**
+   * The game's own manifest `version` (D9, docs/DECISIONS-PENDING.md §D9 —
+   * orphan/mismatch detection), when this descriptor was built straight from
+   * a manifest that has one. `ingest/discovery.ts`'s in-tree fixture route
+   * sets this from the parsed manifest's `version`; `adapter-resolver.ts`'s
+   * `resolveIngestDescriptor` (the CLI-on-folder / manifest-world route)
+   * cannot — it only has a `ResolvedWorldEntry`, not the manifest's top-level
+   * `version` — so `ingest-mode.ts`'s `enterIngestModeFromManifestWorld`
+   * threads the resolved manifest's `version` through as an explicit
+   * parameter instead, taking precedence over this field where both exist.
+   */
+  gameVersion?: string;
+
+  // ---------------------------------------------------------------------
+  // D-W1 (docs/WAVE4-FTUE-HARDENING-DESIGN.md) — IFRAME-REACHABLE
+  // PREBUILT-BUNDLE mount fields, the three-side mirror of `IngestGame2D`'s
+  // Track-P fields (`@engine/world2d/ingest2d.ts`). Populated only when
+  // `iframeReachableSrc`/`load` are both absent and the world's manifest
+  // strategy is `iframe-reachable` with a `bundleUrl` (see
+  // `adapter-resolver.ts`'s `resolveIngestDescriptor`). The bundle MUST
+  // externalize `three` (a bare, un-rewritten `import 'three'`) — same bar
+  // as pixi's D-X5/D-Z4 — so it resolves through the importmap below to the
+  // HOST's `three`, not an inlined copy the capture trap can't see.
+  // ---------------------------------------------------------------------
+  /**
+   * Absolute URL of the externalized built game bundle, mounted via
+   * `<script type="module" src=...>` instead of an inline source string
+   * (`mountIngestGameIframeReachableBundle`, `ingest-iframe-reachable-adapter.ts`).
+   */
+  bundleUrl?: string;
+  /** `<base href>` for the iframe so the game's relative asset URLs resolve. */
+  baseHref?: string;
+  /**
+   * Host-side asset URL remap forced onto the host THREE's
+   * `DefaultLoadingManager.setURLModifier` — the three analog of pixi's
+   * `Assets.init` basePath wrap (a document.write iframe keeps the PARENT's
+   * `window.location`, so a relative asset request would otherwise resolve
+   * against the parent page, not the served bundle dir).
+   */
+  assetBaseUrl?: string;
+  /** DOM injected into the iframe body before the bundle's script boots (e.g. a `<div id="game-root">` it expects to find). */
+  bodyHtml?: string;
+  /**
+   * Lazily resolve this game's bare-specifier -> extraDeps resolution (D-Z3,
+   * the SAME `ExtraDepsResolution2D` shape the pixi/world2d side uses —
+   * namespaces + verbatim URLs) via the editor's host-namespace registry.
+   * Absent means no extra externalized deps beyond `three` itself.
+   */
+  extraDeps?: () => Promise<ExtraDepsResolution2D>;
+}

package/src/ingest-hierarchy-rows.ts

@@ -0,0 +1,207 @@
+/**
+ * Pure row-flattening for `IngestHierarchy` (no React) — D-W4 (F14/F18,
+ * docs/WAVE4-FTUE-HARDENING-DESIGN.md §D-W4), extracted the same way
+ * `hierarchy-rows.ts` extracts `SceneHierarchy`'s equivalent, so the
+ * key/collapse/cycle-guard logic is unit-testable without rendering.
+ *
+ * §0.5's ground truth: an ingested game's structural ids
+ * (`ingest:<path>:<type>:<name>`, `@engine/adapter/ingest/overlay-apply.ts`'s
+ * `assignStructuralIds`) are baked ONCE at capture and are the overlay
+ * PERSISTENCE key (overlay-apply.ts:45-51) — never touched here. But
+ * `IngestHierarchy` re-reads the LIVE `Object3D` tree every render
+ * (`adapter.hierarchy.node(id)`), and a live game can reorder or clone
+ * subtrees after capture, so the SAME baked id can legitimately show up in
+ * more than one place in a single walk — `EditorNode.id` alone is no longer
+ * a safe React key, and naively recursing `childIds` with no guard can loop
+ * forever if a stale/duplicated id ever points back at one of its own
+ * ancestors.
+ *
+ * Wave-7 (docs/WAVE7-HIERARCHY-CAP-DESIGN.md §1 D-C1..D-C6): per-parent
+ * child cap, copied from `hierarchy-rows.ts`'s `flattenVisibleRows`/
+ * `CHILD_CAP`/`MORE_ID_PREFIX` (same constants, no drift). Unlike
+ * first-party (which only caps in play mode), the adapter panel's tree is
+ * BY DEFINITION a live game scene graph, so `capEnabled` defaults to
+ * `false` here (matching this function's PRE-cap behavior byte-for-byte —
+ * every existing caller/test that doesn't pass the new params keeps working
+ * unchanged) and `IngestHierarchy` explicitly turns it on for the browse
+ * view. Search bypasses the cap by calling with `capEnabled=false` (D-C4) —
+ * the exact same "flatten UNCAPPED, filter flat" shape this module already
+ * used for search before the cap existed.
+ */
+
+import type { EditorNode, HierarchyProvider } from '@engine/adapter';
+import { CHILD_CAP, MORE_ID_PREFIX } from './hierarchy-rows';
+
+/** One flattened, render-ready row over an ingested game's live hierarchy. */
+export interface IngestRow {
+  readonly node: EditorNode;
+  readonly depth: number;
+  /**
+   * Render key material: the walk path (root index, then child index at
+   * each level) — NOT `node.id` alone. Stays unique across a render even
+   * when the id scheme collides, because it is derived from POSITION in
+   * the walk, not from the adapter's (potentially stale/duplicated) data.
+   */
+  readonly pathKey: string;
+  readonly hasChildren: boolean;
+  /** True when an ANCESTOR's `pathKey` is in the caller's collapsed-set —
+   *  i.e. this row is inside a collapsed subtree (F18). The row itself is
+   *  still included in the returned array (so a search can still find it);
+   *  the component filters it out when not searching. */
+  readonly hiddenByCollapse: boolean;
+  /** Present on a synthetic "… N more" row that reveals capped siblings
+   *  (D-C2) — `parentPathKey` is the capped parent's `pathKey`, `hidden` is
+   *  how many of its children are not shown. Never present on a real row. */
+  readonly more?: { readonly parentPathKey: string; readonly hidden: number };
+}
+
+/**
+ * Backstop against a childIds list this guard's own dedup somehow doesn't
+ * anticipate (e.g. a very deep but genuinely acyclic live tree) — ingested
+ * games are not expected to nest anywhere near this deep; this is a second,
+ * independent safety net, not the primary guard (see `visited` below).
+ */
+const MAX_DEPTH = 500;
+
+/** How many of a parent's children to walk (D-C1/D-C3) — split out of `walk`
+ *  below purely to keep that function's cognitive-complexity score down. */
+function childLimit(
+  capEnabled: boolean,
+  revealed: ReadonlyMap<string, number>,
+  parentPathKey: string,
+): number {
+  return capEnabled
+    ? Math.max(CHILD_CAP, revealed.get(parentPathKey) ?? CHILD_CAP)
+    : Number.POSITIVE_INFINITY;
+}
+
+/** The synthetic "… N more" row for a capped parent (D-C2) — a render-only
+ *  stub, never fed back to the adapter. Split out of `walk` below purely to
+ *  keep that function's cognitive-complexity score down. */
+function buildMoreRow(
+  parentPathKey: string,
+  depth: number,
+  parentId: string,
+  hiddenByCollapse: boolean,
+  hidden: number,
+): IngestRow {
+  return {
+    node: {
+      id: `${MORE_ID_PREFIX}${parentPathKey}`,
+      label: '',
+      kind: 'object',
+      parentId,
+      childIds: [],
+      flags: {},
+    },
+    depth,
+    pathKey: `${parentPathKey}/__more__`,
+    hasChildren: false,
+    hiddenByCollapse,
+    more: { parentPathKey, hidden },
+  };
+}
+
+/**
+ * Flatten an ingest adapter's hierarchy into display rows.
+ *
+ * F14 cycle/dup guard: `visited` tracks every `node.id` already emitted in
+ * THIS walk. A live game reordering/cloning objects can make the same baked
+ * id reachable from more than one place (a real duplicate) or, in principle,
+ * from one of its own descendants (a cycle) — either way the id is stale
+ * data describing the CURRENT live scene, not a second logical node. The
+ * chosen semantics: render the first occurrence encountered (root-first,
+ * then depth-first child order) and silently skip every later one — no
+ * second row, and a cycle can never recurse forever. `collapsedKeys` is
+ * keyed by `pathKey`, not `node.id` (F18) — a walk-path is stable for "this
+ * position in the tree shape", which is what "collapsed" means to a user
+ * looking at the panel; keying by id would let a stale/reused id apply a
+ * collapse to the WRONG node after a live reorder, or fail to distinguish
+ * two positions that happen to share a duplicated id.
+ *
+ * D-C1/D-C3 cap: when `capEnabled`, each parent's children are limited to
+ * `max(CHILD_CAP, revealed.get(parentPathKey) ?? CHILD_CAP)` and a synthetic
+ * more-row is appended when some are hidden (D-C2). D-C5: children beyond
+ * the limit are never walked, so never added to `visited` — a duplicate id
+ * whose first structural occurrence was capped away still renders at its
+ * next reachable occurrence (the dedup guard's "once, not zero times"
+ * guarantee holds). D-C6: a COLLAPSED parent (its own `pathKey` is in
+ * `collapsedKeys`) contributes no child rows and no more-row at all when
+ * capped — the walk stops at the parent itself rather than descending and
+ * relying on `hiddenByCollapse` filtering, since a more-row would otherwise
+ * still need suppressing. Uncapped calls (search, D-C4) are unaffected:
+ * collapse only ever gates recursion when `capEnabled`, so a collapsed
+ * subtree's matches stay reachable when searching, exactly as before.
+ */
+export function flattenIngestRows(
+  hierarchy: Pick<HierarchyProvider, 'roots' | 'node'>,
+  collapsedKeys: ReadonlySet<string>,
+  revealed: ReadonlyMap<string, number> = new Map(),
+  capEnabled = false,
+): IngestRow[] {
+  const rows: IngestRow[] = [];
+  const visited = new Set<string>();
+
+  const walk = (node: EditorNode, depth: number, pathKey: string, parentHidden: boolean): void => {
+    if (visited.has(node.id) || depth > MAX_DEPTH) return;
+    visited.add(node.id);
+
+    const hasChildren = node.childIds.length > 0;
+    rows.push({ node, depth, pathKey, hasChildren, hiddenByCollapse: parentHidden });
+
+    const isCollapsed = collapsedKeys.has(pathKey);
+    if (capEnabled && isCollapsed) return; // D-C6: nothing of a collapsed subtree renders.
+
+    const childHidden = parentHidden || isCollapsed;
+    const shown = Math.min(node.childIds.length, childLimit(capEnabled, revealed, pathKey));
+
+    for (let i = 0; i < shown; i++) {
+      const child = hierarchy.node(node.childIds[i]!);
+      if (child) walk(child, depth + 1, `${pathKey}.${i}`, childHidden);
+    }
+
+    if (capEnabled && node.childIds.length > shown) {
+      rows.push(
+        buildMoreRow(pathKey, depth + 1, node.id, childHidden, node.childIds.length - shown),
+      );
+    }
+  };
+
+  hierarchy.roots().forEach((root, i) => {
+    walk(root, 0, `r${i}`, false);
+  });
+  return rows;
+}
+
+/** Stable React key for a row — walk path + id, so it never collides even
+ *  when the underlying id scheme does (F14). */
+export function ingestRowKey(row: Pick<IngestRow, 'pathKey' | 'node'>): string {
+  return `${row.pathKey}:${row.node.id}`;
+}
+
+/**
+ * Wave-18 (docs/WAVE18-INGEST-HIERARCHY-VIRTUALIZATION-DESIGN.md): the pure
+ * start/end row-index math for `IngestHierarchy`'s scroll-windowed rendering.
+ * Kept here (not inlined in the component) for two reasons: it is
+ * unit-testable standalone with no React/jsdom involved, and a tamper test
+ * can `vi.mock` this ONE function to neutralize windowing (return the full
+ * range) and prove the render-bounding behavior actually depends on it, not
+ * on some other accidental cap.
+ *
+ * `overscan` extra rows are kept rendered on each side of the visible band
+ * so a fast scroll or keyboard nav doesn't flash empty space before the next
+ * paint catches up. `end` is clamped to `totalRows`; `start` is clamped to 0
+ * (never negative near the top of the list).
+ */
+export function ingestRowWindow(
+  totalRows: number,
+  scrollTop: number,
+  viewportPx: number,
+  rowH: number,
+  overscan: number,
+): { start: number; end: number } {
+  const start = Math.max(0, Math.floor(scrollTop / rowH) - overscan);
+  const visibleCount = Math.ceil(viewportPx / rowH) + overscan * 2;
+  const end = Math.min(totalRows, start + visibleCount);
+  return { start, end };
+}