summer-engine 3.8.0 → 4.2.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 (527) hide show
  1. package/.claude-plugin/marketplace.json +2 -13
  2. package/.claude-plugin/plugin.json +24 -22
  3. package/.codex-plugin/plugin.json +18 -22
  4. package/.cursor-plugin/plugin.json +8 -14
  5. package/.factory-plugin/plugin.json +6 -13
  6. package/AGENTS.md +19 -12
  7. package/CHANGELOG.md +133 -0
  8. package/GEMINI.md +3 -3
  9. package/README.md +118 -37
  10. package/assets/icon.png +0 -0
  11. package/commands/start.md +71 -0
  12. package/commands/summer.md +3 -2
  13. package/dist/cli/banner.js +3 -0
  14. package/dist/cli/commands/config.js +3 -2
  15. package/dist/cli/commands/create.js +12 -3
  16. package/dist/cli/commands/list.d.ts +5 -0
  17. package/dist/cli/commands/list.js +30 -13
  18. package/dist/cli/commands/login.d.ts +27 -0
  19. package/dist/cli/commands/login.js +58 -12
  20. package/dist/cli/commands/memory.js +6 -2
  21. package/dist/cli/commands/ops.d.ts +64 -0
  22. package/dist/cli/commands/ops.js +329 -0
  23. package/dist/cli/commands/setup.d.ts +4 -0
  24. package/dist/cli/commands/setup.js +254 -26
  25. package/dist/cli/commands/skills.js +28 -11
  26. package/dist/cli/commands/status.d.ts +26 -0
  27. package/dist/cli/commands/status.js +36 -21
  28. package/dist/cli/index.js +7 -0
  29. package/dist/core/agent-host.d.ts +65 -0
  30. package/dist/core/agent-host.js +193 -0
  31. package/dist/core/capabilities/agent-playbook.d.ts +3 -0
  32. package/dist/core/capabilities/agent-playbook.js +54 -2
  33. package/dist/core/capabilities/apps.d.ts +33 -10
  34. package/dist/core/capabilities/apps.js +25 -12
  35. package/dist/core/capabilities/audit/args.d.ts +6 -6
  36. package/dist/core/capabilities/doctor.d.ts +3 -0
  37. package/dist/core/capabilities/doctor.js +20 -15
  38. package/dist/core/capabilities/fabricate-mesh.d.ts +4 -4
  39. package/dist/core/capabilities/game-task-plan.d.ts +12 -6
  40. package/dist/core/capabilities/game-task-plan.js +80 -5
  41. package/dist/core/capabilities/hdri-import.d.ts +2 -2
  42. package/dist/core/capabilities/motion-generation.d.ts +2 -2
  43. package/dist/core/capabilities/motion-generation.js +2 -2
  44. package/dist/core/capabilities/navigation/open.d.ts +6 -2
  45. package/dist/core/capabilities/navigation/open.js +3 -0
  46. package/dist/core/capabilities/placement.d.ts +23 -23
  47. package/dist/core/capabilities/publish-build.js +2 -0
  48. package/dist/core/capabilities/runtime-control.d.ts +42 -42
  49. package/dist/core/capabilities/scene-script-target.d.ts +17 -0
  50. package/dist/core/capabilities/scene-script-target.js +70 -0
  51. package/dist/core/capabilities/seeing/args.d.ts +16 -16
  52. package/dist/core/capabilities/sfx-choices.d.ts +4 -0
  53. package/dist/core/capabilities/sfx-choices.js +13 -6
  54. package/dist/core/capabilities/tool-dispatch.d.ts +12 -3
  55. package/dist/core/capabilities/tool-dispatch.js +81 -46
  56. package/dist/core/capabilities/ui-control.d.ts +2 -2
  57. package/dist/core/capabilities/world-snapshot.d.ts +4 -4
  58. package/dist/core/embeddings.d.ts +2 -0
  59. package/dist/core/embeddings.js +1 -1
  60. package/dist/core/error-codes.d.ts +62 -0
  61. package/dist/core/error-codes.js +97 -0
  62. package/dist/core/format.d.ts +2 -0
  63. package/dist/core/format.js +2 -1
  64. package/dist/core/hosted-mcp.d.ts +22 -0
  65. package/dist/core/hosted-mcp.js +56 -1
  66. package/dist/core/library-read.js +5 -0
  67. package/dist/core/library-search.d.ts +2 -2
  68. package/dist/core/library-search.js +2 -1
  69. package/dist/core/oauth.js +4 -0
  70. package/dist/core/ops/areas.d.ts +11 -0
  71. package/dist/core/ops/areas.js +24 -0
  72. package/dist/core/ops/catalog.d.ts +45 -0
  73. package/dist/core/ops/catalog.js +157 -0
  74. package/dist/core/ops/cloud.d.ts +64 -0
  75. package/dist/core/ops/cloud.js +198 -0
  76. package/dist/core/ops/contract.d.ts +120 -0
  77. package/dist/core/ops/contract.js +134 -0
  78. package/dist/core/ops/engine-answer.d.ts +25 -0
  79. package/dist/core/ops/engine-answer.js +117 -0
  80. package/dist/core/ops/engine.d.ts +55 -0
  81. package/dist/core/ops/engine.js +649 -0
  82. package/dist/core/ops/public-catalog.d.ts +48 -0
  83. package/dist/core/ops/public-catalog.js +56 -0
  84. package/dist/core/ops/save-files.d.ts +78 -0
  85. package/dist/core/ops/save-files.js +419 -0
  86. package/dist/core/ops/search.d.ts +8 -0
  87. package/dist/core/ops/search.js +187 -0
  88. package/dist/core/skills-registry.d.ts +16 -1
  89. package/dist/core/skills-registry.js +35 -2
  90. package/dist/core/telemetry.d.ts +32 -0
  91. package/dist/core/telemetry.js +38 -10
  92. package/dist/core/tool-profiles.d.ts +25 -0
  93. package/dist/core/tool-profiles.js +41 -0
  94. package/dist/installer/agent-config.d.ts +17 -4
  95. package/dist/installer/agent-config.js +27 -6
  96. package/dist/installer/agent-table.d.ts +12 -0
  97. package/dist/installer/agent-table.js +33 -9
  98. package/dist/installer/cli-permissions.d.ts +65 -0
  99. package/dist/installer/cli-permissions.js +182 -0
  100. package/dist/installer/setup.d.ts +4 -0
  101. package/dist/installer/setup.js +12 -4
  102. package/dist/installer/skills-refresh.d.ts +29 -0
  103. package/dist/installer/skills-refresh.js +261 -0
  104. package/dist/installer/version-check.d.ts +51 -11
  105. package/dist/installer/version-check.js +147 -37
  106. package/dist/mcp/command.js +7 -0
  107. package/dist/mcp/hosted-mount.d.ts +27 -2
  108. package/dist/mcp/hosted-mount.js +53 -23
  109. package/dist/mcp/legacy-toolset.d.ts +27 -0
  110. package/dist/mcp/legacy-toolset.js +43 -0
  111. package/dist/mcp/ops-surface.d.ts +59 -0
  112. package/dist/mcp/ops-surface.js +453 -0
  113. package/dist/mcp/server.d.ts +45 -11
  114. package/dist/mcp/server.js +263 -89
  115. package/dist/mcp/tool-results.d.ts +26 -0
  116. package/dist/mcp/tool-results.js +81 -0
  117. package/dist/mcp/tool-surface.d.ts +65 -0
  118. package/dist/mcp/tool-surface.js +317 -0
  119. package/dist/mcp/tools/app-tools.js +9 -2
  120. package/dist/mcp/tools/asset-tools.js +55 -53
  121. package/dist/mcp/tools/audit-tools.js +21 -21
  122. package/dist/mcp/tools/debug-tools.js +6 -6
  123. package/dist/mcp/tools/fabricate-tools.js +6 -6
  124. package/dist/mcp/tools/generate-tools.js +76 -70
  125. package/dist/mcp/tools/project-tools.d.ts +9 -4
  126. package/dist/mcp/tools/project-tools.js +16 -10
  127. package/dist/mcp/tools/scene-tools.js +12 -23
  128. package/dist/mcp/tools/script-tools.js +9 -5
  129. package/dist/mcp/tools/with-engine.d.ts +6 -0
  130. package/dist/mcp/tools/with-engine.js +19 -0
  131. package/dist/project-memory/agent-instructions.d.ts +47 -0
  132. package/dist/project-memory/agent-instructions.js +226 -0
  133. package/gemini-extension.json +6 -13
  134. package/hooks/pre-commit-doctor.sh +5 -4
  135. package/hooks/session-start.sh +24 -28
  136. package/integrations/README.md +1 -1
  137. package/integrations/claude/README.md +6 -0
  138. package/integrations/claude/manifest-target.json +4 -0
  139. package/integrations/claude-desktop/README.md +1 -1
  140. package/integrations/copilot-jetbrains/README.md +1 -1
  141. package/integrations/gemini/README.md +11 -0
  142. package/integrations/junie/README.md +1 -1
  143. package/integrations/lm-studio/README.md +1 -1
  144. package/integrations/trae/README.md +1 -1
  145. package/integrations/visual-studio/README.md +1 -1
  146. package/integrations/windsurf/README.md +1 -1
  147. package/library/references/mcp-tools-reference/mcp-tools-reference.md +79 -51
  148. package/library/references/mcp-tools-reference/resource.yaml +1 -1
  149. package/library/references/product-map/resource.yaml +2 -2
  150. package/library/skills/3d-lighting/SKILL.md +69 -28
  151. package/library/skills/3d-lighting/resource.yaml +1 -1
  152. package/library/skills/README.md +121 -118
  153. package/library/skills/adaptive-music/SKILL.md +40 -23
  154. package/library/skills/adaptive-music/resource.yaml +1 -1
  155. package/library/skills/agent-playtesting/SKILL.md +23 -1
  156. package/library/skills/agent-playtesting/resource.yaml +1 -1
  157. package/library/skills/ai-characters-in-games/SKILL.md +16 -1
  158. package/library/skills/ai-characters-in-games/resource.yaml +1 -1
  159. package/library/skills/ambient-bed/SKILL.md +38 -13
  160. package/library/skills/ambient-bed/resource.yaml +1 -1
  161. package/library/skills/animated-loop/SKILL.md +60 -32
  162. package/library/skills/animated-loop/resource.yaml +1 -1
  163. package/library/skills/animation-tree/SKILL.md +27 -1
  164. package/library/skills/animation-tree/resource.yaml +1 -1
  165. package/library/skills/art-direction/SKILL.md +17 -3
  166. package/library/skills/art-direction/resource.yaml +1 -1
  167. package/library/skills/asset-strategy/SKILL.md +51 -4
  168. package/library/skills/asset-strategy/resource.yaml +2 -1
  169. package/library/skills/audio-direction/SKILL.md +26 -10
  170. package/library/skills/audio-direction/resource.yaml +1 -1
  171. package/library/skills/auto-fire-targeting/SKILL.md +15 -1
  172. package/library/skills/auto-fire-targeting/resource.yaml +1 -1
  173. package/library/skills/bounded-engine-runs/SKILL.md +1 -1
  174. package/library/skills/bounded-engine-runs/resource.yaml +1 -1
  175. package/library/skills/brainstorm-game/SKILL.md +14 -1
  176. package/library/skills/brainstorm-game/resource.yaml +1 -1
  177. package/library/skills/brainstorming/SKILL.md +1 -1
  178. package/library/skills/brainstorming/resource.yaml +1 -1
  179. package/library/skills/browse-templates/SKILL.md +11 -1
  180. package/library/skills/browse-templates/resource.yaml +1 -1
  181. package/library/skills/camera-rigs/SKILL.md +22 -2
  182. package/library/skills/camera-rigs/resource.yaml +1 -1
  183. package/library/skills/celeste-momentum-platforming/resource.yaml +1 -0
  184. package/library/skills/character-animation-wiring/SKILL.md +28 -4
  185. package/library/skills/character-animation-wiring/resource.yaml +1 -1
  186. package/library/skills/character-model/SKILL.md +83 -47
  187. package/library/skills/character-model/resource.yaml +1 -1
  188. package/library/skills/character-movement/SKILL.md +27 -3
  189. package/library/skills/character-movement/resource.yaml +1 -1
  190. package/library/skills/character-portrait/SKILL.md +39 -19
  191. package/library/skills/character-portrait/resource.yaml +1 -1
  192. package/library/skills/cinematic-cutscene/SKILL.md +79 -46
  193. package/library/skills/cinematic-cutscene/resource.yaml +1 -1
  194. package/library/skills/combat-basics/SKILL.md +20 -1
  195. package/library/skills/combat-basics/resource.yaml +1 -1
  196. package/library/skills/compatibility-renderer-traps/SKILL.md +12 -1
  197. package/library/skills/compatibility-renderer-traps/resource.yaml +1 -1
  198. package/library/skills/concept-art/SKILL.md +29 -12
  199. package/library/skills/concept-art/resource.yaml +1 -1
  200. package/library/skills/concept-to-level/SKILL.md +258 -0
  201. package/library/skills/concept-to-level/references/technical-rules.md +150 -0
  202. package/library/skills/concept-to-level/resource.yaml +44 -0
  203. package/library/skills/create-asset-sheet/SKILL.md +37 -13
  204. package/library/skills/create-asset-sheet/resource.yaml +1 -1
  205. package/library/skills/debug/SKILL.md +34 -2
  206. package/library/skills/debug/resource.yaml +1 -1
  207. package/library/skills/debugging-game-feel/SKILL.md +13 -1
  208. package/library/skills/debugging-game-feel/resource.yaml +1 -1
  209. package/library/skills/design-level/SKILL.md +40 -35
  210. package/library/skills/design-level/resource.yaml +1 -1
  211. package/library/skills/design-mechanic/SKILL.md +18 -1
  212. package/library/skills/design-mechanic/resource.yaml +1 -1
  213. package/library/skills/design-npc/SKILL.md +43 -24
  214. package/library/skills/design-npc/resource.yaml +1 -1
  215. package/library/skills/diagnosing-perf-regressions/SKILL.md +13 -1
  216. package/library/skills/diagnosing-perf-regressions/resource.yaml +1 -1
  217. package/library/skills/driving-the-editor-ui/SKILL.md +24 -1
  218. package/library/skills/driving-the-editor-ui/resource.yaml +1 -1
  219. package/library/skills/environment-kit/SKILL.md +43 -16
  220. package/library/skills/environment-kit/resource.yaml +1 -1
  221. package/library/skills/export-and-ship/SKILL.md +29 -6
  222. package/library/skills/export-and-ship/resource.yaml +1 -1
  223. package/library/skills/fabricating-assets/SKILL.md +30 -7
  224. package/library/skills/fabricating-assets/resource.yaml +3 -3
  225. package/library/skills/facial-and-lipsync/SKILL.md +36 -15
  226. package/library/skills/facial-and-lipsync/resource.yaml +1 -1
  227. package/library/skills/fps-controller/SKILL.md +50 -41
  228. package/library/skills/fps-controller/resource.yaml +1 -1
  229. package/library/skills/game-feel/SKILL.md +34 -8
  230. package/library/skills/game-feel/resource.yaml +1 -1
  231. package/library/skills/gameskill/SKILL.md +15 -4
  232. package/library/skills/gameskill/resource.yaml +1 -1
  233. package/library/skills/gdscript-patterns/SKILL.md +16 -1
  234. package/library/skills/gdscript-patterns/resource.yaml +1 -1
  235. package/library/skills/generate-motion/SKILL.md +51 -21
  236. package/library/skills/generate-motion/resource.yaml +1 -1
  237. package/library/skills/godogen-visual-proof-game-generation/SKILL.md +18 -1
  238. package/library/skills/godogen-visual-proof-game-generation/resource.yaml +1 -0
  239. package/library/skills/grow-analytics/SKILL.md +13 -3
  240. package/library/skills/grow-analytics/resource.yaml +1 -1
  241. package/library/skills/headless-scripting/SKILL.md +14 -1
  242. package/library/skills/headless-scripting/resource.yaml +1 -1
  243. package/library/skills/in-game-purchases/SKILL.md +12 -1
  244. package/library/skills/in-game-purchases/resource.yaml +1 -1
  245. package/library/skills/instantiate-asset-pack/SKILL.md +19 -2
  246. package/library/skills/instantiate-asset-pack/resource.yaml +1 -1
  247. package/library/skills/lumera-single-image-scene-reconstruction/resource.yaml +1 -0
  248. package/library/skills/make-game/SKILL.md +33 -4
  249. package/library/skills/make-game/references/2d-platformer.md +1 -1
  250. package/library/skills/make-game/references/3d-fps.md +1 -1
  251. package/library/skills/make-game/references/3d-horror.md +1 -1
  252. package/library/skills/make-game/references/3d-third-person.md +2 -2
  253. package/library/skills/make-game/resource.yaml +1 -1
  254. package/library/skills/multiplayer/SKILL.md +13 -1
  255. package/library/skills/multiplayer/resource.yaml +1 -1
  256. package/library/skills/multiplayer-movement/SKILL.md +19 -1
  257. package/library/skills/multiplayer-movement/resource.yaml +1 -1
  258. package/library/skills/multiplayer-project/SKILL.md +18 -1
  259. package/library/skills/multiplayer-project/resource.yaml +1 -1
  260. package/library/skills/multiplayer-publish/SKILL.md +25 -7
  261. package/library/skills/multiplayer-publish/resource.yaml +3 -3
  262. package/library/skills/multiplayer-state/SKILL.md +17 -1
  263. package/library/skills/multiplayer-state/resource.yaml +1 -1
  264. package/library/skills/multiplayer-testing/SKILL.md +16 -1
  265. package/library/skills/multiplayer-testing/resource.yaml +1 -1
  266. package/library/skills/music-track/SKILL.md +38 -13
  267. package/library/skills/music-track/resource.yaml +1 -1
  268. package/library/skills/navigate-summer/SKILL.md +26 -9
  269. package/library/skills/navigate-summer/resource.yaml +1 -1
  270. package/library/skills/new-project/SKILL.md +12 -1
  271. package/library/skills/new-project/resource.yaml +1 -1
  272. package/library/skills/organic-model/SKILL.md +48 -18
  273. package/library/skills/organic-model/resource.yaml +1 -1
  274. package/library/skills/pixel-art/SKILL.md +42 -23
  275. package/library/skills/pixel-art/resource.yaml +1 -1
  276. package/library/skills/play/SKILL.md +19 -1
  277. package/library/skills/play/resource.yaml +1 -1
  278. package/library/skills/playtesting-a-feature/SKILL.md +24 -1
  279. package/library/skills/playtesting-a-feature/resource.yaml +1 -1
  280. package/library/skills/procedural-animation/SKILL.md +38 -16
  281. package/library/skills/procedural-animation/resource.yaml +1 -1
  282. package/library/skills/prop-model/SKILL.md +48 -19
  283. package/library/skills/prop-model/resource.yaml +1 -1
  284. package/library/skills/psx-retro-rendering/resource.yaml +1 -0
  285. package/library/skills/publish-your-game/SKILL.md +43 -6
  286. package/library/skills/publish-your-game/resource.yaml +3 -3
  287. package/library/skills/realtime-wet-surfaces/resource.yaml +1 -0
  288. package/library/skills/release-readiness/SKILL.md +13 -1
  289. package/library/skills/release-readiness/resource.yaml +1 -1
  290. package/library/skills/remote-deploy/SKILL.md +15 -1
  291. package/library/skills/remote-deploy/resource.yaml +1 -1
  292. package/library/skills/retarget/SKILL.md +43 -20
  293. package/library/skills/retarget/resource.yaml +1 -1
  294. package/library/skills/running-in-the-cloud/SKILL.md +11 -1
  295. package/library/skills/running-in-the-cloud/resource.yaml +1 -1
  296. package/library/skills/save-load/SKILL.md +16 -1
  297. package/library/skills/save-load/resource.yaml +1 -1
  298. package/library/skills/scene-composition/SKILL.md +18 -1
  299. package/library/skills/scene-composition/resource.yaml +1 -1
  300. package/library/skills/scene-hierarchy-design/SKILL.md +26 -2
  301. package/library/skills/scene-hierarchy-design/resource.yaml +1 -1
  302. package/library/skills/scene-scripting/SKILL.md +96 -636
  303. package/library/skills/scene-scripting/references/ctx-api.md +184 -0
  304. package/library/skills/scene-scripting/references/recipes-2d-ui.md +193 -0
  305. package/library/skills/scene-scripting/references/recipes-3d.md +280 -0
  306. package/library/skills/scene-scripting/resource.yaml +4 -4
  307. package/library/skills/scene-to-level/SKILL.md +24 -2
  308. package/library/skills/scene-to-level/resource.yaml +1 -1
  309. package/library/skills/skill-create/resource.yaml +1 -0
  310. package/library/skills/skill-improve/resource.yaml +1 -0
  311. package/library/skills/skill-test/SKILL.md +12 -2
  312. package/library/skills/skill-test/resource.yaml +1 -0
  313. package/library/skills/skintokens-auto-rigging/resource.yaml +1 -0
  314. package/library/skills/skybox-panorama/SKILL.md +47 -21
  315. package/library/skills/skybox-panorama/resource.yaml +1 -1
  316. package/library/skills/sound-effect/SKILL.md +52 -20
  317. package/library/skills/sound-effect/resource.yaml +1 -1
  318. package/library/skills/spatial-placement/SKILL.md +44 -9
  319. package/library/skills/spatial-placement/resource.yaml +1 -1
  320. package/library/skills/sprite-sheet/SKILL.md +55 -27
  321. package/library/skills/sprite-sheet/resource.yaml +1 -1
  322. package/library/skills/store-art/SKILL.md +14 -3
  323. package/library/skills/store-art/resource.yaml +2 -2
  324. package/library/skills/store-listing/SKILL.md +13 -3
  325. package/library/skills/store-listing/resource.yaml +2 -2
  326. package/library/skills/summer-analytics/SKILL.md +22 -5
  327. package/library/skills/summer-analytics/resource.yaml +2 -2
  328. package/library/skills/summer-apps/SKILL.md +77 -32
  329. package/library/skills/summer-apps/manifest.md +1 -1
  330. package/library/skills/summer-apps/minimal-app.md +7 -7
  331. package/library/skills/summer-apps/resource.yaml +1 -1
  332. package/library/skills/summer-apps/sdk-reference.md +5 -5
  333. package/library/skills/summer-apps-design/SKILL.md +1 -1
  334. package/library/skills/summer-apps-design/resource.yaml +1 -1
  335. package/library/skills/summer-assets/SKILL.md +86 -0
  336. package/library/skills/summer-assets/resource.yaml +34 -0
  337. package/library/skills/summer-cli/SKILL.md +133 -0
  338. package/library/skills/summer-cli/resource.yaml +31 -0
  339. package/library/skills/summer-friends/SKILL.md +14 -0
  340. package/library/skills/summer-leaderboards/SKILL.md +16 -0
  341. package/library/skills/summer-match-results/SKILL.md +17 -0
  342. package/library/skills/summer-matchmaking/SKILL.md +17 -0
  343. package/library/skills/summer-parties/SKILL.md +14 -0
  344. package/library/skills/summer-player-data/SKILL.md +14 -0
  345. package/library/skills/summer-store/SKILL.md +16 -1
  346. package/library/skills/summer-world-chat/SKILL.md +14 -0
  347. package/library/skills/summer-world-saves/SKILL.md +14 -0
  348. package/library/skills/text-to-motion/SKILL.md +45 -23
  349. package/library/skills/text-to-motion/prompts-and-controls.md +5 -5
  350. package/library/skills/text-to-motion/resource.yaml +1 -1
  351. package/library/skills/text-to-motion/rigging-for-text-motion.md +2 -2
  352. package/library/skills/tileable-texture/SKILL.md +37 -15
  353. package/library/skills/tileable-texture/resource.yaml +1 -1
  354. package/library/skills/trailer-shot/SKILL.md +46 -24
  355. package/library/skills/trailer-shot/resource.yaml +1 -1
  356. package/library/skills/tune-performance/SKILL.md +32 -6
  357. package/library/skills/tune-performance/resource.yaml +1 -1
  358. package/library/skills/ui-basics/SKILL.md +55 -36
  359. package/library/skills/ui-basics/resource.yaml +1 -1
  360. package/library/skills/ui-graphics/SKILL.md +64 -38
  361. package/library/skills/ui-graphics/resource.yaml +1 -1
  362. package/library/skills/use-widget-asset/SKILL.md +15 -1
  363. package/library/skills/use-widget-asset/resource.yaml +1 -1
  364. package/library/skills/using-summer/SKILL.md +32 -5
  365. package/library/skills/using-summer/resource.yaml +3 -2
  366. package/library/skills/vehicle-model/SKILL.md +92 -57
  367. package/library/skills/vehicle-model/resource.yaml +1 -1
  368. package/library/skills/verification-before-completion/SKILL.md +1 -1
  369. package/library/skills/verification-before-completion/resource.yaml +1 -1
  370. package/library/skills/verifying-scenes/SKILL.md +31 -2
  371. package/library/skills/verifying-scenes/resource.yaml +1 -1
  372. package/library/skills/vfx-dissolve/SKILL.md +21 -2
  373. package/library/skills/vfx-dissolve/resource.yaml +1 -1
  374. package/library/skills/vfx-fire/SKILL.md +41 -41
  375. package/library/skills/vfx-fire/resource.yaml +1 -1
  376. package/library/skills/vfx-hit-spark/SKILL.md +24 -1
  377. package/library/skills/vfx-hit-spark/resource.yaml +1 -1
  378. package/library/skills/vfx-lightning/SKILL.md +30 -16
  379. package/library/skills/vfx-lightning/resource.yaml +1 -1
  380. package/library/skills/vfx-magic-glow/SKILL.md +46 -32
  381. package/library/skills/vfx-magic-glow/resource.yaml +1 -1
  382. package/library/skills/vfx-muzzle-flash/SKILL.md +43 -35
  383. package/library/skills/vfx-muzzle-flash/resource.yaml +1 -1
  384. package/library/skills/vfx-smoke/SKILL.md +39 -31
  385. package/library/skills/vfx-smoke/resource.yaml +1 -1
  386. package/library/skills/vfx-water-ripple/SKILL.md +35 -31
  387. package/library/skills/vfx-water-ripple/resource.yaml +1 -1
  388. package/library/skills/voice-line/SKILL.md +87 -40
  389. package/library/skills/voice-line/resource.yaml +1 -1
  390. package/library/skills/web-and-touch-input/SKILL.md +20 -1
  391. package/library/skills/web-and-touch-input/resource.yaml +1 -1
  392. package/library/skills/web-compatibility-look/SKILL.md +21 -1
  393. package/library/skills/web-compatibility-look/resource.yaml +1 -1
  394. package/library/skills/world-building-3d/SKILL.md +29 -1
  395. package/library/skills/world-building-3d/resource.yaml +1 -1
  396. package/library/skills/writing-skills/resource.yaml +1 -0
  397. package/library/tools/add-node/GUIDE.md +14 -0
  398. package/library/tools/align-distribute-3d/GUIDE.md +7 -0
  399. package/library/tools/app-call/resource.yaml +1 -1
  400. package/library/tools/app-guide/resource.yaml +2 -2
  401. package/library/tools/app-page/resource.yaml +1 -1
  402. package/library/tools/app-screenshot/resource.yaml +19 -1
  403. package/library/tools/app-tools/resource.yaml +1 -1
  404. package/library/tools/attach-to-surface/GUIDE.md +15 -0
  405. package/library/tools/batch/GUIDE.md +27 -0
  406. package/library/tools/camera-bookmark/GUIDE.md +12 -0
  407. package/library/tools/capture-gameplay/GUIDE.md +3 -0
  408. package/library/tools/capture-gameplay/resource.yaml +3 -3
  409. package/library/tools/check-job/resource.yaml +1 -1
  410. package/library/tools/clear-console/GUIDE.md +3 -0
  411. package/library/tools/connect-ports/GUIDE.md +9 -0
  412. package/library/tools/connect-signal/GUIDE.md +14 -0
  413. package/library/tools/create-debug-report/GUIDE.md +10 -0
  414. package/library/tools/create-scene/GUIDE.md +10 -0
  415. package/library/tools/debug-views/GUIDE.md +7 -0
  416. package/library/tools/enable-plugin/GUIDE.md +3 -0
  417. package/library/tools/export-game/GUIDE.md +3 -0
  418. package/library/tools/export-game/resource.yaml +3 -3
  419. package/library/tools/export-templates/GUIDE.md +3 -0
  420. package/library/tools/fabricate-3d/GUIDE.md +19 -0
  421. package/library/tools/frame-nodes/GUIDE.md +9 -0
  422. package/library/tools/frame-shot/GUIDE.md +9 -0
  423. package/library/tools/game-control/GUIDE.md +9 -0
  424. package/library/tools/game-input/GUIDE.md +9 -0
  425. package/library/tools/game-probe/GUIDE.md +9 -0
  426. package/library/tools/generate-3d/resource.yaml +3 -3
  427. package/library/tools/generate-motion/resource.yaml +2 -2
  428. package/library/tools/get-console/GUIDE.md +9 -0
  429. package/library/tools/get-console/resource.yaml +5 -0
  430. package/library/tools/get-debugger-errors/GUIDE.md +7 -0
  431. package/library/tools/get-debugger-errors/resource.yaml +5 -0
  432. package/library/tools/get-debugger-warnings/GUIDE.md +7 -0
  433. package/library/tools/get-debugger-warnings/resource.yaml +5 -0
  434. package/library/tools/get-diagnostics/GUIDE.md +13 -0
  435. package/library/tools/get-project-context/GUIDE.md +25 -0
  436. package/library/tools/get-runtime-tree/GUIDE.md +7 -0
  437. package/library/tools/get-runtime-tree/resource.yaml +5 -0
  438. package/library/tools/get-scene-tree/GUIDE.md +11 -0
  439. package/library/tools/get-scene-tree/resource.yaml +5 -0
  440. package/library/tools/get-script-errors/GUIDE.md +5 -0
  441. package/library/tools/grep/GUIDE.md +11 -0
  442. package/library/tools/import-asset/GUIDE.md +8 -0
  443. package/library/tools/import-asset-by-id/GUIDE.md +12 -0
  444. package/library/tools/import-from-url/GUIDE.md +10 -0
  445. package/library/tools/import-from-url-batch/GUIDE.md +3 -0
  446. package/library/tools/import-hdri/GUIDE.md +16 -0
  447. package/library/tools/input-map-bind/GUIDE.md +11 -0
  448. package/library/tools/inspect-asset/GUIDE.md +14 -0
  449. package/library/tools/inspect-asset/resource.yaml +5 -0
  450. package/library/tools/inspect-node/GUIDE.md +11 -0
  451. package/library/tools/inspect-node/resource.yaml +5 -0
  452. package/library/tools/inspect-resource/GUIDE.md +7 -0
  453. package/library/tools/inspect-resource/resource.yaml +5 -0
  454. package/library/tools/inspect-runtime-node/GUIDE.md +7 -0
  455. package/library/tools/inspect-runtime-node/resource.yaml +5 -0
  456. package/library/tools/instantiate-scene/GUIDE.md +12 -0
  457. package/library/tools/is-running/GUIDE.md +3 -0
  458. package/library/tools/measure/GUIDE.md +8 -0
  459. package/library/tools/navigation-probe/GUIDE.md +9 -0
  460. package/library/tools/open/resource.yaml +2 -2
  461. package/library/tools/open-main-scene/GUIDE.md +6 -0
  462. package/library/tools/open-scene/GUIDE.md +8 -0
  463. package/library/tools/place-adjacent/GUIDE.md +7 -0
  464. package/library/tools/play/GUIDE.md +13 -0
  465. package/library/tools/project-setting/GUIDE.md +9 -0
  466. package/library/tools/publish-build/resource.yaml +6 -6
  467. package/library/tools/raycast/GUIDE.md +7 -0
  468. package/library/tools/read-file/GUIDE.md +10 -0
  469. package/library/tools/read-library/resource.yaml +5 -0
  470. package/library/tools/recent-events/GUIDE.md +7 -0
  471. package/library/tools/remove-node/GUIDE.md +3 -0
  472. package/library/tools/repeat-along/GUIDE.md +5 -0
  473. package/library/tools/replace-node/GUIDE.md +9 -0
  474. package/library/tools/replace-text/GUIDE.md +5 -0
  475. package/library/tools/run-editor-script/GUIDE.md +16 -0
  476. package/library/tools/run-script/GUIDE.md +30 -0
  477. package/library/tools/run-script/resource.yaml +6 -3
  478. package/library/tools/runtime-animate/GUIDE.md +7 -0
  479. package/library/tools/runtime-call/GUIDE.md +7 -0
  480. package/library/tools/runtime-set/GUIDE.md +9 -0
  481. package/library/tools/runtime-spawn/GUIDE.md +9 -0
  482. package/library/tools/save-scene/GUIDE.md +3 -0
  483. package/library/tools/scene-audit/GUIDE.md +29 -0
  484. package/library/tools/screenshot/GUIDE.md +17 -0
  485. package/library/tools/select-node/GUIDE.md +3 -0
  486. package/library/tools/set-prop/GUIDE.md +23 -0
  487. package/library/tools/set-resource-property/GUIDE.md +8 -0
  488. package/library/tools/shot-sheet/GUIDE.md +7 -0
  489. package/library/tools/snap-to-surface/GUIDE.md +17 -0
  490. package/library/tools/snapshot-diff/GUIDE.md +7 -0
  491. package/library/tools/starcast/GUIDE.md +12 -0
  492. package/library/tools/stop/GUIDE.md +3 -0
  493. package/library/tools/test-placement/GUIDE.md +7 -0
  494. package/library/tools/ui-actions/GUIDE.md +12 -0
  495. package/library/tools/ui-activate/GUIDE.md +11 -0
  496. package/library/tools/ui-screenshot/GUIDE.md +9 -0
  497. package/library/tools/ui-tree/GUIDE.md +10 -0
  498. package/library/tools/wait-for-event/GUIDE.md +11 -0
  499. package/library/tools/world-snapshot/GUIDE.md +9 -0
  500. package/library/tools/write-file/GUIDE.md +5 -0
  501. package/library/tools/zoom/GUIDE.md +5 -0
  502. package/package.json +8 -5
  503. package/registry/generated/counts.json +2 -2
  504. package/registry/generated/gemini-extension.json +6 -13
  505. package/registry/generated/index.json +482 -349
  506. package/registry/generated/marketplace.claude.json +2 -13
  507. package/registry/generated/plugin.claude-directory.json +168 -0
  508. package/registry/generated/plugin.claude.json +24 -22
  509. package/registry/generated/plugin.codex.json +18 -22
  510. package/registry/generated/plugin.cursor.json +8 -14
  511. package/registry/generated/plugin.factory.json +6 -13
  512. package/registry/generated/server.json +43 -0
  513. package/registry/generated/skills-index.md +121 -118
  514. package/registry/generated/skills-registry.json +167 -115
  515. package/registry/operations/fixtures/invalid-deprecated-without-replacement.json +60 -0
  516. package/registry/operations/fixtures/invalid-name.json +60 -0
  517. package/registry/operations/fixtures/invalid-publish-without-owner.json +82 -0
  518. package/registry/operations/fixtures/invalid-spend-without-estimate.json +42 -0
  519. package/registry/operations/fixtures/invalid-unknown-field.json +61 -0
  520. package/registry/operations/fixtures/valid-player-facing.json +82 -0
  521. package/registry/operations/fixtures/valid-read.json +60 -0
  522. package/registry/operations/fixtures/valid-spend.json +43 -0
  523. package/registry/operations/legacy-names.json +1241 -0
  524. package/registry/operations/public-catalog.json +33160 -0
  525. package/registry/schemas/operation.schema.json +318 -0
  526. package/registry/schemas/skill.schema.json +4 -0
  527. package/CLAUDE.md +0 -7
@@ -140,18 +140,18 @@ export declare const runtimeSpawnArgsSchema: z.ZodObject<{
140
140
  }, "strip", z.ZodTypeAny, {
141
141
  action: "spawn" | "free";
142
142
  mode?: "free" | "queue_free" | undefined;
143
+ name?: string | undefined;
143
144
  instance?: string | undefined;
144
145
  scene?: string | undefined;
145
- name?: string | undefined;
146
146
  path?: string | undefined;
147
147
  parent?: string | undefined;
148
148
  props?: Record<string, string | number | boolean> | undefined;
149
149
  }, {
150
150
  action: "spawn" | "free";
151
151
  mode?: "free" | "queue_free" | undefined;
152
+ name?: string | undefined;
152
153
  instance?: string | undefined;
153
154
  scene?: string | undefined;
154
- name?: string | undefined;
155
155
  path?: string | undefined;
156
156
  parent?: string | undefined;
157
157
  props?: Record<string, string | number | boolean> | undefined;
@@ -181,15 +181,15 @@ export declare const runtimeAnimateArgsSchema: z.ZodObject<{
181
181
  instance: z.ZodOptional<z.ZodString>;
182
182
  }, "strip", z.ZodTypeAny, {
183
183
  path: string;
184
- target: "tree" | "player" | "bones";
184
+ target: "player" | "tree" | "bones";
185
+ name?: string | undefined;
185
186
  state?: string | undefined;
186
187
  value?: string | number | boolean | undefined;
187
188
  instance?: string | undefined;
188
- name?: string | undefined;
189
189
  space?: "local" | "global" | "both" | undefined;
190
- cmd?: "state" | "pause" | "play" | "stop" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
191
- blend?: number | undefined;
190
+ cmd?: "state" | "pause" | "play" | "start" | "stop" | "seek" | "speed" | "travel" | "set_param" | "get_param" | undefined;
192
191
  position?: number | undefined;
192
+ blend?: number | undefined;
193
193
  speed?: number | undefined;
194
194
  bones?: string[] | undefined;
195
195
  from_end?: boolean | undefined;
@@ -200,15 +200,15 @@ export declare const runtimeAnimateArgsSchema: z.ZodObject<{
200
200
  include_rest?: boolean | undefined;
201
201
  }, {
202
202
  path: string;
203
- target: "tree" | "player" | "bones";
203
+ target: "player" | "tree" | "bones";
204
+ name?: string | undefined;
204
205
  state?: string | undefined;
205
206
  value?: string | number | boolean | undefined;
206
207
  instance?: string | undefined;
207
- name?: string | undefined;
208
208
  space?: "local" | "global" | "both" | undefined;
209
- cmd?: "state" | "pause" | "play" | "stop" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
210
- blend?: number | undefined;
209
+ cmd?: "state" | "pause" | "play" | "start" | "stop" | "seek" | "speed" | "travel" | "set_param" | "get_param" | undefined;
211
210
  position?: number | undefined;
211
+ blend?: number | undefined;
212
212
  speed?: number | undefined;
213
213
  bones?: string[] | undefined;
214
214
  from_end?: boolean | undefined;
@@ -227,17 +227,17 @@ export declare const gameControlArgsSchema: z.ZodObject<{
227
227
  speed: z.ZodOptional<z.ZodNumber>;
228
228
  instance: z.ZodOptional<z.ZodString>;
229
229
  }, "strip", z.ZodTypeAny, {
230
- action: "instances" | "pause" | "resume" | "speed" | "step";
230
+ action: "instances" | "pause" | "resume" | "step" | "speed";
231
231
  instance?: string | undefined;
232
232
  kind?: "physics" | "process" | undefined;
233
- speed?: number | undefined;
234
233
  frames?: number | undefined;
234
+ speed?: number | undefined;
235
235
  }, {
236
- action: "instances" | "pause" | "resume" | "speed" | "step";
236
+ action: "instances" | "pause" | "resume" | "step" | "speed";
237
237
  instance?: string | undefined;
238
238
  kind?: "physics" | "process" | undefined;
239
- speed?: number | undefined;
240
239
  frames?: number | undefined;
240
+ speed?: number | undefined;
241
241
  }>;
242
242
  export type GameControlArgs = z.infer<typeof gameControlArgsSchema>;
243
243
  export declare function buildGameControlOp(args: GameControlArgs): BuiltRuntimeOp;
@@ -259,15 +259,15 @@ export declare const inputEventSchema: z.ZodObject<{
259
259
  class: z.ZodOptional<z.ZodString>;
260
260
  props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
261
261
  }, "strip", z.ZodTypeAny, {
262
- type: "key" | "action" | "mouse_click" | "axis" | "raw";
262
+ type: "key" | "action" | "axis" | "mouse_click" | "raw";
263
263
  action?: string | undefined;
264
- button?: number | undefined;
265
- class?: string | undefined;
266
264
  position?: [number, number] | undefined;
265
+ pressed?: boolean | undefined;
267
266
  props?: Record<string, unknown> | undefined;
267
+ button?: number | undefined;
268
+ class?: string | undefined;
268
269
  at_frame?: number | undefined;
269
270
  at_ms?: number | undefined;
270
- pressed?: boolean | undefined;
271
271
  strength?: number | undefined;
272
272
  hold_ms?: number | undefined;
273
273
  keycode?: number | undefined;
@@ -276,15 +276,15 @@ export declare const inputEventSchema: z.ZodObject<{
276
276
  action_positive?: string | undefined;
277
277
  duration_ms?: number | undefined;
278
278
  }, {
279
- type: "key" | "action" | "mouse_click" | "axis" | "raw";
279
+ type: "key" | "action" | "axis" | "mouse_click" | "raw";
280
280
  action?: string | undefined;
281
- button?: number | undefined;
282
- class?: string | undefined;
283
281
  position?: [number, number] | undefined;
282
+ pressed?: boolean | undefined;
284
283
  props?: Record<string, unknown> | undefined;
284
+ button?: number | undefined;
285
+ class?: string | undefined;
285
286
  at_frame?: number | undefined;
286
287
  at_ms?: number | undefined;
287
- pressed?: boolean | undefined;
288
288
  strength?: number | undefined;
289
289
  hold_ms?: number | undefined;
290
290
  keycode?: number | undefined;
@@ -314,15 +314,15 @@ export declare const gameInputArgsSchema: z.ZodObject<{
314
314
  class: z.ZodOptional<z.ZodString>;
315
315
  props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
316
316
  }, "strip", z.ZodTypeAny, {
317
- type: "key" | "action" | "mouse_click" | "axis" | "raw";
317
+ type: "key" | "action" | "axis" | "mouse_click" | "raw";
318
318
  action?: string | undefined;
319
- button?: number | undefined;
320
- class?: string | undefined;
321
319
  position?: [number, number] | undefined;
320
+ pressed?: boolean | undefined;
322
321
  props?: Record<string, unknown> | undefined;
322
+ button?: number | undefined;
323
+ class?: string | undefined;
323
324
  at_frame?: number | undefined;
324
325
  at_ms?: number | undefined;
325
- pressed?: boolean | undefined;
326
326
  strength?: number | undefined;
327
327
  hold_ms?: number | undefined;
328
328
  keycode?: number | undefined;
@@ -331,15 +331,15 @@ export declare const gameInputArgsSchema: z.ZodObject<{
331
331
  action_positive?: string | undefined;
332
332
  duration_ms?: number | undefined;
333
333
  }, {
334
- type: "key" | "action" | "mouse_click" | "axis" | "raw";
334
+ type: "key" | "action" | "axis" | "mouse_click" | "raw";
335
335
  action?: string | undefined;
336
- button?: number | undefined;
337
- class?: string | undefined;
338
336
  position?: [number, number] | undefined;
337
+ pressed?: boolean | undefined;
339
338
  props?: Record<string, unknown> | undefined;
339
+ button?: number | undefined;
340
+ class?: string | undefined;
340
341
  at_frame?: number | undefined;
341
342
  at_ms?: number | undefined;
342
- pressed?: boolean | undefined;
343
343
  strength?: number | undefined;
344
344
  hold_ms?: number | undefined;
345
345
  keycode?: number | undefined;
@@ -358,15 +358,15 @@ export declare const gameInputArgsSchema: z.ZodObject<{
358
358
  }, "strip", z.ZodTypeAny, {
359
359
  action: "script" | "record_start" | "record_stop" | "replay";
360
360
  events?: {
361
- type: "key" | "action" | "mouse_click" | "axis" | "raw";
361
+ type: "key" | "action" | "axis" | "mouse_click" | "raw";
362
362
  action?: string | undefined;
363
- button?: number | undefined;
364
- class?: string | undefined;
365
363
  position?: [number, number] | undefined;
364
+ pressed?: boolean | undefined;
366
365
  props?: Record<string, unknown> | undefined;
366
+ button?: number | undefined;
367
+ class?: string | undefined;
367
368
  at_frame?: number | undefined;
368
369
  at_ms?: number | undefined;
369
- pressed?: boolean | undefined;
370
370
  strength?: number | undefined;
371
371
  hold_ms?: number | undefined;
372
372
  keycode?: number | undefined;
@@ -385,15 +385,15 @@ export declare const gameInputArgsSchema: z.ZodObject<{
385
385
  }, {
386
386
  action: "script" | "record_start" | "record_stop" | "replay";
387
387
  events?: {
388
- type: "key" | "action" | "mouse_click" | "axis" | "raw";
388
+ type: "key" | "action" | "axis" | "mouse_click" | "raw";
389
389
  action?: string | undefined;
390
- button?: number | undefined;
391
- class?: string | undefined;
392
390
  position?: [number, number] | undefined;
391
+ pressed?: boolean | undefined;
393
392
  props?: Record<string, unknown> | undefined;
393
+ button?: number | undefined;
394
+ class?: string | undefined;
394
395
  at_frame?: number | undefined;
395
396
  at_ms?: number | undefined;
396
- pressed?: boolean | undefined;
397
397
  strength?: number | undefined;
398
398
  hold_ms?: number | undefined;
399
399
  keycode?: number | undefined;
@@ -436,23 +436,23 @@ export declare const gameProbeArgsSchema: z.ZodObject<{
436
436
  instance: z.ZodOptional<z.ZodString>;
437
437
  }, "strip", z.ZodTypeAny, {
438
438
  instance?: string | undefined;
439
+ props?: string[] | undefined;
440
+ screenshot?: boolean | undefined;
439
441
  tree?: {
440
442
  path?: string | undefined;
441
443
  limit?: number | undefined;
442
444
  depth?: number | undefined;
443
445
  } | undefined;
444
- props?: string[] | undefined;
445
- screenshot?: boolean | undefined;
446
446
  max_dim?: number | undefined;
447
447
  }, {
448
448
  instance?: string | undefined;
449
+ props?: string[] | undefined;
450
+ screenshot?: boolean | undefined;
449
451
  tree?: {
450
452
  path?: string | undefined;
451
453
  limit?: number | undefined;
452
454
  depth?: number | undefined;
453
455
  } | undefined;
454
- props?: string[] | undefined;
455
- screenshot?: boolean | undefined;
456
456
  max_dim?: number | undefined;
457
457
  }>;
458
458
  export type GameProbeArgs = z.infer<typeof gameProbeArgsSchema>;
@@ -0,0 +1,17 @@
1
+ import { type RunSceneScriptArgs } from "./scene-script.js";
2
+ export interface SceneScriptClient {
3
+ executeIdentityBoundOps(ops: Record<string, unknown>[], options?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
4
+ getSceneState(): Promise<unknown>;
5
+ }
6
+ export interface SceneTarget {
7
+ scenePath: string;
8
+ /** The script's scene was not the edited one, so its tab was brought forward. */
9
+ opened: boolean;
10
+ /** The scene the editor showed before, opened again after the run. */
11
+ restored?: string;
12
+ /** Why that tab could not be restored (the script still ran). */
13
+ restore_error?: string;
14
+ }
15
+ export declare function runSceneScriptOn(client: SceneScriptClient, args: RunSceneScriptArgs & {
16
+ scenePath?: string;
17
+ }): Promise<unknown>;
@@ -0,0 +1,70 @@
1
+ /**
2
+ * summer_run_script with a target scene. The engine's RunSceneScript runs
3
+ * against the scene the editor is editing and takes no target of its own, so
4
+ * a scenePath is honored here, the same way for the MCP tool and the CLI:
5
+ *
6
+ * 1. Read the scene the editor is editing (a snapshot up to ~300 ms old).
7
+ * 2. OpenScene scenePath, alone (never in one batch with a mutation), even
8
+ * when the snapshot says it is already the edited scene: the person may
9
+ * have switched tabs since, and opening the current scene again changes
10
+ * nothing. The engine answers ok only once that scene is the edited one,
11
+ * so a failed open stops here and the script never runs.
12
+ * 3. Run the script.
13
+ * 4. Give the person back the tab they had (OpenScene of the earlier scene),
14
+ * as the engine's own scene-targeted ops do.
15
+ *
16
+ * The result is the engine's RunSceneScript receipt plus `scene_target`.
17
+ */
18
+ import { resolveCurrentScene } from "./project-context.js";
19
+ import { buildRunSceneScriptOp } from "./scene-script.js";
20
+ import { validateScenePath } from "./seeing/seeing.js";
21
+ import { extractOpError } from "./engine-receipt.js";
22
+ function withTarget(result, target) {
23
+ return result && typeof result === "object" && !Array.isArray(result)
24
+ ? { ...result, scene_target: target }
25
+ : { result, scene_target: target };
26
+ }
27
+ export async function runSceneScriptOn(client, args) {
28
+ const { op, timeoutMs } = buildRunSceneScriptOp(args);
29
+ if (args.scenePath === undefined)
30
+ return client.executeIdentityBoundOps([op], undefined, timeoutMs);
31
+ const scenePath = validateScenePath(args.scenePath);
32
+ let before = null;
33
+ let beforeError;
34
+ try {
35
+ before = resolveCurrentScene(undefined, await client.getSceneState(), undefined);
36
+ }
37
+ catch (error) {
38
+ beforeError = error instanceof Error ? error.message : String(error);
39
+ }
40
+ const open = await client.executeIdentityBoundOps([{ op: "OpenScene", path: scenePath }]);
41
+ const openError = extractOpError(open);
42
+ if (openError) {
43
+ return {
44
+ ok: false,
45
+ error: `Could not open ${scenePath}, so the script did not run. ${openError}`,
46
+ failure_reason: "scene_target_failed",
47
+ scene_target: { scenePath, opened: false },
48
+ receipt: open,
49
+ };
50
+ }
51
+ const opened = before !== scenePath;
52
+ const result = await client.executeIdentityBoundOps([op], undefined, timeoutMs);
53
+ const target = { scenePath, opened };
54
+ if (beforeError !== undefined)
55
+ target.restore_error = `The scene open before could not be read, so no tab was restored: ${beforeError}`;
56
+ if (opened && before) {
57
+ try {
58
+ const restore = await client.executeIdentityBoundOps([{ op: "OpenScene", path: before }]);
59
+ const restoreError = extractOpError(restore);
60
+ if (restoreError)
61
+ target.restore_error = restoreError;
62
+ else
63
+ target.restored = before;
64
+ }
65
+ catch (error) {
66
+ target.restore_error = error instanceof Error ? error.message : String(error);
67
+ }
68
+ }
69
+ return withTarget(result, target);
70
+ }
@@ -124,10 +124,10 @@ export declare const frameNodesArgsSchema: z.ZodObject<{
124
124
  marks?: boolean | undefined;
125
125
  max_marks?: number | undefined;
126
126
  from?: string | undefined;
127
- max_size?: number | undefined;
127
+ direction?: "top" | "front" | "iso" | "back" | "left" | "right" | undefined;
128
128
  bookmark_name?: string | undefined;
129
+ max_size?: number | undefined;
129
130
  aspect?: number | undefined;
130
- direction?: "top" | "iso" | "front" | "back" | "left" | "right" | undefined;
131
131
  }, {
132
132
  nodes: string[];
133
133
  fill?: number | undefined;
@@ -136,10 +136,10 @@ export declare const frameNodesArgsSchema: z.ZodObject<{
136
136
  marks?: boolean | undefined;
137
137
  max_marks?: number | undefined;
138
138
  from?: string | undefined;
139
- max_size?: number | undefined;
139
+ direction?: "top" | "front" | "iso" | "back" | "left" | "right" | undefined;
140
140
  bookmark_name?: string | undefined;
141
+ max_size?: number | undefined;
141
142
  aspect?: number | undefined;
142
- direction?: "top" | "iso" | "front" | "back" | "left" | "right" | undefined;
143
143
  }>;
144
144
  export declare const shotSheetArgsSchema: z.ZodObject<{
145
145
  scenePath: z.ZodOptional<z.ZodString>;
@@ -177,12 +177,12 @@ export declare const shotSheetArgsSchema: z.ZodObject<{
177
177
  bookmark_name?: string | undefined;
178
178
  }[];
179
179
  scenePath?: string | undefined;
180
+ compare_previous?: boolean | undefined;
180
181
  max_size?: number | undefined;
181
182
  save_to?: string | undefined;
182
183
  view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
183
184
  update_previous?: boolean | undefined;
184
185
  aspect?: number | undefined;
185
- compare_previous?: boolean | undefined;
186
186
  }, {
187
187
  shots: {
188
188
  camera_position?: string | undefined;
@@ -192,12 +192,12 @@ export declare const shotSheetArgsSchema: z.ZodObject<{
192
192
  bookmark_name?: string | undefined;
193
193
  }[];
194
194
  scenePath?: string | undefined;
195
+ compare_previous?: boolean | undefined;
195
196
  max_size?: number | undefined;
196
197
  save_to?: string | undefined;
197
198
  view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
198
199
  update_previous?: boolean | undefined;
199
200
  aspect?: number | undefined;
200
- compare_previous?: boolean | undefined;
201
201
  }>;
202
202
  export declare const debugViewsArgsSchema: z.ZodObject<{
203
203
  scenePath: z.ZodOptional<z.ZodString>;
@@ -215,9 +215,9 @@ export declare const debugViewsArgsSchema: z.ZodObject<{
215
215
  camera_position?: string | undefined;
216
216
  camera_look_at?: string | undefined;
217
217
  fov?: number | undefined;
218
+ bookmark_name?: string | undefined;
218
219
  max_size?: number | undefined;
219
220
  save_to?: string | undefined;
220
- bookmark_name?: string | undefined;
221
221
  views?: ("lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe")[] | undefined;
222
222
  update_previous?: boolean | undefined;
223
223
  aspect?: number | undefined;
@@ -226,9 +226,9 @@ export declare const debugViewsArgsSchema: z.ZodObject<{
226
226
  camera_position?: string | undefined;
227
227
  camera_look_at?: string | undefined;
228
228
  fov?: number | undefined;
229
+ bookmark_name?: string | undefined;
229
230
  max_size?: number | undefined;
230
231
  save_to?: string | undefined;
231
- bookmark_name?: string | undefined;
232
232
  views?: ("lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe")[] | undefined;
233
233
  update_previous?: boolean | undefined;
234
234
  aspect?: number | undefined;
@@ -251,11 +251,11 @@ export declare const zoomArgsSchema: z.ZodObject<{
251
251
  camera_position?: string | undefined;
252
252
  camera_look_at?: string | undefined;
253
253
  fov?: number | undefined;
254
+ bookmark_name?: string | undefined;
255
+ region?: number[] | undefined;
254
256
  max_size?: number | undefined;
255
257
  save_to?: string | undefined;
256
- bookmark_name?: string | undefined;
257
258
  view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
258
- region?: number[] | undefined;
259
259
  mark?: number | undefined;
260
260
  reference_size?: number[] | undefined;
261
261
  pad?: number | undefined;
@@ -264,11 +264,11 @@ export declare const zoomArgsSchema: z.ZodObject<{
264
264
  camera_position?: string | undefined;
265
265
  camera_look_at?: string | undefined;
266
266
  fov?: number | undefined;
267
+ bookmark_name?: string | undefined;
268
+ region?: number[] | undefined;
267
269
  max_size?: number | undefined;
268
270
  save_to?: string | undefined;
269
- bookmark_name?: string | undefined;
270
271
  view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
271
- region?: number[] | undefined;
272
272
  mark?: number | undefined;
273
273
  reference_size?: number[] | undefined;
274
274
  pad?: number | undefined;
@@ -310,8 +310,9 @@ export declare const frameShotArgsSchema: z.ZodObject<{
310
310
  spawn?: string | undefined;
311
311
  scenePath?: string | undefined;
312
312
  fov?: number | undefined;
313
- max_size?: number | undefined;
314
313
  bookmark_name?: string | undefined;
314
+ subject?: string[] | undefined;
315
+ max_size?: number | undefined;
315
316
  render?: "none" | "sheet" | "best" | undefined;
316
317
  aspect?: number | undefined;
317
318
  occluders?: {
@@ -321,7 +322,6 @@ export declare const frameShotArgsSchema: z.ZodObject<{
321
322
  hard_layers?: number | undefined;
322
323
  soft_layers?: number | undefined;
323
324
  } | undefined;
324
- subject?: string[] | undefined;
325
325
  eye_height?: number | undefined;
326
326
  max_soft_fraction?: number | undefined;
327
327
  save_bookmark?: boolean | undefined;
@@ -330,8 +330,9 @@ export declare const frameShotArgsSchema: z.ZodObject<{
330
330
  spawn?: string | undefined;
331
331
  scenePath?: string | undefined;
332
332
  fov?: number | undefined;
333
- max_size?: number | undefined;
334
333
  bookmark_name?: string | undefined;
334
+ subject?: string[] | undefined;
335
+ max_size?: number | undefined;
335
336
  render?: "none" | "sheet" | "best" | undefined;
336
337
  aspect?: number | undefined;
337
338
  occluders?: {
@@ -341,7 +342,6 @@ export declare const frameShotArgsSchema: z.ZodObject<{
341
342
  hard_layers?: number | undefined;
342
343
  soft_layers?: number | undefined;
343
344
  } | undefined;
344
- subject?: string[] | undefined;
345
345
  eye_height?: number | undefined;
346
346
  max_soft_fraction?: number | undefined;
347
347
  save_bookmark?: boolean | undefined;
@@ -1,4 +1,5 @@
1
1
  import { z } from "zod";
2
+ import { type SummerErrorCode } from "../error-codes.js";
2
3
  /**
3
4
  * Sound-effect choices (summer_generate_sfx_choices + summer_get_choices).
4
5
  *
@@ -59,6 +60,9 @@ export interface GatewayReply {
59
60
  data?: any;
60
61
  error?: string;
61
62
  status: number;
63
+ /** Set for the shared failures (not signed in, no credits, network). */
64
+ code?: SummerErrorCode;
65
+ recovery?: string;
62
66
  }
63
67
  export interface SfxChoicesDeps {
64
68
  post(endpoint: string, body: Record<string, unknown>, timeoutMs: number): Promise<GatewayReply>;
@@ -1,4 +1,5 @@
1
1
  import { z } from "zod";
2
+ import { codedFailure } from "../error-codes.js";
2
3
  /**
3
4
  * Sound-effect choices (summer_generate_sfx_choices + summer_get_choices).
4
5
  *
@@ -59,6 +60,14 @@ export const getChoicesArgsSchema = z.object({
59
60
  .optional()
60
61
  .describe("Wait up to this many seconds (max 50) for the person to decide before answering. 0 or omitted: answer now"),
61
62
  });
63
+ /** A failed reply as a tool result; coded when the reply carries a code. */
64
+ function replyFailure(reply) {
65
+ // An unavailable reply's data is already `{details: {cause}}`.
66
+ const details = reply.code === "unavailable" ? reply.data ?? {} : reply.data ? { details: reply.data } : {};
67
+ return reply.code
68
+ ? codedFailure(reply.code, reply.error ?? "Request failed", details, reply.recovery)
69
+ : { ok: false, error: reply.error, ...details };
70
+ }
62
71
  // ---------------------------------------------------------------------------
63
72
  // Showing the page
64
73
  // ---------------------------------------------------------------------------
@@ -138,9 +147,8 @@ function clipSummary(clip) {
138
147
  }
139
148
  export async function generateSfxChoices(args, deps) {
140
149
  const reply = await deps.post(SFX_CHOICES_ENDPOINT, sfxChoicesRequestBody(args), SFX_CHOICES_TIMEOUT_MS);
141
- if (reply.error) {
142
- return { ok: false, error: reply.error, ...(reply.data ? { details: reply.data } : {}) };
143
- }
150
+ if (reply.error)
151
+ return replyFailure(reply);
144
152
  const data = reply.data ?? {};
145
153
  const clips = Array.isArray(data.clips) ? data.clips : [];
146
154
  const failed = Array.isArray(data.failed) ? data.failed : [];
@@ -211,9 +219,8 @@ export async function getChoices(args, deps) {
211
219
  if (args.waitSeconds)
212
220
  params.set("waitSeconds", String(args.waitSeconds));
213
221
  const reply = await deps.get(choicesEndpoint(args.choiceSetId), params, choicesTimeoutMs(args.waitSeconds));
214
- if (reply.error) {
215
- return { ok: false, error: reply.error, ...(reply.data ? { details: reply.data } : {}) };
216
- }
222
+ if (reply.error)
223
+ return replyFailure(reply);
217
224
  const data = reply.data ?? {};
218
225
  const clips = Array.isArray(data.clips) ? data.clips : [];
219
226
  const status = data.status === "decided" ? "decided" : "pending";
@@ -1,4 +1,5 @@
1
1
  import { EngineApiClient } from "../api-client.js";
2
+ import { type SummerErrorCode } from "../error-codes.js";
2
3
  export type DispatchArgs = Record<string, unknown>;
3
4
  export interface ToolDispatchContext {
4
5
  /** Lazily connect to the local engine. Throws EngineUnavailableError with a
@@ -19,9 +20,6 @@ export interface ToolDispatchEntry {
19
20
  /** Dispatch-level failure with a user-facing message (no stack needed). */
20
21
  export declare class ToolDispatchError extends Error {
21
22
  }
22
- /** The local engine is not reachable — a clean state, not a crash. */
23
- export declare class EngineUnavailableError extends ToolDispatchError {
24
- }
25
23
  /** A tool failed with a structured receipt that `summer tool` prints whole
26
24
  * (JSON on stdout, exit 1) instead of flattening to `message`: every engine
27
25
  * envelope extractOpError reads as a failure (the same gate the MCP face
@@ -33,6 +31,17 @@ export declare class ToolResultError extends ToolDispatchError {
33
31
  readonly result: Record<string, unknown>;
34
32
  constructor(result: Record<string, unknown>, message: string);
35
33
  }
34
+ /** A shared failure (core/error-codes.ts) — not signed in, no credits,
35
+ * network — printed as `{ok:false, code, error, recovery}` with the shell
36
+ * wording of the next step. */
37
+ export declare class CodedToolError extends ToolResultError {
38
+ constructor(code: SummerErrorCode, message: string, extra?: Record<string, unknown>, recovery?: string);
39
+ }
40
+ /** The local engine is not reachable — a clean state, not a crash. Prints
41
+ * `{ok:false, code:"engine_not_running", error, recovery, hint}`. */
42
+ export declare class EngineUnavailableError extends CodedToolError {
43
+ constructor(message: string);
44
+ }
36
45
  export declare function createDefaultDispatchContext(): ToolDispatchContext;
37
46
  export declare const TOOL_DISPATCH: readonly ToolDispatchEntry[];
38
47
  export declare function listToolDispatches(): readonly ToolDispatchEntry[];