@forgeax/engine-devkit 0.1.2

package/LICENSE

@@ -0,0 +1,15 @@
+Apache License 2.0
+
+Copyright 2026 ForgeaXGame
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,192 @@
+# @forgeax/engine-devkit
+
+DevKit is the Node-only external-project seam for ForgeaX. It derives project
+commands, authoring-preview contributions, and one AI-facing RHI-debug path from
+the existing project authorities. It owns orchestration and file access; Engine
+owns rendering, RHI events, replay backends, and preview execution.
+
+> [!IMPORTANT]
+> Keep one artifact reference across the RHI-debug flow. `rhi.summary` and
+> `rhi.inspect` never rediscover a tape, infer a file pair, or parse error text.
+
+## Navigation
+
+- [CLI and catalog](#cli-and-catalog)
+- [RHI-debug operations](#rhi-debug-operations)
+- [Authoring preview](#authoring-preview)
+- [Project authority](#project-authority)
+- [Migration and carrier](#migration-and-carrier)
+
+## CLI and catalog
+
+The normal project commands remain available through the `forgeax` CLI:
+
+```text
+forgeax new [directory] [--template empty|game-default]
+forgeax init
+forgeax doctor
+forgeax skill install
+forgeax skill verify
+forgeax test
+forgeax dev
+forgeax build
+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}
+```
+
+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
+`forgeax-dist.json` closure.
+
+```bash
+forgeax build ./games/my-game \
+  --base /games/my-game/ \
+  --out-dir ./website-staging/games/my-game \
+  --json
+```
+
+`--out-dir` resolves relative to the game project root unless it is absolute.
+The selected directory is a derived build root and is emptied before writing.
+`forgeax preview` continues to verify and serve the default `dist/` directory.
+
+`forgeax new` accepts an absent or empty target only when that target is outside the unpacked SDK
+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 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.
+
+`discoverRhiDebugOperations()` returns the same descriptors used by help and
+schema output. The operation manifest is the single discovery and recovery
+surface for RHI-debug.
+
+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.
+
+## RHI-debug operations
+
+```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"
+  H-->>AI: "one ArtifactRef"
+  AI->>D: "rhi.summary + ArtifactRef"
+  D-->>AI: "FrameModel and workIndex"
+  AI->>R: "rhi.inspect + ArtifactRef + workIndex"
+  R-->>AI: "WorkInspection or structured failure"
+```
+
+| Operation | Input | Output | Owner |
+|:--|:--|:--|:--|
+| `rhi.capture` | Optional abort signal | One `ArtifactRef` plus capture bytes | Host and recorder attachment |
+| `rhi.summary` | One `ArtifactRef` | Strict v7 tape decode and `FrameModel` | Protocol decoder and frame model |
+| `rhi.inspect` | One `ArtifactRef`, one `workIndex`, optional fields | Fresh-backend `WorkInspection` | Replay session and readback matrix |
+
+### ArtifactRef
+
+`ArtifactRef` is the handoff SSOT:
+
+| Field | Type | Meaning |
+|:--|:--|:--|
+| `kind` | `'rhi-tape'` | The only RHI-debug artifact kind. |
+| `digest` | `string` | Digest of the canonical v7 tape payload. |
+| `source` | `string` | Host or operation that produced the artifact. |
+| `path` | `string` | Optional Node-side path owned by the host. |
+| `bytes` | `Uint8Array` | Capture payload supplied at the host boundary. |
+
+Consumers switch on `RhiDebugError.code`, then narrow `.detail`. `.expected`
+and `.hint` provide the next action without message parsing. Unknown operation
+names, fields, artifact kinds, and tape versions fail at the boundary.
+
+## Authoring preview
+
+Preview defaults to four explicit Engine-owned domain descriptors:
+`material.preview`, `mesh.preview`, `vfx.preview`, and `texture.preview`.
+Each follows the same `list -> describe -> run -> terminal` path and binds its
+report and evidence to the requested subject and snapshot.
+
+```mermaid
+flowchart LR
+  catalog["Digest-bound catalog"] --> descriptor["Domain descriptor"]
+  descriptor --> owner["Engine realm owner"]
+  owner --> terminal["One terminal result"]
+  terminal --> evidence["PNG, RHI tape, and profile refs"]
+```
+
+The generic `asset.preview` and `preview.run` shapes are not discoverable. A
+private legacy proof helper may remain for migration tests, but it cannot appear
+in the default catalog or act as a second domain owner. Browser and Dawn
+consumers must verify subject pixels and structured evidence; DOM liveness and
+RhiNull readiness are not visual proof.
+
+## Project authority
+
+Game projects keep authority in `forge.json`, package manifests,
+`package.json#forgeax.assets`, source Meta/Pack files, and imported game code.
+DevKit derives Vite and producer assembly from those facts.
+
+`forge.json#entry` is the required game bootstrap authority. When that module
+is not also named by `forge.json.plugins[]`, DevKit adapts its named
+`bootstrap(world, gameHost)` export into the native plugin lifecycle after the
+declared project plugins are ready. Plugin install/uninstall updates
+`forge.json.plugins[]`; a dependency failure restores the original manifest.
+The next dev/build generation deterministically adds or removes the literal
+Catalog import and production bundle reachability.
+
+SDK-created games keep all Engine usage skills as ordinary, committable files
+under root `skills/`. `skill install` idempotently projects those files into the
+supported Agent discovery roots with relative symlinks and narrow managed
+`.gitignore` blocks. `skill verify` checks the source inventory, local manifest,
+links, and ignore rules; foreign content at a managed destination fails closed.
+SDK-backed installs disable pnpm's side-effects cache so the manifest-bound
+offline store remains unchanged.
+
+Game modules default-export native Cordis plugins. Plugin install/uninstall
+updates `forge.json.plugins[]`; a dependency failure restores the original
+manifest. The next dev/build generation deterministically adds or removes the
+literal Catalog import and production bundle reachability.
+
+## Migration and carrier
+
+Only operations with committed, owner-attributed ArtifactRef proofs are admitted
+to the migration roster. Operations without a verifiable digest remain absent:
+
+| Operation | Owner | Evidence | Fallback |
+|:--|:--|:--|:--|
+| `preview.run` | Preview host | RHI, ProfileCapture, and PNG refs | Private executor |
+| `preview.offline-analysis` | RHI-debug consumer | RHI and ProfileCapture refs | Private executor |
+
+`resolveMigration` rechecks target realm, catalog digest, RHI backend, and
+evidence before selecting a service. Service admission is optional; absent or
+invalid admission selects the private executor.
+
+`createCarrierProviderService` owns an authenticated, ephemeral provider
+process. It exposes only POD carrier routes and keeps no provider registry after
+`close()`. Consumers validate descriptor and recipe digests before execution.
+A provider exit after `started` returns a structured terminal failure and never
+migrates the run to a private executor.
+
+<details>
+<summary>Ownership boundary</summary>
+
+DevKit does not own World, Renderer, Canvas, Context, Fiber, RHI events, a
+second operation registry, or a replay backend. The host supplies capture and
+backend factories; Engine supplies the actual rendering and replay behavior.
+
+</details>