@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/components/DebugConsolePanel.tsx

@@ -0,0 +1,461 @@
+import { Checkbox, Select, TextInput, themeVars } from '../design-system';
+/**
+ * Debug Console — the human door onto the game's registered debug COMMANDS
+ * (`ctx.debug.registerCommand`, docs/SYNTHETIC-PLAYER-SPEC.md §3.6): lists
+ * every command with its locus badge, renders a schema-driven invoke form
+ * from the command's `argsJsonSchema` (the JSON-Schema projection of its Zod
+ * args tuple), and keeps an invocation history.
+ *
+ * Reads the live adapter through `getActiveDebug()` (the authoring seam —
+ * play-mode installs the whole `SystemAdapters` bag on enter, clears on
+ * exit) and renders NOTHING when no debug adapter is active — same
+ * degrade-to-absent discipline as `NetworkSection`. The 250ms poll covers
+ * the adapter's IDENTITY changing (play started/stopped) and new
+ * registrations appearing (hot reload re-seeds).
+ *
+ * Widget reuse: the args form funnels through the SAME
+ * `jsonSchemaToFieldDescriptors` module the Data panel renders from
+ * (`inspectors/json-schema-fields.ts`) — a command's Zod tuple is adapted to
+ * a pseudo-object (`arg0`/`arg1`/… from `prefixItems`, or the older
+ * array-form `items`) so tuple args get the same typed widgets for free.
+ *
+ * Layout: one bordered row per command — header line (monospace name, locus
+ * chip, ellipsized description, right-aligned Invoke) with the args form
+ * indented on its own line below — and a `ConsolePanel`-style history region
+ * pinned under the command list (timestamped, ✓/✗ per entry, newest first).
+ */
+
+import type { DebugCommandInfo } from '@engine/adapter/system-adapter';
+import { useEffect, useState } from 'react';
+import { getActiveDebug } from '../authoring/active-systems';
+import { Button } from '../design-system';
+import {
+  type DataFieldDescriptor,
+  defaultValueForDescriptor,
+  jsonSchemaToFieldDescriptors,
+} from './inspectors/json-schema-fields';
+
+/**
+ * Adapt a command's args JSON Schema (a TUPLE: JSON Schema 2020-12
+ * `prefixItems`, or the older array-form `items`) into the pseudo-object
+ * field descriptors (`arg0`, `arg1`, …) the shared widget converter
+ * understands. Pure — unit-tested headlessly.
+ */
+export function tupleSchemaToFields(argsJsonSchema: unknown): DataFieldDescriptor[] {
+  const node = argsJsonSchema as { prefixItems?: unknown[]; items?: unknown } | null | undefined;
+  const items = Array.isArray(node?.prefixItems)
+    ? node.prefixItems
+    : Array.isArray(node?.items)
+      ? node.items
+      : [];
+  const properties = Object.fromEntries(items.map((item, i) => [`arg${i}`, item]));
+  return jsonSchemaToFieldDescriptors({ type: 'object', properties });
+}
+
+/** Ordered positional args out of the form's `arg<i>`-keyed values. */
+export function fieldValuesToArgs(
+  fields: DataFieldDescriptor[],
+  values: Record<string, unknown>,
+): unknown[] {
+  return fields.map((f) => values[f.name]);
+}
+
+interface HistoryEntry {
+  name: string;
+  args: unknown[];
+  ok: boolean;
+  /** Rendered result/error text (already stringified for display). */
+  detail: string;
+  at: number;
+}
+
+const LOCUS_COLORS: Record<'client' | 'server', string> = {
+  client: themeVars.accent.default,
+  server: themeVars.semantic.warning,
+};
+
+const LOCUS_HINTS: Record<'client' | 'server', string> = {
+  client: 'Runs in this client',
+  server: 'Runs on the authoritative server — needs an attached Colyseus room',
+};
+
+function LocusBadge({ locus, name }: { locus: 'client' | 'server'; name: string }) {
+  const color = LOCUS_COLORS[locus];
+  return (
+    <span
+      data-testid={`debug-command-locus-${name}`}
+      title={LOCUS_HINTS[locus]}
+      style={{
+        border: `1px solid ${color}55`,
+        background: `${color}14`,
+        color,
+        borderRadius: themeVars.shape.small,
+        padding: '0 4px',
+        fontSize: 9,
+        fontWeight: 700,
+        lineHeight: '14px',
+        textTransform: 'uppercase',
+        letterSpacing: 0.4,
+        flexShrink: 0,
+      }}
+    >
+      {locus}
+    </span>
+  );
+}
+
+function FieldInput({
+  field,
+  value,
+  onChange,
+}: {
+  field: DataFieldDescriptor;
+  value: unknown;
+  onChange: (v: unknown) => void;
+}) {
+  switch (field.kind) {
+    case 'number':
+      return (
+        <TextInput
+          data-testid={`debug-arg-${field.name}`}
+          type="number"
+          className="vgai-input"
+          style={{ width: 72 }}
+          value={typeof value === 'number' ? value : ''}
+          {...(field.min !== undefined ? { min: field.min } : {})}
+          {...(field.max !== undefined ? { max: field.max } : {})}
+          onChange={(e) => onChange(e.target.value === '' ? 0 : Number(e.target.value))}
+        />
+      );
+    case 'boolean':
+      return (
+        <Checkbox
+          data-testid={`debug-arg-${field.name}`}
+          className="vgai-checkbox"
+          style={{ margin: 0 }}
+          checked={value === true}
+          onChange={(e) => onChange(e.target.checked)}
+        />
+      );
+    case 'enum':
+      return (
+        <Select
+          data-testid={`debug-arg-${field.name}`}
+          className="vgai-select"
+          value={typeof value === 'string' ? value : ''}
+          onChange={(e) => onChange(e.target.value)}
+        >
+          {(field.options ?? []).map((opt) => (
+            <option key={opt} value={opt}>
+              {opt}
+            </option>
+          ))}
+        </Select>
+      );
+    case 'string':
+    case 'color':
+    case 'ref':
+      return (
+        <TextInput
+          data-testid={`debug-arg-${field.name}`}
+          type="text"
+          className="vgai-input"
+          style={{ width: 140 }}
+          value={typeof value === 'string' ? value : ''}
+          onChange={(e) => onChange(e.target.value)}
+        />
+      );
+    default: {
+      // 'json' / 'group' — raw JSON, parsed on commit; an unparsable edit
+      // keeps the previous value (same refuse-don't-widen rule as DataPanel's
+      // JsonCell).
+      return (
+        <TextInput
+          data-testid={`debug-arg-${field.name}`}
+          type="text"
+          className="vgai-input"
+          style={{ width: 160, fontFamily: themeVars.typography.mono }}
+          defaultValue={JSON.stringify(value ?? null)}
+          onBlur={(e) => {
+            try {
+              onChange(JSON.parse(e.target.value));
+            } catch {
+              /* refuse invalid JSON */
+            }
+          }}
+        />
+      );
+    }
+  }
+}
+
+/** Args-form label: the schema's own `.describe()` text when it's short
+ *  enough to sit inline (the tuple projection's `arg0`/`arg1` names carry no
+ *  meaning), else the positional name with the description as a tooltip. */
+function fieldLabel(f: DataFieldDescriptor): string {
+  return f.description && f.description.length <= 24 ? f.description : f.name;
+}
+
+function CommandRow({
+  command,
+  onInvoked,
+}: {
+  command: DebugCommandInfo;
+  onInvoked: (entry: HistoryEntry) => void;
+}) {
+  const fields = tupleSchemaToFields(command.argsJsonSchema);
+  const [values, setValues] = useState<Record<string, unknown>>(() =>
+    Object.fromEntries(fields.map((f) => [f.name, defaultValueForDescriptor(f)])),
+  );
+  const [busy, setBusy] = useState(false);
+
+  const invoke = async () => {
+    const debug = getActiveDebug();
+    if (!debug) return;
+    const args = fieldValuesToArgs(fields, values);
+    setBusy(true);
+    try {
+      const result = await debug.invoke(command.name, args);
+      onInvoked({
+        name: command.name,
+        args,
+        ok: true,
+        detail: result === undefined ? 'ok' : JSON.stringify(result),
+        at: Date.now(),
+      });
+    } catch (err) {
+      onInvoked({
+        name: command.name,
+        args,
+        ok: false,
+        detail: err instanceof Error ? err.message : String(err),
+        at: Date.now(),
+      });
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <div
+      data-testid={`debug-command-${command.name}`}
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 4,
+        padding: '5px 8px 6px',
+        borderBottom: `1px solid ${themeVars.boundary.default}`,
+      }}
+    >
+      {/* Header line: name · locus · description ······ Invoke */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8, minWidth: 0 }}>
+        <span
+          style={{
+            fontFamily: themeVars.typography.mono,
+            color: themeVars.content.primary,
+            flexShrink: 0,
+          }}
+        >
+          {command.name}
+        </span>
+        <LocusBadge locus={command.locus} name={command.name} />
+        <span
+          style={{
+            color: themeVars.content.dim,
+            fontSize: 10,
+            flex: 1,
+            minWidth: 0,
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+          }}
+          {...(command.description ? { title: command.description } : {})}
+        >
+          {command.description ?? ''}
+        </span>
+        <Button
+          variant="primary"
+          size="compact"
+          data-testid={`debug-invoke-${command.name}`}
+          disabled={busy}
+          onClick={() => void invoke()}
+          style={{ flexShrink: 0 }}
+        >
+          Invoke
+        </Button>
+      </div>
+      {/* Args form (only when the command takes args), indented under the name */}
+      {fields.length > 0 && (
+        <div
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: 10,
+            flexWrap: 'wrap',
+            paddingLeft: 12,
+          }}
+        >
+          {fields.map((f) => (
+            <label
+              key={f.name}
+              style={{ display: 'flex', alignItems: 'center', gap: 4 }}
+              {...(f.description ? { title: f.description } : {})}
+            >
+              <span style={{ color: themeVars.content.muted, fontSize: 10 }}>{fieldLabel(f)}</span>
+              <FieldInput
+                field={f}
+                value={values[f.name]}
+                onChange={(v) => setValues((prev) => ({ ...prev, [f.name]: v }))}
+              />
+            </label>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function formatTime(ts: number): string {
+  const d = new Date(ts);
+  const pad = (n: number) => n.toString().padStart(2, '0');
+  return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+
+/** Keep huge stringified results from flooding a history line — the full
+ *  text stays reachable via the row's title tooltip. */
+function truncateDetail(detail: string): string {
+  return detail.length > 160 ? `${detail.slice(0, 160)}…` : detail;
+}
+
+function HistoryRow({ entry }: { entry: HistoryEntry }) {
+  return (
+    <div
+      title={entry.detail}
+      style={{
+        display: 'flex',
+        alignItems: 'flex-start',
+        gap: 6,
+        padding: '1px 8px',
+        // themeVars.semantic.dangerFaint: deliberate low-emphasis RESTING row tint (see theme.ts).
+        background: entry.ok ? 'transparent' : themeVars.semantic.dangerFaint,
+      }}
+    >
+      <span style={{ color: themeVars.content.dim, flexShrink: 0 }}>{formatTime(entry.at)}</span>
+      <span
+        style={{
+          color: entry.ok ? themeVars.semantic.success : themeVars.semantic.danger,
+          flexShrink: 0,
+        }}
+      >
+        {entry.ok ? '✓' : '✗'}
+      </span>
+      <span
+        style={{ flex: 1, minWidth: 0, wordBreak: 'break-word', color: themeVars.content.primary }}
+      >
+        {entry.name}({entry.args.map((a) => JSON.stringify(a)).join(', ')})
+        <span style={{ color: themeVars.content.muted }}> → </span>
+        <span style={{ color: entry.ok ? themeVars.content.muted : themeVars.semantic.danger }}>
+          {truncateDetail(entry.detail)}
+        </span>
+      </span>
+    </div>
+  );
+}
+
+export function DebugConsolePanel() {
+  const [commands, setCommands] = useState<DebugCommandInfo[] | null>(() => {
+    const debug = getActiveDebug();
+    return debug ? debug.commands() : null;
+  });
+  const [history, setHistory] = useState<HistoryEntry[]>([]);
+
+  useEffect(() => {
+    const tick = () => {
+      const debug = getActiveDebug();
+      setCommands(debug ? debug.commands() : null);
+    };
+    tick();
+    const intervalId = setInterval(tick, 250);
+    return () => clearInterval(intervalId);
+  }, []);
+
+  if (!commands) return null;
+
+  return (
+    <div
+      data-testid="debug-console-panel"
+      style={{
+        flex: 1,
+        minHeight: 0,
+        display: 'flex',
+        flexDirection: 'column',
+        fontSize: 11,
+        color: themeVars.content.primary,
+        background: themeVars.surface.inset,
+      }}
+    >
+      <div style={{ flex: 1, minHeight: 0, overflowY: 'auto' }}>
+        {commands.length === 0 ? (
+          <div style={{ padding: 12, fontSize: 12, color: themeVars.content.muted, maxWidth: 480 }}>
+            <p style={{ margin: '0 0 6px' }}>No debug commands registered.</p>
+            <p style={{ margin: 0 }}>
+              Register one from a GameComponent with{' '}
+              <code>ctx.debug.registerCommand(name, spec, fn)</code> — it shows up here live.
+            </p>
+          </div>
+        ) : (
+          commands.map((c) => (
+            <CommandRow
+              key={c.name}
+              command={c}
+              onInvoked={(entry) => setHistory((prev) => [entry, ...prev].slice(0, 50))}
+            />
+          ))
+        )}
+      </div>
+      {history.length > 0 && (
+        <div
+          data-testid="debug-history"
+          style={{
+            flexShrink: 0,
+            maxHeight: '45%',
+            display: 'flex',
+            flexDirection: 'column',
+            borderTop: `1px solid ${themeVars.boundary.default}`,
+          }}
+        >
+          <div style={{ display: 'flex', alignItems: 'center', padding: '3px 8px', flexShrink: 0 }}>
+            <span
+              style={{
+                fontSize: 10,
+                fontWeight: 600,
+                color: themeVars.content.muted,
+                textTransform: 'uppercase',
+                letterSpacing: 0.5,
+              }}
+            >
+              History
+            </span>
+            <Button
+              type="button"
+              variant="ghost"
+              size="compact"
+              onClick={() => setHistory([])}
+              title="Clear history"
+              style={{ marginLeft: 'auto' }}
+            >
+              Clear
+            </Button>
+          </div>
+          <div
+            style={{ overflowY: 'auto', fontFamily: themeVars.typography.mono, lineHeight: '17px' }}
+          >
+            {history.map((h) => (
+              <HistoryRow key={`${h.at}-${h.name}`} entry={h} />
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/DebuggerPanel.tsx

@@ -0,0 +1,165 @@
+import {
+  getXStateAnimationBindingsVersion,
+  subscribeXStateAnimationBindings,
+} from '@engine/animation/xstate-animation-binding';
+import { clipNamesOf, collectMachineAnimationMeta } from '@engine/animation/xstate-animation-meta';
+import { useEffect, useSyncExternalStore } from 'react';
+import type { AnyStateMachine } from 'xstate';
+import { getActiveDebug, getActiveNetworking } from '../authoring/active-systems';
+import { useAvailabilityTick } from '../availability-tick';
+import { Button, EditorTab, EditorTabList, themeVars } from '../design-system';
+import { XStateMachineInspector } from '../xstate-inspect/XStateMachineInspector';
+import { DebugConsolePanel } from './DebugConsolePanel';
+import {
+  activeDebuggerTab,
+  type DebuggerTabId,
+  debuggerMachineNodeId,
+  debuggerPanelVersion,
+  selectDebuggerMachine,
+  setDebuggerTab,
+  subscribeDebuggerPanel,
+} from './debugger-panel-state';
+import { NetworkSection } from './NetworkSection';
+import { PerformancePanel } from './PerformancePanel';
+import { StateWatchPanel } from './StateWatchPanel';
+import { listLiveMachines, liveBindingFor } from './xstate-documents';
+
+interface TabSpec {
+  id: DebuggerTabId;
+  label: string;
+}
+
+function EmptyDebugState({ children }: { children: React.ReactNode }) {
+  return (
+    <div style={{ padding: 12, color: themeVars.content.muted, fontSize: 12 }}>{children}</div>
+  );
+}
+
+function MachinesPanel() {
+  useSyncExternalStore(
+    subscribeXStateAnimationBindings,
+    getXStateAnimationBindingsVersion,
+    getXStateAnimationBindingsVersion,
+  );
+  const machines = listLiveMachines();
+  const requested = debuggerMachineNodeId();
+  const selected = machines.find((machine) => machine.nodeId === requested) ?? machines[0];
+  const binding = selected ? liveBindingFor(selected.nodeId) : undefined;
+
+  useEffect(() => {
+    if (selected && requested !== selected.nodeId) selectDebuggerMachine(selected.nodeId);
+  }, [requested, selected]);
+
+  if (!selected || !binding) {
+    return (
+      <EmptyDebugState>Select a live entity with an XState animation binding.</EmptyDebugState>
+    );
+  }
+
+  return (
+    <div style={{ flex: 1, minHeight: 0, display: 'flex' }}>
+      <div
+        style={{
+          width: 190,
+          flexShrink: 0,
+          overflow: 'auto',
+          borderRight: `1px solid ${themeVars.boundary.default}`,
+          background: themeVars.surface.inset,
+          padding: 4,
+        }}
+      >
+        {machines.map((machine) => (
+          <Button
+            key={machine.nodeId}
+            type="button"
+            variant="ghost"
+            className="vgai-debugger-machine"
+            data-selected={machine.nodeId === selected.nodeId || undefined}
+            onClick={() => selectDebuggerMachine(machine.nodeId)}
+          >
+            <div>{machine.machineId}</div>
+            <div style={{ color: themeVars.content.dim, fontSize: 10 }}>{machine.label}</div>
+          </Button>
+        ))}
+      </div>
+      <div style={{ flex: 1, minWidth: 0, minHeight: 0 }}>
+        <XStateMachineInspector
+          machine={binding.actor.logic as AnyStateMachine}
+          collectMachineAnimationMeta={collectMachineAnimationMeta}
+          clipNamesOf={clipNamesOf}
+          actor={binding.actor}
+        />
+      </div>
+    </div>
+  );
+}
+
+export function DebuggerPanel() {
+  useSyncExternalStore(subscribeDebuggerPanel, debuggerPanelVersion, debuggerPanelVersion);
+  useAvailabilityTick();
+  const active = activeDebuggerTab();
+  const debugAvailable = getActiveDebug() !== null;
+  const networkAvailable = getActiveNetworking() !== null;
+  const machinesAvailable = listLiveMachines().length > 0;
+  const tabs: TabSpec[] = [
+    { id: 'state', label: 'State' },
+    { id: 'profiler', label: 'Profiler' },
+    { id: 'network', label: 'Network' },
+    { id: 'machines', label: 'Machines' },
+    { id: 'commands', label: 'Commands' },
+  ];
+  return (
+    <div
+      data-testid="debugger-panel"
+      style={{
+        flex: 1,
+        minHeight: 0,
+        display: 'flex',
+        flexDirection: 'column',
+        background: themeVars.surface.inset,
+      }}
+    >
+      <EditorTabList aria-label="Debugger views">
+        {tabs.map((tab) => (
+          <EditorTab
+            key={tab.id}
+            selected={active === tab.id}
+            data-testid={`debugger-tab-${tab.id}`}
+            onClick={() => setDebuggerTab(tab.id)}
+          >
+            {tab.label}
+          </EditorTab>
+        ))}
+      </EditorTabList>
+      <div role="tabpanel" style={{ flex: 1, minHeight: 0, display: 'flex' }}>
+        {active === 'state' &&
+          (debugAvailable ? (
+            <StateWatchPanel />
+          ) : (
+            <EmptyDebugState>
+              Enter Play mode to inspect registered state providers.
+            </EmptyDebugState>
+          ))}
+        {active === 'profiler' && <PerformancePanel />}
+        {active === 'network' &&
+          (networkAvailable ? (
+            <NetworkSection variant="panel" />
+          ) : (
+            <EmptyDebugState>No live networking adapter is registered.</EmptyDebugState>
+          ))}
+        {active === 'machines' &&
+          (machinesAvailable ? (
+            <MachinesPanel />
+          ) : (
+            <EmptyDebugState>No live XState animation bindings are registered.</EmptyDebugState>
+          ))}
+        {active === 'commands' &&
+          (debugAvailable ? (
+            <DebugConsolePanel />
+          ) : (
+            <EmptyDebugState>Enter Play mode to run registered debug commands.</EmptyDebugState>
+          ))}
+      </div>
+    </div>
+  );
+}