@forgeax/engine-devkit 0.1.6 → 0.1.19

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,8 +33,9 @@ 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 package [--format web-zip|single-html] [--output release/game-web.zip]
 forgeax list --json
 forgeax describe project.build --json
 forgeax run project.build --input request.json --json
@@ -73,21 +77,170 @@ The selected directory is a derived build root and is emptied before writing.
 root. An SDK-owned target fails before template copying with `project-target-inside-sdk`; use a
 sibling directory or an absolute path outside the SDK.
 
+`forgeax new` requires an explicit template: choose `game-3d` for every 3D game, including custom
+3D genres, and choose `empty` otherwise. Omitting `--template` fails with `sdk-template-required`.
+
 `forgeax package` rebuilds with relative URLs, verifies the complete `forgeax-dist.json` closure,
 and emits a deterministic Web ZIP plus an adjacent SHA-256 file. The archive contains the bundled
 Engine JavaScript/WASM runtime and game assets at its root for HTTPS static or HTML-game hosting;
 it does not contain source, `node_modules`, or a local development server. Use `forgeax preview`
 for local HTTP acceptance. Opening the archived `index.html` through `file://` is unsupported.
 
+`forgeax package --format single-html --output release/game-offline.html` emits a self-contained
+single-HTML candidate and adjacent SHA-256. DevKit derives it from the same verified dist manifest,
+embeds the generated module/worker/WASM/resource closure, and reports the candidate path, digest,
+dist-manifest digest, and embedded asset count. The candidate is the acceptance object: open that
+exact file through `file://` in the release browser profile and require zero remote requests, failed
+requests, console/page errors, and resource misses before promotion. This format does not make
+arbitrary dist `index.html` files or network-dependent services offline.
+
 `discoverRhiDebugOperations()` returns the same descriptors used by help and
 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