@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/components/xstate-documents.tsx

@@ -0,0 +1,209 @@
+import { themeVars } from '../design-system';
+/**
+ * XState contributions (W3, docs/EDITOR-WORKSPACE-SHELL-TODO.md §4.3/§9 W3 —
+ * inventory row B6): the permanent bottom XSTATE tab and its demo-machine
+ * fallback are GONE from production UI. What replaces them, per §4.3's
+ * truthfulness rules:
+ *
+ *  - a compact **State Machine** Inspector section that renders ONLY for a
+ *    selected live entity whose object carries a real `bindXStateAnimation`
+ *    binding (`_xstateAnimation` user-data, engine
+ *    `animation/xstate-animation-binding.ts`) — active state(s) per layer,
+ *    the machine's own id as its source identity, and an `Inspect Machine`
+ *    action;
+ *  - `Inspect Machine` opens the REAL machine inside the bottom Debugger.
+ *    That instrument observes the live Game/Scene without replacing it;
+ *  - an `Open State Machine: <id>` palette action per live registered
+ *    machine (`listLiveMachines` scans the live object map for real
+ *    bindings — the only truthful registry that exists today).
+ *
+ * NO fabricated hierarchy rows, NO demo machine anywhere: the shipped
+ * `character-animation-machine.fixture.ts` is now a TEST fixture only
+ * (`test/xstate-fixture-ban.test.ts` pins that), and every open path here
+ * requires an actual live binding — with none, nothing renders and nothing
+ * can be opened. The template project has no XState machine, so a template
+ * session shows no XState UI at all.
+ *
+ * `Open Source` (§4.3 mentions it MAY exist): deliberately NOT built —
+ * neither XState nor the binding carries a machine→source-file identity, and
+ * fabricating one (e.g. grepping for the machine id) would violate §4.3's
+ * "no ids decoded for magic words". When the engine grows a real
+ * machine→module provenance, the section is where it lands.
+ *
+ * Editing stays a code change: the graph view is inspect-only
+ * (docs/decisions/e4-xstate-authoring-boundary.md — its ownership decision
+ * is unchanged; only its bottom-dock placement is superseded, TODO §12).
+ */
+
+import {
+  getXStateAnimationBindingsVersion,
+  subscribeXStateAnimationBindings,
+  type XStateAnimationBinding,
+} from '@engine/animation/xstate-animation-binding';
+import { getUserData } from '@engine/scene/user-data';
+import { useSyncExternalStore } from 'react';
+import type * as THREE from 'three';
+import type { AnyStateMachine } from 'xstate';
+import type { EditorAction } from '../action-registry';
+import { Button } from '../design-system';
+import { createHmrRegistrationGroup } from '../hmr-registration-group';
+import { registerInspectorSections } from '../inspector-section-registry';
+import { useLiveActorState } from '../xstate-inspect/use-live-actor-state';
+import { openDebuggerPanel } from './debugger-panel-state';
+
+/** The narrow store surface the XState contributions read: the live object
+ *  map where real bindings live. */
+export interface XStateInspectorStore {
+  readonly objectMap: Map<string, THREE.Object3D>;
+}
+
+let _store: XStateInspectorStore | null = null;
+const registrationGroup = createHmrRegistrationGroup(import.meta.hot, 'xstate-inspector');
+
+/** The selected entity's live binding, or `undefined` — the ONLY discovery
+ *  path (§4.3: a machine is truthfully discoverable only through a live
+ *  `bindXStateAnimation` binding). */
+export function liveBindingFor(nodeId: string): XStateAnimationBinding | undefined {
+  const object = _store?.objectMap.get(nodeId);
+  return object ? getUserData(object, '_xstateAnimation') : undefined;
+}
+
+/**
+ * Wire the store and register the Inspector section (idempotent — the
+ * registration is permanent; `match` reads the CURRENT store, so with no
+ * configured store nothing ever matches). Returns a cleanup that clears the
+ * store reference (project switch / layout teardown).
+ */
+export function configureXStateInspector(store: XStateInspectorStore): () => void {
+  _store = store;
+  registrationGroup.ensure((track) => {
+    track(
+      registerInspectorSections({
+        // §4.3 gating: matches ONLY a real node whose live object carries a
+        // real binding. Template entities (no machine) never match — the
+        // section must not render for them (unit-pinned).
+        match: (node) => node !== null && liveBindingFor(node.id) !== undefined,
+        Section: XStateMachineSection,
+      }),
+    );
+  });
+  return () => {
+    if (_store === store) _store = null;
+  };
+}
+
+/** Every live machine, by scanning the live object map for real bindings —
+ *  the `Open State Machine…` command's truthful listing. */
+export function listLiveMachines(): {
+  nodeId: string;
+  machineId: string;
+  label: string;
+}[] {
+  if (!_store) return [];
+  const seen = new Set<XStateAnimationBinding>();
+  const out: { nodeId: string; machineId: string; label: string }[] = [];
+  for (const [nodeId, object] of _store.objectMap) {
+    const binding = getUserData(object, '_xstateAnimation');
+    if (!binding || seen.has(binding)) continue;
+    seen.add(binding);
+    const machine = binding.actor.logic as AnyStateMachine;
+    out.push({ nodeId, machineId: machine.id, label: object.name || nodeId });
+  }
+  return out;
+}
+
+/** `Open State Machine: <id>` palette actions — one per live machine; an
+ *  empty list when none are live (never a demo entry). */
+export function buildXStateMachineActions(): EditorAction[] {
+  return listLiveMachines().map((m) => ({
+    id: `xstate-machine:${m.machineId}:${m.nodeId}`,
+    label: `Open State Machine: ${m.machineId}`,
+    category: 'action' as const,
+    execute: () => void openXStateGraphDocument(m.nodeId),
+  }));
+}
+
+/** Open a live machine in the bottom Debugger while preserving the Game. */
+export function openXStateGraphDocument(nodeId: string): boolean {
+  const binding = liveBindingFor(nodeId);
+  if (!_store || !binding) return false;
+  openDebuggerPanel('machines', nodeId);
+  return true;
+}
+
+/** Test-only reset — PAIR with `__resetInspectorSectionRegistryForTest`
+ *  (clearing `_sectionRegistered` without clearing the section registry
+ *  would double-register on the next configure). */
+export function __resetXStateContributionsForTest(): void {
+  _store = null;
+  registrationGroup.reset();
+}
+
+// --- The compact Inspector section (§4.3) -----------------------------------
+
+/** Registered via `configureXStateInspector` — renders ONLY when `match`
+ *  found a real live binding for the selected node. */
+export function XStateMachineSection({ nodeId }: { nodeId: string | null }) {
+  useSyncExternalStore(
+    subscribeXStateAnimationBindings,
+    getXStateAnimationBindingsVersion,
+    getXStateAnimationBindingsVersion,
+  );
+  const binding = nodeId ? liveBindingFor(nodeId) : undefined;
+  const machine = binding ? (binding.actor.logic as AnyStateMachine) : undefined;
+  // Follow live transitions (re-render per snapshot) — the layer readout
+  // below re-reads `getActiveLayers()` on each.
+  useLiveActorState(machine as AnyStateMachine, binding?.actor);
+  if (!binding || !machine || !nodeId) return null;
+  return (
+    <div
+      data-testid="inspector-xstate-section"
+      style={{
+        pointerEvents: 'auto',
+        padding: 8,
+        borderBottom: `1px solid ${themeVars.boundary.default}`,
+      }}
+    >
+      <div
+        style={{
+          fontSize: 11,
+          color: themeVars.content.dim,
+          textTransform: 'uppercase',
+          marginBottom: 4,
+        }}
+      >
+        State Machine
+      </div>
+      <div
+        style={{ fontSize: 11, color: themeVars.content.primary, fontWeight: 600, marginBottom: 2 }}
+      >
+        {machine.id}
+      </div>
+      <div style={{ fontSize: 10, color: themeVars.content.muted, marginBottom: 4 }}>
+        <span style={{ color: themeVars.semantic.success, fontWeight: 700 }}>●</span> Live —{' '}
+        {binding.getActiveLayers().map((layer, i) => (
+          <span key={layer.layer} data-testid={`xstate-section-layer-${layer.layer}`}>
+            {i > 0 && ' · '}
+            {layer.layer}:{' '}
+            <span
+              style={{ fontFamily: themeVars.typography.mono, color: themeVars.accent.default }}
+            >
+              {layer.stateId}
+            </span>
+          </span>
+        ))}
+      </div>
+      <div style={{ fontSize: 10, color: themeVars.content.dim, marginBottom: 6 }}>
+        Source: hand-authored XState TypeScript — inspect-only
+        (docs/decisions/e4-xstate-authoring-boundary.md).
+      </div>
+      <Button
+        size="compact"
+        data-testid="xstate-open-graph"
+        onClick={() => void openXStateGraphDocument(nodeId)}
+      >
+        Inspect Machine
+      </Button>
+    </div>
+  );
+}

package/src/composite-screenshot.ts

@@ -0,0 +1,248 @@
+/**
+ * #146 — full-stack play screenshot: the game canvas(es) PLUS the DOM UI
+ * layers stacked over/beside them (React adapter roots,
+ * world layers), composited into one PNG. This is "what the game looks
+ * like" for agent eyes — a canvas-only capture of a game whose score/health
+ * lives in the HUD reads as a different (often emptier) game than the one
+ * the human is watching.
+ *
+ * How: each `<canvas>` child of the play container is drawn onto an
+ * offscreen 2D canvas at its on-screen rect (readable because every canvas
+ * the runtime mounts sets `preserveDrawingBuffer: true` — see
+ * `create-runtime.ts`), then the NON-canvas children are serialized into an
+ * SVG `<foreignObject>` and drawn on top. The foreignObject leg is faithful
+ * by construction: the HUD rule is inline-styles-only (CLAUDE.md), and
+ * react-world layers are engine-mounted with inline positioning — so a
+ * detached serialization loses no styling. The SVG rides a `data:` URL with
+ * no external references, which keeps the output canvas untainted (the same
+ * mechanism html-to-image libraries rely on).
+ *
+ * Editor chrome is deliberately OUT of scope (docs/SHARED-SESSION-SPEC.md —
+ * capturing it needs CDP, deferred as an opt-in niche).
+ */
+
+export interface OverlaySvg {
+  svg: string;
+  /** How many non-canvas layers were serialized (0 ⇒ callers skip the leg). */
+  overlayCount: number;
+}
+
+/**
+ * Serialize the play container's NON-canvas children into a standalone SVG
+ * sized `width`×`height` (CSS pixels). Children are cloned into a neutral
+ * relatively-positioned wrapper — never the container itself, whose own
+ * styling comes from editor CSS classes that a detached serialization would
+ * silently drop. Returns null when there is nothing but canvases to show.
+ * Pure DOM (no rasterizing), so it's unit-testable under jsdom.
+ */
+export function buildOverlaySvg(
+  container: HTMLElement,
+  width: number,
+  height: number,
+): OverlaySvg | null {
+  const overlays = Array.from(container.children).filter(
+    (el) => el.tagName.toLowerCase() !== 'canvas',
+  );
+  if (overlays.length === 0) return null;
+
+  const wrapper = container.ownerDocument.createElement('div');
+  wrapper.setAttribute('style', `position:relative;width:${width}px;height:${height}px;margin:0;`);
+  // Snapshot a stable DOM frame. CSS animations/transitions inside an SVG
+  // foreignObject can be rasterized while Chrome is between compositor
+  // layers, producing large opaque-black rectangles even though the live DOM
+  // is fine (reproduced by the 2048 dogfood run during a tile-pop frame).
+  // Disabling motion in the detached clone leaves the live game untouched
+  // and makes the captured evidence atomic.
+  const freezeMotion = container.ownerDocument.createElement('style');
+  freezeMotion.textContent =
+    '*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important;' +
+    'backdrop-filter:none!important;-webkit-backdrop-filter:none!important;}';
+  wrapper.appendChild(freezeMotion);
+  for (const el of overlays) {
+    const clone = el.cloneNode(true) as Element;
+    // A canvas nested INSIDE an overlay layer (react roots may render one)
+    // serializes as an empty box — strip it rather than ship a lying blank.
+    for (const nested of Array.from(clone.querySelectorAll('canvas'))) nested.remove();
+    wrapper.appendChild(clone);
+  }
+
+  const serialized = new XMLSerializer().serializeToString(wrapper);
+  const svg =
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">` +
+    `<foreignObject width="100%" height="100%">${serialized}</foreignObject></svg>`;
+  return { svg, overlayCount: overlays.length };
+}
+
+export interface CompositeCapture {
+  base64: string;
+  mimeType: 'image/png';
+  /** Honest capture provenance: how many canvases were drawn, and how many
+   *  DOM layers rode the foreignObject leg. */
+  layers: { canvases: number; domOverlays: number };
+}
+
+/** Wait briefly for finite CSS/Web Animations to settle before serializing a
+ * DOM frame. Chromium can rasterize an actively animated foreignObject as
+ * opaque black compositor tiles; a settled frame is both more legible and
+ * closer to what a human sees after the interaction. Infinite ambience never
+ * blocks evidence capture, and the timeout keeps a broken animation from
+ * wedging the relay. */
+export async function waitForFiniteMotion(container: HTMLElement, maxWaitMs = 350): Promise<void> {
+  if (typeof container.getAnimations !== 'function') return;
+  const animations = container.getAnimations({ subtree: true }).filter((animation) => {
+    const endTime = animation.effect?.getComputedTiming().endTime;
+    return typeof endTime === 'number' && Number.isFinite(endTime);
+  });
+  if (animations.length === 0) return;
+  await Promise.race([
+    Promise.allSettled(animations.map((animation) => animation.finished)),
+    new Promise<void>((resolve) => setTimeout(resolve, maxWaitMs)),
+  ]);
+}
+
+/** Cross two paint boundaries when the tab is rendering, but never depend on
+ * rAF firing: Chromium suspends it for hidden/background editor tabs, and a
+ * screenshot is specifically expected to work there. The timer is the
+ * bounded fallback, not an extra delay after a successful frame. */
+export async function waitForPaint(container: HTMLElement, maxWaitMs = 75): Promise<void> {
+  const requestFrame = container.ownerDocument.defaultView?.requestAnimationFrame.bind(
+    container.ownerDocument.defaultView,
+  );
+  if (!requestFrame) return;
+  await new Promise<void>((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolve();
+    };
+    const timeout = setTimeout(finish, maxWaitMs);
+    requestFrame(() => requestFrame(finish));
+  });
+}
+
+/**
+ * Rasterize the full play container (canvases + DOM UI layers) to a PNG.
+ * Output is sized to the container's CSS rect — the same geometry the human
+ * sees. Throws on any rasterization failure; the caller
+ * (`handleBridgeScreenshot`) degrades to the canvas-only capture and marks
+ * the result honestly rather than failing the op.
+ */
+export async function capturePlayComposite(container: HTMLElement): Promise<CompositeCapture> {
+  // Debug state can become observable just before React commits the matching
+  // DOM. Cross two paint boundaries first, then let newly-mounted finite
+  // transitions finish, then cross one more stable paint before cloning.
+  await waitForPaint(container);
+  // Chrome's foreignObject renderer can retain opaque-black compositor tiles
+  // for several frames after a React-only tree replaces an overlay (observed
+  // on an immediate game-over -> restart capture even after its 180ms tile
+  // animation reported finished). Give DOM-only roots one short compositor
+  // settle window; canvas-backed games do not use this fragile leg as their
+  // sole image and keep the faster path.
+  if (container.querySelectorAll('canvas').length === 0) {
+    await new Promise<void>((resolve) => setTimeout(resolve, 650));
+  }
+  await waitForFiniteMotion(container);
+  await waitForPaint(container);
+  return capturePlayCompositeAttempt(container, 2);
+}
+
+export function hasExcessTransparentPixels(
+  rgba: Uint8ClampedArray,
+  pixelCount: number,
+  limit = 0.03,
+): boolean {
+  if (pixelCount <= 0) return false;
+  let transparent = 0;
+  for (let alpha = 3; alpha < rgba.length; alpha += 4) {
+    if (rgba[alpha] === 0) transparent += 1;
+  }
+  return transparent / pixelCount > limit;
+}
+
+/** Chromium's foreignObject compositor sometimes fills a torn tile with
+ * fully-opaque black rather than transparency. Catch only a LARGE region of
+ * near-pure black; a legitimately dark game merely takes the bounded retry
+ * path and is still returned unchanged when it remains dark. */
+export function hasExcessNearBlackPixels(
+  rgba: Uint8ClampedArray,
+  pixelCount: number,
+  limit = 0.08,
+): boolean {
+  if (pixelCount <= 0) return false;
+  let black = 0;
+  for (let offset = 0; offset < rgba.length; offset += 4) {
+    if (
+      rgba[offset]! <= 8 &&
+      rgba[offset + 1]! <= 8 &&
+      rgba[offset + 2]! <= 8 &&
+      rgba[offset + 3]! >= 250
+    ) {
+      black += 1;
+    }
+  }
+  return black / pixelCount > limit;
+}
+
+async function capturePlayCompositeAttempt(
+  container: HTMLElement,
+  retriesRemaining: number,
+): Promise<CompositeCapture> {
+  const rect = container.getBoundingClientRect();
+  const width = Math.max(1, Math.round(rect.width));
+  const height = Math.max(1, Math.round(rect.height));
+
+  const out = container.ownerDocument.createElement('canvas');
+  out.width = width;
+  out.height = height;
+  const ctx2d = out.getContext('2d');
+  if (!ctx2d) throw new Error('composite screenshot: no 2d canvas context');
+
+  const canvases = Array.from(container.querySelectorAll('canvas'));
+  for (const c of canvases) {
+    const r = c.getBoundingClientRect();
+    ctx2d.drawImage(c, r.left - rect.left, r.top - rect.top, r.width, r.height);
+  }
+
+  let domOverlays = 0;
+  const overlay = buildOverlaySvg(container, width, height);
+  if (overlay) {
+    const img = new Image();
+    img.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(overlay.svg)}`;
+    await img.decode();
+    ctx2d.drawImage(img, 0, 0, width, height);
+    domOverlays = overlay.overlayCount;
+  }
+
+  // A Chromium foreignObject can occasionally decode while React is between
+  // compositor frames, leaving large transparent rectangles in an otherwise
+  // opaque React-only game. Those pixels show up as black in the PNG. Detect
+  // that lying frame and retry after a real paint; rounded-corner edge pixels
+  // stay far below the 3% threshold. Canvas-backed games already have their
+  // canvas underneath, so this retry is specific to DOM-only captures.
+  if (canvases.length === 0 && domOverlays > 0 && retriesRemaining > 0) {
+    try {
+      const pixels = ctx2d.getImageData(0, 0, width, height);
+      if (
+        hasExcessTransparentPixels(pixels.data, width * height) ||
+        hasExcessNearBlackPixels(pixels.data, width * height)
+      ) {
+        await new Promise<void>((resolve) => setTimeout(resolve, 300));
+        await waitForPaint(container);
+        return capturePlayCompositeAttempt(container, retriesRemaining - 1);
+      }
+    } catch {
+      // If readback is unavailable, preserve the existing honest capture or
+      // let toDataURL surface the underlying taint below.
+    }
+  }
+
+  const dataUrl = out.toDataURL('image/png');
+  const comma = dataUrl.indexOf(',');
+  return {
+    base64: comma >= 0 ? dataUrl.slice(comma + 1) : dataUrl,
+    mimeType: 'image/png',
+    layers: { canvases: canvases.length, domOverlays },
+  };
+}

package/src/design-system/index.ts

@@ -0,0 +1,70 @@
+/**
+ * The single internal editor design-system boundary.
+ *
+ * Product surfaces import from this module. Theme definitions, CSS recipes,
+ * primitives, and recurring patterns remain implementation details below it.
+ * Project-authored tools receive the same surface through `@editor/widgets`.
+ */
+
+export * from '../components/patterns/Dialog';
+export * from '../components/patterns/Fields';
+export * from '../components/patterns/List';
+export * from '../components/patterns/StateSurface';
+export * from '../components/patterns/Surfaces';
+export * from '../components/patterns/Tabs';
+export * from '../components/patterns/Toolbar';
+export * from '../components/patterns/Tree';
+export * from '../components/primitives/Button';
+export * from '../components/primitives/banner-tones';
+export * from '../components/primitives/ColorInput';
+export * from '../components/primitives/EditorIcon';
+export { editorIcons } from '../components/primitives/editor-icons';
+export * from '../components/primitives/FormControls';
+export * from '../components/primitives/JsonInput';
+export * from '../components/primitives/Layout';
+export * from '../components/primitives/Menu';
+export * from '../components/primitives/NumberInput';
+export * from '../components/primitives/Panel';
+export * from '../components/primitives/SectionHeader';
+export * from '../components/primitives/Text';
+export * from '../components/primitives/Tooltip';
+export * from '../components/primitives/Vec3Input';
+
+// Product surfaces consume runtime theme references through this boundary as
+// they migrate away from direct `theme.ts` imports. Keeping the references
+// here preserves custom-theme behavior without exposing design-system internals.
+export {
+  accent,
+  accentMuted,
+  bg,
+  border,
+  chromeSize,
+  controlSize,
+  danger,
+  dangerFaint,
+  dangerMuted,
+  EDITOR_THEME_CLASS,
+  type EditorTheme,
+  type EditorThemeId,
+  type EditorThemeVariable,
+  editorThemes,
+  editorThemeVariables,
+  fontMono,
+  fontSans,
+  fontSize,
+  fontWeight,
+  graphiteDarkEditorTheme,
+  midnightHighContrastEditorTheme,
+  radius,
+  scrim,
+  shadow,
+  space,
+  strokeWidth,
+  success,
+  successMuted,
+  text,
+  themeVars,
+  warn,
+  warnMuted,
+} from '../theme';
+export { zIndex } from '../z-index';