@forgeax/engine-devkit 0.1.4 → 0.1.7

package/README.md

@@ -12,6 +12,9 @@ owns rendering, RHI events, replay backends, and preview execution.
 ## Navigation
 
 - [CLI and catalog](#cli-and-catalog)
+- [Browser compositor capture](#browser-compositor-capture)
+- [Engine source binding](#engine-source-binding)
+- [Startup diagnostics](#startup-diagnostics)
 - [RHI-debug operations](#rhi-debug-operations)
 - [Authoring preview](#authoring-preview)
 - [Project authority](#project-authority)
@@ -22,7 +25,7 @@ owns rendering, RHI events, replay backends, and preview execution.
 The normal project commands remain available through the `forgeax` CLI:
 
 ```text
-forgeax new [directory] [--template empty|game-default]
+forgeax new [directory] [--template empty|game-3d]
 forgeax init
 forgeax doctor
 forgeax skill install
@@ -30,17 +33,23 @@ forgeax skill verify
 forgeax test
 forgeax dev
 forgeax build
+forgeax capture --backend auto --require-ui --output artifacts/capture/game-ui.png --json
 forgeax preview
 forgeax package [--output release/game-web.zip]
 forgeax list --json
 forgeax describe project.build --json
 forgeax run project.build --input request.json --json
 forgeax exec program.mjs --json
-forgeax run rhi.capture
-forgeax run rhi.summary --artifact {ArtifactRef}
-forgeax run rhi.inspect --artifact {ArtifactRef} --work-index {workIndex}
+forgeax run rhi.summary --artifact .forgeax-debug/{runId}/frame.rhitape --digest {sha256}
+forgeax run rhi.inspect --artifact .forgeax-debug/{runId}/frame.rhitape --digest {sha256} --work-index {workIndex}
 ```
 
+> [!IMPORTANT]
+> `forgeax dev` is a source-development server and `forgeax preview` is a
+> verified static `dist/` server. Their `--json` startup envelopes expose
+> `mode`, `serves`, and the current `rhi.capture` capability. Neither command
+> silently invents a live capture attachment.
+
 Static deployment is an Engine-owned build product. A publishing host supplies
 the project root, public URL base, and dedicated output directory; DevKit owns
 the generated host, asset cooking, shader compilation, Pack index, and
@@ -78,20 +87,168 @@ for local HTTP acceptance. Opening the archived `index.html` through `file://` i
 schema output. The operation manifest is the single discovery and recovery
 surface for RHI-debug.
 
+## Browser compositor capture
+
+> [!IMPORTANT]
+> forgeax capture is a development visual-evidence path. It uses the host browser adapter when
+> available and can explicitly use a software lane on machines with no physical GPU or display. It
+> is not a player or release-acceptance gate.
+
+The command starts the source-development host on an ephemeral loopback port, creates an Xvfb display
+when `$DISPLAY` is absent on Linux, launches a real Chromium browser, waits for an engine frame signal
+and non-flat **canvas** pixels, then takes a Playwright **page screenshot**. A page screenshot
+composites the WebGPU canvas with normal DOM and open ShadowRoot UI;
+`canvas.toDataURL()` cannot provide that proof. `--wait-ms` is an additional settle interval after the
+first non-flat canvas frame, not a guess for CPU startup time.
+
+```bash
+forgeax capture --backend software --require-ui \
+  --output artifacts/capture/game-ui.png \
+  --width 1280 --height 720 --wait-ms 4000 --json
+```
+
+The adjacent `game-ui.json` is the schema-v2 run manifest. Its run-level fields record the browser,
+viewport, X display, lavapipe ICD discovery, and browser errors; its ordered `captures[]` rows record
+each PNG digest, checkpoint, actual `GPUAdapterInfo`, canvas/UI witnesses, and canvas-only sampled luma
+backend auto (the default) tries the normal browser adapter and falls back to the software lane only
+when WebGPU is unavailable. backend hardware requires a non-software adapter; backend software pins
+SwiftShader/lavapipe-compatible browser flags. The old --software spelling remains a compatibility
+alias for backend software.
+
+range. The witness screenshot temporarily hides every non-canvas element, so a visible HUD cannot
+disguise a black 3D frame; the written PNG remains the complete page compositor output.
+`--require-ui` requires at least one mounted child under the generated host's `#game-ui` root; unrelated
+Engine or browser ShadowRoots are only diagnostics and cannot satisfy the gate. A uniform black frame
+also fails even when canvas and adapter structure exist. Use `--browser` only when Chrome Beta is not at
+`/opt/google/chrome-beta/chrome`.
+
+The browser context fixes the viewport and screen size, DPR 1, sRGB colour profile, light colour
+scheme, `en-US` locale, UTC timezone, and waits for `document.fonts.ready`. Projects must ship the same
+Web font files on every machine; a system-font fallback is not a colour or layout parity contract.
+
+For local/remote pixel or colour comparison, add `--deterministic`. The command navigates with
+`?forgeaxCapture=1`. The Engine App publishes
+`document.documentElement.dataset.forgeaxFrameSubmitted` (the monotonic frame id) after the Renderer
+crosses its real queue-submit boundary and dispatches `forgeax:frame-submitted` on the canvas. DevKit
+waits for that engine signal and a non-flat canvas crop before consuming the game's
+`document.documentElement.dataset.forgeaxCaptureReady` checkpoint; it never guesses startup time. The
+game remains the time authority: in capture mode it must pin its random seed, viewport-independent
+state, local web fonts, and logical time/frame, render that state, then publish the ready marker. A
+wall-clock delay is useful only as extra settle and is not parity evidence.
+
+```bash
+forgeax capture --backend software --require-ui --deterministic \
+  --width 1280 --height 720 --output artifacts/capture/parity.png --json
+```
+
+### Persistent playthrough capture
+
+`capture` is the one-shot adapter over the same browser owner. For one game boot followed by input,
+assertions, and multiple compositor captures, compose the persistent session through `forgeax exec`:
+
+```js
+export default async function playthrough({ browser }) {
+  const session = await browser.open({
+    backend: 'auto',
+    deterministic: true,
+    requireUi: true,
+    outputDir: 'artifacts/playthrough/boss-flow',
+  });
+  try {
+    const { page } = session;
+    await page.getByRole('button', { name: 'Start' }).click();
+    const spawn = await session.capture('spawn');
+    await page.keyboard.press('KeyW');
+    const arena = await session.capture('arena');
+    await page.getByRole('button', { name: 'Cast' }).click();
+    const bossHit = await session.capture('boss-hit');
+    return { report: session.reportPath, captures: [spawn, arena, bossHit] };
+  } finally {
+    await session.close();
+  }
+}
+```
+
+```bash
+forgeax exec tests/boss-playthrough.mjs --json
+```
+
+The Engine App frame signal and the game checkpoint are separate composable authorities:
+`session.capture('boss-hit')` waits for the engine frame signal, then the exact
+`document.documentElement.dataset.forgeaxCaptureReady` value and non-flat pixels. Playwright remains
+the input/assertion owner through the unwrapped `session.page`.
+DevKit owns Xvfb/Chrome/Vite lifecycle, compositor stabilization, PNG validation, numbering, digests,
+and one `run.json`. A live `Page` or session may not be returned from the program; `exec` accepts only
+JSON-safe results and closes leaked sessions on exit.
+
+| Browser backend | Owner | What it proves |
+|:--|:--|:--|
+| Mesa lavapipe | Dawn/Node smoke and explicit GPUTexture readback | Offscreen render pixels without a display; no HTML UI |
+| Chrome hardware adapter | forgeax capture --backend hardware | Browser compositor pixels on the selected adapter plus HTML/Shadow DOM |
+| Chrome SwiftShader under Xvfb | forgeax capture --backend software or forgeax exec browser session | Browser WebGPU canvas plus HTML/Shadow DOM in ordered viewport PNGs |
+
+> [!CAUTION]
+> Software pixels are iteration evidence. They do not prove physical-GPU performance, vendor-driver
+> behavior, HDR-display output, or release visual acceptance.
+
+## Engine source binding
+
+Built-package games normally resolve @forgeax/engine from the registry. A source-development game
+can bind the same dependency name to a checked-out Engine workspace without editing its manifest:
+
+```bash
+forgeax engine status --json
+forgeax engine use-local ../forgeax-engine --json
+forgeax engine doctor --json
+forgeax engine unlink --json
+```
+
+The binding is stored only in .forgeax/engine-binding.json; file absence is the single normal
+registry/SDK state. The project manifest remains the dependency authority. engine doctor fails
+closed for a pnpm workspace dependency that npm cannot consume, for an unbuilt local workspace, or
+for a missing SDK package. Status derives its workspace digest from the actual built entry bytes and
+reports their newest modification time. engine unlink removes the sole override and returns to the
+normal registry/SDK resolution path.
+
 Physical realm consumers use `createRealmDispatch`. Each descriptor is routed to
 one owner for its declared `build`, `host`, or `engine` realm. A missing owner
 returns `tool-capability-unavailable` with the realm in `detail`; it never falls
 through to another realm.
 
+## Startup diagnostics
+
+The generated game host renders structured startup failures recursively instead
+of coercing thrown objects to `[object Object]`. It preserves `name`, `message`,
+`code`, `expected`, `hint`, `reason`, and bounded nested
+`cause/detail/webgpuError/wgpuError/error` fields. Generic objects use bounded
+JSON serialization and circular objects receive an explicit diagnostic.
+
+When the resulting evidence mentions WebGPU, adapter absence, or no usable
+backend, the host also states that ForgeaX supports browser WebGPU and a
+wgpu/WebGL2 fallback. This note is intentionally not a fallback decision: the
+structured cause remains the authority. A publishing Agent must not infer
+unsupported hardware, swallow the entry error, or inject a replacement Canvas
+game merely to remove an uncaught exception.
+
 ## RHI-debug operations
 
+The operation manifest describes the complete host contract, but a standalone
+CLI process does not own a running browser App. Consequently,
+`forgeax run rhi.capture --json` is a structured capability probe and returns
+`capture-unavailable` until a recorder-enabled live host supplies the
+`rhiCapture` eval root. Use the browser live bridge described by the
+`forgeax-engine-cli` skill to invoke that root; preserve the resulting tape's
+`digest` and `path` for the offline commands below. `rhi.summary` and
+`rhi.inspect` remain directly executable because they consume the persisted
+artifact rather than live App state.
+
 ```mermaid
 sequenceDiagram
   participant AI as "AI or CLI"
   participant H as "Host"
   participant D as "DevKit"
   participant R as "Fresh replay backend"
-  AI->>H: "rhi.capture"
+  AI->>H: "rhiCapture.captureFrame through the live host"
   H-->>AI: "one ArtifactRef"
   AI->>D: "rhi.summary + ArtifactRef"
   D-->>AI: "FrameModel and workIndex"