@forgeax/view 0.2.1-beta-20260924075842

package/package.json

@@ -0,0 +1,174 @@
+{
+  "name": "@forgeax/view",
+  "version": "0.2.1-beta-20260924075842",
+  "type": "module",
+  "description": "An optional display host for ForgeaX CLI runs",
+  "bin": {
+    "forgeax-view": "./dist/modules/cli.mjs",
+    "forgeax-view-start": "./dist/modules/start-cli.mjs"
+  },
+  "files": [
+    "dist",
+    "host.pack.json",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@forgeax/engine": "0.2.0",
+    "@forgeax/engine-host": "0.2.0",
+    "@forgeax/engine-plugin": "0.2.0",
+    "@forgeax/engine-tool-runtime": "0.2.0",
+    "dockview": "^6.6.1",
+    "lucide-react": "^0.460.0",
+    "playwright": "1.63.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "ws": "^8.21.0"
+  },
+  "devDependencies": {
+    "@forgeax/view-components": "0.0.0",
+    "@forgeax/view-plugin-content-browser": "0.0.0",
+    "@forgeax/view-plugin-display": "0.0.0",
+    "@forgeax/view-plugin-inspector": "0.0.0",
+    "@forgeax/view-plugin-material": "0.0.0",
+    "@forgeax/view-plugin-mesh": "0.0.0",
+    "@forgeax/view-plugin-texture": "0.0.0",
+    "@forgeax/view-plugin-asset": "0.0.0",
+    "@forgeax/view-plugin-plugins": "0.0.0",
+    "@forgeax/view-plugin-scene": "0.0.0",
+    "@forgeax/view-plugin-scene-tree": "0.0.0",
+    "@forgeax/view-plugin-viewport": "0.0.0",
+    "@forgeax/view-viewer": "0.0.0",
+    "@forgeax/view-workspace-core": "0.0.0",
+    "@changesets/changelog-github": "0.5.2",
+    "@changesets/cli": "2.29.8",
+    "esbuild": "0.28.2",
+    "typescript": "5.9.3",
+    "vite": "8.0.10"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./workspace/presentation": "./dist/modules/workspace/presentation.mjs",
+    "./pages/scene": "./dist/modules/pages/scene.mjs",
+    "./shell/frontend": "./dist/modules/shell/frontend.mjs",
+    ".": "./dist/modules/index.mjs",
+    "./browser": "./dist/modules/browser.mjs",
+    "./carrier": "./dist/modules/carrier.mjs",
+    "./carrier-contract": "./dist/modules/carrier-contract.mjs",
+    "./backend": "./dist/modules/backend.mjs",
+    "./extension-bridge": "./dist/modules/extension-bridge.mjs",
+    "./cli": "./dist/modules/cli.mjs",
+    "./start": "./dist/modules/start.mjs",
+    "./page": "./dist/modules/page.mjs",
+    "./embedded": "./dist/modules/embedded.mjs",
+    "./workspace-frontend": "./dist/modules/workspace-frontend.mjs",
+    "./frontend-root": "./dist/modules/frontend-root.mjs",
+    "./commands": "./dist/modules/commands.mjs",
+    "./command-executor": "./dist/modules/command-executor.mjs",
+    "./plugin": "./dist/modules/plugin.mjs",
+    "./cli-contributions": "./dist/modules/cli-contributions.mjs",
+    "./viewer": "./dist/modules/viewer.mjs",
+    "./viewer/catalog": "./dist/modules/viewer/catalog.mjs",
+    "./viewer/catalog/shared": "./dist/modules/viewer/catalog/shared.mjs",
+    "./viewer/catalog/backend": "./dist/modules/viewer/catalog/backend.mjs",
+    "./viewer/catalog/frontend": "./dist/modules/viewer/catalog/frontend.mjs",
+    "./viewer/cli": "./dist/modules/viewer/cli.mjs",
+    "./plugins/display/identity": "./dist/modules/plugins/display/identity.mjs",
+    "./plugins/display/backend": "./dist/modules/plugins/display/backend.mjs",
+    "./plugins/display/frontend": "./dist/modules/plugins/display/frontend.mjs",
+    "./plugins/display/ui": "./dist/modules/plugins/display/ui.mjs",
+    "./plugins/display/api": "./dist/modules/plugins/display/api.mjs",
+    "./plugins/display/schema": "./dist/modules/plugins/display/schema.mjs",
+    "./plugins/content-browser/identity": "./dist/modules/plugins/content-browser/identity.mjs",
+    "./plugins/content-browser/frontend": "./dist/modules/plugins/content-browser/frontend.mjs",
+    "./plugins/content-browser/schema": "./dist/modules/plugins/content-browser/schema.mjs",
+    "./plugins/content-browser/ui": "./dist/modules/plugins/content-browser/ui.mjs",
+    "./plugins/plugins/identity": "./dist/modules/plugins/plugins/identity.mjs",
+    "./plugins/plugins/backend": "./dist/modules/plugins/plugins/backend.mjs",
+    "./plugins/plugins/frontend": "./dist/modules/plugins/plugins/frontend.mjs",
+    "./plugins/plugins/api": "./dist/modules/plugins/plugins/api.mjs",
+    "./plugins/plugins/cli": "./dist/modules/plugins/plugins/cli.mjs",
+    "./plugins/plugins/schema": "./dist/modules/plugins/plugins/schema.mjs",
+    "./plugins/plugins/ui": "./dist/modules/plugins/plugins/ui.mjs",
+    "./plugins/inspector/identity": "./dist/modules/plugins/inspector/identity.mjs",
+    "./plugins/inspector/frontend": "./dist/modules/plugins/inspector/frontend.mjs",
+    "./plugins/inspector/schema": "./dist/modules/plugins/inspector/schema.mjs",
+    "./plugins/inspector/ui": "./dist/modules/plugins/inspector/ui.mjs",
+    "./plugins/scene/identity": "./dist/modules/plugins/scene/identity.mjs",
+    "./plugins/scene/frontend": "./dist/modules/plugins/scene/frontend.mjs",
+    "./plugins/scene-tree/identity": "./dist/modules/plugins/scene-tree/identity.mjs",
+    "./plugins/scene-tree/frontend": "./dist/modules/plugins/scene-tree/frontend.mjs",
+    "./plugins/scene-tree/schema": "./dist/modules/plugins/scene-tree/schema.mjs",
+    "./plugins/scene-tree/ui": "./dist/modules/plugins/scene-tree/ui.mjs",
+    "./plugins/material/identity": "./dist/modules/plugins/material/identity.mjs",
+    "./plugins/material/frontend": "./dist/modules/plugins/material/frontend.mjs",
+    "./plugins/material/schema": "./dist/modules/plugins/material/schema.mjs",
+    "./plugins/material/ui": "./dist/modules/plugins/material/ui.mjs",
+    "./plugins/mesh/identity": "./dist/modules/plugins/mesh/identity.mjs",
+    "./plugins/mesh/frontend": "./dist/modules/plugins/mesh/frontend.mjs",
+    "./plugins/mesh/schema": "./dist/modules/plugins/mesh/schema.mjs",
+    "./plugins/mesh/ui": "./dist/modules/plugins/mesh/ui.mjs",
+    "./plugins/texture/identity": "./dist/modules/plugins/texture/identity.mjs",
+    "./plugins/texture/frontend": "./dist/modules/plugins/texture/frontend.mjs",
+    "./plugins/texture/schema": "./dist/modules/plugins/texture/schema.mjs",
+    "./plugins/texture/ui": "./dist/modules/plugins/texture/ui.mjs",
+    "./plugins/asset/identity": "./dist/modules/plugins/asset/identity.mjs",
+    "./plugins/asset/frontend": "./dist/modules/plugins/asset/frontend.mjs",
+    "./plugins/asset/schema": "./dist/modules/plugins/asset/schema.mjs",
+    "./plugins/asset/ui": "./dist/modules/plugins/asset/ui.mjs",
+    "./plugins/viewport/identity": "./dist/modules/plugins/viewport/identity.mjs",
+    "./plugins/viewport/frontend": "./dist/modules/plugins/viewport/frontend.mjs",
+    "./plugins/viewport/schema": "./dist/modules/plugins/viewport/schema.mjs",
+    "./workspace/api": "./dist/modules/workspace/api.mjs",
+    "./workspace/backend": "./dist/modules/workspace/backend.mjs",
+    "./workspace/broker": "./dist/modules/workspace/broker.mjs",
+    "./workspace/cli": "./dist/modules/workspace/cli.mjs",
+    "./workspace/client": "./dist/modules/workspace/client.mjs",
+    "./workspace/contract": "./dist/modules/workspace/contract.mjs",
+    "./workspace/engine-adapter": "./dist/modules/workspace/engine-adapter.mjs",
+    "./workspace/extension-bridge": "./dist/modules/workspace/extension-bridge.mjs",
+    "./workspace/frontend-plugin": "./dist/modules/workspace/frontend-plugin.mjs",
+    "./workspace/frontend": "./dist/modules/workspace/frontend.mjs",
+    "./workspace/id": "./dist/modules/workspace/id.mjs",
+    "./workspace/resident": "./dist/modules/workspace/resident.mjs",
+    "./workspace/resource-open": "./dist/modules/workspace/resource-open.mjs",
+    "./workspace/tool-runtime": "./dist/modules/workspace/tool-runtime.mjs",
+    "./shell/contract": "./dist/modules/shell/contract.mjs",
+    "./shell/layout-zones": "./dist/modules/shell/layout-zones.mjs",
+    "./viewer-host": "./dist/modules/viewer-host.mjs",
+    "./viewer-host/frontend": "./dist/modules/viewer-host/frontend.mjs",
+    "./viewer-host/page-registry": "./dist/modules/viewer-host/page-registry.mjs",
+    "./viewer-host/slot-registry": "./dist/modules/viewer-host/slot-registry.mjs"
+  },
+  "scripts": {
+    "build": "pnpm run build:viewer && node scripts/build-package.mjs",
+    "build:viewer": "pnpm --filter @forgeax/view-viewer build",
+    "dev": "pnpm --filter @forgeax/view-viewer dev",
+    "dev:ui": "pnpm --filter @forgeax/view-viewer dev:ui",
+    "storybook": "pnpm --filter @forgeax/view-components storybook",
+    "build:storybook": "pnpm --filter @forgeax/view-components build:storybook",
+    "check:components": "pnpm --filter @forgeax/view-components check",
+    "check:packages": "pnpm -r --if-present check",
+    "check:architecture": "node scripts/check-architecture.mjs && node --test test/source-boundaries.test.mjs test/architecture-ci.test.mjs test/no-legacy-surfaces.test.mjs",
+    "changeset": "changeset",
+    "changeset:version": "changeset version && node scripts/sync-release-version.mjs",
+    "release": "node scripts/release-npm.mjs",
+    "release:snapshot": "node scripts/release-npm.mjs snapshot",
+    "release:dry-run": "node scripts/release-npm.mjs dry-run --tag beta",
+    "release:verify": "node scripts/release-npm.mjs verify",
+    "postinstall": "node --input-type=module -e \"import{existsSync}from'node:fs';if(existsSync('.git'))await import('./scripts/sync-harness.mjs')\"",
+    "harness:sync": "node scripts/sync-harness.mjs",
+    "harness:init": "node scripts/init-harness.mjs",
+    "test": "node --test scripts/sync-harness.test.mjs scripts/release-npm.test.mjs test/*.test.mjs",
+    "test:view": "node --test test/*.test.mjs",
+    "test:package": "node --test test/package-aggregate.test.mjs"
+  }
+}

package/skills/forgeax-view-cli/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: forgeax-view-cli
+description: >-
+  Use the authoritative View workspace API through its CLI clients. Use when
+  inspecting or changing View project bindings, opening assets, selecting scene
+  entities, or checking whether a CLI request affects an open View page.
+---
+
+# ForgeaX View API and CLI
+
+> [!IMPORTANT]
+> The resident workspace API is authoritative. The browser and CLI are clients
+> of the same owner; the CLI does not implement project, asset, scene, or camera
+> behavior. Engine owns project and target execution. View owns workspace
+> bindings, selection, and presentation requests.
+
+## Find the live contract
+
+Read `@forgeax/view/workspace/contract` for operation names and request shape
+(`packages/view-workspace-core/src/contract.mjs` in this repository). For
+programmatic clients, call
+`connectViewWorkspace(...).capabilities()` to see what the connected owner can
+execute. The contract's operation list alone does not prove that a provider is
+installed and callable. Use `tabs.get` for the current project, tab, and exact
+target identities; obtain asset GUIDs from `assets.list`. Keep the returned
+`projectId`, `targetId`, and `targetGeneration` with subsequent requests instead
+of guessing from paths, names, or a previous target.
+
+| Need | Owner and entry |
+|:--|:--|
+| Backend or optional View lifecycle | `forgeax backend ...` and `forgeax view start\|status\|stop`; use [View startup](../forgeax-view-start/SKILL.md) |
+| Allocate an Editor project on the running View | `forgeax view project open --root <backend-root> --project <project-root> --json`; open the returned headed URL |
+| Call one resident workspace operation through Engine CLI | `forgeax view workspace call --root <backend-root> --operation <id> --args <json> --json`; requires the selected View host Pack and running View owner |
+| Call the resident View workspace API | `forgeax-view workspace --operation <id> --args <json>` with the issued endpoint and token |
+| Author assets or control an independent AI run | Engine CLI; use the installed `forgeax-engine-cli` skill when available |
+
+`forgeax help view --tree --json` discovers declarations from the running
+backend's selected host Pack. A listed command does not prove its plugin
+is mounted or its provider is callable. The `forgeax-view workspace --help`
+operation list describes its client grammar; an unavailable operation fails at
+the connected owner. The workspace CLI accepts `--endpoint` and `--token`, or
+`FORGEAX_VIEW_WORKSPACE_ENDPOINT` and `FORGEAX_VIEW_WORKSPACE_TOKEN`. Treat
+these credentials as connection secrets; do not paste them into reports.
+The resident View registers `view.workspace.*` on ToolApi; the frontend
+transport and both CLI entries reach the same View owner. The Engine CLI
+entry uses the backend's existing authentication. Select the package host
+with `backend start --host-pack`; a downloaded View package alone
+does not make this command discoverable.
+
+## Open a scene through the API
+
+With an Editor project already open, call `tabs.get`, then `assets.list` for its
+`projectId`. Choose the scene asset's exact GUID. The Content Browser's double
+click and the following CLI call both submit `asset.open` with the same
+workspace tab and project identity:
+
+```sh
+forgeax-view workspace --operation asset.open \
+  --args '{"projectId":"<project-id>","guid":"<scene-guid>","tabId":"forgeax-user-workspace"}'
+```
+
+After success, read `tabs.get` again and check its `openRequest` and Editor
+target. If an already connected frontend has the scene PageType, it observes
+the new request and focuses the Editor page. A frontend that connects later
+baselines the retained request; the CLI response alone does not prove a page
+is visible or that a rendered frame exists. Verify the browser and target when
+the requested outcome is visual.
+
+Use `scene.select`, `scene.pick`, or `scene.clear` for View selection; direct
+Engine `target.pick` only returns query facts. Page layout, Content Browser
+filters, and other local UI interactions are frontend policy and need not have
+workspace CLI operations. Keep multi-call camera transactions on one client
+connection with `--batch`; a single CLI call closes its connection after the
+API response.

package/skills/forgeax-view-start/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: forgeax-view-start
+description: >-
+  Bind a local Engine checkout and compose independent ForgeaX backend, View,
+  project, browser and run operations. Use when opening a project with View, starting View, switching a project to
+  local Engine, or diagnosing a startup that stalls before the interface opens.
+---
+
+# ForgeaX View startup
+
+## Open a project with one script
+
+For a local Engine checkout and known game project, run the bundled script:
+
+```sh
+node skills/forgeax-view-start/scripts/start-view.mjs \
+  --project /absolute/path/to/game \
+  --engine /absolute/path/to/forgeax-engine
+```
+
+The script checks the package link and local Engine binding, builds stale
+Engine/View outputs, prepares the shader profile, reuses or starts a managed
+backend with View's `host.pack.json`, and calls `view start --project`. It
+returns one JSON result on stdout. Read `url` from an `ok: true` result and
+open it with the available browser tool. Then verify the requested project
+name/content and a live Engine target in the browser. The URL alone proves
+only that View is serving the project intent. The script does not launch a
+browser, open Play, or control an independent AI run.
+
+Use `--view` for another View checkout, `--root` for a dedicated empty backend
+workspace, `--restart` after a compatible host needs replacement, and
+`--profile point-ssao` for a project that uses point shadows. `--build auto`
+is the default; `--build always` rebuilds, and `--build never` requires fresh
+outputs. The script refuses a conflicting package link, foreign backend, or
+nonempty unmanaged workspace and reports the failing stage in JSON. Do not
+silently replace those owners. Progress and command diagnostics go to stderr.
+
+The manual composition below remains useful for a narrower service-only
+request or diagnosis of a failed stage.
+
+Read [Start here](../../README.md#start-here) for the current commands and Pack
+PluginAsset root. Check the selected Engine package's public exports and CLI help
+before using a command.
+
+## Interpret the requested outcome
+
+Treat "use View to start this project" as a request to open that project in
+View for editing. Compose the necessary steps in this skill; do not require the
+user to request each service separately. Start Play or an independent AI run
+only when the user requests that execution mode. A request for just a service
+or URL ends at that narrower outcome.
+
+| Step | Owner and boundary | Completion evidence |
+|:--|:--|:--|
+| Backend | Explicit Engine backend command; reuse a compatible owner or start a missing one | Backend responds with the requested Engine and host composition |
+| View | View plugin command on that backend; never implicitly starts the backend | View returns its interface URL |
+| Browser | Agent uses an available browser tool when the request includes opening the project | Returned URL is visited; low-level CLI commands do not launch a browser |
+| Project | Existing workspace API, reached through the project-intent URL or explicit project.open | Requested project identity, content and exact Engine target are present |
+| Play / AI run | Explicit Engine execution operation for the requested mode | Its own target or run readiness; separate from Editor readiness |
+
+Use a documented convenience command when the installed CLI provides one;
+otherwise compose the independent commands here. Check which services it starts,
+whether it opens a browser/project, its reuse policy, and its completion result.
+Do not assume a `forgeax view open` command exists. Command discovery/help must
+not activate services. Follow the installed package's current root and
+PluginAsset contract; design proposals are not available commands.
+
+Keep API calls usable independently of CLI workflows. Convenience commands may
+compose public APIs, while each underlying CLI command retains its documented
+single-operation behavior. Do not duplicate domain validation or state in a
+convenience wrapper, or make a low-level API silently perform the full workflow.
+
+For a known project, carry its canonical path through the returned URL or
+project.open request. Prefer the URL-intent path for an ordinary browser open;
+use explicit project.open when allocation before navigation is required. Do not
+issue both as independent allocations. Reuse an existing matching project and
+URL; a different open project or incompatible backend requires resolving that
+specific conflict, not silently switching or restarting it.
+
+If no suitable browser tool or desktop is available, return the actual URL and
+report that browser/project readiness remains unverified. A URL or allocated
+target alone is not completion of a request to open the project. Preserve the
+last successful stage and original failure; retry only the failed step after
+checking current owner state. Do not replay editing, scene-open, or Play actions.
+
+## Resolve the requested Engine
+
+For a local repository request, follow
+[Use a local Engine checkout](../../README.md#use-a-local-engine-checkout).
+Inspect the current package link and `project engine status` first. Keep a
+matching healthy binding; do not replace it with an SDK archive or rebuild it
+merely to start View.
+
+The package link selects the local CLI and Node-side Pack imports. The existing
+`project engine use-local` binding selects local workspace exports for the
+browser host. Verify `mode: "local"`, the requested checkout, the resolved built
+entry, and `project engine check` before reporting the binding complete. Use
+public built exports; do not redirect package exports or Vite aliases to `src`.
+Resolve the actual `node_modules/@forgeax/engine` link from the project and
+compare it with the checkout in `.forgeax/engine-binding.json`. Both sides must
+select the same Engine revision. `project engine check` proves the browser
+binding is healthy, but a different Node-side package link can still cook Pack
+assets with stale component fields.
+
+Build missing or changed outputs explicitly. After building a local Engine
+checkout, prepare the shader profile used by the target and check both
+`packages/vite-plugin-shader/dist/engine-inputs/<profile>/manifest.json` and
+`imports.json` before starting a rendering target. The default profile is
+`base-ssao`; use the matching point-shadow profile when that feature is enabled.
+Recheck after rebuilding the shader package, since its `dist` output can replace
+the prepared profile. A missing profile makes each fresh Backend compile Engine
+shaders from source and can keep one CPU busy for minutes; a healthy package
+build count alone does not establish rendering readiness. Report preparation
+separately from backend/View startup. Do not pack a candidate SDK as a
+substitute for the requested local repository binding.
+
+## Compose only the requested operations
+
+Inspect `backend status` and `view status` for the chosen workspace root. Reuse
+an existing healthy service with the requested Engine. A binding change does
+not update running owners; apply it with an explicit backend restart, and keep
+independent runs under their separate lifecycle. Select the installed View
+package's `host.pack.json` with `backend start --host-pack <absolute-pack-path>`.
+The game needs no View asset or changed `roots.host`. If it already owns a host
+root, use a separate backend workspace root and open the game with `--project`.
+Perform the operations needed for the user's requested outcome:
+
+| Request | Action and completion evidence |
+|:--|:--|
+| Start Engine backend | `backend start --host-pack <View package>/host.pack.json`; Engine API and the selected View plugin are ready |
+| Start View | Connect to the backend with `view start`; return the actual URL |
+| Open the interface | Open that URL in the user's browser; verify Shell connection if browser interaction is requested |
+| Edit a project | Return the URL with the known project intent: backend root is the default project if it contains `forge.json`; `--project /absolute/project` overrides it. Verify project identity and Engine target after opening that URL |
+| Explicitly allocate a project | `forgeax view project open --root <backend> --project /absolute/project --json`; open `projectTarget.url`, or let an already-open empty Shell adopt it. Command success alone does not prove the headed page is ready |
+| Play in Editor | Start Play for the open project; use its exact target for shared tools |
+| Observe an AI run | Bind its explicit `{root, runId}`; verify a timestamped image from that run |
+
+For a complete View startup request, start a missing backend first, then enable
+View. Stop after the requested outcome. The browser opens the known project from
+the returned URL; Play and independent AI runs still require separate intent.
+Browser automation setup belongs to an explicitly requested browser workflow,
+not to `backend start` or `view start`.
+
+`--root` selects the existing backend workspace. `view start` creates no
+project target. Do not ask users to retype a known project path. Verify repeated
+refresh carries the confirmed project and old target through the resident View
+entry, then opens a fresh Editor only after Engine validates that exact lost
+target. Verify no manual reconnect or resource/camera/layout history replay. Never
+resend commands to the lost target or restart Play automatically. Report
+conflicts with another active page and require an explicit project choice.
+During the transfer, verify the resident View entry shows restoration progress
+without target-bound panels or stale-target command errors. Measure the time to
+the fresh target separately from the time to reach the resident entry.
+When startup speed matters, start the Engine backend with
+`FORGEAX_WORKSPACE_TIMING=1` and use the Engine checkout's
+`node scripts/workspace-timing-report.mjs <backend-root>` after repeated opens or
+refreshes. The report groups exact targets and separates Vite config, server
+creation/listening, Catalog wait and browser readiness. Record the browser's
+time to reach the resident View entry separately; the Engine timer starts when
+the replacement target opens. Check the stage distribution before changing
+startup behavior.
+`view project open` takes the
+editor project directory as `--project` and opens it on the running View; it
+never launches a browser, starts Play, or switches away from a different open
+project. Its JSON result only proves the headed session was allocated: open
+`projectTarget.url`, or confirm the empty shell navigated there, before
+treating the project as open in the interface.
+
+When the user supplied a project path and asked to open it, use the project-intent
+URL or `view project open` with that path; do not stop at the
+connected Shell and do not type into the path dialog. `No project`, an empty path field, or a disabled **Open
+project** button means the project-open step is incomplete. The final project
+screenshot must contain the requested project target. Treat scene preview and
+Play as independent follow-up gates: a scene tree proves scene loading, while a
+running Play target plus real pixels proves game execution. During a slow Play
+start, retain the pending state until Engine reports readiness; do not infer
+failure from temporarily disabled controls.
+
+For WebGPU pixel evidence, use the repository's canonical Playwright launch
+configuration or the browser flags required by its real integration script. A
+browser that merely exposes `navigator.gpu` can still leave the canvas black on
+an unsuitable backend. Wait for the Engine document's submitted-frame marker,
+then inspect the screenshot itself; `play.ready`, a mounted iframe, and a black
+canvas are not pixel acceptance.
+
+Use [status and stop](../../README.md#check-status-and-stop) for cleanup. Stop
+only owned/requested resources; View stop preserves the backend and independent
+runs, and borrowed browser resources remain with their caller.
+
+## Preserve the failing boundary
+
+| Evidence | Next action |
+|:--|:--|
+| Command missing | Verify the selected Engine CLI version, backend `hostPack` status, built View exports, and packaged `host.pack.json` |
+| Pack module initialization timeout | Retain the source filename and diagnostic; inspect actual resolved imports before claiming whole-Engine compilation |
+| Terminal Pack/catalog failure | Return the producer error; repair and explicitly reopen the project instead of adding another readiness wait |
+| Shell ready, rendering failed | Report target failure separately; inspect Engine's original renderer error while keeping View available |
+| Missing automation browser | Report that prerequisite only for the browser task; a View URL does not require Playwright |
+
+Return the selected Engine entry, workspace root, service/URL state and the
+verification boundary. Keep URL readiness, DOM interaction, real pixels and CI
+results distinct. Update this guidance with README startup contract changes.