playcanvas-agent-bridge-cli 0.6.2 → 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.
@@ -0,0 +1,220 @@
1
+ ---
2
+ name: pcbridge-plugin-authoring
3
+ description: Create, test, and manage pcbridge plugins: optional packages that add local Node code to the pcbridge daemon and inject scripts into PlayCanvas Editor or Launch pages. Use when asked to build or change a pcbridge plugin, add Editor UI or tooling through pcbridge, connect a local application such as Blender to PlayCanvas, or add, enable, disable, update, or debug plugins.
4
+ ---
5
+
6
+ # pcbridge Plugin Authoring
7
+
8
+ A pcbridge plugin is an optional package that users add, enable, disable, and remove
9
+ independently. It is **not** the Chrome extension: the extension is a fixed part of pcbridge,
10
+ while plugins are loaded by the pcbridge daemon and delivered to pages through that extension.
11
+ Different users enable different plugins (a modeller's Blender sync, a programmer's Editor
12
+ buttons), so never add plugin features to pcbridge core or to the extension source.
13
+
14
+ ## Where plugin code runs
15
+
16
+ | Runtime | Entry in the manifest | Runs in | Use it for |
17
+ | --- | --- | --- | --- |
18
+ | node | `node` | The local pcbridge daemon (Bun) | Files, network, credentials, child processes, local apps (Blender, DCC tools), heavy work |
19
+ | page | `page.editor`, `page.launch` | The PlayCanvas Editor / Launch page (MAIN world) | Editor UI, `editor.api.globals` reads and writes, runtime inspection |
20
+ | extension | none | Isolated world, service worker, popup | Not extensible. It only relays messages and hosts the **Plugins** management tab |
21
+
22
+ Plugins cannot ship code into the extension runtime: Manifest V3 forbids running code that is not
23
+ packaged with the extension, and that runtime holds the daemon session token. A page script
24
+ therefore has no `chrome.*` API and no token; anything privileged goes through a node action.
25
+
26
+ ```text
27
+ pcbridge plugin call <id> <action> ─┐
28
+ page: plugin.call(action, params) ─┴─> node: plugin.handle(action, fn)
29
+ node: plugin.callPage(target, name, params) ──> page: plugin.handle(name, fn)
30
+ ```
31
+
32
+ ## Package layout
33
+
34
+ ```text
35
+ my-plugin/
36
+ pcbridge-plugin.json # manifest (required)
37
+ node/index.js # optional node entry
38
+ page/editor.js # optional Editor page script
39
+ page/launch.js # optional Launch page script
40
+ package.json # optional; only when the node side has npm dependencies
41
+ ```
42
+
43
+ `pcbridge-plugin.json`:
44
+
45
+ ```json
46
+ {
47
+ "id": "my-plugin",
48
+ "name": "My Plugin",
49
+ "version": "1.0.0",
50
+ "apiVersion": 1,
51
+ "minPcbridgeVersion": "0.7.0",
52
+ "description": "One sentence shown in plugin lists.",
53
+ "node": "node/index.js",
54
+ "page": { "editor": "page/editor.js", "launch": "page/launch.js" },
55
+ "actions": {
56
+ "export": {
57
+ "description": "What the action does and returns.",
58
+ "params": { "assetId": "Asset id (required).", "format": "glb or fbx; default glb." }
59
+ }
60
+ }
61
+ }
62
+ ```
63
+
64
+ Manifest rules:
65
+
66
+ - `id`: 2-49 characters, lowercase letters, digits, and hyphens. It names the plugin in the CLI,
67
+ in RPC routes, and in the install directory; never change it after release.
68
+ - `name`, `version` (semantic version), and `apiVersion: 1` are required.
69
+ - `minPcbridgeVersion` (optional semantic version) declares the minimum `pcbridge` core version required to install or update this plugin.
70
+ - At least one of `node`, `page.editor`, `page.launch` is required. Every entry is a relative path
71
+ to an existing file inside the plugin directory.
72
+ - `actions` documents the node actions for other agents (`pcbridge plugin info <id>`). Keep it in
73
+ step with the `plugin.handle` calls in the node entry.
74
+ - Bump `version` on every released change.
75
+
76
+ ## Node entry
77
+
78
+ An ES module (JavaScript or TypeScript; the daemon runs on Bun) that exports `activate(plugin)`.
79
+ `activate` may be async. It runs when the daemon starts and whenever the plugin is added, enabled,
80
+ updated, or reloaded.
81
+
82
+ ```js
83
+ export function activate(plugin) {
84
+ plugin.handle("export", async (params, { target }) => {
85
+ if (!target || target.kind !== "editor") throw new Error("export requires an Editor target.");
86
+ const selection = await plugin.callPage(target, "selection");
87
+ return { exported: selection.length };
88
+ });
89
+ const timer = setInterval(() => { /* ... */ }, 5000);
90
+ plugin.onDispose(() => clearInterval(timer));
91
+ }
92
+ ```
93
+
94
+ | Member | Purpose |
95
+ | --- | --- |
96
+ | `plugin.id`, `plugin.version`, `plugin.dir` | Identity and the absolute plugin directory |
97
+ | `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) |
98
+ | `plugin.callPage(target, name, params?, timeoutMs?)` | Call a handler registered by this plugin's page script; resolves with its result |
99
+ | `plugin.rpc(target, method, params?, timeoutMs?)` | Call a built-in bridge method, for example `bridge:eval` with `{ code, args }` |
100
+ | `plugin.targets()` | Connected targets (`id`, `kind`, `ready`, `projectId`, `sceneId`, ...) for node-initiated work |
101
+ | `plugin.workspace.rootDir` | The daemon workspace root |
102
+ | `plugin.workspace.status(target)` | Workspace status, including `projectDirectory` and `tmpDirectory` |
103
+ | `plugin.workspace.prepareAssetFiles(target, assetIds)` | Materialize asset files locally; returns `{ projectDirectory, tmpDirectory, assets: [{ id, name, type, filename, path, hash }] }` |
104
+ | `plugin.workspace.prepareAssetResources(target, requests)` | Materialize auxiliary files such as texture variants: `[{ assetId, filename, url, hash? }]` |
105
+ | `plugin.log(message)` | Write to the daemon log |
106
+ | `plugin.onDispose(fn)` | Register cleanup; runs on disable, remove, reload, update, and daemon stop |
107
+
108
+ `target` in an action context is the `--target` of the CLI call, the calling tab for a page call,
109
+ otherwise the most recent ready target, otherwise `null`. Functions that take a target accept that
110
+ object or a selector string such as `tab:5` or `editor:<sceneId>`.
111
+
112
+ ## Page script
113
+
114
+ A single classic script. pcbridge runs its text as the body of an async function once the target
115
+ is ready (Editor: `editor.api.globals` exists; Launch: the app has started in a visible tab), with
116
+ `plugin`, `editor`, `pc`, `pcui`, and `runtimeApp` in scope. `import` and `export` are not
117
+ available; bundle to one file if you need modules.
118
+
119
+ ```js
120
+ const button = new pcui.Button({ text: "Export selection" });
121
+ button.class.add("my-plugin-export");
122
+ editor.call("layout.toolbar").append(button);
123
+ button.on("click", async () => {
124
+ const result = await plugin.call("export", { format: "glb" });
125
+ console.info("[my-plugin] exported", result.exported);
126
+ });
127
+
128
+ plugin.handle("selection", () =>
129
+ editor.api.globals.selection.items.map((item) => String(item.get("resource_id") || item.get("id"))));
130
+
131
+ plugin.onDispose(() => button.destroy());
132
+ ```
133
+
134
+ | Member | Purpose |
135
+ | --- | --- |
136
+ | `plugin.id`, `plugin.version`, `plugin.kind` | Identity; `kind` is `"editor"` or `"launch"` |
137
+ | `plugin.handle(name, fn)` | Register a handler for `plugin.callPage` on the node side; return plain JSON |
138
+ | `plugin.call(action, params?, timeoutMs?)` | Call a node action of the same plugin; the target is this tab |
139
+ | `plugin.onDispose(fn)` | Register cleanup; runs when the plugin is disabled, removed, or its code changes |
140
+
141
+ Enabling, disabling, and reloading take effect in open pages immediately; no page refresh is
142
+ needed. A script whose text is unchanged is not re-run.
143
+
144
+ ## Rules
145
+
146
+ 1. **Split by capability.** Credentials, file paths, and network calls to other services stay in
147
+ node. Page scripts only touch the page. Never send secrets to a page or return them from an
148
+ action.
149
+ 2. **Everything is disposable.** Whatever `activate` or a page script creates (timers, sockets,
150
+ servers, child processes, DOM and pcui elements, event subscriptions via `handle.unbind()`)
151
+ must be undone in `onDispose`. A reload must not leave duplicates.
152
+ 3. **Top level must be fast.** Page activation times out after 10 seconds and `activate` blocks
153
+ other plugin operations; start long work in the background and report it through an action
154
+ such as `status`.
155
+ 4. **Plain JSON across boundaries.** Never return Observers, Entities, DOM nodes, or class
156
+ instances. Pass asset ids and local paths instead of file contents.
157
+ 5. **Catch errors in your own callbacks.** An uncaught exception in a node timer or socket callback
158
+ can stop the daemon. If a plugin prevents the daemon from starting, stop the daemon and run
159
+ `pcbridge plugin disable <id>`; management commands work on disk while the daemon is down.
160
+ 6. **Namespace by plugin id.** CSS classes, `localStorage` keys, and global names start with the id.
161
+ 7. **Feature-detect Editor and Engine APIs** and use `{ history: true }` for Editor mutations when
162
+ available, as in `pcbridge eval` snippets.
163
+ 8. **Declare npm dependencies** in the plugin's own `package.json` `dependencies`. pcbridge runs
164
+ `bun install --production` when the plugin is added or updated. For `--link` plugins run
165
+ `bun install` in the directory yourself. Do not rely on pcbridge's own dependencies.
166
+ 9. Keep plugin source outside any project `assets/` directory; the workspace watcher uploads files
167
+ created there.
168
+
169
+ ## Develop and verify
170
+
171
+ ```bash
172
+ pcbridge plugin add ./my-plugin --link # use the directory in place
173
+ pcbridge plugin list # state must be "active"; read error and pages[]
174
+ pcbridge plugin call my-plugin export --target editor:<sceneId> --params '{"format":"glb"}'
175
+ pcbridge plugin reload my-plugin # after every edit to node or page files
176
+ pcbridge eval --target editor:<sceneId> --code "return !!document.querySelector('.my-plugin-export')"
177
+ pcbridge logs get --target editor:<sceneId> --level error
178
+ ```
179
+
180
+ `plugin list` and `plugin info <id>` report `state` (`active`, `error`, `disabled`, or `stopped`
181
+ when the daemon is not running), the node activation `error`, and one `pages[]` entry per connected
182
+ target with the page script result. Treat a plugin as working only when the state is `active`,
183
+ every `pages[]` entry is `ok`, each action returns the expected data, and the page effect is
184
+ confirmed with `eval` or a viewport capture. `--params-json <file>` reads parameters from a file
185
+ inside the project workspace.
186
+
187
+ Other management commands, also available in the extension popup under **Plugins**:
188
+
189
+ ```bash
190
+ pcbridge plugin enable|disable|remove <id>
191
+ pcbridge plugin update <id> # re-fetch from the recorded source, reinstall dependencies, reload
192
+ pcbridge plugin update --all # update all outdated installed plugins
193
+ pcbridge plugin list --refresh # refresh remote official plugin catalog and versions
194
+ pcbridge help plugin
195
+ ```
196
+
197
+ ## Distribute through GitHub
198
+
199
+ Publish the plugin directory in a public GitHub repository, at the root or in a subdirectory, and
200
+ tag releases. Users install and update with:
201
+
202
+ ```bash
203
+ pcbridge plugin add github:<owner>/<repo> # default branch, plugin at the root
204
+ pcbridge plugin add github:<owner>/<repo>/plugins/my-plugin#v1.2.0 # subdirectory, pinned tag
205
+ pcbridge plugin update my-plugin # same source and ref again
206
+ ```
207
+
208
+ A source without `#ref` follows the default branch, so `update` picks up new commits; a pinned
209
+ `#ref` only changes when the plugin is removed and added again with another ref. Commit built
210
+ output if the plugin needs a build step, because pcbridge installs the repository files as they
211
+ are. Plugins run with full local and page access; tell users to add only sources they trust.
212
+
213
+ ## Reference implementation
214
+
215
+ `tinyapp-builder` is the official plugin shipped with pcbridge (`pcbridge plugin add
216
+ tinyapp-builder`, source under `plugins/tinyapp-builder/` of the pcbridge package). It shows a
217
+ node entry with background jobs and npm dependencies, an Editor page script that injects an
218
+ Inspector panel and serves `callPage` requests, and a complete `actions` section.
219
+ When adding or bumping an official plugin under `plugins/<id>/`, run `bun run plugins:sync` to
220
+ synchronize `plugins/index.json` (`bun run check:version` enforces this).
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "pcbridge Plugin Authoring"
3
+ short_description: "Build and manage pcbridge plugins for PlayCanvas Editor and Launch."
4
+ default_prompt: "Create or update a pcbridge plugin, link it, and verify it with pcbridge plugin commands."
@@ -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 `bun add --global 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.
@@ -72,7 +77,7 @@ steps have been acknowledged or verified.
72
77
  3. **Inspect local files first (0 RPC)** to understand the project before calling Editor RPCs:
73
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).
74
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.
75
- 4. Use layered help to load only the command group you need: `pcbridge help`, then `pcbridge help core|workspace|processing|import|frontend|target|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
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`.
76
81
  5. **Choose the right write path** (never mix local file edits and CLI write RPCs on the same target concurrently):
77
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 }`).
78
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.
@@ -125,14 +130,21 @@ Only collision paths gain `.__pc_<type>_<assetId>`. The catalog is managed by pc
125
130
  to request remote asset operations. Confirmed remote deletions are quarantined under
126
131
  `tmp/trash/remote/`; `tmp/conflicts/` is reserved for divergent local and remote contents.
127
132
 
128
- 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
129
141
  dependencies, materializes missing or remote-updated primary files, texture variants, and additional
130
142
  font maps under `assets/`, then uploads individual S3 objects without a ZIP. `local.resources` in the
131
143
  schema-v3 manifest identifies managed read-only auxiliary files; `.pcbridge/objects` is only the
132
144
  internal content cache. Project `.env` overrides workspace-root `.env`; never read or return
133
145
  credential values. CLI equivalents are
134
- `pcbridge builder start --target editor:<sceneId> --asset <id>` and
135
- `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>"}'`.
136
148
 
137
149
  Local file arguments are restricted to the selected project workspace. Never use
138
150
  `--allow-external-path` unless the user explicitly asks to use a known external file.
@@ -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).
@@ -17,19 +17,16 @@ pcbridge targets
17
17
  Run `pcbridge daemon start` only for `DAEMON_NOT_LISTENING`; for `LOOPBACK_ACCESS_DENIED`, retry
18
18
  with local-loopback permission. If no target appears, ask the user to install/reload the extension.
19
19
 
20
- Updates are component-specific. For an explicit update request, record the workspace root from
21
- `pcbridge daemon status`. Run
22
- `bun add --global playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, then rerun
23
- `pcbridge install-skill --agent all`. For a custom or project-local parent directory, use
24
- `pcbridge install-skill --agent <one-agent> --path <parent-directory>`; it appends the standard
25
- artifact name and cannot be combined with `--agent all`. Regenerate the extension with
26
- `pcbridge install-extension --no-open`; the user must manually click **Reload** in
27
- `chrome://extensions` and refresh Editor/Launch tabs. Run `pcbridge daemon restart --workspace
28
- <original-root>` and verify `pcbridge doctor`. A daemon version without authenticated shutdown must
29
- be stopped once with Ctrl+C before starting the updated daemon. Update the independently published Editor build with
20
+ CLI responses attach `meta.updates` when a newer `pcbridge` release, local component version mismatch,
21
+ or official plugin update is available. Check updates with `pcbridge update status --refresh` or
22
+ `pcbridge plugin list --refresh`. Apply a one-click core update with `pcbridge update` (or
23
+ `pcbridge update --plugins`), which upgrades the global package, refreshes installed skills,
24
+ rewrites `~/.pcbridge/extension`, triggers Chrome extension reload + PlayCanvas tab refresh
25
+ (`--no-reload-tabs` skips tab refresh), and restarts the running daemon in-place. Update official
26
+ plugins independently without restarting the daemon via `pcbridge plugin update <id>` or
27
+ `pcbridge plugin update --all` (or the extension popup **Plugins** tab). Update the independently published Editor build with
30
28
  `pcbridge frontend update` and `frontend status`; a frontend-only update needs no daemon restart,
31
- but the Editor tab must be refreshed and custom mode selected in the popup when necessary. Do not
32
- claim completion before these manual steps are confirmed.
29
+ but the Editor tab must be refreshed and custom mode selected in the popup when necessary.
33
30
 
34
31
  The current directory is the default workspace root; `daemon start/restart --workspace <directory>`
35
32
  selects it explicitly, and `daemon stop` stops the authenticated daemon. After selecting a target, run
@@ -67,6 +64,10 @@ Read schema-v3 `pcbridge.project.json.assets`: `folder` is the remote display pa
67
64
  effective metadata, presence, writability, and hashes. Only collisions gain
68
65
  `.__pc_<type>_<assetId>`. Treat that asset catalog as pcbridge-managed. Confirmed remote
69
66
  deletions are quarantined under `tmp/trash/remote/`; `tmp/conflicts/` contains content divergence.
67
+ Optional features ship as plugins: `pcbridge plugin list` shows installed and available plugins with
68
+ their actions, and `pcbridge plugin call <id> <action> --target editor:<sceneId> --params '<json>'`
69
+ runs one. Use the pcbridge-plugin-authoring rule to create or change a plugin.
70
+ With the official `tinyapp-builder` plugin enabled (`pcbridge plugin add tinyapp-builder`),
70
71
  Template selection exposes pcbridge Tiny Builder for direct S3 object uploads; project `.env`
71
72
  overrides workspace-root `.env`. A build materializes every primary dependency plus texture
72
73
  variants and additional font maps under the Asset's remote folder in `assets/`, then uploads only
@@ -79,7 +80,7 @@ For the optional published Editor build, use `pcbridge frontend install latest`,
79
80
  The popup remembers that choice per project and reapplies it on later project-picker and scene
80
81
  Editor navigations; change the remembered choice only through the popup.
81
82
 
82
- Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help core|target|workspace|processing|import|frontend|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
83
+ Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help core|target|workspace|plugin|processing|import|frontend|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
83
84
 
84
85
  Prefer local file edits for scripts, shaders, text, `*.material.json` / `*.template.json` data, and multi-property
85
86
  edits in the active `.scene.json`. Use structured commands for Editor pipelines (`scene open`,