@pinepaper.studio/mcp-server 1.6.17 → 1.6.18

package/dist/tools/definitions.js

@@ -11,7 +11,8 @@ import { COMPACT_DESCRIPTIONS } from './compact-descriptions.js';
 import { MINIMAL_DESCRIPTIONS } from './minimal-descriptions.js';
 import { STICK_GAITS, STICK_POSES, STICK_SEQUENCES, STICK_EXPRESSIONS, STICK_PROPS } from './stick-vocabulary.js';
 import { GeneratorNameSchema, ItemTypeSchema } from '../types/schemas.js';
-import { EffectTypeSchema, SimpleAnimationTypeSchema, EasingSchema, GEOMETRY_OPERATIONS, THREAD_STITCHES, } from '../types/schemas.js';
+import { DESIGN_MEDIA, DESIGN_MEDIA_APPLY } from './engine-lists.js';
+import { EffectTypeSchema, SimpleAnimationTypeSchema, EasingSchema, KEYFRAME_EASINGS, EASING_DESCRIPTIONS, KEYFRAME_EASING_JSON_SCHEMA, GEOMETRY_OPERATIONS, THREAD_STITCHES, } from '../types/schemas.js';
 /**
  * Vocabulary lists derived from Zod schemas so tool descriptions stay in
  * sync automatically. The description-schema-parity test
@@ -25,6 +26,7 @@ const SIMPLE_ANIMATION_TYPES_LIST = SimpleAnimationTypeSchema.options.join(', ')
 // easeInCubic / easeOutCubic / easeOutBounce, which keyframe_animate rejects
 // (round 8 DD, 1.68) — derived now, so it cannot say what the schema refuses.
 const KEYFRAME_EASINGS_LIST = EasingSchema.options.join(', ');
+const EASING_LINES = KEYFRAME_EASINGS.map((e) => `- ${e}: ${EASING_DESCRIPTIONS[e]}`).join('\n');
 // =============================================================================
 // AI AGENT GUIDE (exported for pinepaper_tool_guide)
 // =============================================================================
@@ -1738,6 +1740,8 @@ EXAMPLES:
         annotations: { title: 'Beat-Snapped Cuts', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
         description: `Cut on the music: analyse a track's beats (or take beat times you already have), fit a beat grid, and return cut points on every beat, every bar, or every N beats — optionally splitting a video or audio clip at each one.
 
+The song is the backbone of the edit: when the music is generated, cut the picture to its beats and bars and use the whole song. Do not trim the song to fit shots that were planned first.
+
 - source: the music — an upload id, URL, data: URL or local file path. Or beats: [seconds] to skip the analysis.
 - every: 'beat' (default) | 'bar' | N beats. beatsPerBar (default 4). range: [from, to] seconds.
 - bpm: the tempo, if you know it (the grid's phase is still fitted to the music). Otherwise the studio's detection and its usual confusions (double, half, 3:4, 4:3 …) are scored against the music and the best is used; bpmHint: [min, max] keeps the choice in a range. The result lists the candidates, and says lowConfidence with a warning when the tempo is uncertain — pass bpm then.
@@ -1805,6 +1809,12 @@ EXAMPLE: { checks: ["contrast", "flash"], duration: 6, fps: 20 }`,
         annotations: { title: 'Generate Image (cloud)', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         description: `Generate images with an AI model in the PinePaper cloud, and optionally place the first one on the canvas. CHARGED per output — price it first with pinepaper_generate_estimate (free).
 
+PLAN FIRST; GENERATE ONLY WHAT THE EDIT USES. Every output is paid in full whether or not it is used, so generate-then-trim is waste:
+- Plan the whole timeline (shots, lengths, roles) before the first paid call, and price the whole plan with pinepaper_generate_estimate.
+- Reuse before generating: an image you already generated is referenced by its ref "/scene-assets/<id>".
+- Video: choose each shot's length from the lengths the model allows (listModels; Veo takes 4, 6 or 8 s) and re-time the edit to them. Do not generate long and crop.
+- Music: the song is the backbone. Its length only loosely follows the request, so cut the picture to its beats and bars with pinepaper_beat_cuts and use the whole song, rather than trimming it to fit the picture.
+
 Needs a service-account key in PINEPAPER_API_KEY (pp_sa_…, render:create scope). It is an internal beta enabled per organisation: without it the result says "not enabled for your organisation", and nothing is charged. Every refusal says whether anything was charged.
 
 - model or useCase: a model id from pinepaper_generate_estimate {listModels: true}, or a use case and the cloud picks its default (hero stills, plates, text in the image, character-consistent edits).
@@ -1847,7 +1857,7 @@ The result: assets [{assetId, ref, width, height}] — the sizes the files HAVE
     {
         name: 'pinepaper_generate_estimate',
         annotations: { title: 'Estimate Generation (free)', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-        description: `Free: price a pinepaper_generate call before making it, or list the models. { listModels: true } returns every model you may use with its price per output, use cases, licence notes and the defaults per use case; { model | useCase, input } returns the estimate for that request. Needs PINEPAPER_API_KEY, like pinepaper_generate.`,
+        description: `Free: price a pinepaper_generate call before making it, or list the models. Estimate the WHOLE plan (every asset the edit needs, at the lengths it will use) before generating any of it, not call by call. { listModels: true } returns every model you may use with its price per output, use cases, licence notes and the defaults per use case; { model | useCase, input } returns the estimate for that request. Needs PINEPAPER_API_KEY, like pinepaper_generate.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -2135,6 +2145,13 @@ By default returns a cheap per-frame hash + byte size (token-light), plus unique
 
 Set includeDataUrls: true to also get each frame as a PNG data URL (large — only for a few frames).
 
+LOOK AT YOUR OWN FILM — sheet: one tiled image of many frames, saved to a file (filePath), plus a review rubric to score it against. Structure checks cannot see what a frame looks like; this can. Pick the frames with times (e.g. the music's beat times), or:
+- sheet.every + sheet.duration: one frame every N seconds.
+- sheet.strip {at, count?, step?}: consecutive frames around a moment (a transition, a stutter).
+- sheet.loopSeam + sheet.duration: the last frame beside the first.
+tileWidth defaults to 360 px, phone width: if a word cannot be read in its tile, it cannot be read on a phone. Then open the file, score review.criteria 1-10, and go through review.checklist.
+EXAMPLE: { sheet: { every: 1, duration: 15 } } → one ~15-tile JPEG.
+
 USE WHEN:
 - Verifying an animation is deterministic / reproducible
 - Checking whether a scene actually animates across a time range
@@ -2157,8 +2174,26 @@ EXAMPLE: { times: [0, 0.5, 1, 1.5, 2], seed: 42 }`,
                     type: 'boolean',
                     description: 'Include each frame as a PNG data URL (large). Default false → hashes only.',
                 },
+                sheet: {
+                    type: 'object',
+                    description: 'Return ONE tiled image saved to a file, plus a critique rubric, instead of per-frame hashes. times is then optional.',
+                    properties: {
+                        every: { type: 'number', description: 'One frame every N seconds from 0 to duration.' },
+                        duration: { type: 'number', description: 'Scene length in seconds (for every and loopSeam).' },
+                        strip: {
+                            type: 'object',
+                            properties: { at: { type: 'number' }, count: { type: 'integer', minimum: 2, maximum: 24 }, step: { type: 'number' } },
+                            required: ['at'],
+                            description: 'Consecutive frames around a moment: count (default 8), step seconds apart (default 1/30).',
+                        },
+                        loopSeam: { type: 'boolean', description: 'The last frame beside the first.' },
+                        tileWidth: { type: 'integer', minimum: 120, maximum: 1080, description: 'Tile width in px (default 360, phone width).' },
+                        columns: { type: 'integer', minimum: 1, maximum: 12 },
+                        format: { type: 'string', enum: ['jpeg', 'png'], description: 'Default jpeg (small).' },
+                        labels: { type: 'boolean', description: 'Stamp each tile with its time (default true).' },
+                    },
+                },
             },
-            required: ['times'],
         },
     },
     {
@@ -2194,11 +2229,15 @@ VIDEO EDITING:
 - apply_track_matte: { id, matteItemId, channel? (luma|alpha|red), invert?, strength?, hideMatte?, live? } — the matte item's pixels drive the target's alpha. The classic: a headline filled with footage. live: true keeps the cut tracking an ANIMATING matte (kinetic mask reveal); otherwise it bakes once, destructively (recorded in data.filterChain for round-trip).
 - stop_live_matte: { id } — stop a live matte, keep the last cut.
 
+MAKE ONE LIKE THIS — a reference video's FORMAT, never its content:
+- analyze_reference: { id, thumbnails? } — the uploaded reference clip (upload_video it first) → cuts (to the frame), shots (length, colours), pacing, beat, and card: the same facts as plain text. Read the card before planning.
+- remake_from_reference: { texts, duration?, clear? } — builds a new piece on the last analysed reference: one card per shot, cut at its cut times, in each shot's colours, the headline popping on its beats. texts are YOUR words, one per shot. Nothing of the footage, its words or its sound is copied; the reference clip stays in the project muted. One undo step.
+
 EXAMPLE: { action: 'upload_video', url: 'https://…/clip.mp4', scale: 0.5, timeOffset: 1 }`,
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['upload_video', 'upload_audio', 'list', 'remove', 'set_playback_rate', 'set_clip', 'split', 'add_transition', 'set_time_remap', 'speed_ramp', 'match_cut', 'apply_track_matte', 'stop_live_matte'], description: "Media action" },
+                action: { type: 'string', enum: ['upload_video', 'upload_audio', 'list', 'remove', 'set_playback_rate', 'set_clip', 'split', 'add_transition', 'set_time_remap', 'speed_ramp', 'match_cut', 'apply_track_matte', 'stop_live_matte', 'analyze_reference', 'remake_from_reference'], description: "Media action" },
                 transition: { type: 'object', properties: { type: { type: 'string', enum: ['crossfade', 'dip'] }, seconds: { type: 'number', exclusiveMinimum: 0, maximum: 10 }, color: { type: 'string' } }, description: "add_transition: { type ('crossfade' default | 'dip'), seconds, color (dip) }." },
                 atPlayhead: { type: 'boolean', description: 'upload_video / upload_audio: start at the current playback time (instead of timeOffset).' },
                 remapTrack: { type: 'array', items: { type: 'object', properties: { time: { type: 'number' }, value: { type: 'number' }, easing: { type: 'string' } }, required: ['time', 'value'] }, description: 'set_time_remap: canvas-seconds → source-seconds curve (≥2 points). null clears the remap.' },
@@ -2218,7 +2257,11 @@ EXAMPLE: { action: 'upload_video', url: 'https://…/clip.mp4', scale: 0.5, time
                 hideMatte: { type: 'boolean', description: 'apply_track_matte: hide the matte item after applying.' },
                 live: { type: 'boolean', description: 'apply_track_matte: keep re-cutting as the matte moves/animates — the kinetic mask reveal. Omitted = bake once, destructively.' },
                 url: { type: 'string', description: "Required for upload_video / upload_audio: an http(s) URL, a data: URL, or a PATH TO A LOCAL FILE. Remote URLs and local files are fetched/read by the server (the page may not fetch third-party hosts), so stock music and SFX links work; the HTTP status or content-type is named if one does not. Up to 48 MB." },
-                id: { type: 'string', description: 'Media id — required for remove / set_playback_rate / set_clip.' },
+                id: { type: 'string', description: 'Media id — required for remove / set_playback_rate / set_clip / analyze_reference.' },
+                texts: { type: 'array', items: { type: 'string' }, description: 'remake_from_reference: your words, one per shot of the reference.' },
+                duration: { type: 'number', description: 'remake_from_reference: total seconds (default the reference\'s own).' },
+                clear: { type: 'boolean', description: 'remake_from_reference: empty the canvas first (media survives).' },
+                thumbnails: { type: 'boolean', description: 'analyze_reference: include a small image per shot (default false; token-heavy).' },
                 rate: { type: 'number', description: 'Playback rate 0.25–4 — set_playback_rate.' },
                 inPoint: { type: 'number', description: 'Clip in-point (media-time s) — set_clip.' },
                 outPoint: { type: 'number', description: 'Clip out-point (media-time s, > inPoint) — set_clip.' },
@@ -2309,9 +2352,10 @@ READ THIS BEFORE PROMISING A MEDIUM. Naming a medium does not create its marks.
 Call resolve before telling a user you will render in a medium. "yes, but as an impression" is the true answer for half of them, and a flat approximation misrepresents a medium rather than approximating it.
 
 ACTIONS:
+- apply: { itemId, medium, options? } — render an item in ANY medium the engine can make: ${Object.keys(DESIGN_MEDIA_APPLY).join(', ')}. One engine entry point; a medium it cannot make (encaustic, absent here) or that is a brush rather than a fill (charcoal, ink) is refused with the reason: pass it on. watercolor options: color, brush, water 0..1, opacity, edge 0..1 (the dark rim), angle, bleed, seed. oil (stylised): color, brush, length, density, toneRange, relief, angle, seed. cutPaper (vector: survives SVG/PDF/video): color, facet, jitter, shadow, shadowColor, shadowOpacity, shadowOffset [dx, dy], seed. The result replaces the source in the stacking order and hides it; applying again replaces; one undo step.
 - list_media: every medium with fidelity, definition and limitation. Read it rather than assuming a fixed set — the catalogue grows (hatch and watercolor are recent additions).
 - resolve: { medium } → { ok, fidelity, reason, markMaker }. ok:false with a reason is a real answer — pass it on rather than trying anyway.
-- list_stitches: the 4 thread stitches with their params.
+- list_stitches: the thread stitches with their params.
 - apply_thread: render an item in thread. Its own silhouette is the region and its own fill is the thread colour, so an existing drawing becomes stitched rather than needing to be redrawn. The source is HIDDEN, not destroyed.
 - apply_hatch: rule an item with hatching. Same deal — silhouette is the region, source is hidden, re-hatching replaces.
 - list_flow_fields: the 7 fields that bend a hatch line.
@@ -2341,11 +2385,12 @@ EXAMPLE — a stitched leaf:
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['list_media', 'resolve', 'list_stitches', 'apply_thread', 'apply_hatch', 'list_flow_fields', 'list_hatch_options'], description: 'Medium operation' },
-                medium: { type: 'string', description: 'resolve: vector | thread | ink | watercolor | hatch | cutPaper | charcoal | oil | encaustic. Six are native (vector, thread, ink, watercolor, hatch, cutPaper), two stylised, one absent — call list_media for the live table rather than trusting this line.' },
-                itemId: { type: 'string', description: 'apply_thread / apply_hatch: a closed path, compound path, or a group of them.' },
+                action: { type: 'string', enum: ['list_media', 'resolve', 'list_stitches', 'apply_thread', 'apply_hatch', 'list_flow_fields', 'list_hatch_options', 'apply'], description: 'Medium operation' },
+                medium: { type: 'string', enum: [...DESIGN_MEDIA], description: `resolve / apply: the medium. apply works for ${Object.keys(DESIGN_MEDIA_APPLY).join(', ')}; the rest are refused by the engine with the reason. Call list_media for each one's fidelity and limitation.` },
+                options: { type: 'object', description: 'apply: the medium\'s own options (see the description; color takes hex).' },
+                itemId: { type: 'string', description: 'apply / apply_thread / apply_hatch: a closed path, compound path (holes kept), or a group of them (applied per path).' },
                 stitch: { type: 'string', enum: [...THREAD_STITCHES], description: "apply_thread: default longAndShort. These six are the stitches the engine publishes; call 'list_stitches' for each one's description and its own parameters. An unknown name is refused rather than quietly stitched as a default fill." },
-                field: { type: 'object', description: "apply_thread: { kind: 'radial'|'spine'|'constant', cx, cy, angle, spine[], across } — default radial from the shape centre." },
+                field: { type: 'object', description: "apply_thread: { kind: 'radial'|'spine'|'constant', cx, cy, angle, spine[], across } — default radial from the shape centre. spine is a list of points, each {x, y} or [x, y], e.g. [{x:400,y:200},{x:400,y:520}]; this tool normalises [x, y] to {x, y} before the engine sees it." },
                 stitchLen: { type: 'number', description: 'apply_thread: nominal stitch length px (default 18).' },
                 rowGap: { type: 'number', description: 'apply_thread: row spacing px; defaults from thread width so rows abut.' },
                 variance: { type: 'number', description: 'apply_thread: length jitter 0..1 (default 0.35) — the long-and-short shading.' },
@@ -2594,6 +2639,13 @@ RECIPE — a playable maze: create_tilemap with wall fills → batch_create colo
     },
     {
         name: 'pinepaper_design_system',
+        annotations: {
+            title: 'Design System',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `The design vocabulary, as data you can read — and eighteen styles that can build a scene.
 
 TWO DIFFERENT THINGS, kept apart on purpose:
@@ -2630,6 +2682,13 @@ A partial composition reports as a failure with the elements that did not create
     },
     {
         name: 'pinepaper_stick',
+        annotations: {
+            title: 'Stick Figure Kit',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `The vendored stick-figure kit — a rigged figure posed, walking, travelling, holding a prop, with a garment and hair, plus the set it stands on and among.
 
 A different construction from pinepaper_character, which places a figure from the DESIGN GRAPH by concept ("pp:Pigeon"). This is the stick kit specifically.
@@ -2695,6 +2754,13 @@ The geometry is vendored from mcp-cloud, which makes this a three-repo artifact:
     },
     {
         name: 'pinepaper_story',
+        annotations: {
+            title: 'Story to Scene',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `A piece of prose becomes a scene.
 
 - distill: reduce an article to its story beats and draw NOTHING. This is the half worth having on its own — a caller can read what the distiller made of the text, edit the beats, and only then assemble. Discovering the reading by looking at a finished scene is the expensive way round.
@@ -2715,6 +2781,13 @@ The geometry is vendored from mcp-cloud, which makes this a three-repo artifact:
     },
     {
         name: 'pinepaper_interchange',
+        annotations: {
+            title: 'Interchange Formats',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `The formats other tools read and write — Lottie, dotLottie, GLB, BVH, PNG sequence.
 
 pinepaper_agent_export covers the PLATFORM formats: png, svg, mp4, webm, gif, pdf, sized for Instagram or YouTube. These are the interchange ones — a Lottie an app plays, a GLB a 3D tool opens, a BVH a rig imports, a PNG sequence an editor ingests. Import is here too, because a format you can only write is half a bridge.
@@ -2733,6 +2806,13 @@ Three of these refuse quietly in the engine: exportGLB with no perspective objec
     },
     {
         name: 'pinepaper_sound',
+        annotations: {
+            title: 'Sound Synthesis & Soundtrack',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `Synthesis — and the drawing that is the same object.
 
 The engine carries a full audio graph, and none of it was reachable. pinepaper_audio_beats ANALYSES audio that already exists; this MAKES audio.
@@ -2786,6 +2866,13 @@ render_soundtrack mixes every placed sound to a WAV and writes it to a file. It
     },
     {
         name: 'pinepaper_motion',
+        annotations: {
+            title: 'Group & Field Motion',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `The generators' Animation knob, pointed at anything — the same motion engine every generator's own animation runs on, reachable for any group or list of items.
 
 Two kinds, and the second is the one nothing else here can do:
@@ -2817,6 +2904,13 @@ This is not pinepaper_animate: that applies a loop preset to ONE item. This move
     },
     {
         name: 'pinepaper_path',
+        annotations: {
+            title: 'Path Operations',
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `Destructive path operations — the ones that REPLACE or ADD items rather than restyling them.
 
 - boolean: unite | subtract | intersect | exclude | divide. CONSUMES its operands and leaves one result, so the input ids stop existing. The first id is the base; the rest apply to it in order.
@@ -2879,7 +2973,7 @@ RECIPE — a character walking through a forest: create {spec:'forest'} → impo
                     anyOf: [{ type: 'boolean' }, { type: 'object' }],
                     description: 'create: include the walkable character (boolean or config).',
                 },
-                patch: { type: 'object', description: 'configure: partial world spec, validated against describe.' },
+                patch: { type: 'object', description: 'configure: partial world spec, validated against describe. Colours (env.zenith, env.horizon, env.fogColor, env.sunColor, env.ambient, env.lowColor … env.propColorB) take hex ("#03050c") or [r, g, b] in 0..1.' },
                 actorId: { type: 'string', description: 'Actor id.' },
                 x: { type: 'number', description: 'add_actor: world x.' },
                 z: { type: 'number', description: 'add_actor: world z.' },
@@ -2890,18 +2984,18 @@ RECIPE — a character walking through a forest: create {spec:'forest'} → impo
                 camera: { type: 'object', description: "set_camera: { mode: follow|fixed|orbit, target?, radius?, speed?, eye?, lookAt? }." },
                 object: { type: 'object', description: 'add_object: { x, z, height?, color?, y? }. metalness/roughness are accepted and IGNORED here — a plain object is drawn by the prop shader, which declares no such uniform. They render on the mesh path only.' },
                 pathId: { type: 'string', description: 'extrude_path / lathe_path: the canvas path to turn into geometry. The path itself is unchanged.' },
-                mesh: { type: 'object', description: 'extrude_path / lathe_path options: { id?, depth?, unitsPerPixel?, caps?, segments?, arc?, flatness?, x?, y?, z?, rotY?, rotYDegrees?, scale?, doubleSided?, color?, metalness?, roughness? }. color is hex or [r,g,b] (default light grey — without it the mesh rendered black); it becomes the shader\'s diffuse uniform. arc is DEGREES; rotY is RADIANS (fed straight to cos/sin in the shader) — pass rotYDegrees to write degrees. These names are the ones the engine records as the mesh provenance, so a captured meshProvenance.opts spreads straight back in.' },
+                mesh: { type: 'object', description: 'extrude_path / lathe_path options: { id?, depth? (WORLD units, default 1), unitsPerPixel? (canvas px → world units, default 0.01), upright? (extrude: stand the drawing up, extruded along Z; default flat, a floor plan extruded along Y), placement? (extrude: \'centered\' default: centred on x/z, base at y; \'canvas\': the outline\'s canvas position), caps?, segments?, arc?, flatness?, x?, y?, z?, rotY?, rotYDegrees?, scale?, doubleSided?, color?, metalness?, roughness? }. color is hex or [r,g,b] (default light grey — without it the mesh rendered black); it becomes the shader\'s diffuse uniform. arc is DEGREES; rotY is RADIANS (fed straight to cos/sin in the shader) — pass rotYDegrees to write degrees. These names are the ones the engine records as the mesh provenance, so a captured meshProvenance.opts spreads straight back in.' },
                 meshId: { type: 'string', description: 'remove_mesh: the mesh id.' },
-                light: { type: 'object', description: 'add_light / set_light: { id?, x?, y?, z?, color?, intensity?, range? }. At most 8 point lights; the ninth is refused by name because the shader array is fixed-size.' },
+                light: { type: 'object', description: 'add_light / set_light: { id?, x?, y?, z?, color? (hex or linear [r, g, b], may exceed 1), intensity?, range? }. At most 8 point lights; the ninth is refused by name because the shader array is fixed-size.' },
                 lightId: { type: 'string', description: 'set_light / remove_light: the light id.' },
-                material: { type: 'object', description: 'add_material / set_material: { id?, color?, emissive?, metalness?, roughness?, emissiveIntensity?, clearcoat?, clearcoatRoughness?, sheenColor?, sheenRoughness? }. A shared surface — one edit restyles every object using it. metalness/roughness render on the mesh path only.' },
+                material: { type: 'object', description: 'add_material / set_material: colours (color, emissive, sheenColor) take hex or [r, g, b] in 0..1. { id?, color?, emissive?, metalness?, roughness?, emissiveIntensity?, clearcoat?, clearcoatRoughness?, sheenColor?, sheenRoughness? }. A shared surface — one edit restyles every object using it. metalness/roughness render on the mesh path only.' },
                 materialId: { type: 'string', description: 'set_material / remove_material: the material id.' },
                 source: { type: 'string', description: 'import_obj: the OBJ file TEXT. import_gltf: a URL or a data: URI of the .glb bytes.' },
                 importOptions: { type: 'object', description: 'import_obj / import_gltf: placement and scale options, passed through.' },
                 clip: { type: 'string', description: 'set_mesh_clip: which imported animation clip a skinned mesh plays.' },
                 crossfade: { type: 'number', description: 'set_mesh_clip: seconds to blend out of the previous clip (blended in LOCAL pose space).' },
                 navTarget: { type: 'string', enum: ['2d', '3d'], description: "set_nav_target: which layer the pointer drives." },
-                point: { type: 'object', description: 'ground_height / canvas_to_ground / world_to_canvas: { x, y, z? }.' },
+                point: { type: 'object', description: 'ground_height: { x, z } in WORLD coordinates (y is read as z if z is absent). canvas_to_ground: { x, y } in canvas pixels. world_to_canvas: { x, y, z? } in world coordinates.' },
                 origin: { type: 'array', items: { type: 'number' }, description: 'raycast: ray origin [x, y, z].' },
                 direction: { type: 'array', items: { type: 'number' }, description: 'raycast: ray direction [x, y, z], need not be normalised.' },
                 multiplier: { type: 'number', description: 'dolly_camera: >1 away, <1 closer.' },
@@ -2924,7 +3018,9 @@ RECIPE — a character walking through a forest: create {spec:'forest'} → impo
         annotations: {
             title: 'Character (place and direct a figure from the graph)',
             readOnlyHint: false,
+            destructiveHint: false,
             idempotentHint: false,
+            openWorldHint: false,
         },
         description: `Place a CHARACTER from the design graph and DIRECT it — no geometry, no bones, no poses.
 
@@ -3472,7 +3568,7 @@ applyFunction: \`
         annotations: {
             title: 'Execute Custom Code',
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: false,
             openWorldHint: true,
         },
@@ -3646,12 +3742,9 @@ The authoritative list for a given item is pinepaper_get_animatable_properties
 
 EASING — IT SHAPES THE SEGMENT ARRIVING AT THE KEYFRAME IT IS ON.
 The move from keyframe A to keyframe B is eased by B's easing, not A's. Easing on the FIRST keyframe does nothing (no segment arrives at it) — a Ken Burns with easing only on its first key plays linear. Put the easing on the key you are moving TO.
-- linear: Constant speed
-- easeIn: Slow start
-- easeOut: Slow end
-- easeInOut: Slow start and end
-- bounce: Bounce effect
-- elastic: Elastic overshoot
+${EASING_LINES}
+- or a custom cubic-bezier [x1, y1, x2, y2] — x in 0..1, y may exceed 0..1 for overshoot. keyframe_animate and camera_animate only.
+Every easing renders exactly in video, GIF and APNG. Lottie and CSS get the closest single Bézier: springPlayful loses its wobble, and the in-out quart/quint/expo/circ curves are within 2–4 %. SMIL is exact for springs and those four.
 
 CLIP WINDOW (optional — Premiere/Canva-style clip behavior):
 - timeOffset: Shift the whole clip in canvas time (seconds). The animation only runs while canvas time is in [timeOffset, timeOffset + (clipOutPoint - clipInPoint)].
@@ -3679,9 +3772,8 @@ EXAMPLE — Reveal at 2s, skip first second of keyframe data, end at 4s of keyfr
                                 additionalProperties: true,
                             },
                             easing: {
-                                type: 'string',
-                                enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'bounce', 'elastic'],
-                                description: 'Shapes the segment ARRIVING at this keyframe (from the previous one). Ignored on the first keyframe.',
+                                ...KEYFRAME_EASING_JSON_SCHEMA,
+                                description: 'Shapes the segment ARRIVING at this keyframe (from the previous one). Ignored on the first keyframe. A name, or a custom cubic-bezier [x1, y1, x2, y2] — x in 0..1, y may exceed 0..1 for overshoot.',
                             },
                         },
                         required: ['time', 'properties'],
@@ -3849,7 +3941,7 @@ MASK TYPES: rectangle, circle, ellipse, star, triangle, hexagon, heart, rounded`
                         properties: {
                             time: { type: 'number', description: 'Normalized time (0-1)' },
                             properties: { type: 'object', description: 'Mask properties (x, y, width, height, radius, scale, rotation, opacity)' },
-                            easing: { type: 'string', enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'bounce', 'elastic'] },
+                            easing: { type: 'string', enum: [...KEYFRAME_EASINGS] },
                         },
                         required: ['time', 'properties'],
                     },
@@ -3860,7 +3952,7 @@ MASK TYPES: rectangle, circle, ellipse, star, triangle, hexagon, heart, rounded`
                     properties: {
                         startTime: { type: 'number', description: 'Start time in seconds', default: 0 },
                         duration: { type: 'number', description: 'Duration in seconds', default: 0.8 },
-                        easing: { type: 'string', enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'bounce'], default: 'easeOut' },
+                        easing: { type: 'string', enum: [...KEYFRAME_EASINGS], default: 'easeOut' },
                         reversed: { type: 'boolean', description: 'Reverse animation (hide instead of reveal)', default: false },
                         loop: { type: 'boolean', description: 'Loop the animation', default: false },
                     },
@@ -3977,7 +4069,7 @@ Needs a studio that publishes the item-side table; without one, the tool says so
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: `[Utility] Get list of available easing functions for mask animations.`,
+        description: `[Utility] List the easing names the studio accepts: one table serves keyframes, masks, relations and the camera. Reads the live engine's list when it reports one.`,
         inputSchema: {
             type: 'object',
             properties: {},
@@ -4101,8 +4193,8 @@ EXAMPLE (curved arc between waypoints):
                             pitch: { type: 'number', description: '3D tilt in degrees — rendered where the studio supports camera tilt (result.tiltRenders).' },
                             yaw: { type: 'number', description: '3D rotation in degrees — rendered where the studio supports camera tilt (result.tiltRenders).' },
                             easing: {
-                                type: 'string',
-                                enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'bounce', 'elastic'],
+                                ...KEYFRAME_EASING_JSON_SCHEMA,
+                                description: 'A name, or a custom cubic-bezier [x1, y1, x2, y2] — x in 0..1, y may exceed 0..1 for overshoot.',
                             },
                             pathOut: {
                                 type: 'array',
@@ -4974,7 +5066,7 @@ flags as a badly-composed scene, and they do not survive an artboard change.`,
         name: 'pinepaper_brand_kit',
         annotations: {
             title: 'Brand Kit', readOnlyHint: false, destructiveHint: false,
-            idempotentHint: true, openWorldHint: false,
+            idempotentHint: true, openWorldHint: true,
         },
         description: `Apply a brand kit — colours, fonts and roles — across the scene.
 
@@ -4982,6 +5074,7 @@ ACTIONS:
 - plan: Report what WOULD change (count, per-role breakdown, WCAG contrast audit) WITHOUT touching
   the canvas. Call this first on an unfamiliar scene; a whole-scene recolour is hard to eyeball afterwards.
 - apply: Commit it. A history snapshot is taken FIRST, so one undo puts everything back.
+- from_url: { url, screenshots? } — read the product's REAL brand from its own site before animating anything: screenshots down the page, the logo (header image or SVG, else the site icon), and a proposed kit from the colours and fonts the site's CSS computes (buttons and links weigh most). Saved to files; the result lists them. Read in an isolated browser context: the studio is not touched. Review the kit against the screenshots, then plan / apply it. Use the brand you are given, never an invented one.
 
 KIT SHAPE — only name and colors.primary are required:
   { "name": "Acme", "colors": { "primary": "#e11d48", "secondary": "#0ea5e9",
@@ -4996,7 +5089,9 @@ Both actions return a WCAG contrast audit, so you can see failing pairs before s
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['plan', 'apply'], description: 'plan (dry run) or apply' },
+                action: { type: 'string', enum: ['plan', 'apply', 'from_url'], description: 'plan (dry run), apply, or from_url (read a site into a proposed kit)' },
+                url: { type: 'string', description: "from_url: the product's site, http(s)." },
+                screenshots: { type: 'integer', minimum: 1, maximum: 6, description: 'from_url: screenshots down the page (default 3).' },
                 kit: {
                     type: 'object',
                     description: 'Brand kit. Requires name and colors.primary; other roles are inferred.',
@@ -5022,7 +5117,7 @@ Both actions return a WCAG contrast audit, so you can see failing pairs before s
                 },
                 selectionOnly: { type: 'boolean', description: 'Restrict to current selection' },
             },
-            required: ['action', 'kit'],
+            required: ['action'],
         },
     },
     {
@@ -7031,7 +7126,7 @@ EXAMPLES:
         annotations: {
             title: 'Execute Generator',
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: false,
             openWorldHint: false,
         },
@@ -7872,7 +7967,7 @@ EXAMPLES:
         annotations: {
             title: 'Build Scene — Items, Animations, Effects in One Call',
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: false,
             openWorldHint: false,
         },
@@ -8195,6 +8290,14 @@ VERIFY MOTION BEFORE YOU RENDER. An export takes seconds to minutes and shows yo
                 broadcast: { type: 'boolean', description: 'mp4 only: broadcast-safe — BT.709, limited range (16-235), tagged bt709, constant bitrate with an 8 Mbps floor at 720p+ (4 below). result.video reports what the encoder did.' },
                 frames: { type: 'integer', minimum: 1, maximum: 36000, description: 'Animated formats: exactly this many frames instead of duration. A duration makes ceil(duration x fps) frames (7.91667 s at 24 fps is 191, not 190), so use frames for frame-exact segments.' },
                 deterministic: { type: 'boolean', description: 'mp4 / webm: byte-identical files for the same scene (pins the container timestamps), so exports can be checksummed or cached by hash.' },
+                motionBlur: {
+                    type: 'object',
+                    description: 'mp4 / webm: real motion blur. Each frame is rendered `subframes` times across the shutter and averaged, so fast movement smears instead of strobing. Costs subframes× the render time: run estimateOnly first (it reports renders and renderCost). The result carries motionBlur (what the exporter applied).',
+                    properties: {
+                        subframes: { type: 'integer', minimum: 1, maximum: 32, description: 'Renders per frame (default 8; 1 = no blur).' },
+                        shutter: { type: 'number', minimum: 0, maximum: 1, description: 'Fraction of the frame interval the shutter is open (default 0.5).' },
+                    },
+                },
                 broadcastHeadroom: { type: 'integer', minimum: 0, maximum: 40, description: 'mp4 with broadcast only, default 12: luma codes kept clear at both ends, so encoder ringing stays legal (12 measured clean on hard edges; 4 = ~100x fewer out-of-range samples, 12 = ~1000x; never zero). Fidelity raises luma_out_of_range with the legaliser command when any remain.' },
                 bitrate: { type: 'integer', minimum: 100000, maximum: 200000000, description: 'mp4 / webm: target bits/s, replacing the quality-derived one. The browser encoder treats it as a CEILING; result.video.achievedBitrate is what it produced.' },
                 minBitrate: { type: 'integer', minimum: 100000, maximum: 200000000, description: 'mp4 / webm: a floor; a miss is a fidelity warning naming the re-encode a delivery spec needs.' },