playcanvas-agent-bridge-cli 0.6.1 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/README.md +148 -31
  2. package/README.zh-CN.md +137 -33
  3. package/dist/cli.js +514 -95
  4. package/dist/config.js +23 -1
  5. package/dist/daemon/server.js +336 -28
  6. package/dist/daemon/target-registry.js +3 -0
  7. package/dist/plugins/host.js +260 -0
  8. package/dist/plugins/store.js +567 -0
  9. package/dist/processing/manager.js +265 -0
  10. package/dist/processing/tools.js +97 -0
  11. package/dist/snippets.js +27 -0
  12. package/dist/updates.js +475 -0
  13. package/dist/workspace/json-sync.js +821 -0
  14. package/dist/workspace/manager.js +1973 -326
  15. package/extension/icons/icon-128.png +0 -0
  16. package/extension/icons/icon-16.png +0 -0
  17. package/extension/icons/icon-256.png +0 -0
  18. package/extension/icons/icon-32.png +0 -0
  19. package/extension/icons/icon-48.png +0 -0
  20. package/extension/isolated.js +59 -2
  21. package/extension/main.js +770 -275
  22. package/extension/manifest.json +60 -10
  23. package/extension/popup.html +115 -3
  24. package/extension/popup.js +398 -14
  25. package/extension/service-worker.js +221 -4
  26. package/package.json +18 -18
  27. package/plugins/index.json +14 -0
  28. package/plugins/tinyapp-builder/node/builder.js +589 -0
  29. package/plugins/tinyapp-builder/node/index.js +30 -0
  30. package/plugins/tinyapp-builder/package.json +13 -0
  31. package/plugins/tinyapp-builder/page/editor.js +249 -0
  32. package/plugins/tinyapp-builder/pcbridge-plugin.json +28 -0
  33. package/skills/claude/pcbridge-plugin-authoring/SKILL.md +220 -0
  34. package/skills/claude/playcanvas-agent-bridge-cli/SKILL.md +99 -43
  35. package/skills/codex/pcbridge-plugin-authoring/SKILL.md +220 -0
  36. package/skills/codex/pcbridge-plugin-authoring/agents/openai.yaml +4 -0
  37. package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +89 -62
  38. package/skills/cursor/pcbridge-plugin-authoring.mdc +221 -0
  39. package/skills/cursor/playcanvas-agent-bridge-cli.mdc +69 -33
  40. package/skills/windsurf/pcbridge-plugin-authoring.md +215 -0
  41. package/skills/windsurf/playcanvas-agent-bridge-cli.md +68 -33
  42. package/dist/builder/manager.js +0 -564
@@ -41,22 +41,27 @@ project-picker and scene Editor navigations; change the remembered mode only thr
41
41
 
42
42
  ## Updating pcbridge
43
43
 
44
- Treat the CLI/daemon, installed agent skill, generated Chrome extension, and custom Editor frontend
45
- as separate components. When the user asks to update pcbridge:
46
-
47
- 1. Record the current workspace root from `pcbridge daemon status`.
48
- 2. Run `npm install -g playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, and reinstall
49
- copied skills with `pcbridge install-skill --agent all`.
50
- For a custom or project-local parent directory, use
51
- `pcbridge install-skill --agent <one-agent> --path <parent-directory>`; `--path` appends the
52
- standard artifact name and cannot be combined with `--agent all`.
53
- 3. Run `pcbridge install-extension --no-open`. The user must click **Reload** for PlayCanvas Agent
54
- Bridge in `chrome://extensions` and refresh open Editor/Launch tabs; rewriting the unpacked
55
- directory is not enough.
56
- 4. Run `pcbridge daemon restart --workspace <original-root>` and verify with `pcbridge doctor`.
57
- When migrating from a daemon version without authenticated shutdown, ask the user to stop that
58
- old daemon once with Ctrl+C, then start the updated daemon with the same `--workspace` value.
59
- 5. Update the independently published Editor build with `pcbridge frontend update`, then verify
44
+ CLI responses attach `meta.updates` whenever cached checks find a newer `pcbridge` release on npm,
45
+ local CLI/daemon/extension version drift, or outdated installed plugins. Check or apply updates with:
46
+
47
+ ```bash
48
+ pcbridge update status --refresh # inspect core + plugin update availability
49
+ pcbridge update # one-click update CLI, skills, Chrome extension, tabs, and daemon
50
+ pcbridge update --plugins # update pcbridge core and all outdated plugins together
51
+ pcbridge plugin update <id> # hot-update a single plugin without restarting daemon or refreshing tabs
52
+ pcbridge plugin update --all # hot-update all outdated installed plugins
53
+ ```
54
+
55
+ 1. `pcbridge update` upgrades the global package (when not running from a git source checkout),
56
+ rewrites `~/.pcbridge/extension`, refreshes previously installed agent skills, triggers
57
+ `chrome.runtime.reload()` + open PlayCanvas tab refresh (pass `--no-reload-tabs` to skip tab
58
+ refresh), and restarts the running daemon in-place while preserving its `--workspace` root.
59
+ Users can also click **Update & Reload** in the Chrome extension popup banner, or **Update** /
60
+ **Update all** in the popup **Plugins** tab.
61
+ 2. Official plugins track the remote `plugins/index.json` catalog on GitHub independently of CLI
62
+ releases. `pcbridge plugin list --refresh` shows `version`, `latestVersion`, `updateAvailable`,
63
+ and `compatible`.
64
+ 3. Update the independently published Editor build with `pcbridge frontend update`, then verify
60
65
  `frontend status`. A frontend-only update does not require daemon restart, but the user must
61
66
  refresh the Editor tab and select **Use custom frontend** in the popup when currently in official
62
67
  mode.
@@ -69,21 +74,26 @@ steps have been acknowledged or verified.
69
74
  1. Run `pcbridge targets`. Use `editor:<sceneId>` for Editor writes and `launch:<sceneId>` for
70
75
  runtime verification; use `tab:<id>` when either selector is ambiguous.
71
76
  2. Run `pcbridge workspace status --target editor:<sceneId>`. Do not write while it reports a conflict or sync error.
72
- 3. Use layered help to load only the command group you need: `pcbridge help`, then `pcbridge help core|workspace|frontend|target|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
73
- 4. Edit asset file contents locally under the selected project's `assets/` tree and let the daemon synchronize them. Keep temporary files, manifests, and captures under `tmp/`, which is not synchronized.
74
- 5. Use structured commands for scene structure and non-file Asset operations that map cleanly to one Editor action.
75
- 6. Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, Launch runtime debugging, and large multi-step scene edits where one script is clearer than many CLI calls.
76
- 7. Return compact JSON from snippets. Never return raw `editor`, `Entity`, `Asset`, `entities.root`, or app objects.
77
- 8. Use PlayCanvas history options for writes when available and verify writes with a read-only command.
77
+ 3. **Inspect local files first (0 RPC)** to understand the project before calling Editor RPCs:
78
+ - Read `pcbridge.project.json` for `scenes[]` (active/writable vs inactive/read-only), full asset IDs, paths, and lazy binary `meta` (texture dimensions/format, model/audio summaries).
79
+ - Read `scenes/<name>.<sceneId>.scene.json` (DFS-ordered `entities` + `settings`) and search `scenes/` + `assets/` with `rg` to trace entities, script attachments, `<name>.material.json`, `<name>.template.json`, scripts, and shaders across the entire project.
80
+ 4. Use layered help to load only the command group you need: `pcbridge help`, then `pcbridge help core|workspace|plugin|processing|import|frontend|target|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
81
+ 5. **Choose the right write path** (never mix local file edits and CLI write RPCs on the same target concurrently):
82
+ - **Edit local files** under `assets/` and `scenes/` for scripts, shaders, CSS/HTML/JSON/text, `<name>.material.json` / `<name>.template.json` / other `*.<type>.json` structured assets (including batch edits and creating new `*.<type>.json` files), file renames/moves, and ordinary property or entity edits in the **active** `.scene.json` (`"$pcbridge": { "active": true }`).
83
+ - **Use structured CLI commands** for Editor-specific pipelines: `scene open` (required before editing an inactive read-only scene), `template instantiate`, `template create --entity-id`, `template overrides`, `template apply` / `apply-many` (never hand-edit `template_ent_ids`), `script parse`, `import submit/wait`, `viewport focus/capture`, and `launch` diagnostics/logs.
84
+ 6. Keep temporary files, manifests, and captures under `tmp/`, which is never synchronized.
85
+ 7. Use `pcbridge eval` for exploratory Editor/Engine API inspection, Launch runtime debugging (`runtimeApp`), and custom Editor workflows not covered by local projections or structured commands.
86
+ 8. Return compact JSON from snippets. Never return raw `editor`, `Entity`, `Asset`, `entities.root`, or app objects.
78
87
 
79
88
  ## Workspace
80
89
 
81
90
  ```text
82
91
  <workspace root>/<projectId>-<projectName>/
83
- pcbridge.project.json # project metadata and agent-readable asset catalog
84
- assets/ # collision-safe projection of the PlayCanvas folder tree
85
- tmp/ # agent files, builds, cache, conflicts, captures, and deletion quarantine; never synchronized
86
- .pcbridge/ # internal sync state and object cache; do not edit
92
+ pcbridge.project.json # project metadata, scenes list, and agent-readable asset catalog (with meta summaries)
93
+ scenes/ # active writable .scene.json plus read-only (0o444) mirrors of inactive scenes
94
+ assets/ # collision-safe projection of the PlayCanvas folder tree (text, *.<type>.json, pulled binaries)
95
+ tmp/ # agent files, builds, conflicts, captures, and local/remote deletion trash; never synchronized
96
+ .pcbridge/ # internal sync state, 3-way JSON baselines, and object cache; do not edit
87
97
  ```
88
98
 
89
99
  Use:
@@ -91,20 +101,24 @@ Use:
91
101
  ```bash
92
102
  pcbridge workspace status --target editor:<sceneId>
93
103
  pcbridge workspace path --target editor:<sceneId>
104
+ pcbridge workspace settings [--eager-max-mb <1..10>]
94
105
  pcbridge workspace sync --target editor:<sceneId>
95
106
  pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
96
107
  ```
97
108
 
98
- Prefer local file operations for file-backed Assets:
109
+ Synchronization is event-driven via WebSocket `workspace:delta` pushes and targeted local `fs.watch` dirty paths (zero idle polling):
99
110
 
100
- - Edit existing scripts directly under `assets/`; the watcher uploads them to PlayCanvas.
101
- - Create files and folders under `assets/` to upload them into the matching remote folder. Let PlayCanvas infer and process the Asset type.
102
- - Rename or move a local file to rename or move the same remote Asset ID.
103
- - Deleting a local file only removes the local lazy cache. It does not delete the remote Asset; use `pcbridge asset delete --id <id>` only when remote deletion is explicitly intended.
104
- - Scripts are downloaded eagerly. Binary files are lazy; run `workspace pull --asset <id>` before modifying a remote binary that is not present locally.
105
- - PlayCanvas-generated derivatives such as GLB Model/Container/material outputs and font atlases are lazy, read-only projections. Edit the source Asset, not a derivative. A local derivative edit or move is quarantined under `tmp/conflicts/`, restored from `.pcbridge/objects`, and never uploaded.
111
+ - **Tier 1 (Eager bidirectional)**: Text assets (`script`, `text`, `json`, `html`, `css`, `shader`) and structured JSON data assets (`material`, `template`, `cubemap`, `sprite`, `animstategraph`, `bundle`, projected as `<name>.<type>.json`) up to the direct-sync limit (**default `2 MB`**, adjustable **`1–10 MB`** via the extension popup **Direct sync limit** slider or `pcbridge workspace settings --eager-max-mb <1..10>`) are downloaded automatically and synced bidirectionally.
112
+ - **Scenes (`scenes/<name>.<sceneId>.scene.json`)**: `entities` are ordered in hierarchy DFS pre-order. The open Editor scene has `"$pcbridge": { "id": "...", "kind": "scene", "active": true }` (`0o644` writable); adding/removing entities locally reconciles `parent <-> children` automatically. Inactive scenes have `"$pcbridge": { "id": "...", "kind": "scene", "active": false, "readonly": true }` (`0o444` read-only) — inspect them freely with `rg`, and run `pcbridge scene open --target editor:<currentSceneId> --id <targetSceneId>` before editing one.
113
+ - **Property-path 3-way merge**: Structured JSON assets and the active `.scene.json` merge against `.pcbridge/baselines/` at property/entity granularity, so non-overlapping local and Editor edits merge automatically without false whole-file conflicts. True same-path conflicts write `.local`, `.remote`, and `.conflict.json` under `tmp/conflicts/`.
114
+ - **Create, rename, and move locally**: Creating files under `assets/` (including new `<name>.material.json` or other `*.<type>.json` files without an ID) creates matching remote folders and Assets and writes back `$pcbridge.id`. Renaming or moving local files preserves the remote Asset ID via `$pcbridge.id`, file inode, or content hash (even when renamed and edited together).
115
+ - **Tier 2 (Lazy binary / over-limit files)**: Images, models, audio, fonts, binaries, and files above `eagerMaxMb` record metadata, dimensions, and MD5 in `pcbridge.project.json` without downloading bytes. Run `workspace pull --asset <id>` before modifying a missing binary locally.
116
+ - **Deletion semantics (important distinction)**:
117
+ - Deleting a local **Tier 1** eagerly synced file (in-limit text/script/shader or `*.<type>.json`) **backs it up under `tmp/trash/local/` AND deletes the remote PlayCanvas Asset** to keep both sides consistent. Delete Tier 1 files only when remote deletion is intended.
118
+ - Deleting a locally pulled **Tier 2** lazy binary (or over-limit file) only evicts the local cache without deleting the remote Asset; use `pcbridge asset delete --id <id>` to delete a remote Tier 2 Asset.
119
+ - **Derived assets**: Binary derivatives (`source_asset_id != null` with a file, such as GLB `container`/`model` outputs and generated font atlases) remain lazy and read-only (`0o444`); local edits are quarantined to `tmp/conflicts/` and restored. Structured JSON assets linked to a source model (such as FBX/GLB-imported `material` files) **are writable (`0o644`)** and sync bidirectionally while keeping `$pcbridge.sourceAssetId` for provenance.
106
120
 
107
- After a local edit, allow the watcher to react, then poll `workspace status` until it reports
121
+ After a local edit, allow ~0.5–1s for the watcher debounce to flush, then check `workspace status` until it reports
108
122
  `synced`. A brief yellow `local-change` is expected. Do not declare completion or alternate to
109
123
  remote editing while the same file is pending. If it does not converge, run one explicit
110
124
  `workspace sync`, inspect `lastError`, `lastWarning`, and `tmp/conflicts/`, and do not overwrite
@@ -116,23 +130,32 @@ Only collision paths gain `.__pc_<type>_<assetId>`. The catalog is managed by pc
116
130
  to request remote asset operations. Confirmed remote deletions are quarantined under
117
131
  `tmp/trash/remote/`; `tmp/conflicts/` is reserved for divergent local and remote contents.
118
132
 
119
- Selecting a Template Asset exposes **pcbridge Tiny Builder** in the Attributes panel. It collects
133
+ Optional features ship as plugins that each user adds and enables. Run `pcbridge plugin list` to
134
+ see installed plugins, their actions, and the official plugins available to add; call an action with
135
+ `pcbridge plugin call <id> <action> --target editor:<sceneId> --params '<json>'`. The extension
136
+ popup **Plugins** tab manages the same list. To create or change a plugin, use the
137
+ `pcbridge-plugin-authoring` skill.
138
+
139
+ Tiny Builder is the official `tinyapp-builder` plugin (`pcbridge plugin add tinyapp-builder`). While
140
+ it is enabled, selecting a Template Asset exposes **pcbridge Tiny Builder** in the Attributes panel. It collects
120
141
  dependencies, materializes missing or remote-updated primary files, texture variants, and additional
121
142
  font maps under `assets/`, then uploads individual S3 objects without a ZIP. `local.resources` in the
122
143
  schema-v3 manifest identifies managed read-only auxiliary files; `.pcbridge/objects` is only the
123
144
  internal content cache. Project `.env` overrides workspace-root `.env`; never read or return
124
145
  credential values. CLI equivalents are
125
- `pcbridge builder start --target editor:<sceneId> --asset <id>` and
126
- `pcbridge builder status --job <jobId>`.
146
+ `pcbridge plugin call tinyapp-builder start --target editor:<sceneId> --params '{"templateAssetId":"<id>"}'` and
147
+ `pcbridge plugin call tinyapp-builder status --params '{"jobId":"<jobId>"}'`.
127
148
 
128
149
  Local file arguments are restricted to the selected project workspace. Never use
129
150
  `--allow-external-path` unless the user explicitly asks to use a known external file.
130
151
 
131
152
  ## Safe Commands
132
153
 
133
- Inspect a scene:
154
+ Prefer reading local `pcbridge.project.json`, `scenes/*.scene.json`, and `assets/` first for static inspection. Use CLI commands when you need live Editor/Launch state, pipeline actions, or single targeted RPC mutations:
134
155
 
135
156
  ```bash
157
+ pcbridge scene list --target editor:<sceneId>
158
+ pcbridge scene open --target editor:<sceneId> --id <otherSceneId>
136
159
  pcbridge eval --target editor:<sceneId> --code "return { href: location.href, hasEditor: !!editor, entityCount: editor.api.globals.entities.list().length }"
137
160
  ```
138
161
 
@@ -175,25 +198,24 @@ Use exactly one of `--asset-id` and `--script-name`. The name form is for a Scri
175
198
  by a bundle or runtime asset and therefore lacking a standalone script asset id. Verify such a
176
199
  script in Launch; explicit script reordering is not yet a dedicated command.
177
200
 
178
- Work with asset metadata, explicit transfers, and script verification. For ordinary file-content
179
- edits, prefer editing the tracked local file under `assets/` over `script set-text` or re-uploading it:
201
+ Work with asset pipelines, explicit transfers, and script verification. For ordinary script/shader/text or `*.material.json` / `*.template.json` content edits, prefer editing the tracked local file under `assets/` over CLI `patch` / `set-text` or re-uploading:
180
202
 
181
203
  ```bash
182
204
  pcbridge asset list --target editor:<sceneId> --type script --limit 50
183
205
  pcbridge asset create --target editor:<sceneId> --json ./assets.json
184
- pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
185
- pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
206
+ pcbridge asset folder ensure --target editor:<sceneId> --path "My Task/Textures"
207
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "My Task/Textures"
186
208
  pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
187
209
  pcbridge asset instantiate --target editor:<sceneId> --id <template_asset_id>
188
- pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
210
+ pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "My Task/Materials" --diffuse-map <texture_asset_id>
189
211
  pcbridge material patch --target editor:<sceneId> --asset-id <material_asset_id> --set diffuse='[1,0,0]'
190
- pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
212
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "My Task/Templates"
191
213
  pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
192
214
  pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
193
215
  pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
194
216
  pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
195
- pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
196
- pcbridge script create --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts"
217
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "My Task/Scripts" --parse --wait
218
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "My Task/Scripts"
197
219
  pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./controller.js --parse --wait
198
220
  pcbridge script parse --target editor:<sceneId> --asset-id <id>
199
221
  ```
@@ -247,16 +269,16 @@ authoritative.
247
269
 
248
270
  ## Asset Organization
249
271
 
250
- Create synchronized files directly under a task-scoped path in the project `assets/` tree. Keep
251
- intermediate or disposable generation files under `tmp/` so the watcher does not upload them:
272
+ Before creating asset folders, inspect the project's existing directory tree and comparable
273
+ resources. Prefer reusing suitable folders and follow the project's naming language, casing,
274
+ separators, hierarchy, and resource grouping when new folders are needed. Organize related assets
275
+ by task or feature within that structure; if the project groups by resource type first, preserve
276
+ that layout rather than imposing a task-first hierarchy. Do not create an `AI Agent Bridge` folder
277
+ by default. If no convention exists, use a descriptive task folder with resource subfolders as needed.
252
278
 
253
- ```text
254
- assets/AI Agent Bridge/<task name>/Textures
255
- assets/AI Agent Bridge/<task name>/Models
256
- assets/AI Agent Bridge/<task name>/Scripts
257
- ```
258
-
259
- Use stable names that describe the asset purpose. Avoid dumping generated files at the project root.
279
+ Keep final file-backed assets in the project `assets/` tree and intermediate or disposable files
280
+ under `tmp/<task name>/` so the watcher does not upload them. Paths in command examples are
281
+ illustrative; adapt them to the project's existing conventions before creating folders.
260
282
 
261
283
  ## Large Task Workflow
262
284
 
@@ -264,11 +286,11 @@ For multi-asset or game-sized tasks:
264
286
 
265
287
  1. Choose an explicit target from `pcbridge targets`, preferably `editor:<sceneId>` for writes or
266
288
  `launch:<sceneId>` for tests; use `tab:<id>` to resolve ambiguity.
267
- 2. Confirm `workspace status` is `synced`. Put disposable generation inputs under `<project>/tmp/<task name>/`.
268
- 3. Put final scripts, textures, models, audio, and other file-backed Assets under `<project>/assets/AI Agent Bridge/<task name>/...`; create or edit them locally and wait for synchronization.
289
+ 2. Confirm `workspace status` is `synced`. Inspect `pcbridge.project.json`, `scenes/*.scene.json`, and `assets/` locally with `rg` to understand existing hierarchy, conventions, and asset IDs without extra RPC traffic. Put disposable generation inputs under `<project>/tmp/<task name>/`.
290
+ 3. Follow existing folder naming and hierarchy. Group new resources within that convention, reuse suitable folders, and create or edit scripts, shaders, `*.material.json` files, and assets locally under `<project>/assets/`; wait for `workspace status` to reach `synced`.
269
291
  4. Use `asset upload-many` only when explicit upload settings or a non-watched source path is required. Do not upload a file again when it is already tracked under `assets/`.
270
292
  5. For an existing script, edit its local file. Use `script parse` after synchronization when parse verification is needed; reserve `script upsert --parse --wait` for recovery or workflows that intentionally bypass the mirror.
271
- 6. Use `pcbridge eval --target editor:<sceneId> --file ./install.js --args-json ./args.json --timeout-ms 120000` for large scene installation scripts. The JSON object is available as `command.args`; increase `--timeout-ms` instead of splitting a coherent install script just to avoid the default 15s timeout.
293
+ 6. For active scene edits, either edit `scenes/<name>.<sceneId>.scene.json` directly (ideal for multi-entity/property tuning with 3-way merge) or use structured `entity` / `template` commands (or `pcbridge eval --target editor:<sceneId> --file ./install.js --args-json ./args.json --timeout-ms 120000` for procedural Editor setup). Do not edit `.scene.json` and run scene-mutating RPCs at the exact same instant.
272
294
  7. Wait for `workspace status` to become `synced`, then verify with read-only commands, a small smoke-test eval, and a capture under `<project>/tmp/captures/`.
273
295
 
274
296
  If repeated manual glue is needed across tasks, improve the CLI or this skill rather than continuing to hand-roll brittle shell/script sequences.
@@ -291,10 +313,10 @@ That verification is limited to the current Editor observer and does not prove r
291
313
  For a textured scripted box, compose structured commands instead of writing one large eval:
292
314
 
293
315
  ```bash
294
- pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/Texture Box/Textures"
295
- pcbridge asset upload --target editor:<sceneId> --file ./image.png --name TextureBoxImage --folder "AI Agent Bridge/Texture Box/Textures"
296
- pcbridge material create --target editor:<sceneId> --name TextureBoxMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
297
- pcbridge script create --target editor:<sceneId> --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
316
+ pcbridge asset folder ensure --target editor:<sceneId> --path "Texture Box/Textures"
317
+ pcbridge asset upload --target editor:<sceneId> --file ./image.png --name TextureBoxImage --folder "Texture Box/Textures"
318
+ pcbridge material create --target editor:<sceneId> --name TextureBoxMaterial --folder "Texture Box/Materials" --diffuse-map <texture_asset_id>
319
+ pcbridge script create --target editor:<sceneId> --filename jumpingBox.js --file ./jumpingBox.js --folder "Texture Box/Scripts"
298
320
  pcbridge entity create --target editor:<sceneId> --json ./box.json
299
321
  pcbridge entity set-material --target editor:<sceneId> --id <box_resource_id> --material-id <material_asset_id>
300
322
  pcbridge entity add-script --target editor:<sceneId> --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
@@ -339,3 +361,8 @@ return entities.slice(0, 20).map((entity) => ({
339
361
  ```
340
362
 
341
363
  Avoid destructive operations unless the user clearly asked for them. When deleting or overwriting, require explicit stable IDs and report affected counts.
364
+
365
+
366
+ ## Self-hosted local processing
367
+
368
+ Use `pcbridge help processing` and `pcbridge help import` for self-hosted conversion. Diagnose with `processing status --target editor:<sceneId>`; tools require explicit installation and `processing enable`. Do not enable local conversion on official targets. Use `import submit --asset <id> --kind model|texture --json options.json`, then `import wait --job <id> --sync-workspace`. Server `complete` means published; workspace synchronization is separate and keeps binary lazy loading. On a wait timeout query the same job before repeating a write. Browser authentication, leases and signed URLs must never be copied into CLI arguments. Extension source upgrades require regenerating the unpacked extension, reloading it in Chrome and refreshing target pages. Custom host permissions are granted by the user through the popup.
@@ -0,0 +1,221 @@
1
+ ---
2
+ description: Create, test, and manage pcbridge plugins for PlayCanvas Editor and Launch from Cursor.
3
+ globs:
4
+ alwaysApply: false
5
+ ---
6
+
7
+ # pcbridge Plugin Authoring
8
+
9
+ A pcbridge plugin is an optional package that users add, enable, disable, and remove
10
+ independently. It is **not** the Chrome extension: the extension is a fixed part of pcbridge,
11
+ while plugins are loaded by the pcbridge daemon and delivered to pages through that extension.
12
+ Different users enable different plugins (a modeller's Blender sync, a programmer's Editor
13
+ buttons), so never add plugin features to pcbridge core or to the extension source.
14
+
15
+ ## Where plugin code runs
16
+
17
+ | Runtime | Entry in the manifest | Runs in | Use it for |
18
+ | --- | --- | --- | --- |
19
+ | node | `node` | The local pcbridge daemon (Bun) | Files, network, credentials, child processes, local apps (Blender, DCC tools), heavy work |
20
+ | page | `page.editor`, `page.launch` | The PlayCanvas Editor / Launch page (MAIN world) | Editor UI, `editor.api.globals` reads and writes, runtime inspection |
21
+ | extension | none | Isolated world, service worker, popup | Not extensible. It only relays messages and hosts the **Plugins** management tab |
22
+
23
+ Plugins cannot ship code into the extension runtime: Manifest V3 forbids running code that is not
24
+ packaged with the extension, and that runtime holds the daemon session token. A page script
25
+ therefore has no `chrome.*` API and no token; anything privileged goes through a node action.
26
+
27
+ ```text
28
+ pcbridge plugin call <id> <action> ─┐
29
+ page: plugin.call(action, params) ─┴─> node: plugin.handle(action, fn)
30
+ node: plugin.callPage(target, name, params) ──> page: plugin.handle(name, fn)
31
+ ```
32
+
33
+ ## Package layout
34
+
35
+ ```text
36
+ my-plugin/
37
+ pcbridge-plugin.json # manifest (required)
38
+ node/index.js # optional node entry
39
+ page/editor.js # optional Editor page script
40
+ page/launch.js # optional Launch page script
41
+ package.json # optional; only when the node side has npm dependencies
42
+ ```
43
+
44
+ `pcbridge-plugin.json`:
45
+
46
+ ```json
47
+ {
48
+ "id": "my-plugin",
49
+ "name": "My Plugin",
50
+ "version": "1.0.0",
51
+ "apiVersion": 1,
52
+ "minPcbridgeVersion": "0.7.0",
53
+ "description": "One sentence shown in plugin lists.",
54
+ "node": "node/index.js",
55
+ "page": { "editor": "page/editor.js", "launch": "page/launch.js" },
56
+ "actions": {
57
+ "export": {
58
+ "description": "What the action does and returns.",
59
+ "params": { "assetId": "Asset id (required).", "format": "glb or fbx; default glb." }
60
+ }
61
+ }
62
+ }
63
+ ```
64
+
65
+ Manifest rules:
66
+
67
+ - `id`: 2-49 characters, lowercase letters, digits, and hyphens. It names the plugin in the CLI,
68
+ in RPC routes, and in the install directory; never change it after release.
69
+ - `name`, `version` (semantic version), and `apiVersion: 1` are required.
70
+ - `minPcbridgeVersion` (optional semantic version) declares the minimum `pcbridge` core version required to install or update this plugin.
71
+ - At least one of `node`, `page.editor`, `page.launch` is required. Every entry is a relative path
72
+ to an existing file inside the plugin directory.
73
+ - `actions` documents the node actions for other agents (`pcbridge plugin info <id>`). Keep it in
74
+ step with the `plugin.handle` calls in the node entry.
75
+ - Bump `version` on every released change.
76
+
77
+ ## Node entry
78
+
79
+ An ES module (JavaScript or TypeScript; the daemon runs on Bun) that exports `activate(plugin)`.
80
+ `activate` may be async. It runs when the daemon starts and whenever the plugin is added, enabled,
81
+ updated, or reloaded.
82
+
83
+ ```js
84
+ export function activate(plugin) {
85
+ plugin.handle("export", async (params, { target }) => {
86
+ if (!target || target.kind !== "editor") throw new Error("export requires an Editor target.");
87
+ const selection = await plugin.callPage(target, "selection");
88
+ return { exported: selection.length };
89
+ });
90
+ const timer = setInterval(() => { /* ... */ }, 5000);
91
+ plugin.onDispose(() => clearInterval(timer));
92
+ }
93
+ ```
94
+
95
+ | Member | Purpose |
96
+ | --- | --- |
97
+ | `plugin.id`, `plugin.version`, `plugin.dir` | Identity and the absolute plugin directory |
98
+ | `plugin.handle(name, fn)` | Register an action. `fn(params, { target })` returns JSON-serializable data or throws an `Error` (an optional string `code` becomes the CLI error code) |
99
+ | `plugin.callPage(target, name, params?, timeoutMs?)` | Call a handler registered by this plugin's page script; resolves with its result |
100
+ | `plugin.rpc(target, method, params?, timeoutMs?)` | Call a built-in bridge method, for example `bridge:eval` with `{ code, args }` |
101
+ | `plugin.targets()` | Connected targets (`id`, `kind`, `ready`, `projectId`, `sceneId`, ...) for node-initiated work |
102
+ | `plugin.workspace.rootDir` | The daemon workspace root |
103
+ | `plugin.workspace.status(target)` | Workspace status, including `projectDirectory` and `tmpDirectory` |
104
+ | `plugin.workspace.prepareAssetFiles(target, assetIds)` | Materialize asset files locally; returns `{ projectDirectory, tmpDirectory, assets: [{ id, name, type, filename, path, hash }] }` |
105
+ | `plugin.workspace.prepareAssetResources(target, requests)` | Materialize auxiliary files such as texture variants: `[{ assetId, filename, url, hash? }]` |
106
+ | `plugin.log(message)` | Write to the daemon log |
107
+ | `plugin.onDispose(fn)` | Register cleanup; runs on disable, remove, reload, update, and daemon stop |
108
+
109
+ `target` in an action context is the `--target` of the CLI call, the calling tab for a page call,
110
+ otherwise the most recent ready target, otherwise `null`. Functions that take a target accept that
111
+ object or a selector string such as `tab:5` or `editor:<sceneId>`.
112
+
113
+ ## Page script
114
+
115
+ A single classic script. pcbridge runs its text as the body of an async function once the target
116
+ is ready (Editor: `editor.api.globals` exists; Launch: the app has started in a visible tab), with
117
+ `plugin`, `editor`, `pc`, `pcui`, and `runtimeApp` in scope. `import` and `export` are not
118
+ available; bundle to one file if you need modules.
119
+
120
+ ```js
121
+ const button = new pcui.Button({ text: "Export selection" });
122
+ button.class.add("my-plugin-export");
123
+ editor.call("layout.toolbar").append(button);
124
+ button.on("click", async () => {
125
+ const result = await plugin.call("export", { format: "glb" });
126
+ console.info("[my-plugin] exported", result.exported);
127
+ });
128
+
129
+ plugin.handle("selection", () =>
130
+ editor.api.globals.selection.items.map((item) => String(item.get("resource_id") || item.get("id"))));
131
+
132
+ plugin.onDispose(() => button.destroy());
133
+ ```
134
+
135
+ | Member | Purpose |
136
+ | --- | --- |
137
+ | `plugin.id`, `plugin.version`, `plugin.kind` | Identity; `kind` is `"editor"` or `"launch"` |
138
+ | `plugin.handle(name, fn)` | Register a handler for `plugin.callPage` on the node side; return plain JSON |
139
+ | `plugin.call(action, params?, timeoutMs?)` | Call a node action of the same plugin; the target is this tab |
140
+ | `plugin.onDispose(fn)` | Register cleanup; runs when the plugin is disabled, removed, or its code changes |
141
+
142
+ Enabling, disabling, and reloading take effect in open pages immediately; no page refresh is
143
+ needed. A script whose text is unchanged is not re-run.
144
+
145
+ ## Rules
146
+
147
+ 1. **Split by capability.** Credentials, file paths, and network calls to other services stay in
148
+ node. Page scripts only touch the page. Never send secrets to a page or return them from an
149
+ action.
150
+ 2. **Everything is disposable.** Whatever `activate` or a page script creates (timers, sockets,
151
+ servers, child processes, DOM and pcui elements, event subscriptions via `handle.unbind()`)
152
+ must be undone in `onDispose`. A reload must not leave duplicates.
153
+ 3. **Top level must be fast.** Page activation times out after 10 seconds and `activate` blocks
154
+ other plugin operations; start long work in the background and report it through an action
155
+ such as `status`.
156
+ 4. **Plain JSON across boundaries.** Never return Observers, Entities, DOM nodes, or class
157
+ instances. Pass asset ids and local paths instead of file contents.
158
+ 5. **Catch errors in your own callbacks.** An uncaught exception in a node timer or socket callback
159
+ can stop the daemon. If a plugin prevents the daemon from starting, stop the daemon and run
160
+ `pcbridge plugin disable <id>`; management commands work on disk while the daemon is down.
161
+ 6. **Namespace by plugin id.** CSS classes, `localStorage` keys, and global names start with the id.
162
+ 7. **Feature-detect Editor and Engine APIs** and use `{ history: true }` for Editor mutations when
163
+ available, as in `pcbridge eval` snippets.
164
+ 8. **Declare npm dependencies** in the plugin's own `package.json` `dependencies`. pcbridge runs
165
+ `bun install --production` when the plugin is added or updated. For `--link` plugins run
166
+ `bun install` in the directory yourself. Do not rely on pcbridge's own dependencies.
167
+ 9. Keep plugin source outside any project `assets/` directory; the workspace watcher uploads files
168
+ created there.
169
+
170
+ ## Develop and verify
171
+
172
+ ```bash
173
+ pcbridge plugin add ./my-plugin --link # use the directory in place
174
+ pcbridge plugin list # state must be "active"; read error and pages[]
175
+ pcbridge plugin call my-plugin export --target editor:<sceneId> --params '{"format":"glb"}'
176
+ pcbridge plugin reload my-plugin # after every edit to node or page files
177
+ pcbridge eval --target editor:<sceneId> --code "return !!document.querySelector('.my-plugin-export')"
178
+ pcbridge logs get --target editor:<sceneId> --level error
179
+ ```
180
+
181
+ `plugin list` and `plugin info <id>` report `state` (`active`, `error`, `disabled`, or `stopped`
182
+ when the daemon is not running), the node activation `error`, and one `pages[]` entry per connected
183
+ target with the page script result. Treat a plugin as working only when the state is `active`,
184
+ every `pages[]` entry is `ok`, each action returns the expected data, and the page effect is
185
+ confirmed with `eval` or a viewport capture. `--params-json <file>` reads parameters from a file
186
+ inside the project workspace.
187
+
188
+ Other management commands, also available in the extension popup under **Plugins**:
189
+
190
+ ```bash
191
+ pcbridge plugin enable|disable|remove <id>
192
+ pcbridge plugin update <id> # re-fetch from the recorded source, reinstall dependencies, reload
193
+ pcbridge plugin update --all # update all outdated installed plugins
194
+ pcbridge plugin list --refresh # refresh remote official plugin catalog and versions
195
+ pcbridge help plugin
196
+ ```
197
+
198
+ ## Distribute through GitHub
199
+
200
+ Publish the plugin directory in a public GitHub repository, at the root or in a subdirectory, and
201
+ tag releases. Users install and update with:
202
+
203
+ ```bash
204
+ pcbridge plugin add github:<owner>/<repo> # default branch, plugin at the root
205
+ pcbridge plugin add github:<owner>/<repo>/plugins/my-plugin#v1.2.0 # subdirectory, pinned tag
206
+ pcbridge plugin update my-plugin # same source and ref again
207
+ ```
208
+
209
+ A source without `#ref` follows the default branch, so `update` picks up new commits; a pinned
210
+ `#ref` only changes when the plugin is removed and added again with another ref. Commit built
211
+ output if the plugin needs a build step, because pcbridge installs the repository files as they
212
+ are. Plugins run with full local and page access; tell users to add only sources they trust.
213
+
214
+ ## Reference implementation
215
+
216
+ `tinyapp-builder` is the official plugin shipped with pcbridge (`pcbridge plugin add
217
+ tinyapp-builder`, source under `plugins/tinyapp-builder/` of the pcbridge package). It shows a
218
+ node entry with background jobs and npm dependencies, an Editor page script that injects an
219
+ Inspector panel and serves `callPage` requests, and a complete `actions` section.
220
+ When adding or bumping an official plugin under `plugins/<id>/`, run `bun run plugins:sync` to
221
+ synchronize `plugins/index.json` (`bun run check:version` enforces this).