@pinepaper.studio/mcp-server 1.6.2 → 1.6.4

package/dist/tools/definitions.js

@@ -1730,11 +1730,34 @@ NOTES:
 - URL-based: the URL is fetched in the browser, so it must be reachable + CORS-permitted.
 - Use the returned id with set_playback_rate / set_clip / remove, and (for video) modify/animate it like any item.
 
+VIDEO EDITING:
+- set_time_remap: { id, remapTrack: [{time, value, easing?}, …] | null } — canvas-time → SOURCE-time curve: speed ramps, freeze frames, reverse. null restores 1:1.
+- speed_ramp: { id, segments: [{duration, speed}, …] } — the human way to say a remap. speed 0 freezes, negative reverses.
+- match_cut: { fromItemId, toItemId, subject? (detect|bounds), label?, at?, settle?, fade?, consent? } — cut between two shots with the SUBJECT aligned across the cut (on-device detection; first use returns {needsConsent, cost} until consent: true).
+- 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.
+
 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'], description: "Media action" },
+                action: { type: 'string', enum: ['upload_video', 'upload_audio', 'list', 'remove', 'set_playback_rate', 'set_clip', 'set_time_remap', 'speed_ramp', 'match_cut', 'apply_track_matte', 'stop_live_matte'], description: "Media action" },
+                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.' },
+                segments: { type: 'array', items: { type: 'object', properties: { duration: { type: 'number' }, speed: { type: 'number' } }, required: ['duration', 'speed'] }, description: 'speed_ramp: consecutive {duration, speed} segments. speed 0 = freeze frame, negative = reverse.' },
+                fromItemId: { type: 'string', description: 'match_cut: outgoing shot item id.' },
+                toItemId: { type: 'string', description: 'match_cut: incoming shot item id.' },
+                subject: { type: 'string', enum: ['detect', 'bounds'], description: "match_cut: subject source — 'detect' (on-device DETR, needs consent on first use) or 'bounds'." },
+                label: { type: 'string', description: 'match_cut: narrow detection to one class ("person") when the biggest object is not the subject.' },
+                at: { type: 'number', description: 'match_cut: cut time in seconds (default 0).' },
+                settle: { type: 'number', description: 'match_cut: seconds to relax to natural framing (default 0.8).' },
+                fade: { type: 'number', description: 'match_cut: crossfade seconds; 0 = hard cut (default 0.12).' },
+                consent: { type: 'boolean', description: 'match_cut: allow the detection model download (a first run without it returns needsConsent instead of downloading silently).' },
+                matteItemId: { type: 'string', description: 'apply_track_matte: the item whose pixels drive the alpha — a headline, a gradient, any raster or vector.' },
+                channel: { type: 'string', enum: ['luma', 'alpha', 'red'], description: 'apply_track_matte: matte channel (default luma).' },
+                invert: { type: 'boolean', description: 'apply_track_matte: invert the matte.' },
+                strength: { type: 'number', description: 'apply_track_matte: 0–1.' },
+                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: 'Media URL — required for upload_video / upload_audio.' },
                 id: { type: 'string', description: 'Media id — required for remove / set_playback_rate / set_clip.' },
                 rate: { type: 'number', description: 'Playback rate 0.25–4 — set_playback_rate.' },
@@ -1752,6 +1775,39 @@ EXAMPLE: { action: 'upload_video', url: 'https://…/clip.mp4', scale: 0.5, time
             required: ['action'],
         },
     },
+    {
+        name: 'pinepaper_text_style',
+        annotations: {
+            title: 'Text Styles (Display Titles / Variable Fonts)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Display TEXT STYLES and variable-font axes — the stacked-layer titles a fill+stroke+shadow cannot make, and weight/width/slant as animatable properties.
+
+ACTIONS:
+- apply_style: { itemId, styleKey, palette?, variant?, content?, fontFamily?, fontSize? } — render a text item as a layered display title (offset copies, outlines, fills). The result GROUP ADOPTS the text's registry id, so existing relations/keyframes/handles keep pointing at it. fontFamily: 'suggested' opts into the face the style was designed around (arcade wants a pixel face — a layer stack can outline any typeface but cannot pixellate one); never automatic.
+- set_font_axes: { itemId, axes: { weight?, width?, slant? } } — STANDARD variable-font axes only (Canvas 2D has no font-variation-settings, so custom foundry axes are unreachable — platform limit, stated, not silent). Returns {applied, rejected}: CHECK rejected — an axis silently ignored is the failure this surface exists to prevent. All three are ordinary animatable properties: keyframe fontWeight and type breathes between weights.
+- list_styles: {} — styles + palettes + axes, for pickers. Call this first; styleKey strings come from here.
+
+EXAMPLE: { action: 'apply_style', itemId: 'title_1', styleKey: 'arcade', fontFamily: 'suggested' }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['apply_style', 'set_font_axes', 'list_styles'], description: 'Text style operation' },
+                itemId: { type: 'string', description: 'Text item id — apply_style / set_font_axes.' },
+                styleKey: { type: 'string', description: 'apply_style: style name from list_styles.' },
+                palette: { description: 'apply_style: named colourway (string) or explicit color array.' },
+                variant: { type: 'number', description: 'apply_style: variation index within the style.' },
+                content: { type: 'string', description: 'apply_style: replace the text while styling.' },
+                fontFamily: { type: 'string', description: "apply_style: font override; 'suggested' = the face the style was designed around." },
+                fontSize: { type: 'number', description: 'apply_style: font size (defaults to the item\'s).' },
+                axes: { type: 'object', properties: { weight: { type: 'number' }, width: {}, slant: { type: 'number' } }, description: 'set_font_axes: weight (wght), width (wdth), slant (slnt).' },
+            },
+            required: ['action'],
+        },
+    },
     {
         name: 'pinepaper_crop_image',
         annotations: {
@@ -1829,6 +1885,145 @@ EXAMPLE: { itemId: 'item_7', color: '#00b140', threshold: 60, smoothing: 12 }`,
             required: ['itemId'],
         },
     },
+    {
+        name: 'pinepaper_shatter_image',
+        annotations: {
+            title: 'Shatter Image (Grid of Tiles)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Split a raster into a GRID OF TILES — the primitive under every "photo breaks apart / assembles from pieces" effect.
+
+Deliberately INERT: the pieces land exactly where the picture was, so the canvas looks unchanged until something animates them (per-tile keyframes, blast/scatter relations, physics bodies, staggered_with). The GROUP inherits the original item's registry id — relations, handles, and composition slots keep pointing at the thing in its place.
+
+Params: { itemId, pieces? (≈100; grid solves for square-ish tiles at source aspect, so 100 of a 3:2 photo → 12×8), rows?/cols? (exact grid, override pieces), keepSource? (hide-don't-delete the original so the photo can be restored) }
+Returns: { groupId (= the original id, adopted), tiles, rows, cols }
+
+RECIPE — assemble-from-pieces: shatter with keepSource, keyframe each tile from a random offscreen position to {x:0,y:0} delta, stagger by index, then swap the source back on completion.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                itemId: { type: 'string', description: 'The raster to shatter (or a group containing one).' },
+                pieces: { type: 'number', description: 'Approximate piece count (default 100).' },
+                rows: { type: 'number', description: 'Exact grid rows — overrides pieces.' },
+                cols: { type: 'number', description: 'Exact grid cols — overrides pieces.' },
+                keepSource: { type: 'boolean', description: 'Keep the original hidden for later restore.' },
+            },
+            required: ['itemId'],
+        },
+    },
+    {
+        name: 'pinepaper_import_layered_character',
+        annotations: {
+            title: 'Import Layered Character (Decomposer Output)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        description: `Land a DECOMPOSED character illustration as one Group of role-bound parts — eyes that blink, a mouth that talks, with ZERO further wiring.
+
+Input is the output of a single-image layer decomposer (See-through — one flat anime drawing in, ~20 occlusion-inpainted layers out — or any PSD-style layer dump with the same manifest shape). The decomposition model does NOT run here: it needs a GPU and minutes per image; run it where it fits and import the folder.
+
+Layer tags map onto the exact role tokens the expresses presets read (eye_left, pupil_right, mouth…), so pinepaper_animate/expresses blink-smile-talk work on the imported character immediately.
+
+Params: { info (the decomposer manifest: tags, xyxy rects, depth_median draw order, frame_size [h,w]), images ({tag: PNG data URL or CORS-reachable https URL} — data URLs are the reliable path; ~20 layers of base64 is a big call, use URLs when you can), position?, scale?, name? }
+Returns: { groupId, parts, roles, rolesWired, warnings }
+
+CHECK rolesWired: a character importing with 0 roles renders perfectly and silently refuses to animate — that number is the difference between a picture and a puppet.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                info: { type: 'object', description: 'Decomposer manifest (See-through meta.json contents).' },
+                images: { type: 'object', description: 'Layer tag → PNG data URL (or https URL, CORS permitting).' },
+                position: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, description: 'Placement (default canvas center).' },
+                scale: { type: 'number', description: 'Uniform scale after the frame→canvas fit.' },
+                name: { type: 'string', description: 'Group name.' },
+            },
+            required: ['info', 'images'],
+        },
+    },
+    {
+        name: 'pinepaper_game',
+        annotations: {
+            title: 'Game Logic (Pathfinding / Tilemaps)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `GAME-LOGIC primitives as pure computation: A* pathfinding and tilemap boards. Nothing here draws — the outputs plug into the surfaces that do.
+
+ACTIONS:
+- pathfind: { grid: { cols, rows, cellSize?, origin?, blocked?|obstacles? }, start, goal, diagonal? } → { path: [{x,y}], waypoints }
+  start/goal are WORLD coordinates (what items have). obstacles is world rects — pass item bounds and the walls block the board. Deterministic (fixed tie-breaking): same board, same route, every time — replays hold. Diagonal never cuts corners. FEED path DIRECTLY into pinepaper_add_relation moves_along_path (params.path) or a keyframe track: that is the movement system, this is only the route.
+- create_tilemap: { cols, rows, tileSize? (32), origin?, tileset? ([{id (1-based; 0=empty), solid?, name?, fill?}]), fills? ([{x0,y0,x1,y1,tileId}] tile-space rects, painted in order) } → { map, grid, collisionRects, rectCount }
+  map is DATA — persist it in item.data or the project document; render tiles only if the design wants them drawn (a 60×40 board should not be 2,400 canvas items for pure logic). grid feeds pathfind unchanged. collisionRects are greedy-merged (a 60-tile wall is ONE rect) — hand them to pinepaper_physics as static bodies.
+
+RECIPE — a playable maze: create_tilemap with wall fills → batch_create colored rects from map data where you want visuals → pathfind player→exit → moves_along_path along the result. Multiplayer sync is deliberately NOT here: it is a live client-runtime protocol (EventSync), not a canvas op.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['pathfind', 'create_tilemap'], description: 'Game operation' },
+                grid: { type: 'object', properties: { cols: { type: 'number' }, rows: { type: 'number' }, cellSize: { type: 'number' }, origin: { type: 'object' }, blocked: { type: 'array', items: { type: 'number' } }, obstacles: { type: 'array', items: { type: 'object' } } }, description: 'pathfind: the board.' },
+                start: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, description: 'pathfind: start (world coords).' },
+                goal: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, description: 'pathfind: goal (world coords).' },
+                diagonal: { type: 'boolean', description: 'pathfind: 8-way movement (default true).' },
+                cols: { type: 'number', description: 'create_tilemap: board width in tiles.' },
+                rows: { type: 'number', description: 'create_tilemap: board height in tiles.' },
+                tileSize: { type: 'number', description: 'create_tilemap: world units per tile (default 32).' },
+                origin: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, description: 'create_tilemap: world position of tile (0,0).' },
+                tileset: { type: 'array', items: { type: 'object' }, description: 'create_tilemap: [{id, solid?, name?, fill?}] — 1-based ids.' },
+                fills: { type: 'array', items: { type: 'object' }, description: 'create_tilemap: [{x0,y0,x1,y1,tileId}] painted in order.' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_world3d',
+        annotations: {
+            title: '3D World (Terrain / Actors / Camera)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `A real 3D WORLD under the canvas — depth-buffered terrain, sky, sun shadows, an addressable actor stage and a directed camera. ADDITIVE: Paper.js keeps every vector item, hit-test and export path; the world composites underneath the (transparent) Paper canvas.
+
+ACTIONS:
+- create: { spec? ('forest' | 'snowMountain' | 'field' | 'jungle' | a full spec object), character? (true/config → a walkable character) } → { configurableKeys }
+- describe: {} → the ENGINE'S OWN parameter schema — every world parameter with type, range and description. Call this before configure; the tool does not restate the schema, so it cannot drift from the engine.
+- configure: { patch } — live deep-merged change to anything describe lists (colours, fog, sun, terrain amplitude/ridge, seed…). Schema-validated: a wrong key errors NAMING the right one, never a silent no-op.
+- add_actor: { actorId?, x, z, height?, sprite? (a canvas item id), live? } → { actorId }. live: true re-rasterizes the item as it animates — a RIGGED character (walk cycle, expressions) PERFORMS in the world instead of standing there as a photograph of itself.
+- remove_actor / list_actors / set_actor_pose: { actorId, pose: { x?, z?, angle? } } — the setter a timeline, sequencer or agent drives frame by frame.
+- set_camera: { camera: { mode: 'follow' | 'fixed' | 'orbit', target? (actorId), radius?, speed?, eye?, lookAt? } }
+- add_object: { object: { x, z, height?, color? } } (y defaults to sitting ON the terrain) / remove_object: { objectId }
+- remove_world: {} — tears the world down; the Paper canvas was always its own layer and is untouched.
+
+RECIPE — a character walking through a forest: create {spec:'forest'} → import/rig a character on the canvas → add_actor {sprite: itemId, live: true} → set_camera {mode:'follow', target} → drive set_actor_pose over time (or let the built-in character control walk).`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['create', 'describe', 'configure', 'add_actor', 'remove_actor', 'list_actors', 'set_actor_pose', 'set_camera', 'add_object', 'remove_object', 'remove_world'], description: 'World operation' },
+                spec: { description: "create: preset id ('forest'|'snowMountain'|'field'|'jungle') or a full spec object." },
+                character: { description: 'create: include the walkable character (boolean or config).' },
+                patch: { type: 'object', description: 'configure: partial world spec, validated against describe.' },
+                actorId: { type: 'string', description: 'Actor id.' },
+                x: { type: 'number', description: 'add_actor: world x.' },
+                z: { type: 'number', description: 'add_actor: world z.' },
+                height: { type: 'number', description: 'add_actor: world-unit size.' },
+                sprite: { type: 'string', description: 'add_actor: canvas item id for the sprite.' },
+                live: { type: 'boolean', description: 'add_actor: re-rasterize as the item animates.' },
+                pose: { type: 'object', description: 'set_actor_pose: { x?, z?, angle? }.' },
+                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? }.' },
+                objectId: { type: 'string', description: 'remove_object: object id.' },
+            },
+            required: ['action'],
+        },
+    },
     {
         name: 'pinepaper_rigging',
         annotations: {
@@ -1851,12 +2046,20 @@ ACTIONS:
 - set_target_path: { skeletonId, chainId, waypoints[] ({x,y,out?,in?} bezier tangents), duration?, loop? } — the IK effector travels an ARC, not a straight line
 - save_pose: { skeletonId, name? } → { poseId } (snapshot current bone angles)
 - save_shape_key: { skeletonId, name? } → { shapeKeyId } (per-item visual delta for facial-style blends)
+- import_bvh: { bvhText, view? (side|front), fps? (15; 0 = every frame), height? (320px), rootPosition?, name? } → { skeletonId, poses, duration, warnings } — build a NEW rig from a BVH mocap clip (CMU / Mixamo), stick figure included. Root translation returns as a separate track rather than baked into poses.
+- retarget_bvh: { bvhText, skeletonId, fps?, name? } → { skeletonId, matched, unmatchedSource, unmatchedTarget, poses, duration } — drive an EXISTING rig with a BVH clip, bones matched by name. CHECK matched/unmatched in the result: a retarget that matched 2 of 15 bones "succeeds" and looks broken.
+- import_spine: { spineJson, rootPosition?, name? } → { skeletonId, bones, placeholders, animations, warnings } — import a Spine editor JSON export (bones, poses, attachment placeholders).
 
 BREAKDOWN POSES (S12): a breakdown keyframe shapes the ARC + SPACING between key poses (favor biases spacing; boneOffsets lag bones so a tip drags its root — follow-through; movingHold keeps a hold alive). This is the difference between mechanical and lifelike motion.`,
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['create_skeleton', 'add_bone', 'attach_item', 'create_ik_chain', 'add_pose_keyframe', 'set_target_path', 'save_pose', 'save_shape_key'], description: 'Rigging operation' },
+                action: { type: 'string', enum: ['create_skeleton', 'add_bone', 'attach_item', 'create_ik_chain', 'add_pose_keyframe', 'set_target_path', 'save_pose', 'save_shape_key', 'import_bvh', 'retarget_bvh', 'import_spine'], description: 'Rigging operation' },
+                bvhText: { type: 'string', description: 'import_bvh / retarget_bvh: the .bvh file contents.' },
+                spineJson: { type: 'string', description: 'import_spine: the Spine JSON export, as a string.' },
+                view: { type: 'string', enum: ['side', 'front'], description: 'import_bvh: 3D→2D projection plane. CMU walks read best from the side (default).' },
+                fps: { type: 'number', description: 'import_bvh / retarget_bvh: pose sampling rate (default 15; 0 keeps every frame).' },
+                height: { type: 'number', description: 'import_bvh: skeleton height on canvas, px (default 320).' },
                 skeletonId: { type: 'string', description: 'Skeleton id — every action except create_skeleton.' },
                 boneId: { type: 'string', description: 'Bone id — attach_item.' },
                 itemId: { type: 'string', description: 'Canvas item id — attach_item.' },
@@ -3182,9 +3385,14 @@ ACTIONS:
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Transform items: nudge position, flip, or change z-order.
+        description: `Transform items: fit to the canvas, nudge position, flip, or change z-order.
 
 ACTIONS:
+- fit: Scale + centre an item to the EXPORT FRAME. Params: itemId, mode (contain|cover, default contain).
+  Use this after uploading a video or image — an uploaded clip lands at its NATIVE size, so a 640x360
+  source occupies a fraction of a 1920x1080 canvas until you fit it. Accepts a canvas item id OR a
+  media id (vraster_…) returned by pinepaper_media upload_video. 'contain' letterboxes, 'cover' crops.
+  Idempotent: fitting twice is the same as fitting once.
 - nudge: Move item by dx/dy offset. Params: itemId, dx, dy
 - flip: Mirror item. Params: itemId, direction (horizontal|vertical)
 - reorder: Change z-order. Params: itemId, order (bringToFront|sendToBack|moveUp|moveDown)`,
@@ -3193,9 +3401,14 @@ ACTIONS:
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['nudge', 'flip', 'reorder'],
+                    enum: ['fit', 'nudge', 'flip', 'reorder'],
                     description: 'Transform action',
                 },
+                mode: {
+                    type: 'string',
+                    enum: ['contain', 'cover'],
+                    description: 'For fit: contain (whole item visible, may letterbox) or cover (fill frame, crop overflow)',
+                },
                 itemId: { type: 'string', description: 'Target item ID' },
                 dx: { type: 'number', description: 'Horizontal offset (for nudge)' },
                 dy: { type: 'number', description: 'Vertical offset (for nudge)' },
@@ -3213,6 +3426,333 @@ ACTIONS:
             required: ['action'],
         },
     },
+    {
+        name: 'pinepaper_compose',
+        annotations: {
+            title: 'Compose', readOnlyHint: false, destructiveHint: false,
+            idempotentHint: false, openWorldHint: false,
+        },
+        description: `Arrange items into a NAMED COMPOSITION and film it — "here are four photos, lay them out
+nicely and give me a clip".
+
+ACTIONS:
+- list_patterns: ~25 patterns with slot counts and when-to-use definitions. CALL THIS FIRST and
+  CHOOSE FROM THE LIST — do not fall back to a remembered favourite. The catalogue spans media
+  grids, no-crop mosaics, typographic cards (title, quote, magazine cover, before/after), vector
+  slots (badge, logo lockup), and video shapes (lower-third, picture-in-picture).
+- list_reveals: temporal reveals (how items ARRIVE over time — staggers, cascades, beat-driven
+  hard cuts). A composition without a reveal is a still.
+- list_styles: visual style bundles (tone treatments + spacing + the motion each implies).
+- apply: Arrange items. Params: pattern, itemIds (IN SLOT ORDER — the order is the composition),
+  reveal + revealOptions ({ duration, beats }), style, text (fills the pattern's own text slots),
+  assets (SVG for vector slots), audio + grid (beat-sync the cuts to a track), treatment,
+  applyCamera, craft.
+- list_treatments / set_treatment: camera treatments; re-film via rootId.
+
+PICKING WELL: match the pattern to the CONTENT (count, aspect ratios, whether type or video is
+involved) — the list_patterns definitions state this per pattern. Vary reveals and styles across a
+session; identical choices on every scene is a sign the list was never consulted.
+
+WHAT THIS RETURNS, AND WHY IT MATTERS: apply positions ONE root and wires structural relations
+(beside / below / on_top_of) for the rest — it does not set a coordinate per item. The composition
+therefore stays live: move the root and everything follows, swap in a taller image and its
+neighbours re-flow. It also records pp:composedAs / pp:fillsSlot so the scene can be queried and
+re-filmed later.
+
+Prefer this over positioning images yourself. Hand-placed coordinates are what pinepaper_lint_scene
+flags as a badly-composed scene, and they do not survive an artboard change.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['list_patterns', 'list_treatments', 'apply', 'set_treatment'] },
+                pattern: { type: 'string', description: 'Pattern key from list_patterns' },
+                itemIds: { type: 'array', items: { type: 'string' }, description: 'Items in slot order' },
+                treatment: { type: 'string', description: 'Camera treatment key' },
+                rootId: { type: 'string', description: 'Composition root (from apply) — for set_treatment' },
+                applyCamera: { type: 'boolean', description: 'false to arrange without compiling a camera track' },
+                loop: { type: 'boolean' },
+                craft: { type: 'object', description: 'Override craft ratios (gutter, margin…), as fractions of the short canvas edge' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_brand_kit',
+        annotations: {
+            title: 'Brand Kit', readOnlyHint: false, destructiveHint: false,
+            idempotentHint: true, openWorldHint: false,
+        },
+        description: `Apply a brand kit — colours, fonts and roles — across the scene.
+
+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.
+
+KIT SHAPE — only name and colors.primary are required:
+  { "name": "Acme", "colors": { "primary": "#e11d48", "secondary": "#0ea5e9",
+    "accent": "#f59e0b", "background": "#ffffff", "text": "#111111" },
+    "fonts": { "heading": "Inter", "body": "Inter" } }
+Missing roles are filled from what is present (secondary←primary, accent←secondary, background←white,
+text←whatever is readable on the background) and reported as warnings, so a kit with just a primary is
+a valid thing to send.
+
+Items are matched to roles by their current styling. Pass selectionOnly to restrict to the selection.
+Both actions return a WCAG contrast audit, so you can see failing pairs before shipping them.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['plan', 'apply'], description: 'plan (dry run) or apply' },
+                kit: {
+                    type: 'object',
+                    description: 'Brand kit. Requires name and colors.primary; other roles are inferred.',
+                    properties: {
+                        name: { type: 'string' },
+                        colors: {
+                            type: 'object',
+                            properties: {
+                                primary: { type: 'string' },
+                                secondary: { type: 'string' },
+                                accent: { type: 'string' },
+                                background: { type: 'string' },
+                                text: { type: 'string' },
+                            },
+                            required: ['primary'],
+                        },
+                        fonts: {
+                            type: 'object',
+                            properties: { heading: { type: 'string' }, body: { type: 'string' } },
+                        },
+                    },
+                    required: ['name', 'colors'],
+                },
+                selectionOnly: { type: 'boolean', description: 'Restrict to current selection' },
+            },
+            required: ['action', 'kit'],
+        },
+    },
+    {
+        name: 'pinepaper_component',
+        annotations: {
+            title: 'Component', readOnlyHint: false, destructiveHint: false,
+            idempotentHint: false, openWorldHint: false,
+        },
+        description: `Reusable components with per-instance overrides — a master and its instances.
+
+ACTIONS:
+- define: Turn items into a component master. Params: itemIds[], name
+- list: All defined components
+- instantiate: Place an instance. Params: componentId, position, overrides
+- set_override: Change ONE part of ONE instance without detaching it. Params: instanceId, componentKey, prop, value
+- sync: Push the master's current state to every instance (overrides are preserved). Params: componentId
+- update_from_instance: Promote an instance's edits back into the master. Params: instanceId
+- detach: Make an instance an ordinary independent item. Params: instanceId
+
+Overrides are the point: an instance can differ from its master and still receive master updates.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['define', 'list', 'instantiate', 'set_override', 'sync', 'update_from_instance', 'detach'],
+                },
+                itemIds: { type: 'array', items: { type: 'string' }, description: 'Items to define a component from' },
+                componentId: { type: 'string' },
+                instanceId: { type: 'string' },
+                name: { type: 'string' },
+                position: {
+                    type: 'object',
+                    properties: { x: { type: 'number' }, y: { type: 'number' } },
+                },
+                componentKey: { type: 'string', description: 'Which part of the component to override' },
+                prop: { type: 'string', description: 'Property to override, e.g. fillColor or content' },
+                value: { description: 'Override value' },
+                overrides: { type: 'object', description: 'Overrides applied at instantiate time' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_artboard',
+        annotations: {
+            title: 'Artboard', readOnlyHint: false, destructiveHint: false,
+            idempotentHint: true, openWorldHint: false,
+        },
+        description: `Resize the artboard and control how items reflow when it changes.
+
+ACTIONS:
+- list_presets: Named artboard sizes (social, print, web…)
+- set: Resize. Params: preset OR width+height. Items reflow according to their constraints.
+- set_constraints: Declare how ONE item behaves on resize. Params: itemId, horizontal, vertical
+  (left|right|center|scale|both). Without constraints an item just scales with the frame, which is
+  wrong for things that should stay pinned to an edge.
+
+Use this to retarget a finished design to another aspect ratio instead of rebuilding it.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['list_presets', 'set', 'set_constraints'] },
+                preset: { type: 'string', description: 'Preset key from list_presets' },
+                width: { type: 'number' },
+                height: { type: 'number' },
+                itemId: { type: 'string' },
+                horizontal: { type: 'string', description: 'left | right | center | scale | both' },
+                vertical: { type: 'string', description: 'top | bottom | center | scale | both' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_comment',
+        annotations: {
+            title: 'Comment', readOnlyHint: false, destructiveHint: false,
+            idempotentHint: false, openWorldHint: false,
+        },
+        description: `Notes pinned to a place and a moment — review feedback on a scene.
+
+ACTIONS:
+- add: Params: text, plus AT LEAST ONE anchor — itemId (the pin follows the item), x+y (a point on the
+  canvas), or time (a moment on the timeline). They combine: "the exit is too fast" on item_4 at 4.2s.
+- list: Comments with their CURRENT resolved position. Params: time (only those visible at that
+  moment), includeResolved
+- resolve: Mark done. Params: id, resolved. The comment is KEPT — the thread is the record.
+- delete: Remove outright. Params: id
+
+An unanchored comment is refused: a note with no anchor is a text file with extra steps. Deleting an
+item ORPHANS its comments rather than dropping them, and they report themselves as orphaned.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['add', 'list', 'resolve', 'delete'] },
+                id: { type: 'string' },
+                text: { type: 'string' },
+                author: { type: 'string' },
+                itemId: { type: 'string', description: 'Anchor to an item — the pin follows it' },
+                x: { type: 'number' },
+                y: { type: 'number' },
+                time: { type: 'number', description: 'Anchor to a moment (seconds)' },
+                resolved: { type: 'boolean' },
+                includeResolved: { type: 'boolean' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_provenance',
+        annotations: {
+            title: 'Provenance', readOnlyHint: true, destructiveHint: false,
+            idempotentHint: true, openWorldHint: false,
+        },
+        description: `Where an item came from and what depends on it.
+
+ACTIONS:
+- get: Who created and last touched this item (human vs agent), and when. Params: itemId
+- lineage: Walk back to the roots — the chain of imports/derivations that produced it. Params: itemId
+- dependents: What breaks if you delete it. Params: itemId — check this BEFORE removing something
+  other items were built from.
+- record: Note that this item derives from a source. Params: itemId, kind, sourceRef, meta`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['get', 'lineage', 'dependents', 'record'] },
+                itemId: { type: 'string' },
+                kind: { type: 'string', description: 'Lineage kind, e.g. traced | imported | derived' },
+                sourceRef: { type: 'string', description: 'What it came from (item id, asset id, URL)' },
+                meta: { type: 'object' },
+            },
+            required: ['action', 'itemId'],
+        },
+    },
+    {
+        name: 'pinepaper_scene_diff',
+        annotations: {
+            title: 'Scene Diff', readOnlyHint: true, destructiveHint: false,
+            idempotentHint: true, openWorldHint: false,
+        },
+        description: `What changed between two states of the scene — added, removed and modified items.
+
+ACTIONS:
+- history: Compare two undo states. Params: indexA, indexB (see pinepaper_history get_state for the range)
+- version: Compare the LIVE scene against a saved version. Params: versionId
+
+Use this to check your own work: snapshot the history index before a batch, run it, then diff to
+confirm the calls produced the scene you intended rather than assuming a success result means the
+graph is right. Also the safe way to preview a destructive change — diff first, then decide.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['history', 'version'] },
+                indexA: { type: 'number' },
+                indexB: { type: 'number' },
+                versionId: { type: 'string' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_audio_beats',
+        annotations: {
+            title: 'Audio Beats', readOnlyHint: false, destructiveHint: false,
+            idempotentHint: false, openWorldHint: false,
+        },
+        description: `Detect beats in audio and bake an item's animation onto them.
+
+ACTIONS:
+- analyze: Onsets, BPM, confidence and duration. Params: source (asset id, data URL or URL),
+  sensitivity, minGap. Read-only — run it first to see what the track gives you.
+- animate_to_beat: Write a keyframe track that pulses on the beat. Params: itemId, plus EITHER
+  source (analyze first) OR beats[] (times you already have). grid:true uses an even pulse from the
+  detected tempo instead of the raw onsets — the difference between following the rhythm and
+  following the beat. property (default scale), base, accent, decay shape the hit.
+
+Analysis runs ONCE and produces keyframes, deliberately not a live analyser: a keyframe track
+survives MP4, SVG/SMIL and Lottie export, and gives the same answer on every run. A live analyser
+node survives none of them.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['analyze', 'animate_to_beat'] },
+                source: { type: 'string', description: 'Asset id, data URL, or URL' },
+                itemId: { type: 'string' },
+                beats: { type: 'array', items: { type: 'number' }, description: 'Beat times (s) you already have' },
+                grid: { type: 'boolean', description: 'Even pulse from the tempo instead of raw onsets' },
+                property: { type: 'string', description: 'Property to pulse (default scale)' },
+                base: { type: 'number' },
+                accent: { type: 'number' },
+                decay: { type: 'number' },
+                sensitivity: { type: 'number', description: 'Lower it if no beats are detected' },
+                minGap: { type: 'number', description: 'Minimum seconds between onsets' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_template_params',
+        annotations: {
+            title: 'Template Params', readOnlyHint: false, destructiveHint: false,
+            idempotentHint: true, openWorldHint: false,
+        },
+        description: `Templates that take typed inputs — the same scene rebuilt for your text and colours.
+
+ACTIONS:
+- get: The template's declared params with their defaults, types and ranges. Params: templateId.
+  Call this first to discover what a template will accept; most templates declare none.
+- apply: Load the template with your values. Params: templateId, params
+
+Values are COERCED to their declared type and range-checked, and anything uncoercible falls back to
+the default with a warning rather than reaching the template — so a number param cannot arrive as the
+string "5" and silently produce "55" instead of 10. The same declaration drives the editor panel and
+this tool, so a control cannot exist that an agent cannot set.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['get', 'apply'] },
+                templateId: { type: 'string' },
+                params: { type: 'object', description: 'key → value, coerced to the declared types' },
+            },
+            required: ['action', 'templateId'],
+        },
+    },
     {
         name: 'pinepaper_history',
         annotations: {
@@ -3257,8 +3797,17 @@ ACTIONS:
 ACTIONS:
 - apply: Apply a single filter. Params: itemId, filterName, params
 - chain: Apply multiple filters in sequence. Params: itemId, filters (array of {name, params})
+- analyze_palette: { itemId, maxSwatches? (8) } → { swatches: [{hex, share}…] largest-area-first } — READ an image's palette. The natural loop: analyze image A → recolor_palette (or the paletteMap filter) on image B with A's hexes.
+- recolor_palette: { itemId, mapping ({from,to}[] or {'#old':'#new'}), amount?, preserveShading? } — swap colours, keep the shading (GPU).
 
-Available filters (GPU raster set): blur, grayscale, sepia, brightness, contrast, saturation, invert, posterize, hsl (hue/saturation/lightness), colorTint (color, intensity, blendMode), vignette (intensity, radius), edgeDetect, halftoneDots (size, angle), halftoneCMYK (size), dither (levels).
+Available filters (GPU raster set):
+- Color: grayscale, sepia, brightness, contrast, saturation, invert, posterize (levels), hsl (hue/saturation/lightness), colorTint (color, intensity, blendMode), colorMatrix (matrix), duotone (shadow, highlight, mix), paletteMap (swatches[], amount, preserveShading — recolor to a fixed palette)
+- Stylize: vignette (intensity, radius), edgeDetect, halftoneDots (size, angle), halftoneCMYK (size), dither (levels), grain (amount, seed), scanlines (intensity, period), chromaticAberration (amount), blur
+- Light (additive): bloom (amount, threshold, radius), glow, halation (warm-fringed bloom; color), lightShafts (amount, threshold, decay, density, x, y, color — volumetric rays from a point)
+- Keying: lumaKey (threshold, softness, invert)
+- SECOND-INPUT (params.map = another item's id, resolved to its pixels): displace (amount, dispersion, map, mapChannel — the map's brightness pushes pixels), refract (displace with per-channel dispersion — glass), trackMatte (channel, invert, strength — prefer pinepaper_media apply_track_matte for the live version), datamosh (amount, block, map? — self-moshes without a map)
+
+RECIPE — grunge poster: chain [grain, scanlines, vignette]. Glass header: refract with map = a gradient item.
 (Scene-wide filters — sharpen/emboss/noise/vintage etc. — are a different surface: use pinepaper_add_filter.)`,
         inputSchema: {
             type: 'object',
@@ -5897,7 +6446,8 @@ EXAMPLES:
 - {platform: "instagram"} — auto-selects best format
 - {platform: "instagram", format: "mp4"} — force MP4
 - {platform: "web", format: "svg"} — animated SVG
-- {platform: "youtube", format: "mp4", framing: "camera"} — render only what the camera frames during the walkthrough`,
+- {platform: "youtube", format: "mp4", framing: "camera"} — render only what the camera frames during the walkthrough
+- {platform: "youtube", format: "mp4", duration: 30, estimateOnly: true} — how big would that be? (renders nothing)`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -5921,11 +6471,15 @@ EXAMPLES:
                     enum: ['canvas', 'camera'],
                     description: 'Output framing. "canvas" (default) renders the full canvas. "camera" renders only the first-keyframe viewport of a camera_animates walkthrough — video formats only.',
                 },
+                estimateOnly: {
+                    type: 'boolean',
+                    description: 'Preflight only — return the estimated file size for these exact settings and render nothing. Modeled for mp4/webm/gif; png/pdf/svg report confidence "none" (no dimension-based model exists for them).',
+                },
                 duration: {
                     type: 'number',
                     minimum: 0.5,
                     maximum: 60,
-                    description: 'Video duration in seconds for mp4/webm/gif (default 5, max 60). Static formats ignore this. If you set play_timeline to N seconds, pass the same N here.',
+                    description: 'Video duration in seconds for mp4/webm/gif (default 5). Max 60 for mp4/webm; GIF is capped at 15 because it has no bitrate target, so size scales with frames × dimensions — use mp4/webm for longer clips. Static formats ignore this. If you set play_timeline to N seconds, pass the same N here.',
                 },
             },
             required: ['platform'],