@playcraft/cli 0.1.65 → 0.1.67

package/project-template/.claude/skills/playcraft-level-editor/references/extensions.md

@@ -0,0 +1,37 @@
+# Project-owned editor extensions
+
+Read the runtime-injected authoring contract first. Capabilities are additive to protocol version 1; a version-2 transaction is required for a composition spanning documents. An older runtime must reject unsupported editing rather than receive several independent writes. Keep project Skill locks and existing source data intact.
+
+## Native spatial composition
+
+`paths2d@1` displays the project collection and selection. Its `edit` action references `path.edit`, which declares `collection`, `selection`, `xField`, `yField`, `edges` (a binding), `edgeIdField`, `fromField`, `toField`, optional `directed`, `allowSelfLoops` and `deletePolicy`. Coordinates, node and edge identifiers use the project's native fields. Default deletion rejects connected nodes; use `cascade` only when removing incident edges is meaningful. Node and edge data stay in one native document. Templates for newly inserted nodes and edges belong in `defaultNode` and `defaultEdge`, preserving required custom metadata.
+
+`objects3d@1` explicitly maps `x/y/z`, optional `rotationX/Y/Z` and `scaleX/Y/Z` bindings to the existing document. It provides three orthographic editing planes, drag, keyboard movement and numeric transforms. Rotations use radians; scales are dimensionless. Choose the actual project units and schema limits; convert units in a neutral game resolver when necessary. This component edits native positions and transforms and does not inspect engine objects or provide an engine scene hierarchy.
+
+For native `objects2d@1`, `shape` and `shapeVariants: {field, values}` define finite circles, rectangles, diamonds or polygons with bounded points, size and hexadecimal color. Variant keys are the actual object's field values. They are presentation data; asset bindings and saved native values keep their existing meaning.
+
+## Typed command composition
+
+`command.batch` composes already declared commands. Give it a supported `inputSchema` and `steps: [{commandId, input: {targetInput: {input: "parameter"} | {value: <constant>}}}]`. The compiler rejects cycles and excessive nesting; execution checks every primitive, complete candidate data, stable targets and readonly boundaries. `command@1` renders a command launcher with project-provided input or an editable structured input. Use a project-local label for its actual purpose.
+
+A command spanning documents uses one version-2 request with a complete `expectedDocuments` baseline. The existing directory lease, private prepared/confirmed history and recovery journal own this operation. A pending or uncertain write blocks other platform reads and writes until recovery; do not bypass it or edit journal files. User code reading operating-system files directly has no cross-file atomic read guarantee.
+
+## Dedicated views and pure projections
+
+Declare `extensions.views[name]: {entry: "editor/custom.html", documents: [<authorized document IDs>], commands: [<allowed command IDs>], mode?: "view" | "projection2d"}` and use `extension-view@1` with `props.extension: name`. Ship one self-contained HTML (HyperText Markup Language, 超文本标记语言) page. The host reads it through the scoped file service, uses an opaque sandbox frame and passes no platform credentials. Do not depend on remote scripts, imports, network requests or direct filesystem access.
+
+Listen for parent messages only from `window.parent`. Start by sending `{kind:"ready",version:1}`. The host sends `{kind:"snapshot",version:1,token,editorId,documents,selection,commands,readonly}`. Recompute from each complete snapshot; the token changes whenever its data, selection or write availability changes.
+
+- Propose an edit using `{kind:"command",version:1,token,requestId,commandId,input}`. Use unique request identifiers. The host pins its current stable selection, rejects stale tokens and unlisted commands, and returns `command-result` with `applied` or `rejected`. `applied` means a local author draft, not saved data or a successful game render.
+- Propose selection using `{kind:"select",version:1,token,slot,identity}`. The host checks the declared collection, authorized document and existing stable identity.
+- For native pure-data rendering, `mode:"projection2d"` consumes `{kind:"projection",version:1,token,width,height,shapes}`. Shapes are bounded circles, rectangles and polylines/polygons; the machine contract supplies exact fields. Optional `action:{commandId,input}` exposes the same authorized command route. Labels are plain text. No arbitrary markup, shaders or executable drawing expressions enter the host.
+
+The host limits source, messages, shapes and command proposals. Loading, handshake or runtime errors isolate the view and leave the native editor available. Include the extension entry in source evidence and keep it out of production output. Do not claim full assistive-technology or scale validation from component tests.
+
+## Custom validators and native file providers
+
+`extensions.validators` contains `{id,module,timeoutMs?}`. A self-contained module exports `validate({documents,definition})` (or its default function) and returns `{diagnostics:[{code,message,severity,documentId?,path?,bindingId?,componentId?}]}`. Validate actual gameplay constraints such as connectivity or resource budgets, not fixed example values. The saving service runs it again and rejects error diagnostics. A timeout, invalid output or missing source is a failure, not a passed check.
+
+A document may declare `format:"json"`, `"json5"` or `"yaml"`; schemas remain ordinary supported schemas. A nonstandard native format instead declares `provider:{module,timeoutMs?}` and no `format`. Its self-contained module exports `parse({text})` returning a neutral data value and `serialize({text,data,changes})` returning the resulting text. The platform reparses that text and compares it with the complete authorized candidate; a provider cannot authorize additional changes. Preserve original comments, unknown fields and formatting wherever the format permits it. Never silently rewrite another format as JSON.
+
+Extension modules run in bounded child execution with a restricted environment, finite input/output and time limits. Imports, dynamic imports and host globals are unavailable. They exchange serializable data only. They are project code running inside the existing engineering sandbox; this mechanism is not a replacement for operating-system isolation. Module bytes join the execution contract, and changes invalidate old transactions. Include the modules and meaningful consumer checks in the task's source report. Run ordinary project checks; keep any unperformed managed, browser, device or performance checks explicitly unverified.

package/project-template/.claude/skills/playcraft-level-editor/references/preview.md

@@ -0,0 +1,15 @@
+# Real development and production consumers
+
+Install the managed development modules with `playcraft preview-runtime init --dir .`. Import `connectLevelEditorRuntime` and `readLevelEditorPreviewContext` from the resulting `.playcraft/preview-runtime/runtime.mjs`. Keep the project's production entry and build behavior. The definition's `preview: {entry, adapter}` points to real engineering-relative development files; it is not proof those files are connected.
+
+`readLevelEditorPreviewContext()` returns the immutable build's `binding` and authorized `parentOrigin`. Call `connectLevelEditorRuntime({...context, commands: [actualCommandIds], adapter})`. The adapter supplies `loadLevel(context)`, `enterEdit(context)`, `afterRender(context)` and `dispose({signal, reason})` (an existing zero-argument implementation remains compatible). The context carries `documents`, `selection`, `draftRevision`, `mode` and an abort `signal`. Resolve the selected stable level from those documents. Both edit and play loading must use the game's real data consumers; `afterRender` waits for a real frame.
+
+The runtime bounds the entire snapshot application, including queue time, to 25 seconds by default and cleanup to 2 seconds. Honor `context.signal` before every state mutation and after asynchronous waits, stop timers/listeners during cleanup, and reject cancelled work. The runtime retires an instance after timeout, cancellation, application failure or a host takeover during active work; it rejects subsequent snapshots and success acknowledgements. Recovery requires a new frame and fresh handshake. A timeout does not prove noncooperative project code stopped; do not reuse the same game instance to fake recovery. Ordinary successful edits retain their frame.
+
+Declare `previewRuntime` in `.playcraft/workspace.json` using `version: 1`, `buildScript: "build:cloud-preview"`, `outputPath: ".playcraft-editor-preview/index.html"`, `reportPath: ".playcraft-editor-preview/report.json"`, a real `configContractVersion`, `entryPath` pointing to the development entry, and `gameFilePaths` covering its source inputs and copied runtime. Add `build:cloud-preview` as `node .playcraft/preview-runtime/build-preview.mjs --entry <actual-entry>`, adapting a separate Vite configuration explicitly when needed. The platform supplies the real build context; do not fabricate it. A level-only project does not need a dummy parameter declaration.
+
+The development adapter loads a complete author-data snapshot, resolves the selected stable level identity, restarts or updates the real game, and acknowledges only after a real render. It reports the actual editor/data contract, source identity, loaded snapshot and supported operations. Reject stale identities and dispose obsolete game instances, listeners and timers.
+
+Use the same neutral resolver in production and development. Game consumers must read the files declared by the editor. Tests should change meaningful fields and exercise those consumers, rather than merely checking declaration strings. Preview capability and browser visual acceptance are separate from passing command-line checks.
+
+Development editor modules and bridges must remain outside production `dist/`. Add `previewRuntimeReleaseGuard({root: process.cwd(), previewEntries: [<actual-development-entry>]})` from the copied `release-guard.mjs` to the real production Vite build. Keep its default report path. A missing required guard or script, a failed release guard, missing adapter methods, or unwired real consumers are actual engineering gaps to fix or report. Later managed builds, browser handshakes and Portal checks that have not run remain explicitly unverified under [the protocol's phase boundaries](protocol-v1.md); their absence alone is not a code `missing` item. Do not replace the real game with a static success fixture.

package/project-template/.claude/skills/playcraft-level-editor/references/protocol-v1.md

@@ -0,0 +1,35 @@
+# Level editor protocol, first version
+
+Preserve unrelated `.playcraft/workspace.json` keys and add `levelEditor: {version: 1, definition: "<engineering-relative-definition-path>"}`. The declaration is data, not a component implementation. Use strict JSON (JavaScript Object Notation, JavaScript 对象表示法) or JSON5 (JSON with ECMAScript 5 syntax, 扩展对象表示格式) for declarations and schemas. Native data additionally supports explicitly declared YAML (YAML Ain’t Markup Language, 结构化数据语言) or a bounded project provider when the installed runtime advertises extensions.
+
+A definition contains `protocolVersion: 1`, stable `editorId`, positive `dataContractVersion`, `documents`, `collections`, `selections`, `bindings`, `commands`, `view`, optional `preview`, `extensions` and `labels`. Obtain the exact schemas and component catalog from the runtime-provided task context; do not assume examples describe every installed capability.
+
+- Documents map a local identifier to `{path, schema}`. Paths stay within the engineering directory. A primitive command changes one document; a declared command composition can use a version-2 transaction with all document baselines and one trusted journal. Do not simulate cross-document atomicity with several independent saves.
+- Collections bind a document and `segments` and declare `idField`. Each segment is `{field: "member"}` or `{item: {key: "stable-key-field", selection: "selection-slot"}}`. Collection identities are unique within their parent scope and independent of ordering.
+- Selections map slot names to `{collection, mode: "single"}` and remain editor state. Bindings use the same structured segments to locate native fields; do not use array indices as object identities.
+- Commands declare supported operations and their targets. The current basic operations are `field.set`, `grid.paint`, `collection.insert`, `collection.duplicate`, `collection.delete`, `collection.reorder`, and declared `object.transform` bindings, `path.edit` and `command.batch`. Register only operations supported by the installed catalog and actual data schema.
+- `view` is a stable-ID component tree: `{id, component, props?, bind?, actions?, children?}`. Component identifiers include their major version, such as `grid2d@1` or `inspector@1`; containers compose project-specific layouts.
+- Labels are project-local dictionaries keyed by language, then label key. Use them for project-specific titles; preserve existing languages.
+
+The platform validates schema rules, identities and references independently. Unsupported constraints must remain explicit errors, not be silently removed to get a writable panel. Preserve sparse defaults and all unknown authored fields. Arrays and complex structures retain their original meaning.
+
+For data schemas, author every declared schema node with one explicit `type`: `object`, `array`, `string`, `number`, `integer`, `boolean`, or `null`. This covers the root, each value inside `properties`, a declared `items` schema, and an object used as an `additionalProperties` schema. The `properties` map itself and `additionalProperties: true/false` switches are not schema nodes. Union type arrays and undeclared schema keywords are unsupported. The parser also accepts nodes constrained by `enum` or `const` without a type; still emit an explicit type when authoring them.
+
+Annotations such as `readOnly`, `title`, `description`, `default`, and `examples` do not provide a type. A node containing only `{ "readOnly": true }` is rejected with `level_editor_schema_type_required`; use the existing value's actual type, for example `{ "type": "string", "readOnly": true }` for a preserved author note. An unknown author extension object can remain opaque as `{ "type": "object", "readOnly": true, "additionalProperties": true }`. This does not require inventing schemas for every internal field. Keep native values intact; do not convert an object into a string, delete unknown fields, or invent one item type for a heterogeneous author array just to satisfy the subset.
+
+Keep `test:level-editor` compatible with future legal edits. Use controlled copies of the current saved author data to exercise real consumer outcomes. Do not hardcode the initial file digest or original gameplay values as permanent test invariants; the platform separately records and checks initialization preservation.
+
+The runtime's report identity is authoritative. A report has `version: 1`, the supplied `taskId`, unique `sources: [{path, sha256}]`, actual `consumers: [{path, line?, summary}]`, implemented command identifiers in `operations`, concrete unfinished items in `missing`, and optional `preserved`. Every consumer must be a declared source with matching current raw-file hash. Include the manifest, definition, schemas, data files, production resolver/consumer, development adapter and `package.json`. Managed runtime files may be tracked as build inputs, but cannot substitute for real game consumers. Never claim verification or manufacture platform receipts.
+
+`missing` records actual incomplete or failed engineering integration: a missing or invalid schema, an unwired real data consumer, missing adapter methods, missing required project scripts, a failed production boundary, or another concrete code capability the task requires. Inspect those capabilities and fix the underlying code or report the remaining gap. Do not clear a known code failure merely to make verification proceed.
+
+Keep the later authorities separate:
+
+1. After the source report is submitted, the platform's independent verification checks the report, sources, project scripts and production isolation. A nonempty `missing` blocks this admission. An empty list does not mean these checks have run or passed.
+2. After admission, the platform's managed development build supplies the authorized preview context. Do not fabricate that context or a build receipt. Running the development entry bare and seeing `preview_runtime_context_missing` is not evidence of an engineering defect by itself.
+3. The real browser runtime establishes its handshake and ACK (Acknowledgement, 确认回执) after consuming the actual snapshot and rendering. Neither `missing: []` nor a passing command-line test establishes connected capability.
+4. Actual Portal interactions establish editing, saving, reopening and playtest behavior. A missing browser inspection tool, `ui_view_unavailable`, or an interaction not yet performed is an unverified fact, not an engineering `missing` item by itself.
+
+If an authorized managed run exposes a concrete adapter, consumer or build defect, fix it or name that actual failed capability in `missing`. Otherwise, keep the unperformed or unavailable later checks explicit in the final reply or project README. Do not invent their results, environment or authorization; do not add unknown `pending` or other fields to the strict report schema. `missing: []` means only that no engineering gaps were identified in this report; it does not mean checked, verified or connected. This separation lets the platform run the later phases without hiding unverified work or creating a verification-before-preview cycle.
+
+When adapting an already declared editor, the platform preserves existing raw author documents privately. Keep their bytes unchanged under the same `dataContractVersion`; layout changes are not a reason to rewrite levels. An actual migration increases that version and adds `migration: {fromDataContractVersion, toDataContractVersion, summary}` and `preserved: true` to the report. Describe how the original user values and identities survive, and exercise the migration in `test:level-editor`. The platform can check the version, plan, backups and executable evidence; this does not automatically prove every arbitrary migration semantically lossless.

package/project-template/vite.config.ts

@@ -20,7 +20,7 @@ export default defineConfig(({ command }) => ({
     open: true,
   },
   build: {
-    outDir: "dist",
+    outDir: "dist/preview",
     sourcemap: true,
   },
 }));

package/project-template-v2/.claude/skills/playcraft-audio-generation/SKILL.md

@@ -3,7 +3,7 @@ name: playcraft-audio-generation
 description: Use when generating or replacing playable audio, reusing library audio, managing durable audio tasks, or locally compressing, trimming, looping, normalizing, and mixing sound.
 triggers: 生成音效,生成bgm,生成背景音乐,generate sfx,generate bgm,generate audio,音频,音效,背景音乐,sfx,bgm,loop音频,音频压缩,音频处理,audio,compress audio,fade,normalize,音频后处理,音频管线
 compatibility: agent,opencode
-version: 1.1.1
+version: 1.3.0
 surfaces:
   - sandbox-agent
 ---
@@ -12,7 +12,77 @@ surfaces:
 
 ## 0. 开始前必读
 
-AI (Artificial Intelligence, 人工智能) 音频包含 SFX (Sound Effects, 音效) 与 BGM (Background Music, 背景音乐)。工作素材写入当前工程的 `assets/audio/` 或当前主题素材目录；最终交付导出到工程根目录 `dist/`。请求文件和工作记录保存在 `dist/` 外。
+AI (Artificial Intelligence, 人工智能) 音频包含 SFX (Sound Effects, 音效) 与 BGM (Background Music, 背景音乐)。文件音频工作素材写入当前工程的 `assets/audio/` 或当前主题素材目录；最终交付导出到工程根目录 `dist/`。可编辑短音效源见下节。请求文件和工作记录保存在 `dist/` 外。
+
+### 云工作区的可编辑短音效
+
+仅在当前锁定技能版本与工作区能力支持时使用本段流程。先运行 `playcraft audio source capabilities`，检查 `enabled`、`writable`、对应 `operations`；生成与渲染还须 `renderer.ready`。能力缺失或关闭时保留源及已有试听，报告不可用，不替换工程技能锁，不移除声音上下文后继续执行。`synth-sfx` 保持短音效流程；仅在 `audioScoreVersion:1` 与 `audioScoreContextVersion:1` 均声明时使用下述乐谱／多轨流程。外部采样和动态混合仍不支持。
+
+默认从描述、试听、采用开始，只展示适用的时长、音量、音高、明亮度简单控件；用户要求细节后再展开精确参数。工程源在 `source/audio/` 等 `dist/` 外目录，最终表示包位于 `dist/audio/`。未采用候选保持私有，不因续改而强制写入工程。
+
+```bash
+# short-sound-request.json: {"kind":"audio","representation":"synth-sfx","category":"sfx","description":"短促明亮的金币音","duration":0.2,"candidateCount":1}
+playcraft audio source create --request short-sound-request.json --request-id <stable-request-id>
+playcraft assets get <taskId>
+playcraft assets wait <taskId>
+playcraft audio source inspect --task <taskId> --candidate <candidateId>
+
+# duration 是秒；volume 是主增益；pitch 是半音；brightness 是滤波截止频率倍数。
+playcraft audio source edit --task <taskId> --candidate <candidateId> \
+  --revision <candidateRevision> --hash <sourceContentHash> --request-id <stable-edit-id> \
+  --macro duration --value 0.15
+playcraft audio source render --task <taskId> --candidate <candidateId> \
+  --revision <newRevision> --hash <newSourceContentHash> --request-id <stable-render-id>
+
+# 用户明确采用后才保存到工程；替换已有目标还须其真实修订和摘要。
+playcraft audio source adopt --task <taskId> --candidate <candidateId> \
+  --revision <candidateRevision> --hash <sourceContentHash> --request-id <stable-adopt-id> \
+  --output source/audio/coin.pcaudio.json --destination-revision 0
+playcraft audio source inspect --path source/audio/coin.pcaudio.json
+```
+
+这些命令使用同一工作区素材任务。候选身份是任务、候选、修订与源内容摘要；工程源身份是工作区、目录、路径、修订与摘要。保存完整源用 `edit/save --document <file>`，只改简单目标用 `--macro`。每次保存后重新渲染才获得对应试听。所有写命令都要求稳定 `--request-id`；响应不确定时使用原身份恢复，不重复生成。`assets download` 不会把参数候选伪装成音频文件，请走专用采用。
+
+接收 `composer.context.audio` 时先核对目录与精确版本，并保留 `selection`、`lockedVoiceIds`、`preserveTargets`。将保护项传给 `edit/save --locked-voices <逗号分隔声部> --preserve-targets <逗号分隔参数目标>`。锁定和曲线不可静默重置。`intent: propose` 只授权提出可比较方向；明确修改并保存才写入原目标；用于游戏需要接入授权。修订冲突表示用户已有新修改，保留结果供比较，不能刷新基准后覆盖。
+
+保存、试听就绪、实际引用、构建通过分别记录。`pending`、`failed`、`cancelled` 和 `render_peak_exceeded` 不能宣称完成；峰值超限时保留原源、说明需调整增益，不静默归一化。候选修改不会自动采用，收起精细视图也不能丢失源字段。
+
+用于游戏时读取采用回执的 `representation.modulePath`，其中 `sound.mjs` 与运行时、源和试听均是不可变包内相对引用。定位用户指定事件的实际调用点，或沿已有绑定替换；保存旧调用和绑定后，导入 `createSound`，在该交互中调用 `play()`，场景销毁调用 `dispose()`。共享播放器最多 8 个实例、32 个声部；播放需浏览器交互解锁，按工程既有方式处理失败。随后执行工程原有构建验证；没有明确调用点时保持待接入，不猜测事件映射。
+
+```javascript
+import { createSound } from '<representation.modulePath 相对当前模块的路径>';
+const coinSound = createSound();
+// 放入用户指定的金币事件处理器；按项目方式处理播放失败。
+await coinSound.play();
+// 场景销毁：coinSound.dispose();
+```
+
+`playcraft audio source bind --path <source> --revision <revision> --hash <hash> --event <event> --request-id <id>` 只创建固定版本的交接记录，返回 `integration_required`，不能证明代码已引用或构建成功。`rollback --path <source> --revision <current> --hash <hash> --version <historical> --request-id <id>` 追加历史源恢复修订，之后重新渲染。游戏回退还必须恢复旧模块调用及绑定，再次构建；不能只恢复源就宣称游戏回退。
+
+### 可编辑音乐与多轨协作
+
+音乐使用 `format: "playcraft.score"`、`content.kind: "score"` 的 `.pcscore.json`，引擎 `playcraft-webaudio-score@1.0.0`。先核对音乐能力、写权限与渲染就绪。默认让用户描述用途、试听候选，再调速度、整体强弱、乐器和循环；选轨、拍段或音符后才展开细节。符号音高采用 MIDI (Musical Instrument Digital Interface, 乐器数字接口) 音符号；时间是四分音符拍点，速度为 BPM (Beats Per Minute, 每分钟节拍数)，不能混用秒和拍。
+
+```bash
+# music-request.json: {"kind":"audio","representation":"score","category":"bgm","description":"轻快的两轨游戏循环音乐","duration":8,"bpm":120,"loop":true,"candidateCount":1}
+playcraft audio source create --request music-request.json --request-id <stable-create-id>
+playcraft assets wait <taskId>
+playcraft audio source inspect --task <taskId> --candidate <candidateId>
+playcraft audio source edit --task <taskId> --candidate <candidateId> \
+  --revision <revision> --hash <sourceContentHash> --request-id <stable-edit-id> --macro tempo --value 132
+playcraft audio source render --task <taskId> --candidate <candidateId> \
+  --revision <newRevision> --hash <newHash> --request-id <stable-render-id>
+playcraft audio source adopt --task <taskId> --candidate <candidateId> \
+  --revision <newRevision> --hash <newHash> --request-id <stable-adopt-id> --output source/audio/loop.pcscore.json
+```
+
+精细操作使用 `edit --adjustment <file>`：例如 `{"kind":"instrument","instrument":"bell","trackIds":["melody"]}`；或者在读取精确源后 `edit --document <file>` 保存完整源。内置音色限 `piano / bell / bass / pad / sine / drums`，不是外部采样乐器库。最多 8 轨、512 音符、32 并发音符、60 秒和 64 KiB 源；超限、无法表达的特性必须报告，不截断或改成另一种音频。
+
+`composer.context.audio.version:2` 明确 `timeUnit:"beats"`，冻结 `selection.trackIds / noteIds / rangeBeats`、`protection.lockedTrackIds / preserveMelody`。把该选区原样写入工程外临时文档，保存时传 `--selection <file> --locked-tracks <ids> --preserve-melody` 中实际适用的项。只调整鼓轨第 5—8 小节时，按拍号计算精确拍段，保护其余轨和拍段；改变整轨音色、增益、自动化或全局速度会影响范围之外，不能把它当作局部修改。服务器会与可信上下文再次核对，命令自行删掉保护条件不会解除限制。
+
+修订不匹配时保留双方，不自行刷新后覆盖。网页可由用户显式合并没有依赖冲突的轨道或音符；速度、循环、全局混音、同轨音色／自动化及同音符冲突需要比较后重做。候选仍须独立采用，回退仍追加新源修订，游戏引用仍单独恢复。
+
+音乐完整包成员为 `sound.pcscore.json / audition.wav / runtime.mjs / sound.mjs / manifest.json`，只使用回执中的固定模块。`createSound().prepare()` 不默认展开整段音乐采样；`play()` 按乐谱和循环段调度，返回的 `stop()` 或播放器 `stop()/dispose()` 会结束循环并释放资源。场景退出、页面隐藏或切换试听时应调用停止，禁止遗留循环。单次播放可传 `play({loop:false})`；指定段落或轨道试听通过受支持的 `selection` 参数。试听渲染文件本身是完整单次表示，循环起止需随乐谱一起使用。
 
 ### 复用素材与持久化音频任务
 
@@ -199,7 +269,7 @@ playcraft audio info --input assets/audio/bgm/main_theme_loop.mp3
 
 ## 3. 本地音频后处理
 
-所有 `playcraft audio` 子命令**完全本地运行**，无需网络。
+本节文件后处理子命令**完全本地运行**，无需网络；前述 `playcraft audio source` 使用云工作区服务。
 
 ### 3.1 常用处理命令
 
@@ -253,7 +323,7 @@ playcraft audio mix \
 
 ### 3.2 标准音频处理管线
 
-AI 生成后的**必做处理步骤**：
+文件音频生成后的处理步骤：
 
 ```
 SFX 管线：

package/project-template-v2/.playcraft/skills.lock.json

@@ -108,8 +108,8 @@
     },
     {
       "skillRef": "remix/playcraft-audio-generation",
-      "version": "1.1.1",
-      "artifactHash": "27661b1b52e7981a0b9cf5531f535fcf10928ea290348fcb469e35ad2082b437",
+      "version": "1.3.0",
+      "artifactHash": "39e9a331a1f5b4ebe96a663fa845b41f2471be239610b12f9fca86c494e82665",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-audio-generation"
     },
@@ -134,6 +134,13 @@
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-image-processing"
     },
+    {
+      "skillRef": "remix/playcraft-level-editor",
+      "version": "1.1.0",
+      "artifactHash": "661664b0b3dd1ff7d75e2e7e724177921ea35f696f33a6974645d9f0f90fd0da",
+      "surface": "sandbox-agent",
+      "mountPath": ".playcraft/skills/remix__playcraft-level-editor"
+    },
     {
       "skillRef": "remix/playcraft-prefab",
       "version": "1.0.0",

package/project-template-v2/vite.config.ts

@@ -21,7 +21,7 @@ export default defineConfig(({ command }) => ({
     open: true,
   },
   build: {
-    outDir: "dist",
+    outDir: "dist/preview",
     sourcemap: true,
   },
 }));

package/project-templates/empty/AGENTS.md

@@ -59,13 +59,17 @@ Do not ask the user to choose reuse versus generation for every asset. Ask only
 - Durable generation: `playcraft assets estimate --request <request-file>` estimates a request. `assets generate --request <request-file> --client-request-id <stable-unique-id>` starts a workspace generation task for images, audio, sprites, frame animation, models, or video. Reuse that identifier for the same request after an uncertain outcome. `assets tasks`, `assets get <taskId>`, `assets wait <taskId>`, and `assets cancel <taskId>` manage existing tasks. `assets download <taskId> --output <new-path>` retrieves a completed result. Commands infer workspace and project directory from the current checkout; explicit `--workspace` and `--directory` must match it.
 - Generated task results can be saved to the shared library through `assets library-targets`, `assets library-save`, `assets library-saves`, and `assets library-retry`. `assets animation` reads and edits animation drafts, uploads frames, and creates export versions. Keep request files and receipts outside `dist/`.
 
-## Deliverable artifacts
+## Workspace artifacts
 
-The artifact panel shows final deliverables under `dist/` at the current project directory's root, including images, video, audio, models, documents, and playable builds. Keep working sources, input references, dependencies, receipts, and build intermediates outside `dist/`. Do not copy unrelated source files into it just to make them appear in the panel.
+The artifact panel shows what this workspace builds and generates, under `dist/` at the current project directory's root: generated images, video, audio, models and documents, and the `playcraft build` preview. Channel packages are packaged by platform export, not built here; they belong in the Delivery tab and never in `dist/`. Keep working sources, input references, dependencies, receipts, and build intermediates outside `dist/`. Do not copy unrelated source files into it just to make them appear in the panel.
 
-When a generated asset is ready for delivery, save or copy it into `dist/` with a stable relative path. Keep the resources required by a model or document within `dist/` and preserve their relative links. Reuse the same delivery path for a revised artifact so its versions remain grouped; the platform retains its history. Use different paths for independent candidates or deliverables.
+When a generated asset is ready, save or copy it into `dist/` with a stable relative path. Keep the resources required by a model or document within `dist/` and preserve their relative links. Reuse the same path for a revised artifact so its versions remain grouped; the platform retains its history. Use different paths for independent candidates or artifacts.
 
-Run playable builds from the project root with `playcraft build`. It takes no channel or format options and always produces the review build at `dist/preview/index.html`; channel packages come only from platform export. In a workspace this command builds in an isolated copy, validates the result, and retains the playable at `dist/preview/index.html` while preserving other deliverables. A successful agent command or turn that writes a valid self-contained HTML (HyperText Markup Language, 超文本标记语言) file at this same path is collected as the same playable preview. No separate publish action is required to view it. A base build's `dist/index.html` can still require resource files and remains a document. The page's generate-preview action rebuilds the current project through the same validation. After a successful build the command also publishes the playable and prints `Public URL: <address>`; when you report the build, link that address as the playable instead of the sandbox path, since it opens directly and can be shared. If the command prints `Public URL unavailable`, report that the build succeeded without a public address and give the reason it printed. Temporary `.playcraft-preview-out/` and `.playcraft-temp/` files are not deliverables. Preserve other artifacts already in `dist/` when rebuilding a playable.
+Run playable builds from the project root with `playcraft build`. It takes no channel or format options and always produces the review build at `dist/preview/index.html`; channel packages come only from platform export. In a workspace this command builds in an isolated copy, validates the result, and retains the playable at `dist/preview/index.html` while preserving other artifacts. A successful agent command or turn that writes a valid self-contained HTML file at this same path is collected as the same playable preview. No separate publish action is required to view it. A base build's `dist/index.html` can still require resource files and remains a document. The page's generate-preview action rebuilds the current project through the same validation. After a successful build the command also publishes the playable and prints `Public URL: <address>`; when you report the build, link that address as the playable instead of the sandbox path, since it opens directly and can be shared. If the command prints `Public URL unavailable`, report that the build succeeded without a public address and give the reason it printed. Temporary `.playcraft-preview-out/` and `.playcraft-temp/` files are not artifacts. Preserve other artifacts already in `dist/` when rebuilding a playable.
+
+Keep the preview current yourself. After changing anything the playable depends on, such as source, scenes, configuration or the assets it uses, run `playcraft build` before you finish the turn so `dist/preview/index.html` matches the current project; do not leave the preview stale or ask the user to rebuild it. Build once after the last change of a turn rather than after every edit, and skip it when the turn changed nothing the playable uses, such as documents or standalone generated artifacts. If the build fails, fix the cause and build again; if it still fails, report the failure and that the preview is out of date.
+
+When reporting finished exports, tell the user the packages are in the Delivery tab and open it with `playcraft_open_delivery`.
 
 Keep this convention in `AGENTS.md`, the project's standard instruction filename. Do not create a separate `AGENT.md`.
 

package/project-templates/phaser/.claude/skills/playcraft-audio-generation/SKILL.md

@@ -3,7 +3,7 @@ name: playcraft-audio-generation
 description: Use when generating or replacing playable audio, reusing library audio, managing durable audio tasks, or locally compressing, trimming, looping, normalizing, and mixing sound.
 triggers: 生成音效,生成bgm,生成背景音乐,generate sfx,generate bgm,generate audio,音频,音效,背景音乐,sfx,bgm,loop音频,音频压缩,音频处理,audio,compress audio,fade,normalize,音频后处理,音频管线
 compatibility: agent,opencode
-version: 1.1.1
+version: 1.3.0
 surfaces:
   - sandbox-agent
 ---
@@ -12,7 +12,77 @@ surfaces:
 
 ## 0. 开始前必读
 
-AI (Artificial Intelligence, 人工智能) 音频包含 SFX (Sound Effects, 音效) 与 BGM (Background Music, 背景音乐)。工作素材写入当前工程的 `assets/audio/` 或当前主题素材目录；最终交付导出到工程根目录 `dist/`。请求文件和工作记录保存在 `dist/` 外。
+AI (Artificial Intelligence, 人工智能) 音频包含 SFX (Sound Effects, 音效) 与 BGM (Background Music, 背景音乐)。文件音频工作素材写入当前工程的 `assets/audio/` 或当前主题素材目录；最终交付导出到工程根目录 `dist/`。可编辑短音效源见下节。请求文件和工作记录保存在 `dist/` 外。
+
+### 云工作区的可编辑短音效
+
+仅在当前锁定技能版本与工作区能力支持时使用本段流程。先运行 `playcraft audio source capabilities`，检查 `enabled`、`writable`、对应 `operations`；生成与渲染还须 `renderer.ready`。能力缺失或关闭时保留源及已有试听，报告不可用，不替换工程技能锁，不移除声音上下文后继续执行。`synth-sfx` 保持短音效流程；仅在 `audioScoreVersion:1` 与 `audioScoreContextVersion:1` 均声明时使用下述乐谱／多轨流程。外部采样和动态混合仍不支持。
+
+默认从描述、试听、采用开始，只展示适用的时长、音量、音高、明亮度简单控件；用户要求细节后再展开精确参数。工程源在 `source/audio/` 等 `dist/` 外目录，最终表示包位于 `dist/audio/`。未采用候选保持私有，不因续改而强制写入工程。
+
+```bash
+# short-sound-request.json: {"kind":"audio","representation":"synth-sfx","category":"sfx","description":"短促明亮的金币音","duration":0.2,"candidateCount":1}
+playcraft audio source create --request short-sound-request.json --request-id <stable-request-id>
+playcraft assets get <taskId>
+playcraft assets wait <taskId>
+playcraft audio source inspect --task <taskId> --candidate <candidateId>
+
+# duration 是秒；volume 是主增益；pitch 是半音；brightness 是滤波截止频率倍数。
+playcraft audio source edit --task <taskId> --candidate <candidateId> \
+  --revision <candidateRevision> --hash <sourceContentHash> --request-id <stable-edit-id> \
+  --macro duration --value 0.15
+playcraft audio source render --task <taskId> --candidate <candidateId> \
+  --revision <newRevision> --hash <newSourceContentHash> --request-id <stable-render-id>
+
+# 用户明确采用后才保存到工程；替换已有目标还须其真实修订和摘要。
+playcraft audio source adopt --task <taskId> --candidate <candidateId> \
+  --revision <candidateRevision> --hash <sourceContentHash> --request-id <stable-adopt-id> \
+  --output source/audio/coin.pcaudio.json --destination-revision 0
+playcraft audio source inspect --path source/audio/coin.pcaudio.json
+```
+
+这些命令使用同一工作区素材任务。候选身份是任务、候选、修订与源内容摘要；工程源身份是工作区、目录、路径、修订与摘要。保存完整源用 `edit/save --document <file>`，只改简单目标用 `--macro`。每次保存后重新渲染才获得对应试听。所有写命令都要求稳定 `--request-id`；响应不确定时使用原身份恢复，不重复生成。`assets download` 不会把参数候选伪装成音频文件，请走专用采用。
+
+接收 `composer.context.audio` 时先核对目录与精确版本，并保留 `selection`、`lockedVoiceIds`、`preserveTargets`。将保护项传给 `edit/save --locked-voices <逗号分隔声部> --preserve-targets <逗号分隔参数目标>`。锁定和曲线不可静默重置。`intent: propose` 只授权提出可比较方向；明确修改并保存才写入原目标；用于游戏需要接入授权。修订冲突表示用户已有新修改，保留结果供比较，不能刷新基准后覆盖。
+
+保存、试听就绪、实际引用、构建通过分别记录。`pending`、`failed`、`cancelled` 和 `render_peak_exceeded` 不能宣称完成；峰值超限时保留原源、说明需调整增益，不静默归一化。候选修改不会自动采用，收起精细视图也不能丢失源字段。
+
+用于游戏时读取采用回执的 `representation.modulePath`，其中 `sound.mjs` 与运行时、源和试听均是不可变包内相对引用。定位用户指定事件的实际调用点，或沿已有绑定替换；保存旧调用和绑定后，导入 `createSound`，在该交互中调用 `play()`，场景销毁调用 `dispose()`。共享播放器最多 8 个实例、32 个声部；播放需浏览器交互解锁，按工程既有方式处理失败。随后执行工程原有构建验证；没有明确调用点时保持待接入，不猜测事件映射。
+
+```javascript
+import { createSound } from '<representation.modulePath 相对当前模块的路径>';
+const coinSound = createSound();
+// 放入用户指定的金币事件处理器；按项目方式处理播放失败。
+await coinSound.play();
+// 场景销毁：coinSound.dispose();
+```
+
+`playcraft audio source bind --path <source> --revision <revision> --hash <hash> --event <event> --request-id <id>` 只创建固定版本的交接记录，返回 `integration_required`，不能证明代码已引用或构建成功。`rollback --path <source> --revision <current> --hash <hash> --version <historical> --request-id <id>` 追加历史源恢复修订，之后重新渲染。游戏回退还必须恢复旧模块调用及绑定，再次构建；不能只恢复源就宣称游戏回退。
+
+### 可编辑音乐与多轨协作
+
+音乐使用 `format: "playcraft.score"`、`content.kind: "score"` 的 `.pcscore.json`，引擎 `playcraft-webaudio-score@1.0.0`。先核对音乐能力、写权限与渲染就绪。默认让用户描述用途、试听候选，再调速度、整体强弱、乐器和循环；选轨、拍段或音符后才展开细节。符号音高采用 MIDI (Musical Instrument Digital Interface, 乐器数字接口) 音符号；时间是四分音符拍点，速度为 BPM (Beats Per Minute, 每分钟节拍数)，不能混用秒和拍。
+
+```bash
+# music-request.json: {"kind":"audio","representation":"score","category":"bgm","description":"轻快的两轨游戏循环音乐","duration":8,"bpm":120,"loop":true,"candidateCount":1}
+playcraft audio source create --request music-request.json --request-id <stable-create-id>
+playcraft assets wait <taskId>
+playcraft audio source inspect --task <taskId> --candidate <candidateId>
+playcraft audio source edit --task <taskId> --candidate <candidateId> \
+  --revision <revision> --hash <sourceContentHash> --request-id <stable-edit-id> --macro tempo --value 132
+playcraft audio source render --task <taskId> --candidate <candidateId> \
+  --revision <newRevision> --hash <newHash> --request-id <stable-render-id>
+playcraft audio source adopt --task <taskId> --candidate <candidateId> \
+  --revision <newRevision> --hash <newHash> --request-id <stable-adopt-id> --output source/audio/loop.pcscore.json
+```
+
+精细操作使用 `edit --adjustment <file>`：例如 `{"kind":"instrument","instrument":"bell","trackIds":["melody"]}`；或者在读取精确源后 `edit --document <file>` 保存完整源。内置音色限 `piano / bell / bass / pad / sine / drums`，不是外部采样乐器库。最多 8 轨、512 音符、32 并发音符、60 秒和 64 KiB 源；超限、无法表达的特性必须报告，不截断或改成另一种音频。
+
+`composer.context.audio.version:2` 明确 `timeUnit:"beats"`，冻结 `selection.trackIds / noteIds / rangeBeats`、`protection.lockedTrackIds / preserveMelody`。把该选区原样写入工程外临时文档，保存时传 `--selection <file> --locked-tracks <ids> --preserve-melody` 中实际适用的项。只调整鼓轨第 5—8 小节时，按拍号计算精确拍段，保护其余轨和拍段；改变整轨音色、增益、自动化或全局速度会影响范围之外，不能把它当作局部修改。服务器会与可信上下文再次核对，命令自行删掉保护条件不会解除限制。
+
+修订不匹配时保留双方，不自行刷新后覆盖。网页可由用户显式合并没有依赖冲突的轨道或音符；速度、循环、全局混音、同轨音色／自动化及同音符冲突需要比较后重做。候选仍须独立采用，回退仍追加新源修订，游戏引用仍单独恢复。
+
+音乐完整包成员为 `sound.pcscore.json / audition.wav / runtime.mjs / sound.mjs / manifest.json`，只使用回执中的固定模块。`createSound().prepare()` 不默认展开整段音乐采样；`play()` 按乐谱和循环段调度，返回的 `stop()` 或播放器 `stop()/dispose()` 会结束循环并释放资源。场景退出、页面隐藏或切换试听时应调用停止，禁止遗留循环。单次播放可传 `play({loop:false})`；指定段落或轨道试听通过受支持的 `selection` 参数。试听渲染文件本身是完整单次表示，循环起止需随乐谱一起使用。
 
 ### 复用素材与持久化音频任务
 
@@ -199,7 +269,7 @@ playcraft audio info --input assets/audio/bgm/main_theme_loop.mp3
 
 ## 3. 本地音频后处理
 
-所有 `playcraft audio` 子命令**完全本地运行**，无需网络。
+本节文件后处理子命令**完全本地运行**，无需网络；前述 `playcraft audio source` 使用云工作区服务。
 
 ### 3.1 常用处理命令
 
@@ -253,7 +323,7 @@ playcraft audio mix \
 
 ### 3.2 标准音频处理管线
 
-AI 生成后的**必做处理步骤**：
+文件音频生成后的处理步骤：
 
 ```
 SFX 管线：

package/project-templates/phaser/vite.config.ts

@@ -20,7 +20,7 @@ export default defineConfig(({ command }) => ({
     open: true,
   },
   build: {
-    outDir: "dist",
+    outDir: "dist/preview",
     sourcemap: true,
   },
 }));

package/project-templates/playable-template-phaser/vite.config.ts

@@ -58,7 +58,7 @@ export default defineConfig({
 
   // 构建配置
   build: {
-    outDir: "dist",
+    outDir: "dist/preview",
     sourcemap: true,
   },
 });

package/project-templates/threejs/.claude/skills/playcraft-audio-generation/SKILL.md

@@ -3,7 +3,7 @@ name: playcraft-audio-generation
 description: Use when generating or replacing playable audio, reusing library audio, managing durable audio tasks, or locally compressing, trimming, looping, normalizing, and mixing sound.
 triggers: 生成音效,生成bgm,生成背景音乐,generate sfx,generate bgm,generate audio,音频,音效,背景音乐,sfx,bgm,loop音频,音频压缩,音频处理,audio,compress audio,fade,normalize,音频后处理,音频管线
 compatibility: agent,opencode
-version: 1.1.1
+version: 1.3.0
 surfaces:
   - sandbox-agent
 ---
@@ -12,7 +12,77 @@ surfaces:
 
 ## 0. 开始前必读
 
-AI (Artificial Intelligence, 人工智能) 音频包含 SFX (Sound Effects, 音效) 与 BGM (Background Music, 背景音乐)。工作素材写入当前工程的 `assets/audio/` 或当前主题素材目录；最终交付导出到工程根目录 `dist/`。请求文件和工作记录保存在 `dist/` 外。
+AI (Artificial Intelligence, 人工智能) 音频包含 SFX (Sound Effects, 音效) 与 BGM (Background Music, 背景音乐)。文件音频工作素材写入当前工程的 `assets/audio/` 或当前主题素材目录；最终交付导出到工程根目录 `dist/`。可编辑短音效源见下节。请求文件和工作记录保存在 `dist/` 外。
+
+### 云工作区的可编辑短音效
+
+仅在当前锁定技能版本与工作区能力支持时使用本段流程。先运行 `playcraft audio source capabilities`，检查 `enabled`、`writable`、对应 `operations`；生成与渲染还须 `renderer.ready`。能力缺失或关闭时保留源及已有试听，报告不可用，不替换工程技能锁，不移除声音上下文后继续执行。`synth-sfx` 保持短音效流程；仅在 `audioScoreVersion:1` 与 `audioScoreContextVersion:1` 均声明时使用下述乐谱／多轨流程。外部采样和动态混合仍不支持。
+
+默认从描述、试听、采用开始，只展示适用的时长、音量、音高、明亮度简单控件；用户要求细节后再展开精确参数。工程源在 `source/audio/` 等 `dist/` 外目录，最终表示包位于 `dist/audio/`。未采用候选保持私有，不因续改而强制写入工程。
+
+```bash
+# short-sound-request.json: {"kind":"audio","representation":"synth-sfx","category":"sfx","description":"短促明亮的金币音","duration":0.2,"candidateCount":1}
+playcraft audio source create --request short-sound-request.json --request-id <stable-request-id>
+playcraft assets get <taskId>
+playcraft assets wait <taskId>
+playcraft audio source inspect --task <taskId> --candidate <candidateId>
+
+# duration 是秒；volume 是主增益；pitch 是半音；brightness 是滤波截止频率倍数。
+playcraft audio source edit --task <taskId> --candidate <candidateId> \
+  --revision <candidateRevision> --hash <sourceContentHash> --request-id <stable-edit-id> \
+  --macro duration --value 0.15
+playcraft audio source render --task <taskId> --candidate <candidateId> \
+  --revision <newRevision> --hash <newSourceContentHash> --request-id <stable-render-id>
+
+# 用户明确采用后才保存到工程；替换已有目标还须其真实修订和摘要。
+playcraft audio source adopt --task <taskId> --candidate <candidateId> \
+  --revision <candidateRevision> --hash <sourceContentHash> --request-id <stable-adopt-id> \
+  --output source/audio/coin.pcaudio.json --destination-revision 0
+playcraft audio source inspect --path source/audio/coin.pcaudio.json
+```
+
+这些命令使用同一工作区素材任务。候选身份是任务、候选、修订与源内容摘要；工程源身份是工作区、目录、路径、修订与摘要。保存完整源用 `edit/save --document <file>`，只改简单目标用 `--macro`。每次保存后重新渲染才获得对应试听。所有写命令都要求稳定 `--request-id`；响应不确定时使用原身份恢复，不重复生成。`assets download` 不会把参数候选伪装成音频文件，请走专用采用。
+
+接收 `composer.context.audio` 时先核对目录与精确版本，并保留 `selection`、`lockedVoiceIds`、`preserveTargets`。将保护项传给 `edit/save --locked-voices <逗号分隔声部> --preserve-targets <逗号分隔参数目标>`。锁定和曲线不可静默重置。`intent: propose` 只授权提出可比较方向；明确修改并保存才写入原目标；用于游戏需要接入授权。修订冲突表示用户已有新修改，保留结果供比较，不能刷新基准后覆盖。
+
+保存、试听就绪、实际引用、构建通过分别记录。`pending`、`failed`、`cancelled` 和 `render_peak_exceeded` 不能宣称完成；峰值超限时保留原源、说明需调整增益，不静默归一化。候选修改不会自动采用，收起精细视图也不能丢失源字段。
+
+用于游戏时读取采用回执的 `representation.modulePath`，其中 `sound.mjs` 与运行时、源和试听均是不可变包内相对引用。定位用户指定事件的实际调用点，或沿已有绑定替换；保存旧调用和绑定后，导入 `createSound`，在该交互中调用 `play()`，场景销毁调用 `dispose()`。共享播放器最多 8 个实例、32 个声部；播放需浏览器交互解锁，按工程既有方式处理失败。随后执行工程原有构建验证；没有明确调用点时保持待接入，不猜测事件映射。
+
+```javascript
+import { createSound } from '<representation.modulePath 相对当前模块的路径>';
+const coinSound = createSound();
+// 放入用户指定的金币事件处理器；按项目方式处理播放失败。
+await coinSound.play();
+// 场景销毁：coinSound.dispose();
+```
+
+`playcraft audio source bind --path <source> --revision <revision> --hash <hash> --event <event> --request-id <id>` 只创建固定版本的交接记录，返回 `integration_required`，不能证明代码已引用或构建成功。`rollback --path <source> --revision <current> --hash <hash> --version <historical> --request-id <id>` 追加历史源恢复修订，之后重新渲染。游戏回退还必须恢复旧模块调用及绑定，再次构建；不能只恢复源就宣称游戏回退。
+
+### 可编辑音乐与多轨协作
+
+音乐使用 `format: "playcraft.score"`、`content.kind: "score"` 的 `.pcscore.json`，引擎 `playcraft-webaudio-score@1.0.0`。先核对音乐能力、写权限与渲染就绪。默认让用户描述用途、试听候选，再调速度、整体强弱、乐器和循环；选轨、拍段或音符后才展开细节。符号音高采用 MIDI (Musical Instrument Digital Interface, 乐器数字接口) 音符号；时间是四分音符拍点，速度为 BPM (Beats Per Minute, 每分钟节拍数)，不能混用秒和拍。
+
+```bash
+# music-request.json: {"kind":"audio","representation":"score","category":"bgm","description":"轻快的两轨游戏循环音乐","duration":8,"bpm":120,"loop":true,"candidateCount":1}
+playcraft audio source create --request music-request.json --request-id <stable-create-id>
+playcraft assets wait <taskId>
+playcraft audio source inspect --task <taskId> --candidate <candidateId>
+playcraft audio source edit --task <taskId> --candidate <candidateId> \
+  --revision <revision> --hash <sourceContentHash> --request-id <stable-edit-id> --macro tempo --value 132
+playcraft audio source render --task <taskId> --candidate <candidateId> \
+  --revision <newRevision> --hash <newHash> --request-id <stable-render-id>
+playcraft audio source adopt --task <taskId> --candidate <candidateId> \
+  --revision <newRevision> --hash <newHash> --request-id <stable-adopt-id> --output source/audio/loop.pcscore.json
+```
+
+精细操作使用 `edit --adjustment <file>`：例如 `{"kind":"instrument","instrument":"bell","trackIds":["melody"]}`；或者在读取精确源后 `edit --document <file>` 保存完整源。内置音色限 `piano / bell / bass / pad / sine / drums`，不是外部采样乐器库。最多 8 轨、512 音符、32 并发音符、60 秒和 64 KiB 源；超限、无法表达的特性必须报告，不截断或改成另一种音频。
+
+`composer.context.audio.version:2` 明确 `timeUnit:"beats"`，冻结 `selection.trackIds / noteIds / rangeBeats`、`protection.lockedTrackIds / preserveMelody`。把该选区原样写入工程外临时文档，保存时传 `--selection <file> --locked-tracks <ids> --preserve-melody` 中实际适用的项。只调整鼓轨第 5—8 小节时，按拍号计算精确拍段，保护其余轨和拍段；改变整轨音色、增益、自动化或全局速度会影响范围之外，不能把它当作局部修改。服务器会与可信上下文再次核对，命令自行删掉保护条件不会解除限制。
+
+修订不匹配时保留双方，不自行刷新后覆盖。网页可由用户显式合并没有依赖冲突的轨道或音符；速度、循环、全局混音、同轨音色／自动化及同音符冲突需要比较后重做。候选仍须独立采用，回退仍追加新源修订，游戏引用仍单独恢复。
+
+音乐完整包成员为 `sound.pcscore.json / audition.wav / runtime.mjs / sound.mjs / manifest.json`，只使用回执中的固定模块。`createSound().prepare()` 不默认展开整段音乐采样；`play()` 按乐谱和循环段调度，返回的 `stop()` 或播放器 `stop()/dispose()` 会结束循环并释放资源。场景退出、页面隐藏或切换试听时应调用停止，禁止遗留循环。单次播放可传 `play({loop:false})`；指定段落或轨道试听通过受支持的 `selection` 参数。试听渲染文件本身是完整单次表示，循环起止需随乐谱一起使用。
 
 ### 复用素材与持久化音频任务
 
@@ -199,7 +269,7 @@ playcraft audio info --input assets/audio/bgm/main_theme_loop.mp3
 
 ## 3. 本地音频后处理
 
-所有 `playcraft audio` 子命令**完全本地运行**，无需网络。
+本节文件后处理子命令**完全本地运行**，无需网络；前述 `playcraft audio source` 使用云工作区服务。
 
 ### 3.1 常用处理命令
 
@@ -253,7 +323,7 @@ playcraft audio mix \
 
 ### 3.2 标准音频处理管线
 
-AI 生成后的**必做处理步骤**：
+文件音频生成后的处理步骤：
 
 ```
 SFX 管线：

package/project-templates/threejs/vite.config.ts

@@ -20,7 +20,7 @@ export default defineConfig(({ command }) => ({
     open: true,
   },
   build: {
-    outDir: "dist",
+    outDir: "dist/preview",
     sourcemap: true,
   },
 }));

package/templates/preview-runtime/v1/README.md

@@ -96,6 +96,18 @@ The report also records raw hashes of actual workspace module inputs and known c
 
 The platform embeds its immutable build profile after checking the report. The runtime reads the exact host origin and binding from platform context, validates the build profile, and then completes a real versioned handshake. A build report never declares live capability.
 
+## Declarative level editor
+
+`runtime.mjs` also exports `connectLevelEditorRuntime` and `readLevelEditorPreviewContext`. The level-editor protocol has its own message namespace and does not require registering level arrays as primitive parameter fields. A project can support parameters, level editing, or both.
+
+Declare `levelEditor: {version: 1, definition: '<actual-definition-path>'}` beside `previewRuntime`. The definition's `preview.entry` and `preview.adapter` name real development files. A level-only project can omit `parameters`; retain the actual `previewRuntime` entry and build settings. Invoke the build through the platform so its context comes from current source files, rather than constructing a profile manually.
+
+`readLevelEditorPreviewContext()` returns `{binding, parentOrigin}` from the immutable build stamp and authorized host context. Pass those to `connectLevelEditorRuntime({...context, commands: [<actual-command-identifiers>], adapter})`. The adapter implements `enterEdit(context)`, `loadLevel(context)`, `afterRender(context)` and `dispose()`. Each load context contains the author `documents`, stable `selection`, `draftRevision`, `mode` and abort `signal`.
+
+Use the production game's real resolver and level loading in those callbacks. Keep authored initial data separate from playtest state; stop obsolete instances and wait for a real frame before acknowledging application. Declaring a command or returning from an empty callback does not establish that the game consumed the data. The platform separately records saved data, successful build, capability handshake and applied snapshots.
+
+The checked development build receives `script#playcraft-level-editor-profile` containing the actual editor identity and execution contract. A historical build retains its own contract and cannot receive edits for changed game code. Ordinary data edits can reuse a compatible build; changes to code or integration need a new development build. Keep the development entry, runtime and profile outside production output using the guard below.
+
 ## Independent production build
 
 Keep the original production entry and output under `dist/`. Never import the preview entry or runtime from production.