@playcraft/cli 0.1.57-beta → 0.1.59-beta

package/project-template/.claude/skills/playcraft-runtime-parameters/references/preview-integration.md

@@ -0,0 +1,57 @@
+# Development preview integration
+
+The development SDK (Software Development Kit, 软件开发工具包) is separate from production advertising integration. Obtain it in the current engineering directory with:
+
+```sh
+playcraft preview-runtime init --dir .
+```
+
+It copies versioned modules, types and helpers to `.playcraft/preview-runtime` and refuses to overwrite modified managed files. Read its `README.md`, which documents the actual supported interfaces. Use a separate preview entry; keep the original production entry and advertising language/configuration behavior.
+
+## Actual game lifecycle
+
+Import `connectPreviewRuntime` and `readWorkspacePreviewContext` from the copied `runtime.mjs` using the correct relative path. Read the real configuration contract version and pass the returned context to `connectPreviewRuntime` along with `fields`, `source`, `resolve` and `createGame`.
+
+- `source.get/install` reads and replaces the actual configuration store; `resolve(documents)` shares production default/override rules.
+- Each field registers its actual `documentId`, raw `path`, resolved `effectivePath`, `groupId` and application `mode`.
+- `createGame(context)` returns real `apply`, `restartScene`, `afterRender` and `dispose` behavior. Honor `context.signal` and `context.assertCurrent()` before asynchronous visible changes. `afterRender` waits for a real frame.
+- Live changes preserve progress and object identity where appropriate. Scene restart uses the game's own lifecycle and disposes obsolete objects, timers, event handlers and owned resources.
+- Image consumers use `resource: "image"`, logical paths and `context.loadImage`. Prepare before installation, retain the previous image on a recoverable load failure, and honor explicit same-path refreshes. See the copied guide for resource error and lifecycle behavior.
+
+Do not route development updates through an advertising configuration cache. Real field registration and a version-matched handshake establish capability; an integration report cannot do so.
+
+## Separate build
+
+The project needs a compatible development Vite. Add `build:cloud-preview` invoking `node .playcraft/preview-runtime/build-preview.mjs --entry <actual-preview-entry>` with optional `--config <actual-preview-configuration>` and `--mount-id <actual-container>`. The helper does not implicitly load production Vite configuration. Adapt aliases, data imports, constants and asset handling explicitly when needed; preserve the production build system.
+
+Preserve unrelated workspace manifest fields and add:
+
+```json
+{
+  "previewRuntime": {
+    "version": 1,
+    "buildScript": "build:cloud-preview",
+    "outputPath": ".playcraft-editor-preview/index.html",
+    "reportPath": ".playcraft-editor-preview/report.json",
+    "configContractVersion": "actual-contract-version",
+    "entryPath": "src/preview/runtime.ts",
+    "gameFilePaths": [
+      "src/preview/runtime.ts",
+      "src/game/configuration.ts",
+      "src/game/game.ts",
+      ".playcraft/preview-runtime/runtime.mjs",
+      ".playcraft/preview-runtime/build-preview.mjs"
+    ]
+  }
+}
+```
+
+Replace example paths and contract version with actual existing inputs. Add optional `viteConfigPath` and `mountId` when used, and include all extra configuration inputs in `gameFilePaths`. The platform invokes its trusted packaged helper and supplies `PLAYCRAFT_RUNTIME_PREVIEW_CONTEXT`; manually inventing this context or authoring a successful module report is invalid.
+
+## Production boundary
+
+Production must read the same neutral resolver and saved data while excluding the preview entry and runtime. With Vite, register `previewRuntimeReleaseGuard({root: process.cwd(), previewEntries: [...]})` from the copied `release-guard.mjs` in the actual production plugins, listing the real preview entry. Keep its default report path `.playcraft-editor-preview/release-report.json`; do not override `reportPath`. Configure production output at the engineering root `dist/`.
+
+Initialization admission removes the previous report before the independent production build, then verifies the new report, actual module boundaries and the complete `dist/` artifact hashes. Missing or stale evidence, soft links, changed artifacts or development runtime markers leave initialization unverified. This establishes the stated module/output boundary, not a general audit of every possible plugin. Other builders need equivalent platform-supported evidence; otherwise report the unsupported boundary.
+
+Keep managed runtime files out of parameter report `sources`, `origins` and `consumers`: they are recorded separately by the preview module report. Parameter evidence names the actual game consumer and resolver, not the copied development library. A successful parameter check or production build alone does not prove live behavior or production isolation.