@forgeax/view 0.2.1-beta-20260924075842

package/README.md

@@ -0,0 +1,742 @@
+# ForgeaX View
+
+View is an optional project workspace and read-only observer of Engine AI runs.
+The CLI and frontend are clients of Engine APIs. The Engine service owns runs,
+project facts, assets, scenes, observation, capture, and termination; View owns
+window resources, tab bindings, and presentation.
+
+## Start here
+
+Agent guidance: [forgeax-view-start](skills/forgeax-view-start/SKILL.md).
+
+For a known game project using a local Engine checkout, one script prepares
+the builds and services and returns the project URL as JSON:
+
+```sh
+node skills/forgeax-view-start/scripts/start-view.mjs \
+  --project /absolute/path/to/game \
+  --engine /absolute/path/to/forgeax-engine
+```
+
+Open its `url` in a browser to load the Editor project. The script leaves the
+browser, Play, and independent AI runs to their separate operations. See the
+[skill](skills/forgeax-view-start/SKILL.md#open-a-project-with-one-script) for
+reuse, restart, and failure behavior.
+
+> [!IMPORTANT]
+> This workflow requires an Engine build with `backend start --host-pack`,
+> a built View package, and an Engine workspace root. A running backend must
+> be restarted to change its selected host Pack.
+
+Select View's installed host Pack when starting Engine. The game project does
+not need a View asset or a `forge.json.roots.host` change:
+
+```sh
+forgeax backend start --root /path/to/workspace \
+  --host-pack /path/to/forgeax-view/host.pack.json --json
+forgeax view start --root /path/to/workspace --project /path/to/game --json
+```
+
+The packaged `host.pack.json` identifies View's native plugin and its CLI
+declarations. The Engine backend loads that Pack from the View package; the
+game remains an ordinary project opened through the Engine workspace API.
+Use a separate workspace root when the game already declares its own host root.
+The selected host Pack is visible in `backend status`.
+
+Start the backend, then enable View:
+
+```sh
+forgeax backend status --root /path/to/workspace --json
+forgeax view start --root /path/to/workspace --json
+# Override the project when it differs from the backend workspace.
+forgeax view start --root /path/to/workspace --project /path/to/game --json
+# Optional explicit allocation on an already-running View.
+forgeax view project open --root /path/to/workspace --project /path/to/game --json
+```
+
+Open the `url` returned by `view start` in your browser. Explicit `--project`
+wins; otherwise a backend root containing `forge.json` is included automatically.
+The browser connects and opens that project without asking you to type its path.
+`view project open`
+allocates the project and returns its headed document as `projectTarget.url`;
+open that URL, or leave an already-open empty shell to navigate there.
+Only an unknown project requires the **Open project** dialog. Open a project before using
+any View page, including Runtime capture. `backend start` and `view start` do
+not open an Editor project or run a game. These
+commands do not launch Playwright or install Chromium. Repeat `view start` to
+retrieve the URL of the existing interface.
+
+| Step | What success means |
+|:--|:--|
+| `backend start` | Engine API and declared host plugins are available; no browser or renderer is required |
+| `view start` | View is serving its interface on the existing Engine Host |
+| Open the returned URL | The browser has loaded the Shell and connected its frontend plugins |
+| Open an Editor project | Engine has opened the chosen project; its rendering target has its own readiness and errors |
+| Play or start an AI run | An explicit Engine execution target has started |
+
+When the request includes a project path, opening the Shell is only an
+intermediate state. Return the URL with that project intent, or run
+`view project open` and open its headed URL; wait for
+the project name, its directories, and an Engine target to appear. A final
+screenshot that still shows `No project`, an empty path, or a disabled
+**Open project** button does not prove that the project opened. A JSON result
+that only contains `projectTarget.url` does not prove the headed page has
+loaded. Scene preview
+and Play are later, separate gates: open a scene asset to verify the hierarchy,
+and select **Play** to verify the game target and rendered pixels.
+
+### Use a local Engine checkout
+
+Build the local repository explicitly, then bind the game to those outputs:
+
+```sh
+pnpm --dir /path/to/forgeax-engine build:engine
+node /path/to/forgeax-engine/scripts/forgeax/prepare-shader-release-inputs.mjs --build --profile base-ssao
+test -s /path/to/forgeax-engine/packages/vite-plugin-shader/dist/engine-inputs/base-ssao/manifest.json
+test -s /path/to/forgeax-engine/packages/vite-plugin-shader/dist/engine-inputs/base-ssao/imports.json
+cd /path/to/game
+pnpm link /path/to/forgeax-engine/packages/engine
+pnpm exec forgeax project engine use-local /path/to/forgeax-engine --json
+pnpm exec forgeax project engine check --json
+pnpm exec forgeax backend start --host-pack /path/to/forgeax-view/host.pack.json --json
+pnpm exec forgeax view start --json
+```
+
+The explicit build and shader preparation happen before startup; the local
+browser proof uses those prepared outputs. Prepare the matching `point-ssao`
+profile instead when point shadows are enabled. Recheck the profile files after
+rebuilding the shader package: without them, every new Backend falls back to
+source compilation, which can take minutes. The package link selects the local
+CLI and Node-side Pack dependencies; the
+existing project binding selects local workspace exports for Engine's browser
+host. The binding is stored in `.forgeax/engine-binding.json`. It must report
+`mode: "local"`, the selected checkout, and a healthy build. No SDK archive or
+candidate packing is required for this path. Rebuild affected Engine packages
+after source changes; binding does not implicitly build Engine or rewrite its
+exports to TypeScript source. Resolve `node_modules/@forgeax/engine` and confirm
+that it belongs to the same checkout recorded by the binding. A healthy browser
+binding cannot prevent Node-side Pack imports from using a different checkout;
+that mismatch can add stale component defaults and make scene cooking fail.
+Open the returned View URL, then choose the game
+project explicitly. A running backend keeps its original Engine; apply a
+binding change with explicit `backend stop` / `backend start`. Independent runs
+retain their own input version and lifecycle.
+
+A Pack initialization timeout occurs while loading its module and dependencies,
+before asset generation. The loader transpiles reachable TypeScript helpers;
+built Engine package exports remain JavaScript imports. The timeout alone does
+not establish that the entire Engine was compiled. Preserve the original Pack
+filename and diagnostic when investigating a different local binding.
+Engine may load a PluginAsset through a compiled chunk. View resolves its static
+UI from the selected View package's `@forgeax/view/plugin` entry instead of
+using that chunk's URL. Game plugins execute in Engine's Worker; browser UI
+belongs to frontend plugins.
+
+### Observe an AI run
+
+```sh
+forgeax engine run start --root /path/to/game --json
+forgeax engine run status --root /path/to/game --json
+```
+
+In View, select **Runtime capture** (AI Display), enter the game project path and the exact
+`runId` from Engine, then select **Observe run**. First complete the required
+project dialog; the observed run can belong to a different project.
+View receives cached status, logs and timestamped screenshots from that run.
+A different run at the same path requires an explicit new binding; opening or
+closing an Editor project does not change the observed run. **Disconnect**
+removes the observation binding and does not stop the game.
+
+### Open an Editor project
+
+With View already started, allocate the project from the command line:
+
+```sh
+forgeax view project open --root /path/to/workspace --project /path/to/game --json
+```
+
+Then open the returned `projectTarget.url`. An empty shell that is already
+connected navigates there when the snapshot gains that target. The required
+dialog remains available: enter the **Project path** and select **Open project**. The
+browser opens the Engine-generated workspace document. Editor and asset
+previews use inline Engine surfaces; **Play** explicitly creates the isolated
+game iframe. Hierarchy and Inspector operate on the selected Engine target.
+Opening a project does not start an independent AI run.
+In Content Browser, select a folder or asset and choose **Open**, double-click
+it, or press **Enter**. A single click selects it for inspection. **Preparing
+Play** means Engine is freezing the game's inputs; **Stop** can cancel this
+preparation before a game target appears, or stop the target after it appears.
+If project scanning fails, View remains available. Inspect the Engine source
+diagnostic, repair that project, then select **Open project** again.
+
+### Check status and stop
+
+```sh
+forgeax view status --root /path/to/workspace --json
+forgeax backend status --root /path/to/workspace --json
+forgeax view stop --root /path/to/workspace --json
+forgeax backend stop --root /path/to/workspace --json
+```
+
+`view stop` disconnects the interface and releases View plugins; it preserves
+the Engine backend and does not close your browser window. Closing a page loses
+its actual Editor rendering targets, but not the backend or independent AI run.
+`backend stop` releases the Engine workspace and its Host. Stop an independent
+run separately with `forgeax engine run stop --root /path/to/game --json`.
+
+The API/CLI operations can be composed by a caller. No startup operation
+implicitly runs the following steps on its behalf.
+
+## Publishing
+
+`@forgeax/view` is the only npm package. Record user-facing work with
+`pnpm changeset`. Pushing that changeset to `main` lets Release open a Version
+Packages PR; merging it updates `CHANGELOG.md` and publishes `@latest`.
+
+Test versions do not move `latest`. Dispatch Release with `dry_run` left enabled
+to pack a `beta` snapshot without publishing. Uncheck it only for a real
+`channel=beta` or `channel=next` snapshot. Install a published snapshot with:
+
+```sh
+pnpm add @forgeax/view@beta
+```
+
+A longer beta line uses `pnpm changeset pre enter beta` on `main`, then the same
+Version Packages flow. Prerelease publishes stay on the `beta` dist-tag until
+`pnpm changeset pre exit`.
+
+## Development and verification
+
+CI tests the installed package distribution by preparing its complete candidate
+closure from a built Engine checkout:
+
+```sh
+export pnpm_config_verify_deps_before_run=false
+node scripts/engine-candidate.mjs pack /path/to/built/forgeax-engine /tmp/view-engine-candidates
+node scripts/engine-candidate.mjs install /path/to/built/forgeax-engine /tmp/view-engine-candidates
+pnpm build
+node scripts/verify-startup-boundaries.mjs
+xvfb-run -a node scripts/verify-engine-plugin-boundary.mjs
+```
+
+CI runs once per PR revision and on pushes to `main`; a newer revision cancels
+the obsolete run. It caches only the complete Engine candidate archives, keyed
+by the exact Engine commit, preparation script, OS/architecture, Node major and
+pnpm version. The cache path is workspace-relative so different runner home
+directories share the same cache version. A cache hit must pass archive digest and dependency-closure checks
+before source preparation is skipped. Missing or invalid candidates rebuild
+from source. View builds, Storybook, package checks and every browser scenario
+always run. Candidate indexes use relative archive names so another runner can
+verify and install the same bytes with the `verify` and `install` commands.
+One build job prepares and checks the candidates, then publishes them as a
+short-lived workflow artifact. Two qualified runners execute the complete
+workspace/10-Play-cycle probe and the startup/game-3d probes concurrently, with
+separate browsers and GPU processes. The existing required `bootstrap` check
+passes only when the build and both browser jobs succeed; failures, skips and
+cancellation cannot turn it green. Cold builds still prepare Engine only once.
+
+Candidate preparation includes Engine's packaged shader inputs before any live
+startup deadline begins. A package build alone does not prepare those inputs;
+source shader compilation may take several minutes. The probe keeps the original
+ScriptablePack and Engine's default startup deadlines.
+The environment setting matches CI and prevents pnpm from replacing the temporary
+candidates with the committed SDK dependencies before running a script.
+Linux CI uses Engine's capacity-checked `heavy` runner pool and headed Chrome
+Beta with SwiftShader. Use at least four CPU cores for the complete combined
+suite; two-core runs provide additional stress diagnostics. The paired Engine
+fences IBL prefilter faces and retires closed-server caches. The gate retains
+every target, Play cycle and browser-error assertion, checks that the original
+asset renderers still submit frames after Play, and keeps the GPU watchdog enabled. Install it with `pnpm exec playwright install --with-deps chrome-beta` and
+set `FORGEAX_BROWSER_EXECUTABLE=/opt/google/chrome-beta/chrome` for Engine/probes
+to reproduce that browser locally. Browser setup is a verification prerequisite,
+not a View startup step. CI records the browser version and process diagnostics; GPU
+device loss remains a failure.
+
+The combined probe checks shared Host identity, three independent Engine Worlds,
+live asset discovery, hierarchy and Inspector, picking/camera input, ten Editor
+Play cycles, Eject/Possess, plugin removal, poisoned-game recovery, and independent
+AI execution before and after View browser loss. A separate real `game-3d` probe
+checks live hierarchy and player input handoff:
+
+```sh
+xvfb-run -a node scripts/verify-game3d-workspace.mjs
+
+# Direct local checkout binding, without packing an SDK candidate:
+FORGEAX_ENGINE_CHECKOUT=/path/to/forgeax-engine FORGEAX_LOCAL_ENGINE=1 \
+  xvfb-run -a node scripts/verify-game3d-workspace.mjs
+```
+
+Both preserve the original browser-error assertions. Captured pixels, actual
+capture resize and target/World identities are checked independently. Asset tabs
+host their dedicated Engine preview surfaces in panel-owned DOM containers;
+they never relocate the Editor owner canvas or restore its old preview cards. Screenshots
+include `/tmp/view-inline-previews.png`, `/tmp/view-editor-play.png`, and
+`/tmp/view-game3d-play.png`. The combined Linux/Xvfb probe also requires Python
+and libX11 for its native window check; it does not use CDP.
+
+The Content Browser presents the Engine catalog; selection inspects read-only
+asset metadata and double-click opens the exact Engine preview. Assets from
+`.pack.ts` show their Catalog `sourceKey` when present; GUIDs remain their
+operation identity. Hierarchy and Inspector use the optional live target tools
+plugin, reporting capability errors when absent. Sample catalogs and entities
+remain restricted to `dev:ui`.
+Material editing and runtime property writes are not implemented.
+
+## Lifecycle and operation ownership
+
+The resident Node process contains a BackendHost. It loads the Engine domain
+plugin first, then the optional View PluginAsset and its native backend children.
+The browser FrontendHost activates View's projected frontend root and its
+Shell/panel children. UI-only plugins have no
+backend/API/CLI stubs. The viewport presents the Engine preview; the content
+browser only mounts its resource UI. AI Display presents cached status, logs and
+recent images from an independent Engine run; it contains no execution iframe.
+
+| Action | Result |
+|:--|:--|
+| Disable a View panel or dispose its native Fiber | Engine domain tools remain callable; independent AI execution is unchanged |
+| Close the View browser | Its Editor target is lost; the independent AI run continues |
+| Finish a CLI call | The resident backend and Engine live owner remain running |
+| Stop View explicitly | Dispose View plugins and connections; Engine backend, AI runs and caller-owned browsers survive |
+
+`view.*` domain operations are thin aliases of Engine ToolApi handlers. UI
+selection never resolves a business target. Pass `targetId` and
+`targetGeneration` (from `preview.target.generation`) for preview/camera calls.
+Engine alone owns camera versions, conflicts, idempotency and disconnect rollback.
+View observation uses only `engine.run.observe`. Frontend callers cannot control
+independent runs; the Engine plugin enforces that permission boundary. Use Engine CLI directly to control independent runs:
+
+```sh
+forgeax engine run start --root /path/to/game --json
+forgeax engine run status --root /path/to/game --json
+forgeax engine run capture --root /path/to/game --revision RUN_REVISION --require-ui --json
+forgeax engine run stop --root /path/to/game --json
+```
+
+Engine snapshots source, assets, configuration and resolved dependencies before
+starting its private browser, headless by default. Editor edits do not update
+that run. Stop/start selects a new input version; reload keeps the current
+snapshot. View tabs, focus, dimensions and lifecycle cannot alter execution.
+Observation displays capture time and stale images explicitly; output is bounded
+and shared per run, with no screenshot loop per viewer.
+After closing a browser, reopen the returned View URL. Its project intent opens
+the same project directly. Refreshing an Editor briefly visits the resident
+View entry, which uses the resident API to replace its exact lost target without
+requiring **Reconnect**.
+During replacement, View shows project restoration status and keeps panels that
+need the old target unmounted. The new target opens automatically when Engine
+reports it ready; a failed replacement remains visible with an explicit retry.
+The new page starts as a freshly opened project: no historical resource tabs,
+selection, camera, dock layout or Play. Saved project files and theme/language
+preferences remain; save authored changes before refreshing. The departing page
+does not initialize another renderer while the View entry opens its replacement.
+`view start` never migrates or replays a target. Conflicts with another active
+page and genuine service failures remain visible with explicit retry; recovery
+never takes over another live target or changes an independent AI run.
+
+### Scene navigation
+
+| Input | Action |
+|:--|:--|
+| Left click | Select the object in the submitted display frame |
+| Right drag; right + WASD/QE | Look; move along camera axes / world up and down |
+| Right + wheel | Adjust flight speed |
+| Wheel; middle drag | Dolly (orthographic zoom); pan |
+| Alt + left / middle / right drag | Orbit / pan / dolly |
+| F | Focus the selected object's bounds |
+| Escape, focus loss, hidden page | Release input and keep the current camera pose |
+
+Pointer lock is optional; pointer capture remains available when the browser
+denies it. Text fields and panel controls do not start viewport navigation.
+View owns these bindings, sensitivity, flight-speed preferences and pitch limits.
+It sends semantic velocity, angle and displacement requests; Engine executes
+them on the actual target and owns camera transactions and the orbit pivot.
+Cancelling a transaction restores the complete camera, including lens and pivot.
+
+## Explicit borrowed-carrier library contract
+
+This optional library seam is separate from the default independent AI path.
+
+| Request | Result |
+|:--|:--|
+| `headless=true` | Existing headless path; do not contact View |
+| Headed, with an injected open, compatible, idle View | Use the same View page for display and capture |
+| Headed, with View unavailable | Existing headed browser path, with the actual carrier and reason reported |
+
+View uses an ordinary browser and page. It has no Electron dependency or
+desktop launcher. Selection happens when a run starts. Engine must not start
+another browser/window for the borrowed path or load a second copy of the game.
+Releasing a run must not close the user's browser.
+
+Engine's public `BrowserCarrierAdapter` supplies the execution seam: select a
+target, attach its exact owner `Page` plus execution realm, then release the
+run's lease. A View lease uses one child `Frame`; the owner Page remains stable
+and is used only for the exact outer-surface presentation envelope.
+`startView({ platform: createBrowserPagePlatform({ page }) })` is the in-process
+owner path. `page` is the already-open browser Page; Engine receives it through
+`view.carrier`, and releasing a lease only removes View's occupancy. The
+connection does not select CDP, a debugger port, or another transport. When an
+embedding application already owns the compatible Engine hosts, pass them as
+`backendHost` and `frontendHost`; View then borrows those lifecycles and does
+not dispose them.
+
+## Current integration
+
+The modules in `src/` provide admission, identity, cancellation, a native
+Engine Host plugin, a browser-safe frontend mount, and the browser-neutral
+owner-Page/execution-Frame carrier seam.
+`startView()` starts an observer Host without a display carrier. Supplying
+`platform` explicitly selects the borrowed-carrier library seam. No default
+platform opens a window. In that explicit seam, the Engine carrier owns
+execution and View owns the lease and presentation boundary. The
+authenticated endpoint carries lease metadata only; it never serializes a Page,
+Frame, debugger endpoint, or cleanup callback. A process-local Engine
+attachment must provide the explicit owner Page, execution realm, and close
+handle contract.
+
+The backend and frontend are real Engine/Cordis Plugins. The project's host
+PluginAsset mounts the View native plugin; View mounts its backend children
+in the same BackendHost. `HostAssembly` v2 carries one View frontend root,
+and the browser FrontendHost activates that root and its native children.
+Neither path launches a browser or owns
+Engine project state. Only explicit borrowed-carrier consumers pass `view.carrier` to Engine's
+`BrowserCarrierAdapter` seam.
+
+For explicit borrowed-carrier consumers, the two target surfaces remain distinct: a workspace target URL
+may be loaded by the one workspace iframe, while a CLI display target is
+presented by the exact iframe allocated by `BrowserPagePlatform`. The browser
+frontend uses `createBrowserPagePresentation()` to find that iframe by its
+lease/generation/surface identity and never reparents or removes it. If the
+exact surface is absent or mismatched, presentation fails closed rather than
+creating a second App/World/renderer.
+
+### Source organization
+
+| Location | Responsibility |
+|:--|:--|
+| `src/` | Public package entry points, CLI clients, platform adapters and host construction |
+| `src/plugins/` | Native backend/product composition; no page UI |
+| `packages/viewer/src/host/` | Frontend connection, root resolution, page/slot infrastructure and panel bridge |
+| `packages/viewer/src/plugins/` and `packages/viewer/src/shell/` | Shell plugin declaration and its React presentation |
+| `packages/viewer/src/*catalog*.mjs` | Static package composition; shared catalog metadata does not import frontend implementations |
+| `packages/view-plugin-*/src/` | Feature-owned identities and native plugins; only implemented backend/API/CLI endpoints |
+| `packages/view-plugin-*/src/ui/` | That feature's panels, DOM presentation and styles |
+| `packages/view-workspace-core/` | React-free workspace contracts, clients, bindings and shared presentation helpers |
+| `packages/view-components/` | Workspace-independent React primitives, tokens and Storybook |
+
+Scene registration lives in `view-plugin-scene`; its viewport and connection-owned
+Play presentation live in `view-plugin-viewport`. Runtime capture's frontend
+lifecycle, status snapshot and DOM view live in `view-plugin-display` as
+`frontend.mjs`, `status.mjs` and `ui/`. Moving source files does not change their
+native plugin names or disposal owners. Existing public entry points,
+including `@forgeax/view/pages/scene` and `@forgeax/view/workspace/presentation`,
+continue to resolve to the same plugins.
+
+Feature packages depend on exported workspace-core/components contracts, not
+Viewer internals or sibling feature implementations. The Viewer composes them.
+Keep metadata in `identity.mjs` so backend catalog imports cannot pull in a
+frontend implementation.
+
+### Architecture gate
+
+Run `pnpm check:architecture` before submitting a change. CI runs this independent
+lane before the Engine build; the final `bootstrap` check requires architecture,
+build and both browser probes to succeed. A failed, skipped or cancelled lane
+cannot produce a successful aggregate. No Engine checkout or browser is needed
+for the static gate itself.
+
+| Constraint | Automated evidence |
+|:--|:--|
+| Features use foundations, never sibling features or Viewer; foundations do not depend upwards | Source imports and all dependency sections in each package manifest |
+| Cross-package access uses declared public exports | AST import/re-export/type-import/CommonJS checks; relative-path, alias, symlink and private-subpath rejection |
+| Core uses Engine Host/tool contracts, not domain implementations; components are workspace/Engine-independent | Dependency checks, no React runtime or JSX/TSX/CSS source in core |
+| Host infrastructure does not absorb Shell, panels or Engine domain implementations | Transitive source graph, including self-package and conditional exports |
+| Shared Catalog metadata does not pull in implementations | Transitive identity/contract graph and an actual metadata bundle inspection |
+| Root clients/platform do not implement features | Source graph with explicit public export, catalog and Host composition seams |
+| Plugins remain optional and own cleanup | Existing operation-ownership, page-plugin and real-browser removal/restoration tests in the build/browser lanes |
+
+`scripts/check-architecture.mjs` reports the file, rule and offending dependency
+chain. It checks root `src/` and every package's `src/`, including unreferenced
+files. Counterexample tests deliberately introduce violations; CI also exercises
+all 125 success/failure/skipped/cancelled/missing aggregate-result combinations.
+The existing panel bundle loader has one scoped computed-import exception;
+another computed import requires a reviewed resolver policy, not an ignore comment.
+
+> [!IMPORTANT]
+> Static checks prove the declared source boundaries, not arbitrary business
+> semantics or complete lifecycle correctness. They do not analyze generated
+> code, arbitrary JavaScript loaders/eval, third-party internals or every possible
+> bundler alias. Changes to resolvers, exports, guardrails or their exceptions
+> require the same architectural review as a boundary change. There is no blanket
+> violation baseline or per-file suppression mechanism.
+
+For Host/core/bootstrap changes, the PR must identify the missing public seam,
+why the existing plugin cannot own the change, the minimal domain-neutral
+contract, its consuming plugin, and plugin-absent/removal evidence. Reviewers
+must also inspect contribution ownership and disposal, new business branches,
+and duplicated state. Functional success alone is not acceptance. Update the
+owning Harness design and `AGENTS.md` when the runtime boundary changes; a new
+rule or exemption needs a rejecting counterexample test.
+
+Repository administrators must require `bootstrap` on `main` and configure
+review/bypass policy separately. A workflow cannot enforce branch protection
+against itself being changed or a direct push that bypasses checks.
+
+### Page plugins and names
+
+Every page is an independent native frontend plugin and Cordis Fiber under
+View's frontend root. Closing a tab only changes presentation.
+Use `createViewProductPlan({ disabledPages: ['editor'] })` to omit a page
+and its panels from that root. Page IDs are `editor`,
+`display`, `plugins`, `material`, `mesh`, `texture` and `asset`. Scene panels depend on `viewScenePage`;
+the plan omits the complete contribution when its page is disabled.
+Backend workspace and inspection services remain available.
+The same option is accepted by `startView({ disabledPages: ['editor'] })`.
+The resident `@forgeax/view/plugin` also accepts `config.disabledPages`.
+
+| Page | Frontend Plugin name | Owned UI |
+|:--|:--|:--|
+| Scene (Editor tab) | `forgeax.view.page.scene.frontend` | Scene page registration and panel dependency |
+| AI Display (Runtime capture) | `forgeax.view.page.ai-display.frontend` | Exact Engine display surface |
+| Plugin Browser | `forgeax.view.page.plugin-browser.frontend` | Actual Host Fibers and activation states |
+| Material | `forgeax.view.page.material.frontend` | Material preview and properties |
+| Mesh | `forgeax.view.page.mesh.frontend` | Mesh preview and properties |
+| Texture | `forgeax.view.page.texture.frontend` | Texture preview and properties |
+| Asset | `forgeax.view.page.asset.frontend` | Fallback resource properties |
+
+Use `forgeax.view.<role>.<feature>.<side>` for native runtime names:
+`page` for pages, `panel` for scene panels, `service` for API clients,
+providers and target presentation, and `shell` for UI hosting. For example,
+`panel.object-inspector.frontend` and `service.plugin-inspection.backend`
+describe different responsibilities. Names are declared beside each plugin
+(product packages use `identity.mjs`). The Scene, Shell and Play presentation
+plugins need no empty backend counterpart. All plugins use the same native Host
+lifecycle.
+
+The asset browser owns only its panel. The independent Play presentation
+service owns connection-scoped browser resources; disabling Scene removes its
+viewport placement without terminating Play. The viewport panel presents
+Engine's exact workspace target. Plugin
+Browser reads live Host facts; missing activation evidence stays `unknown`.
+
+Plugin Browser groups Fibers by their reported Host source, with backend
+Fibers first. Host selection, text search and tags intersect; multiple tags
+must all match. Counts describe the observed snapshot, not every possible Host.
+
+| Filter | Evidence |
+|:--|:--|
+| Backend / Frontend | The reporting Host source kind |
+| Game | A reported game/engine source, or an Engine Fiber declaring `world` / `gameHost` dependencies; the View frontend's Engine realm alone is not enough |
+| API | Tool API operations attributed to the exact provider / Fiber |
+| CLI | A command contract or command paths declared by those Tool API operations; not a running CLI process |
+
+The shared workspace client uses `sources()` and `inspectPlugins()`; the
+standalone inspector client's `inspect()` is also supported. Inspection and
+watch `generation` arguments identify the source, not the transport service.
+Remote source failures produce a partial-inventory notice while available
+sources remain visible. Other frontend connections are not hidden when the
+current frontend supplies its local snapshot.
+
+> [!NOTE]
+> Inspection covers only reported sources. A zero Game count does not establish
+> that no game is running; independent game/worker Hosts without an inspection
+> report are not fabricated or inferred from names.
+
+After `pnpm build` with the matching Engine candidates, run
+`xvfb-run -a node scripts/verify-engine-plugin-boundary.mjs`. Its page-plugin
+probe exercises tab close/reopen, all seven page disable/restore paths,
+service isolation, real backend inventory, Host/tag/search combinations, reset,
+and narrow-screen layout inside the real Engine workspace. Screenshots are saved
+under `artifacts/page-plugins/`.
+For the focused page lifecycle probe without Play stress cycles, run
+`xvfb-run -a node scripts/verify-page-plugin-lifecycle.mjs`.
+
+### Workspace CLI
+
+Agent guidance: [forgeax-view-cli](skills/forgeax-view-cli/SKILL.md). The
+resident workspace API is authoritative; the browser and CLI are its clients.
+
+With a running View owner, Engine CLI can call a workspace operation through
+the native ToolApi provider:
+
+```sh
+forgeax view workspace call --root /path/to/backend \
+  --operation tabs.get --args '{}' --json
+```
+
+This command is declared by the selected View host Pack, so it appears while
+that Pack's backend is running. View must be
+started. The returned operation result comes from the resident View workspace
+owner. The frontend's workspace transport now routes through the same ToolApi
+provider. Browser presentation remains a separate completion check.
+
+An independent process can call the same resident `view.*` API through the
+authenticated Engine Host WebSocket. The CLI is deliberately a transport
+client; it does not implement project, asset, scene, camera, or capture logic.
+
+```sh
+forgeax-view workspace --operation project.open \
+  --endpoint "$FORGEAX_VIEW_WORKSPACE_ENDPOINT" \
+  --token "$FORGEAX_VIEW_WORKSPACE_TOKEN" \
+  --args '{"root":"/path/to/project","tabId":"forgeax-user-workspace"}'
+```
+
+The endpoint and token are explicit capabilities issued by the View owner (or
+can be supplied with `FORGEAX_VIEW_WORKSPACE_ENDPOINT` and
+`FORGEAX_VIEW_WORKSPACE_TOKEN`). The client uses the same operation names and
+JSON argument shape as the browser frontend. This independent CLI path is for
+the workspace API. Independent AI controls use `forgeax engine run`, whose
+private browser does not depend on this connection.
+
+Use `--batch '[{"operation":"camera.begin",...},{"operation":"camera.update",...},{"operation":"camera.commit",...}]'`
+when a camera gesture must keep one authenticated client connection. A
+single-operation invocation closes its connection after the Engine API reply.
+
+Viewport clicks use View's `scene.pick` selection workflow with physical output
+pixels (`x`, `y`) and the exact `targetId` / `targetGeneration`. It calls Engine's
+existing `target.pick` query; direct `target.pick` calls do not change View
+selection. `scene.select`, `scene.pick` and `scene.clear` share cancellation and
+target guards, so a late result cannot replace a newer selection. Clearing also
+requires the exact target identity. Query or highlight failures preserve the
+last confirmed selection and use the ordinary workspace error channel.
+
+## Custom workspace embedding
+
+The CLI startup path above already uses Engine's resident workspace provider.
+For a custom embedding application, the library accepts an Engine-owned
+workspace capability through the same Host transport:
+
+```js
+const view = await startView({ platform, workspaceEngine });
+const api = await connectViewWorkspace({
+  endpoint: view.workspaceEndpoint,
+  clientId: 'forgeax-cli',
+  token: view.workspaceAccessToken,
+});
+
+const tabId = 'forgeax-user-workspace';
+const state = await api.openProject(projectRoot, { tabId });
+const projectId = state.project.id;
+const { assets } = await api.listAssets(projectId, { tabId });
+const scene = assets.find((asset) => asset.kind === 'scene');
+if (scene) {
+  await api.inspectAsset(scene.guid, { projectId, tabId });
+  await api.openAsset(scene.guid, { projectId, tabId });
+}
+```
+
+Authored-asset operations are projections of Engine CLI / ScriptablePack / ToolClient APIs. View does not parse `*.pack.ts`, write DDC, cook, or invent `applyParams`:
+
+| View operation | Engine API | View owns |
+|:--|:--|:--|
+| `assets.list` | DevKit `assetList({ root })` / existing `listAssets` → `PackEntry[]` | session catalog snapshot, including optional `sourceKey` |
+| `asset.inspect` | DevKit `assetInspect({ root, subject })` plus ScriptablePack `inspect(sourcePath)` / gateway `inspect-meta` | session inspection of PackEntry + `ScriptablePackMetaJson` |
+| `asset-source.rebuild` | ScriptablePack `rebuild(sourcePath, 'rebuild')` / gateway `rebuild` / ToolClient `asset-source.rebuild` | forwarding + CAS `expectedRevision` |
+| `asset-source.cold-cook` | ScriptablePack `rebuild(sourcePath, 'cold-cook')` / gateway `cold-cook` / ToolClient `asset-source.cold-cook` | forwarding + CAS `expectedRevision` |
+
+Codex edits `pack.ts` through the workspace files. The browser shell places the `sourcePath`-grouped Engine catalog and exact viewport on the left, and a **read-only** Engine meta inspector on the right (`packageId`, `importer`, `subAssets`, `cookReceiptUrl`). `Rebuild` / `Cold-cook` only forward Engine cook. Selecting an already-previewed GUID inspects again and does not open a second preview surface. Missing Engine methods fail closed with `view-engine-capability-unavailable`. Engine revision conflicts surface as `pack-source-revision-conflict`.
+
+In the already-open browser Page, load the browser entry and mount the View
+frontend once. The returned `api` is the same API used by the independent CLI;
+the returned `shell` owns only DOM presentation and input sampling.
+
+```js
+import { mountViewWorkspace } from '@forgeax/view/browser';
+
+const mounted = await mountViewWorkspace({
+  endpoint: view.workspaceEndpoint,
+  token: view.workspaceAccessToken,
+});
+await mounted.api.openProject(projectRoot, { tabId: 'forgeax-user-workspace' });
+```
+
+`mountViewWorkspace()` must execute in the browser document that owns the View
+window. It does not navigate the page, start a browser, or create a second
+workspace runtime. For a custom host, `connectViewFrontend()` exposes the
+underlying Engine `FrontendHost` while retaining the same plugin and transport.
+
+`workspaceEngine` is the host-supplied Engine capability. View binds Engine's public commands and ports; it does not wrap a second cook implementation. A host should pass the same objects Engine already exposes:
+
+```js
+const workspaceEngine = {
+  openProject,
+  closeProject,
+  listAssets: (input) => assetListCommand({ root: input.project.root }),
+  assetInspect: (input) => assetInspectCommand({ root: input.root, subject: input.subject }),
+  openPreview,
+  pack: scriptablePackAuthoringPort, // inspect / preflight / rebuild
+  tools: toolClient,                 // ToolClient.run('asset-source.rebuild' | 'asset-source.cold-cook')
+};
+const view = await startView({ platform, workspaceEngine });
+```
+
+Asset listing, SceneAsset preview, Engine-owned camera motion, capture, and close all remain on the headed Engine page. An independent CLI may use the authenticated `workspaceEndpoint` with the out-of-band access token; `connectViewWorkspace()` only creates a client and never starts another Engine target.
+
+For another Engine host, `createEngineWorkspaceProvider()` remains the explicit
+adapter boundary: its `openProjectSession` must return an Engine-owned,
+long-lived project session and headed target. View does not invent a project
+loader, copy App/World internals, or provide a mock target. The optional
+`presentation.createSurface` plus `attach`/`detach` callbacks bind the exact
+target surface (the Engine host may return its existing app-shell; View never
+creates a renderer copy). `applyInput` passes semantic motion to the host-owned
+camera executor. Selecting the CLI display tab changes presentation and input focus only;
+it never changes the CLI target or execution. The browser entry installs
+`createBrowserPagePresentation()` by default; a custom adapter is only needed
+when the embedding Engine host supplies a different exact surface.
+
+The workspace reports `view-engine-capability-unavailable` until the matching
+Engine plugin is installed. It does not fall back to a mock scene, a second
+game runtime, or an Electron page.
+
+For an Engine project capture that owns the browser document Host, keep the
+View frontend out of the bootstrap page and pass the backend binding to the
+Engine capture surface:
+
+```js
+const view = await startView({ platform, frontend: false });
+const session = await createBrowserCapture(projectRoot).open({
+  headless: false,
+  host: view.hostBinding,
+  carrier: view.carrier,
+  carrierRun: { serviceId: 'forgeax-cli', runId },
+  carrierGeneration: 1,
+});
+```
+
+The Engine host contribution then activates View's frontend root in the actual
+runtime document. Detached live-dev and external
+`serverUrl` paths remain out of scope until their server owner can carry the
+same binding.
+
+## Bootstrap
+
+Use Node.js 22+, pnpm, Git, Python 3, and authenticated access to the private
+repositories. Clone `ForgeaXGame/forgeax-harness` alongside this repository,
+or set `FORGEAX_HARNESS_ROOT` to that tooling checkout.
+
+```sh
+pnpm harness:init
+pnpm test
+```
+
+| Command / setting | Behavior |
+|:--|:--|
+| `pnpm harness:sync` | Clone or fast-forward the independent `.forgeax-harness` repository |
+| `pnpm harness:init` | Install local skills and initialize/verify Harness data |
+| `pnpm install` | Attempt optional Harness synchronization through `postinstall` |
+| `FORGEAX_SKIP_HARNESS_SYNC=1` | Skip optional synchronization |
+| `FORGEAX_HARNESS_STRICT=1` | Make standalone synchronization failures fatal |
+| `FORGEAX_HARNESS_ROOT=/path/to/forgeax-harness` | Select shared tooling |
+
+Synchronization preserves dirty, divergent, and differently configured clones.
+Harness data and machine-local installation state are not runtime dependencies.
+
+## Design
+
+- [Architecture north star](.forgeax-harness/knowledge-base/wiki/architecture-north-star.md)
+- [CLI-authoritative View design](.forgeax-harness/docs/specs/2026-09-12-cli-authoritative-plugin-view-design.md)
+- [Engine Host/Plugin architecture design](.forgeax-harness/docs/specs/2026-09-12-view-engine-host-plugin-architecture-design.md)
+- [Contributor instructions](AGENTS.md)
+
+The first two documents belong to the independent
+[forgeax-view-harness](https://github.com/ForgeaXGame/forgeax-view-harness) repository.