@theprototype/agent 1.53.1 → 1.54.0

package/catalog.json

@@ -538,7 +538,7 @@
 		{
 			"name": "create_flow_nodes",
 			"title": "Add behaviour (flow) nodes",
-			"description": "Add behavior (flow) nodes to a node graph — this is how objects get MOTION and interactivity: spin, bounce, patrol a path, pulse, blink, react to clicks. graph is \"scene\" or an object uuid (ONE graph per call). KEY RULE: a behavior node placed in an OBJECT's graph with no edges automatically drives that object — most behaviors are one node, zero edges, so usually OMIT edges. A script node runs every frame FROM THE BASE POSE, so object.rotation.y += 0.02 lands at base + 0.02 and stays: write object.rotation.y = base.rot[1] + time * speed (base has pos, rot, scale as arrays). Describe nodes EITHER as text (graph lines, see the system prompt) OR as nodes/edges arrays. A call with some bad nodes still creates the good ones and returns partial:true + errors[] — resend only what errors[] names.\nMotion and interaction are flow nodes (create_flow_nodes); call describe_node_types before wiring edges.\nTake a screenshot after each change to check your work.",
+			"description": "Add behavior (flow) nodes to a node graph — this is how objects get MOTION and interactivity: spin, bounce, patrol a path, pulse, blink, react to clicks. graph is \"scene\" or an object uuid (ONE graph per call). KEY RULE: a behavior node placed in an OBJECT's graph with no edges automatically drives that object — most behaviors are one node, zero edges, so usually OMIT edges. A script node runs every frame FROM THE BASE POSE, so object.rotation.y += 0.02 lands at base + 0.02 and stays: write object.rotation.y = base.rot[1] + elapsed * speed (base has pos, rot, scale as arrays; elapsed = seconds since Play started, time = the shared clock, seconds of the day, a large number). Particle gravity is the acceleration along world Y: negative falls, positive rises. Describe nodes EITHER as text (graph lines, see the system prompt) OR as nodes/edges arrays. A call with some bad nodes still creates the good ones and returns partial:true + errors[] — resend only what errors[] names.\nMotion and interaction are flow nodes (create_flow_nodes); call describe_node_types before wiring edges.\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -613,7 +613,7 @@
 		{
 			"name": "update_flow_nodes",
 			"title": "Change or remove flow nodes",
-			"description": "Tune or remove existing behavior nodes in one graph. Node ids and current data are in the scene summary under each object's \"flow\" (and \"sceneFlow\"). Script code runs every frame from the base pose: use object.rotation.y = base.rot[1] + time * speed, not +=.\nTake a screenshot after each change to check your work.",
+			"description": "Tune or remove existing behavior nodes in one graph. Node ids and current data are in the scene summary under each object's \"flow\" (and \"sceneFlow\"). Script code runs every frame from the base pose: use object.rotation.y = base.rot[1] + elapsed * speed, not += (elapsed = seconds since Play started, time = the shared clock, seconds of the day).\nTake a screenshot after each change to check your work.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -1330,7 +1330,7 @@
 		{
 			"name": "screenshot",
 			"title": "Take a picture of the scene",
-			"description": "See the scene: a PNG of a clean frame (no gizmos) from a temporary camera, never moving anyone's view. view: current | top | front | iso | focus (focus needs uuid).",
+			"description": "See the scene: a PNG of a clean frame (no gizmos) from a temporary camera, never moving anyone's view. view: current | top | front | iso | focus (focus needs uuid or uuids); from = an angle or {yaw, pitch}; camera = a free {position, target}. 4:3 unless aspect says otherwise (current follows the person's window). Answers with the camera it used.",
 			"inputSchema": {
 				"type": "object",
 				"properties": {
@@ -1346,7 +1346,93 @@
 					},
 					"uuid": {
 						"type": "string",
-						"description": "object to frame (view focus)"
+						"description": "object to frame"
+					},
+					"uuids": {
+						"type": "array",
+						"items": {
+							"type": "string"
+						},
+						"description": "objects to frame together"
+					},
+					"from": {
+						"description": "the angle around the subject, instead of view: front, back, left, right, top, below, iso, or {yaw, pitch} in degrees (yaw 0 = front, 90 = right; pitch 90 = from above)",
+						"anyOf": [
+							{
+								"type": "string",
+								"enum": [
+									"front",
+									"back",
+									"left",
+									"right",
+									"top",
+									"below",
+									"iso"
+								]
+							},
+							{
+								"type": "object",
+								"properties": {
+									"yaw": {
+										"type": "number"
+									},
+									"pitch": {
+										"type": "number"
+									}
+								},
+								"required": [
+									"yaw",
+									"pitch"
+								]
+							}
+						]
+					},
+					"camera": {
+						"type": "object",
+						"description": "a free camera, instead of view and from",
+						"properties": {
+							"position": {
+								"type": "array",
+								"items": {
+									"type": "number"
+								},
+								"minItems": 3,
+								"maxItems": 3,
+								"description": "[x,y,z]"
+							},
+							"target": {
+								"type": "array",
+								"items": {
+									"type": "number"
+								},
+								"minItems": 3,
+								"maxItems": 3,
+								"description": "[x,y,z]"
+							}
+						},
+						"required": [
+							"position",
+							"target"
+						]
+					},
+					"aspect": {
+						"description": "width to height: \"4:3\" (default), \"1:1\", \"16:9\" or a number. view current defaults to the person's window",
+						"anyOf": [
+							{
+								"type": "string"
+							},
+							{
+								"type": "number"
+							}
+						]
+					},
+					"zoom": {
+						"type": "number",
+						"description": "above 1 is closer, 0.1 to 10"
+					},
+					"margin": {
+						"type": "number",
+						"description": "room around the subject: 1 touches the frame, default 1.15"
 					},
 					"size": {
 						"type": "number",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@theprototype/agent",
-	"version": "1.53.1",
+	"version": "1.54.0",
 	"description": "Let an AI agent (Claude Code, Claude Desktop, any MCP host) join a theprototype.app session from its link and build the 3D scene with you.",
 	"type": "module",
 	"license": "MIT",

package/src/browserEngine.js

@@ -357,13 +357,14 @@ export class BrowserEngine extends EventEmitter {
 						fr.readAsDataURL(/** @type {Blob} */ (r));
 					});
 				}
-				if (r && typeof r === 'object' && typeof r.data === 'string') return { data: r.data, mimeType: r.mimeType || 'image/png' };
-				return typeof r === 'string' ? { data: r, mimeType: 'image/png' } : null;
+				const camera = typeof api.lastShot === 'function' ? api.lastShot() : null;
+				if (r && typeof r === 'object' && typeof r.data === 'string') return { data: r.data, mimeType: r.mimeType || 'image/png', camera };
+				return typeof r === 'string' ? { data: r, mimeType: 'image/png', camera } : null;
 			}, opts)
 			.catch((/** @type {any} */ e) => ({ error: firstLine(e) }));
 		if (viaApi && typeof viaApi.data === 'string') {
 			const m = /^data:([^;,]+)(;base64)?,/.exec(viaApi.data);
-			return m ? { data: viaApi.data.slice(m[0].length), mimeType: m[1] } : viaApi;
+			return m ? { data: viaApi.data.slice(m[0].length), mimeType: m[1], camera: viaApi.camera } : viaApi;
 		}
 		const canvas = await this.page.evaluateHandle(() => {
 			const all = [...document.querySelectorAll('canvas')].filter((c) => c.width > 0 && c.height > 0 && c.offsetParent !== null);

package/src/mcpServer.js

@@ -222,10 +222,12 @@ export function createBridgeServer(opts) {
 			if (!engine) return textResult({ error: 'not connected — join first', note: 'call connect with the session link first' }, true);
 			if (name === 'screenshot' && reserved.includes('screenshot')) {
 				if (!engineReady()) return textResult({ error: 'the agent page is not up yet (' + engine.state + ')' }, true);
-				const shot = await engine.screenshot({ view: a.view, uuid: a.uuid, size: a.size });
+				const { view, uuid, uuids, from, camera, aspect, zoom, margin, size } = a;
+				const shot = await engine.screenshot({ view, uuid, uuids, from, camera, aspect, zoom, margin, size });
 				/** @type {any[]} */
 				const content = [{ type: 'image', data: shot.data, mimeType: shot.mimeType || 'image/png' }];
 				if (shot.note) content.push({ type: 'text', text: shot.note });
+				if (shot.camera) content.push({ type: 'text', text: JSON.stringify({ camera: shot.camera }) });
 				return { content };
 			}
 			if (name === 'wait_for_edit' && reserved.includes('wait_for_edit')) {

package/src/mcpTools.js

@@ -86,12 +86,32 @@ export function bridgeTools(engine = 'browser') {
 			{
 				name: 'screenshot',
 				description:
-					'See the scene: a PNG of a clean frame (no gizmos) from a temporary camera, never moving anyone\'s view. view: current | top | front | iso | focus (focus needs uuid).',
+					'See the scene: a PNG of a clean frame (no gizmos) from a temporary camera, never moving anyone\'s view. view: current | top | front | iso | focus (focus needs uuid or uuids); from = an angle or {yaw, pitch}; camera = a free {position, target}. 4:3 unless aspect says otherwise (current follows the person\'s window). Answers with the camera it used.',
 				inputSchema: {
 					type: 'object',
 					properties: {
 						view: { type: 'string', enum: ['current', 'top', 'front', 'iso', 'focus'] },
-						uuid: { type: 'string', description: 'object to frame (view focus)' },
+						uuid: { type: 'string', description: 'object to frame' },
+						uuids: { type: 'array', items: { type: 'string' }, description: 'objects to frame together' },
+						from: {
+							description: 'the angle around the subject, instead of view: front, back, left, right, top, below, iso, or {yaw, pitch} in degrees (yaw 0 = front, 90 = right; pitch 90 = from above)',
+							anyOf: [
+								{ type: 'string', enum: ['front', 'back', 'left', 'right', 'top', 'below', 'iso'] },
+								{ type: 'object', properties: { yaw: { type: 'number' }, pitch: { type: 'number' } }, required: ['yaw', 'pitch'] }
+							]
+						},
+						camera: {
+							type: 'object',
+							description: 'a free camera, instead of view and from',
+							properties: {
+								position: { type: 'array', items: { type: 'number' }, minItems: 3, maxItems: 3, description: '[x,y,z]' },
+								target: { type: 'array', items: { type: 'number' }, minItems: 3, maxItems: 3, description: '[x,y,z]' }
+							},
+							required: ['position', 'target']
+						},
+						aspect: { description: 'width to height: "4:3" (default), "1:1", "16:9" or a number. view current defaults to the person\'s window', anyOf: [{ type: 'string' }, { type: 'number' }] },
+						zoom: { type: 'number', description: 'above 1 is closer, 0.1 to 10' },
+						margin: { type: 'number', description: 'room around the subject: 1 touches the frame, default 1.15' },
 						size: { type: 'number', description: 'longest side in pixels' }
 					}
 				}