playcanvas-agent-bridge-cli 0.3.0 → 0.5.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.
@@ -1,3 +1,244 @@
1
+ const FRONTEND_PREFERENCES_KEY = "pcbridgeFrontendPreferences";
2
+ const SCENE_PROJECTS_KEY = "pcbridgeSceneProjects";
3
+ const TAB_PROJECTS_KEY = "pcbridgeTabProjects";
4
+ const tabProjects = new Map();
5
+
6
+ function normalizeId(value) {
7
+ const id = String(value || "").trim();
8
+ return /^\d+$/.test(id) ? id : null;
9
+ }
10
+
11
+ function parseEditorUrl(value) {
12
+ try {
13
+ const url = new URL(value);
14
+ if (
15
+ (url.protocol !== "https:" && url.protocol !== "http:") ||
16
+ url.hostname !== "playcanvas.com"
17
+ ) {
18
+ return null;
19
+ }
20
+
21
+ const projectMatch = url.pathname.match(/^\/editor\/project\/(\d+)(?:\/|$)/);
22
+ const sceneMatch = url.pathname.match(/^\/editor\/scene\/(\d+)(?:\/|$)/);
23
+ if (!projectMatch && !sceneMatch) return null;
24
+ return {
25
+ url,
26
+ projectId: projectMatch ? projectMatch[1] : null,
27
+ sceneId: sceneMatch ? sceneMatch[1] : null
28
+ };
29
+ } catch {
30
+ return null;
31
+ }
32
+ }
33
+
34
+ async function readObject(area, key) {
35
+ if (!area) return {};
36
+ const data = await area.get(key);
37
+ const value = data && data[key];
38
+ return value && typeof value === "object" && !Array.isArray(value) ? value : {};
39
+ }
40
+
41
+ async function rememberTabProject(tabId, projectId) {
42
+ if (!Number.isInteger(tabId) || !projectId) return;
43
+ tabProjects.set(tabId, projectId);
44
+ if (!chrome.storage.session) return;
45
+ const stored = await readObject(chrome.storage.session, TAB_PROJECTS_KEY);
46
+ if (stored[String(tabId)] === projectId) return;
47
+ await chrome.storage.session.set({
48
+ [TAB_PROJECTS_KEY]: { ...stored, [String(tabId)]: projectId }
49
+ });
50
+ }
51
+
52
+ async function forgetTabProject(tabId) {
53
+ tabProjects.delete(tabId);
54
+ if (!chrome.storage.session) return;
55
+ const stored = await readObject(chrome.storage.session, TAB_PROJECTS_KEY);
56
+ if (!Object.hasOwn(stored, String(tabId))) return;
57
+ delete stored[String(tabId)];
58
+ await chrome.storage.session.set({ [TAB_PROJECTS_KEY]: stored });
59
+ }
60
+
61
+ async function getTabProject(tabId) {
62
+ if (!Number.isInteger(tabId)) return null;
63
+ if (tabProjects.has(tabId)) return tabProjects.get(tabId);
64
+ const stored = await readObject(chrome.storage.session, TAB_PROJECTS_KEY);
65
+ const projectId = normalizeId(stored[String(tabId)]);
66
+ if (projectId) tabProjects.set(tabId, projectId);
67
+ return projectId;
68
+ }
69
+
70
+ async function rememberSceneProject(sceneId, projectId) {
71
+ if (!sceneId || !projectId) return;
72
+ const stored = await readObject(chrome.storage.local, SCENE_PROJECTS_KEY);
73
+ if (stored[sceneId] === projectId) return;
74
+ await chrome.storage.local.set({
75
+ [SCENE_PROJECTS_KEY]: { ...stored, [sceneId]: projectId }
76
+ });
77
+ }
78
+
79
+ async function getSceneProject(sceneId) {
80
+ if (!sceneId) return null;
81
+ const stored = await readObject(chrome.storage.local, SCENE_PROJECTS_KEY);
82
+ return normalizeId(stored[sceneId]);
83
+ }
84
+
85
+ async function resolveProjectContext({ url, tabId, projectId, sceneId } = {}) {
86
+ const parsed = parseEditorUrl(url);
87
+ const resolvedSceneId = normalizeId(sceneId) || (parsed && parsed.sceneId);
88
+ let resolvedProjectId = normalizeId(projectId) || (parsed && parsed.projectId);
89
+
90
+ if (!resolvedProjectId && resolvedSceneId) {
91
+ resolvedProjectId = await getSceneProject(resolvedSceneId);
92
+ }
93
+ if (!resolvedProjectId) {
94
+ resolvedProjectId = await getTabProject(tabId);
95
+ }
96
+ if (resolvedProjectId) {
97
+ await rememberTabProject(tabId, resolvedProjectId);
98
+ await rememberSceneProject(resolvedSceneId, resolvedProjectId);
99
+ }
100
+
101
+ return {
102
+ parsed,
103
+ projectId: resolvedProjectId,
104
+ sceneId: resolvedSceneId
105
+ };
106
+ }
107
+
108
+ async function getFrontendPreference(context) {
109
+ const resolved = await resolveProjectContext(context);
110
+ if (!resolved.projectId) return { ok: false, mode: null, projectId: null };
111
+ const preferences = await readObject(chrome.storage.local, FRONTEND_PREFERENCES_KEY);
112
+ const mode = preferences[resolved.projectId];
113
+ return {
114
+ ok: true,
115
+ mode: mode === "custom" || mode === "official" ? mode : null,
116
+ projectId: resolved.projectId
117
+ };
118
+ }
119
+
120
+ async function setFrontendPreference(context, mode) {
121
+ if (mode !== "custom" && mode !== "official") {
122
+ return { ok: false, mode: null, projectId: null };
123
+ }
124
+ const resolved = await resolveProjectContext(context);
125
+ if (!resolved.projectId) return { ok: false, mode: null, projectId: null };
126
+ const preferences = await readObject(chrome.storage.local, FRONTEND_PREFERENCES_KEY);
127
+ await chrome.storage.local.set({
128
+ [FRONTEND_PREFERENCES_KEY]: {
129
+ ...preferences,
130
+ [resolved.projectId]: mode
131
+ }
132
+ });
133
+ return { ok: true, mode, projectId: resolved.projectId };
134
+ }
135
+
136
+ function frontendUrlForMode(value, mode) {
137
+ const parsed = parseEditorUrl(value);
138
+ if (!parsed || (mode !== "custom" && mode !== "official")) return null;
139
+ const hadCustom = parsed.url.searchParams.has("use_local_frontend");
140
+ if (mode === "custom") parsed.url.searchParams.set("use_local_frontend", "");
141
+ else parsed.url.searchParams.delete("use_local_frontend");
142
+ const changed = hadCustom !== parsed.url.searchParams.has("use_local_frontend");
143
+ return { changed, url: parsed.url.toString() };
144
+ }
145
+
146
+ async function applyFrontendPreference(tabId, value, projectId) {
147
+ const preference = await getFrontendPreference({ url: value, tabId, projectId });
148
+ if (!preference.ok || !preference.mode) {
149
+ return { ...preference, redirected: false };
150
+ }
151
+ const next = frontendUrlForMode(value, preference.mode);
152
+ if (!next || !next.changed) return { ...preference, redirected: false };
153
+ await chrome.tabs.update(tabId, { url: next.url });
154
+ return { ...preference, redirected: true, url: next.url };
155
+ }
156
+
157
+ async function loadConfig() {
158
+ try {
159
+ const response = await fetch(chrome.runtime.getURL("config.json"));
160
+ if (response.ok) return response.json();
161
+ } catch {
162
+ // Use the generated-extension defaults below.
163
+ }
164
+ return {
165
+ host: "127.0.0.1",
166
+ port: 17329,
167
+ token: ""
168
+ };
169
+ }
170
+
171
+ async function requestDaemon(message, sender) {
172
+ const path = String(message.path || "");
173
+ const method = String(message.method || "GET").toUpperCase();
174
+ const allowed =
175
+ (path === "/builder/jobs" && method === "POST") ||
176
+ (/^\/builder\/jobs\/[^/]+$/.test(path) && method === "GET");
177
+ if (!allowed) {
178
+ return {
179
+ ok: false,
180
+ error: { code: "UNSUPPORTED_DAEMON_REQUEST", message: "Unsupported pcbridge browser request." }
181
+ };
182
+ }
183
+
184
+ const config = await loadConfig();
185
+ if (!config.token) {
186
+ return {
187
+ ok: false,
188
+ error: { code: "DAEMON_CONFIG_UNAVAILABLE", message: "pcbridge daemon configuration is unavailable." }
189
+ };
190
+ }
191
+ const payload = message.body && typeof message.body === "object" ? { ...message.body } : {};
192
+ const tabId = sender.tab && sender.tab.id;
193
+ if (method === "POST" && !payload.target && Number.isInteger(tabId)) {
194
+ payload.target = "tab:" + tabId;
195
+ }
196
+ const host = config.host || "127.0.0.1";
197
+ const port = config.port || 17329;
198
+ try {
199
+ const response = await fetch(`http://${host}:${port}${path}`, {
200
+ method,
201
+ headers: {
202
+ "Content-Type": "application/json",
203
+ "X-PCBridge-Token": config.token
204
+ },
205
+ body: method === "POST" ? JSON.stringify(payload) : undefined
206
+ });
207
+ const envelope = await response.json().catch(() => null);
208
+ if (!response.ok || !envelope || !envelope.ok) {
209
+ return {
210
+ ok: false,
211
+ error: (envelope && envelope.error) || {
212
+ code: "DAEMON_HTTP_ERROR",
213
+ message: `pcbridge daemon request failed with HTTP ${response.status}.`
214
+ }
215
+ };
216
+ }
217
+ return { ok: true, data: envelope.data };
218
+ } catch (error) {
219
+ return {
220
+ ok: false,
221
+ error: {
222
+ code: "DAEMON_UNREACHABLE",
223
+ message: String((error && error.message) || error)
224
+ }
225
+ };
226
+ }
227
+ }
228
+
229
+ async function focusSenderTab(sender) {
230
+ const tabId = sender.tab && sender.tab.id;
231
+ const windowId = sender.tab && sender.tab.windowId;
232
+ if (!Number.isInteger(tabId)) {
233
+ return { ok: false, error: "The requesting PlayCanvas tab is unavailable." };
234
+ }
235
+ if (Number.isInteger(windowId) && chrome.windows && chrome.windows.update) {
236
+ await chrome.windows.update(windowId, { focused: true });
237
+ }
238
+ await chrome.tabs.update(tabId, { active: true });
239
+ return { ok: true, tabId, windowId: Number.isInteger(windowId) ? windowId : null };
240
+ }
241
+
1
242
  chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
2
243
  if (message && message.type === "pcbridge:getTabInfo") {
3
244
  sendResponse({
@@ -8,26 +249,99 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
8
249
  }
9
250
 
10
251
  if (message && message.type === "pcbridge:getConfig") {
11
- fetch(chrome.runtime.getURL("config.json"))
12
- .then((response) => (response.ok ? response.json() : null))
13
- .then((config) => {
14
- sendResponse(
15
- config || {
16
- host: "127.0.0.1",
17
- port: 17329,
18
- token: ""
19
- }
20
- );
252
+ loadConfig().then(sendResponse);
253
+ return true;
254
+ }
255
+
256
+ if (message && message.type === "pcbridge:focusCurrentTab") {
257
+ focusSenderTab(sender)
258
+ .then(sendResponse)
259
+ .catch((error) => sendResponse({ ok: false, error: String(error) }));
260
+ return true;
261
+ }
262
+
263
+ if (message && message.type === "pcbridge:probeDaemon") {
264
+ loadConfig()
265
+ .then(async (config) => {
266
+ if (!config.token) return { reachable: false };
267
+ const host = config.host || "127.0.0.1";
268
+ const port = config.port || 17329;
269
+ try {
270
+ const response = await fetch(`http://${host}:${port}/health`, {
271
+ headers: { "X-PCBridge-Token": config.token }
272
+ });
273
+ return { reachable: response.ok };
274
+ } catch {
275
+ return { reachable: false };
276
+ }
21
277
  })
22
- .catch(() => {
23
- sendResponse({
24
- host: "127.0.0.1",
25
- port: 17329,
26
- token: ""
27
- });
28
- });
278
+ .then(sendResponse);
279
+ return true;
280
+ }
281
+
282
+ if (message && message.type === "pcbridge:daemonRequest") {
283
+ requestDaemon(message, sender).then(sendResponse);
284
+ return true;
285
+ }
286
+
287
+ if (message && message.type === "pcbridge:getFrontendPreference") {
288
+ getFrontendPreference({
289
+ url: message.url || (sender.tab && sender.tab.url),
290
+ tabId: Number.isInteger(message.tabId) ? message.tabId : sender.tab && sender.tab.id,
291
+ projectId: message.projectId,
292
+ sceneId: message.sceneId
293
+ }).then(sendResponse);
294
+ return true;
295
+ }
296
+
297
+ if (message && message.type === "pcbridge:setFrontendPreference") {
298
+ setFrontendPreference({
299
+ url: message.url || (sender.tab && sender.tab.url),
300
+ tabId: Number.isInteger(message.tabId) ? message.tabId : sender.tab && sender.tab.id,
301
+ projectId: message.projectId,
302
+ sceneId: message.sceneId
303
+ }, message.mode).then(sendResponse);
304
+ return true;
305
+ }
306
+
307
+ if (message && message.type === "pcbridge:rememberProjectContext") {
308
+ resolveProjectContext({
309
+ url: message.url || (sender.tab && sender.tab.url),
310
+ tabId: sender.tab && sender.tab.id,
311
+ projectId: message.projectId,
312
+ sceneId: message.sceneId
313
+ }).then((context) => sendResponse({
314
+ ok: Boolean(context.projectId),
315
+ projectId: context.projectId,
316
+ sceneId: context.sceneId
317
+ }));
318
+ return true;
319
+ }
320
+
321
+ if (message && message.type === "pcbridge:applyFrontendPreference") {
322
+ const tabId = sender.tab && sender.tab.id;
323
+ if (!Number.isInteger(tabId)) {
324
+ sendResponse({ ok: false, redirected: false });
325
+ return false;
326
+ }
327
+ applyFrontendPreference(tabId, message.url || sender.tab.url, message.projectId)
328
+ .then(sendResponse)
329
+ .catch(() => sendResponse({ ok: false, redirected: false }));
29
330
  return true;
30
331
  }
31
332
 
32
333
  return false;
33
334
  });
335
+
336
+ chrome.tabs.onUpdated.addListener((tabId, changeInfo) => {
337
+ if (!changeInfo.url) return;
338
+ if (!parseEditorUrl(changeInfo.url)) {
339
+ void forgetTabProject(tabId);
340
+ return;
341
+ }
342
+ void applyFrontendPreference(tabId, changeInfo.url).catch(() => undefined);
343
+ });
344
+
345
+ chrome.tabs.onRemoved.addListener((tabId) => {
346
+ void forgetTabProject(tabId);
347
+ });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "playcanvas-agent-bridge-cli",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "CLI-first local bridge for automating open PlayCanvas Editor tabs from AI coding agents.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -46,6 +46,8 @@
46
46
  "registry": "https://registry.npmjs.org/"
47
47
  },
48
48
  "dependencies": {
49
+ "@aws-sdk/client-s3": "^3.1102.0",
50
+ "dotenv": "^17.4.2",
49
51
  "tar": "^7.5.22",
50
52
  "ws": "^8.18.3"
51
53
  },
@@ -13,15 +13,31 @@ pcbridge daemon status
13
13
  pcbridge targets
14
14
  ```
15
15
 
16
- If the daemon is offline, ask the user to run `pcbridge daemon start` in another terminal. If no PlayCanvas target appears, ask the user to run `pcbridge install-extension`, load the printed directory in `chrome://extensions`, and refresh the Editor or Launch tab.
16
+ If `doctor` reports `DAEMON_NOT_LISTENING`, ask the user to run `pcbridge daemon start` in another
17
+ terminal. For `LOOPBACK_ACCESS_DENIED`, retry with local-loopback permission instead of starting a
18
+ second daemon. If no PlayCanvas target appears, ask the user to run `pcbridge install-extension`,
19
+ load the printed directory in `chrome://extensions`, and refresh the Editor or Launch tab.
20
+
21
+ The directory where `pcbridge daemon start` runs is the workspace root. Each ready Editor project
22
+ is mirrored into `<projectId>-<projectName>/` below it. After choosing an explicit target, run
23
+ `pcbridge workspace status --target editor:<sceneId>` and do not write while it reports a conflict
24
+ or sync error.
17
25
 
18
26
  Use `pcbridge frontend install latest` and `pcbridge frontend status` when the user wants the
19
27
  published custom Editor build. The extension popup switches between custom and official modes.
28
+ The popup remembers that choice per PlayCanvas project and applies it automatically on later
29
+ project-picker and scene Editor navigations; change the remembered mode only through the popup.
20
30
 
21
31
  Use layered help to load only the command surface you need:
22
32
 
23
33
  ```bash
24
34
  pcbridge help
35
+ pcbridge help core
36
+ pcbridge help material
37
+ pcbridge help script
38
+ pcbridge help store
39
+ pcbridge help target
40
+ pcbridge help workspace
25
41
  pcbridge help frontend
26
42
  pcbridge help entity
27
43
  pcbridge help asset
@@ -33,31 +49,61 @@ pcbridge help logs
33
49
  pcbridge help eval
34
50
  ```
35
51
 
52
+ Workspace layout:
53
+
54
+ ```text
55
+ <workspace root>/<projectId>-<projectName>/
56
+ pcbridge.project.json # project metadata and agent-readable asset catalog
57
+ assets/ # remote folder tree and synchronized asset file contents
58
+ tmp/ # task files, builds, cache, conflicts, captures, and deletion quarantine
59
+ .pcbridge/ # internal state; do not edit
60
+ ```
61
+
62
+ Existing script and binary asset contents synchronize in both directions. Use structured commands
63
+ for asset create, move, rename, and delete operations. `pcbridge workspace pull --target
64
+ editor:<sceneId> --asset <assetId>` explicitly refreshes one file. Local file
65
+ arguments must stay inside the selected project workspace. Do not use `--allow-external-path`
66
+ unless the user explicitly asks to use a known external file.
67
+ Read `pcbridge.project.json.assets` to resolve asset ids to project-relative `assets/...` paths and
68
+ compare remote, local, and base MD5 values. Do not edit the managed asset catalog to request remote
69
+ operations. Remote deletions are quarantined under `tmp/trash/remote/`, while true content
70
+ divergence remains under `tmp/conflicts/`.
71
+
72
+ Selecting a Template Asset exposes **pcbridge Tiny Builder** in the Attributes panel. It collects
73
+ dependencies, fills the workspace cache, and uploads individual S3 objects without a ZIP. Project
74
+ `.env` overrides workspace-root `.env`; never expose credential values. CLI equivalents are
75
+ `pcbridge builder start --target editor:<sceneId> --asset <id>` and
76
+ `pcbridge builder status --job <jobId>`.
77
+
36
78
  Use structured commands for small, known Editor operations:
37
79
 
38
80
  ```bash
39
- pcbridge entity list --target current --limit 50
40
- pcbridge entity create --target current --json ./entity.json
41
- pcbridge entity create-many --target current --json ./entities.json
42
- pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
43
- pcbridge entity duplicate --target current --id <resource_id>
44
- pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
45
- pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
46
- pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
47
- pcbridge asset list --target current --type script
48
- pcbridge asset create --target current --json ./assets.json
49
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/My Task/Textures"
50
- pcbridge asset upload --target current --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
51
- pcbridge asset upload-many --target current --json ./upload-manifest.json
52
- pcbridge material create --target current --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
53
- pcbridge template create --target current --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
54
- pcbridge template instantiate --target current --id <template_asset_id>
55
- pcbridge scene settings get --target current
56
- pcbridge viewport focus --target current --id <resource_id> --view perspective
57
- pcbridge script upsert --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse
58
- pcbridge script create --target current --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
59
- pcbridge script set-text --target current --asset-id <id> --file ./script.js
60
- pcbridge viewport capture --target current --out ./tmp/playcanvas.png
81
+ pcbridge entity list --target editor:<sceneId> --limit 50
82
+ pcbridge entity create --target editor:<sceneId> --json ./entity.json
83
+ pcbridge entity create-many --target editor:<sceneId> --json ./entities.json
84
+ pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set position='[0,1,0]'
85
+ pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
86
+ pcbridge entity reparent --target editor:<sceneId> --id <resource_id> --parent <parent_resource_id>
87
+ pcbridge entity set-material --target editor:<sceneId> --id <resource_id> --material-id <material_asset_id>
88
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.4}'
89
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
90
+ pcbridge asset list --target editor:<sceneId> --type script
91
+ pcbridge asset create --target editor:<sceneId> --json ./assets.json
92
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
93
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
94
+ pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
95
+ pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
96
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
97
+ pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
98
+ pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
99
+ pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
100
+ pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
101
+ pcbridge scene settings get --target editor:<sceneId>
102
+ pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
103
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
104
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
105
+ pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
106
+ pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
61
107
  pcbridge logs get --target launch:<sceneId> --limit 100
62
108
  pcbridge logs get --target launch:<sceneId> --level error
63
109
  ```
@@ -65,15 +111,34 @@ pcbridge logs get --target launch:<sceneId> --level error
65
111
  Organize generated assets under `AI Agent Bridge/<task name>/Textures`, `Materials`, and `Scripts`. Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, and large multi-step scene edits:
66
112
 
67
113
  ```bash
68
- pcbridge eval --target current --code "return { href: location.href, entityCount: editor.api.globals.entities.list().length }"
69
- pcbridge eval --target current --file ./install.js --args-json ./install-args.json --timeout-ms 120000
70
- pcbridge eval --target launch:<sceneId> --code "return { href: location.href, hasPc: !!pc, canvasCount: document.querySelectorAll('canvas').length }"
114
+ pcbridge eval --target editor:<sceneId> --code "return { href: location.href, entityCount: editor.api.globals.entities.list().length }"
115
+ pcbridge eval --target editor:<sceneId> --file ./install.js --args-json ./install-args.json --timeout-ms 120000
116
+ pcbridge launch diagnose --target launch:<sceneId>
117
+ pcbridge launch wait-ready --target launch:<sceneId> --focus --timeout-ms 30000
118
+ pcbridge eval --target launch:<sceneId> --code "return { runtimeCreated: !!runtimeApp, rootChildCount: runtimeApp?.root?.children?.length ?? 0 }"
71
119
  ```
72
120
 
73
- Eval snippets run in an async function with `editor`, `pc`, `pcui`, `window`, `document`, `command`, and `serialize`. Return compact JSON only. Do not return raw PlayCanvas Editor objects. Use `{ history: true }` for Editor mutations when available, and verify changes with a read-only command.
121
+ Eval snippets run in an async function with `editor`, `pc`, `pcui`, `runtimeApp`, `window`,
122
+ `document`, `command`, and `serialize`. `runtimeApp` uses a compatibility resolver for Engine V1/V2. Return compact
123
+ JSON only; bounded `--max-depth`/`--max-items` are available when projection is insufficient. Do
124
+ not return raw PlayCanvas Editor or runtime objects. Use `{ history: true }` for Editor mutations
125
+ when available, and verify changes with a read-only command.
74
126
 
75
127
  For Launch runtime debugging, target `launch:<sceneId>` or `tab:<id>` and use `pcbridge eval`, `pcbridge viewport capture`, and `pcbridge logs get`. Editor-only structured entity/asset/script commands require an Editor target.
76
128
 
77
- For large PlayCanvas tasks, choose an explicit target from `pcbridge targets`, keep task files in a local folder, upload assets with an upload manifest, use `script upsert` for repeatable script updates, and capture the viewport after smoke tests. If the same manual glue repeats across tasks, improve the CLI or this skill instead of continuing the brittle sequence.
129
+ Use `editor:<sceneId>` for writes and `launch:<sceneId>` for runtime tests. Launch
130
+ `lifecycleReady` is a best-effort heuristic based on an owned graphics canvas/context, attached
131
+ scene root, a completed frame, and recognized splash state; target `ready` also requires visibility.
132
+ These are not Engine lifecycle events, and script type count is diagnostic only. For a hidden tab,
133
+ use `launch diagnose` and `launch wait-ready --focus`. Capture records the
134
+ current canvas, defaults to `--max-width 1200`, and does not emulate a mobile viewport or DPR. Use `--script-name` for bundle- or
135
+ runtime-registered ScriptTypes that have no standalone asset id.
136
+
137
+ Editor patches are durable. Restore preview-only enabled/visibility changes before Template apply,
138
+ then verify overrides. Template `verified` covers the current Editor observer, not reload
139
+ persistence. Prefer `script upsert --parse --wait` after script edits; its completion check does not
140
+ wait for a later workspace mirror sync.
141
+
142
+ For large PlayCanvas tasks, choose an explicit target from `pcbridge targets`, confirm `workspace status`, keep task files under the project `tmp/` directory, upload assets with an upload manifest, edit tracked scripts under `assets/`, and capture the viewport under `tmp/captures/` after smoke tests. If the same manual glue repeats across tasks, improve the CLI or this skill instead of continuing the brittle sequence.
78
143
 
79
144
  Do not pre-place runtime-generated content just to prove a game exists. Keep procedural maps, pickups, enemies, and VFX in the runtime script, with only a small durable Editor root and helper entities when needed. If Editor entities must be created, use structured commands and small `entity create-many` batches with read-back verification; large eval scripts that create many entities in a tight loop can briefly show objects and then lose them from the Editor data model.