@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/package.json

@@ -2,12 +2,22 @@
   "name": "@vgai/editor",
   "author": "Volter AI, Inc.",
   "license": "AGPL-3.0-only",
-  "version": "0.2.0",
+  "version": "0.4.0-canary.20260715.0",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/vgai-engine.git",
+    "directory": "packages/editor"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "files": [
     "dist",
     "dist-server",
     "server",
+    "scripts/run-probe.ts",
+    "scripts/probe-reporter.ts",
     "src",
     "vite-plugin-*.ts",
     "template"
@@ -17,20 +27,37 @@
   },
   "scripts": {
     "build": "cd ../.. && npx vite build --outDir packages/editor/dist --emptyOutDir",
-    "build:server": "npx esbuild server/packaged.ts --bundle --platform=node --format=esm --outfile=dist-server/packaged.mjs --tsconfig=../../tsconfig.server.json --external:express --external:chokidar --external:vite --external:esbuild --external:typescript",
-    "prepack": "npm run build && npm run build:server"
+    "build:server": "npx esbuild server/packaged.ts --bundle --platform=node --format=esm --outfile=dist-server/packaged.mjs --tsconfig=../../tsconfig.server.json --external:express --external:chokidar --external:vite --external:esbuild --external:typescript --external:@volter-ai-dev/supercode-client --external:@volter-ai-dev/supercode-harness-sdk",
+    "prepack": "npm run build && npm run build:server",
+    "storybook": "storybook dev -p 6006 --config-dir .storybook",
+    "storybook:build": "storybook build --config-dir .storybook",
+    "storybook:test:visual": "playwright test -c playwright.storybook.config.ts"
   },
   "dependencies": {
+    "@fortawesome/fontawesome-svg-core": "^7.2.0",
+    "@fortawesome/free-solid-svg-icons": "^7.2.0",
+    "@fortawesome/react-fontawesome": "^3.2.0",
     "@pixi/tilemap": "^5.0.0",
-    "@vgai/engine": "^0.3.0",
+    "@vgai/engine": "0.4.0-canary.20260715.0",
+    "axe-core": "^4.12.1",
     "chokidar": "^5.0.0",
+    "dockview-react": "^7.0.2",
     "esbuild": "^0.25.12",
     "express": "^5.2.1",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
     "typescript": "^5.6.0",
     "vite": "^6.0.0"
   },
+  "optionalDependencies": {
+    "@volter-ai-dev/supercode": "^0.2.1",
+    "@volter-ai-dev/supercode-client": "^0.3.0",
+    "@volter-ai-dev/supercode-harness-sdk": "^0.2.0"
+  },
   "devDependencies": {
+    "@storybook/addon-a11y": "^9.1.20",
     "@storybook/react": "^9.1.20",
+    "@storybook/react-vite": "^9.1.20",
     "storybook": "^9.1.20"
   }
 }

package/scripts/probe-reporter.ts

@@ -0,0 +1,349 @@
+/**
+ * `vgai probe`'s own Playwright reporter (ACCEPTANCE-DRIVER-BUILD-PLAN.md
+ * Task 3.4 steps 4/7, docs/ACCEPTANCE-DRIVER-SPEC.md §2.2) — writes the
+ * versioned `last-run.json` envelope every `vgai probe` run produces.
+ *
+ * This module is loaded by Playwright INSIDE the spawned `npx playwright
+ * test` process (referenced by absolute path from the generated config's
+ * `reporter` list — see `run-probe.ts`'s `buildProbeConfigSource`). It only
+ * ever sees Playwright's own Reporter API (`TestCase`/`TestResult`/
+ * `FullResult`) — never a live `Page`/`Browser` handle (those belong to the
+ * `game` fixture in `@vgai/probe`, a different module this reporter does not
+ * import and must not duplicate).
+ *
+ * Playwright's `TestError` type (`playwright/types/testReporter.d.ts`) has NO
+ * generic `data` field — only `message`/`stack`/`cause`/`location`/`snippet`/
+ * `value` survive a thrown Error's properties across the worker boundary.
+ * `@vgai/probe`'s `ProbeFailure`/`ProbeError` DO carry a rich `.data` object
+ * when caught inside the SAME process (see its own `errors.ts`), but that
+ * structure is invisible here — `failure-block.ts`'s `assembleFailureBlock`
+ * renders the identical eight-member block to BOTH the assertion `message`
+ * and its `data` (Task 3.3's contract: "renders... to the assertion message
+ * AND as structured data"), so `result.error.message` (or the first of
+ * `result.errors`) already contains the full contract text; this reporter
+ * treats it as the source of truth rather than reconstructing a lost object.
+ * A best-effort `code` is recovered by checking whether the message begins
+ * with one of `@vgai/probe`'s frozen error-code tokens (a match on the
+ * FROZEN CODE embedded in the message by that package's own `errors.ts`, not
+ * a prose heuristic — see `classifyFailureCode`).
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { FullResult, Reporter, TestCase, TestResult } from '@playwright/test/reporter';
+
+export const PROBE_REPORT_VERSION = 1 as const;
+
+export interface ProbeVerdict {
+  title: string;
+  file: string;
+  line: number;
+  status: 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted';
+  durationMs: number;
+  retry: number;
+}
+
+export interface ProbeFailureAttachment {
+  name: string;
+  contentType: string;
+  path?: string;
+}
+
+export interface ProbeFailureRecord {
+  title: string;
+  file: string;
+  line: number;
+  /** Best-effort, recovered from the frozen code token at the start of the
+   *  message (see module doc) — `null` when no known token matched (an
+   *  ordinary `expect()` assertion failure, not a `@vgai/probe` error). */
+  code: string | null;
+  /** D3: which `GAME_SEAM_NEVER_APPEARED` sub-case this is, recovered the
+   *  same way (a stable message prefix — see `classifyGameSeamSubCase`).
+   *  `null` for every other code, including when `code` itself is `null`. */
+  subCase: 'page-threw' | 'no-bridge' | null;
+  /** The full rendered failure-block text (or plain assertion message) —
+   *  see the module doc for why this, not a lost `.data` object, is the
+   *  structured contract this reporter can actually observe. */
+  message: string;
+  attachments: ProbeFailureAttachment[];
+}
+
+export interface ProbePerfSample {
+  title: string;
+  wallMs: number;
+}
+
+export interface LastRunEnvelope {
+  probeReportVersion: 1;
+  project: string;
+  startedAt: string;
+  finishedAt: string;
+  status: FullResult['status'];
+  verdicts: ProbeVerdict[];
+  failures: ProbeFailureRecord[];
+  artifacts: { outputDir: string };
+  perf: {
+    /** Honest-degrade note (never a fabricated fps/sim-speed number): full
+     *  per-test fps/frame-time-percentile/sim-speed capture needs page-side
+     *  instrumentation living in `@vgai/probe`'s fixture teardown (a
+     *  different package/agent's territory) — this reporter can only see
+     *  Playwright's own wall-clock `duration` per test. */
+    note: string;
+    samples: ProbePerfSample[];
+  };
+  /** AC-B1.7 — set ONLY on the synthetic envelope {@link buildWedgeEnvelope}
+   *  writes when `run-probe.ts`'s `main()` kills the child as a harness
+   *  wedge (exit 5): this class's `Reporter.onEnd` (the normal writer of
+   *  this file) never runs in that case — the child is killed mid-suite, not
+   *  finished — so an ordinary run's envelope never carries this field at
+   *  all. A consumer (`--last-failure`, a panel, a human `cat`-ing the file)
+   *  can check this BEFORE trusting `status`/`verdicts`/`failures` as "what
+   *  actually ran": a wedge envelope's `verdicts`/`failures` are always empty
+   *  by construction, not because nothing failed. */
+  wedged?: true;
+}
+
+/** Frozen error-code tokens `@vgai/probe`'s `errors.ts`/`failure-block.ts`
+ *  put at the START of a thrown error's message — see the module doc for why
+ *  matching these specific tokens is not the banned "identify a failure by
+ *  parsing message prose" pattern (Ground rule 4): it is the one channel
+ *  through which a frozen `code` survives the Playwright reporter boundary
+ *  at all. */
+const KNOWN_MESSAGE_CODE_PREFIXES: ReadonlyArray<{ prefix: string; code: string }> = [
+  { prefix: 'PROBE_ENV_MISSING:', code: 'PROBE_ENV_MISSING' },
+  { prefix: 'GAME_SEAM_NEVER_APPEARED:', code: 'GAME_SEAM_NEVER_APPEARED' },
+  { prefix: 'INPUT_GATED:', code: 'INPUT_GATED' },
+  { prefix: 'game.waitFor timed out', code: 'WAIT_FOR_TIMEOUT' },
+  { prefix: 'game.events.expect failed', code: 'EVENTS_EXPECT_FAILED' },
+];
+
+/** Strips the assisted-tier warning header (failure-block.ts prepends a line
+ *  before the headline) so prefix-matching still works on a
+ *  consumed-assisted-state failure. Shared by `classifyFailureCode` and
+ *  `classifyGameSeamSubCase`. */
+function stripWarningHeader(message: string): string {
+  return message.startsWith('⚠') ? (message.split('\n').slice(1).join('\n') ?? message) : message;
+}
+
+export function classifyFailureCode(message: string | undefined): string | null {
+  if (!message) return null;
+  const withoutWarningHeader = stripWarningHeader(message);
+  for (const { prefix, code } of KNOWN_MESSAGE_CODE_PREFIXES) {
+    if (withoutWarningHeader.startsWith(prefix)) return code;
+  }
+  return null;
+}
+
+/** D3: recovers `GAME_SEAM_NEVER_APPEARED`'s sub-case from the stable message
+ *  prefix `@vgai/probe`'s `gameSeamNeverAppearedError` embeds (its own
+ *  `data.subCase` does not survive the Playwright reporter boundary — see
+ *  this module's doc comment). `null` for any other failure, including a
+ *  `GAME_SEAM_NEVER_APPEARED` message that somehow carries neither prefix
+ *  (shouldn't happen — defensive, not silently misclassified as one or the
+ *  other). */
+export function classifyGameSeamSubCase(
+  message: string | undefined,
+): 'page-threw' | 'no-bridge' | null {
+  if (!message) return null;
+  const withoutWarningHeader = stripWarningHeader(message);
+  if (withoutWarningHeader.startsWith('GAME_SEAM_NEVER_APPEARED:page-threw:')) return 'page-threw';
+  if (withoutWarningHeader.startsWith('GAME_SEAM_NEVER_APPEARED:no-bridge:')) return 'no-bridge';
+  return null;
+}
+
+/** Minimal duck-typed views of Playwright's real `TestCase`/`TestResult` —
+ *  named separately so unit tests can construct plain fixtures without
+ *  standing up a real Playwright run (this module's exported pure functions
+ *  never require the real classes, only these shapes). */
+export interface MinimalTestCase {
+  title: string;
+  location: { file: string; line: number };
+}
+export interface MinimalTestResult {
+  status: 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted';
+  duration: number;
+  retry: number;
+  errors: ReadonlyArray<{ message?: string }>;
+  attachments: ReadonlyArray<{ name: string; contentType: string; path?: string }>;
+}
+
+export function buildVerdict(test: MinimalTestCase, result: MinimalTestResult): ProbeVerdict {
+  return {
+    title: test.title,
+    file: test.location.file,
+    line: test.location.line,
+    status: result.status,
+    durationMs: result.duration,
+    retry: result.retry,
+  };
+}
+
+/** `null` for a passed/skipped result — only failed/timedOut/interrupted
+ *  results produce a failure record. */
+export function buildFailureRecord(
+  test: MinimalTestCase,
+  result: MinimalTestResult,
+): ProbeFailureRecord | null {
+  if (result.status === 'passed' || result.status === 'skipped') return null;
+  const firstError = result.errors[0];
+  const message = firstError?.message ?? `${test.title}: ${result.status} with no captured error`;
+  return {
+    title: test.title,
+    file: test.location.file,
+    line: test.location.line,
+    code: classifyFailureCode(firstError?.message),
+    subCase: classifyGameSeamSubCase(firstError?.message),
+    message,
+    attachments: result.attachments.map((a) => ({
+      name: a.name,
+      contentType: a.contentType,
+      ...(a.path !== undefined ? { path: a.path } : {}),
+    })),
+  };
+}
+
+export interface BuildLastRunEnvelopeInput {
+  project: string;
+  startedAt: string;
+  finishedAt: string;
+  status: FullResult['status'];
+  verdicts: ProbeVerdict[];
+  failures: ProbeFailureRecord[];
+  outputDir: string;
+}
+
+/** Task 3.4's exit-code table needs "3 missing capability" distinguished
+ *  from an ordinary spec failure: true only when EVERY failure in the run
+ *  is the fixture's own `GAME_SEAM_NEVER_APPEARED` AND its `no-bridge`
+ *  sub-case (D3) — the page loaded fine but no debug bridge ever appeared.
+ *  The OTHER sub-case, `page-threw` (the game's own setup code crashed
+ *  before the bridge could install), is a real spec/build failure and must
+ *  classify as exit 1, not exit 3 — a mix of either sub-case plus an
+ *  ordinary assertion failure is likewise a real spec failure (exit 1), not
+ *  purely a missing capability. */
+export function allFailuresAreMissingCapability(failures: readonly ProbeFailureRecord[]): boolean {
+  return (
+    failures.length > 0 &&
+    failures.every((f) => f.code === 'GAME_SEAM_NEVER_APPEARED' && f.subCase === 'no-bridge')
+  );
+}
+
+export function buildLastRunEnvelope(input: BuildLastRunEnvelopeInput): LastRunEnvelope {
+  return {
+    probeReportVersion: PROBE_REPORT_VERSION,
+    project: input.project,
+    startedAt: input.startedAt,
+    finishedAt: input.finishedAt,
+    status: input.status,
+    verdicts: input.verdicts,
+    failures: input.failures,
+    artifacts: { outputDir: input.outputDir },
+    perf: {
+      note:
+        'wall-clock duration only — full fps/frame-time-percentile/sim-speed capture needs ' +
+        "page-side instrumentation in @vgai/probe's fixture teardown, not yet wired here.",
+      samples: input.verdicts.map((v) => ({ title: v.title, wallMs: v.durationMs })),
+    },
+  };
+}
+
+export interface BuildWedgeEnvelopeInput {
+  project: string;
+  startedAt: string;
+  /** The actual silent-window budget that triggered the kill
+   *  (`strikeIntervalMs * strikesToWedge`) — see `run-probe.ts`'s
+   *  `runPlaywrightSuite` doc comment; never hardcoded here so the note below
+   *  never lies about a test-shrunk budget. */
+  wedgeSilenceMs: number;
+  outputDir: string;
+}
+
+/**
+ * AC-B1.7 — the envelope `run-probe.ts`'s `main()` writes to `last-run.json`
+ * on a harness wedge (exit 5) INSTEAD of `ProbeJsonReporter.onEnd` (which
+ * never runs: the child is killed mid-suite, not finished — see
+ * `runPlaywrightSuite`'s `wedgeTriggered` doc comment for the exact
+ * mechanics). Without this, `clearStaleLastRun`'s own D4(a) delete (this
+ * module's header doc references it) leaves NO `last-run.json` at all after
+ * a wedge — a caller reading the file (`--last-failure`, a panel) would see
+ * "no file" and have no way to distinguish "no run has ever happened" from
+ * "a run just wedged". `verdicts`/`failures` are always empty here — not
+ * because nothing failed, but because no test in this run ever reached
+ * `onTestEnd` at all; `status: 'interrupted'` is Playwright's own closest
+ * documented meaning ("interrupted by the user" — this harness playing that
+ * role on the child's behalf), and `wedged: true` is the unambiguous marker
+ * a consumer should actually key off rather than inferring intent from
+ * `status` prose.
+ */
+export function buildWedgeEnvelope(input: BuildWedgeEnvelopeInput): LastRunEnvelope {
+  const silenceSeconds = Math.round(input.wedgeSilenceMs / 1000);
+  return {
+    probeReportVersion: PROBE_REPORT_VERSION,
+    project: input.project,
+    startedAt: input.startedAt,
+    finishedAt: new Date().toISOString(),
+    status: 'interrupted',
+    verdicts: [],
+    failures: [],
+    artifacts: { outputDir: input.outputDir },
+    wedged: true,
+    perf: {
+      note:
+        `harness wedge: the child produced no output for ${silenceSeconds}s and was killed ` +
+        '(exit 5) before any test reached onTestEnd — there are no verdicts/failures to report ' +
+        'from this run; see docs/ACCEPTANCE-DRIVER-SPEC.md §2.2.',
+      samples: [],
+    },
+  };
+}
+
+export interface ProbeJsonReporterOptions {
+  /** Absolute path to write the envelope to (`.vgai/probe/last-run.json`). */
+  outputFile: string;
+  /** Absolute project directory — carried into the envelope's `project`. */
+  projectDir: string;
+  /** Absolute artifacts directory (`.vgai/probe/last-run/`) — carried into `artifacts.outputDir`. */
+  outputDir: string;
+}
+
+/** The real Playwright-facing reporter — a thin glue layer over the pure
+ *  functions above. Constructed by Playwright itself via the generated
+ *  config's `reporter: [[<this module's path>, options]]` entry. */
+export default class ProbeJsonReporter implements Reporter {
+  private readonly opts: ProbeJsonReporterOptions;
+  private readonly startedAt = new Date().toISOString();
+  private verdicts: ProbeVerdict[] = [];
+  private failures: ProbeFailureRecord[] = [];
+
+  constructor(opts: ProbeJsonReporterOptions) {
+    this.opts = opts;
+  }
+
+  onTestEnd(test: TestCase, result: TestResult): void {
+    const minimalTest: MinimalTestCase = { title: test.title, location: test.location };
+    const minimalResult: MinimalTestResult = {
+      status: result.status,
+      duration: result.duration,
+      retry: result.retry,
+      errors: result.errors,
+      attachments: result.attachments,
+    };
+    this.verdicts.push(buildVerdict(minimalTest, minimalResult));
+    const failure = buildFailureRecord(minimalTest, minimalResult);
+    if (failure) this.failures.push(failure);
+  }
+
+  onEnd(result: FullResult): void {
+    const envelope = buildLastRunEnvelope({
+      project: this.opts.projectDir,
+      startedAt: this.startedAt,
+      finishedAt: new Date().toISOString(),
+      status: result.status,
+      verdicts: this.verdicts,
+      failures: this.failures,
+      outputDir: this.opts.outputDir,
+    });
+    mkdirSync(dirname(this.opts.outputFile), { recursive: true });
+    writeFileSync(this.opts.outputFile, `${JSON.stringify(envelope, null, 2)}\n`);
+  }
+}