@pinepaper.studio/mcp-server 1.5.5 → 1.6.0

package/dist/tools/definitions.js

@@ -9,7 +9,7 @@
  */
 import { COMPACT_DESCRIPTIONS } from './compact-descriptions.js';
 import { MINIMAL_DESCRIPTIONS } from './minimal-descriptions.js';
-import { EffectTypeSchema, SimpleAnimationTypeSchema, } from '../types/schemas.js';
+import { EffectTypeSchema, SimpleAnimationTypeSchema, GEOMETRY_OPERATIONS, } from '../types/schemas.js';
 /**
  * Vocabulary lists derived from Zod schemas so tool descriptions stay in
  * sync automatically. The description-schema-parity test
@@ -55,7 +55,7 @@ RULES:
 ─── BATCH OPERATIONS (12 types, in order) ───
 
 CANVAS:  set_canvas_size (width/height or preset) → set_background (color) → execute_generator (procedural art)
-ITEMS:   create (itemType, position, properties) → modify (itemId, properties) → delete (itemId)
+ITEMS:   create (itemType, position, properties) → modify (itemId, properties) → delete (itemId) → group (itemIds → one entity)
 ANIMATE: animate (loop presets) → keyframe_animate (timed reveals) → relation (behavioral links)
 EFFECTS: apply_mask (reveal animations) → apply_effect (sparkle/blast/bubbles/fireflies/trail...)
 PLAY:    play_timeline (start playback)
@@ -72,19 +72,35 @@ Choose based on mood:
 
 ─── ITEMS ───
 
-Shapes: circle, rectangle, star, ellipse, triangle, polygon, line, arc, path
+Shapes: circle, rectangle, star, ellipse, triangle, polygon, line, arc, path, pentagon, hexagon, diamond, arrow, heart
 Text: text (content, fontSize, fontFamily, color, fontWeight)
   Dynamic text: set contentType on text items → clock (live time), timer (elapsed), countdown (from N seconds), stopwatch (pauseable)
 All items: opacity, shadowColor, shadowBlur, blendMode, strokeColor, strokeWidth
 
 SVG imports for recognizable objects (planes, cars, animals, buildings):
   pinepaper_search_assets → pinepaper_import_asset (850k+ SVG icons)
+  An imported SVG is ONE opaque item. To move/recolor its parts (a wheel, a window), pinepaper_group action:"break_apart" splits it into individually movable, re-grouped sub-parts.
+
+Photos / raster images (on-device, no upload):
+  pinepaper_detect_objects — find objects (labeled boxes), or asNodes:true to promote each to an image-anchored design NODE (pp:Detected*) you can bind a shape to with a relation (relational compositing — e.g. a hat that follows a detected person as the photo moves).
+  pinepaper_extract_object — crop the best-matching object (label: "cat") out of a photo into its own item.
+
+⚠️ COMPOSITE OBJECTS — GROUP THE PARTS:
+  When the user asks for ONE specific named object built from multiple primitives — a car (body + wheels + windows), a robot, a house, a tree, a snowman, a character — the pieces are INDEPENDENT until grouped. Without grouping, dragging the "car" only moves the piece grabbed; the wheels stay behind, and it can't be moved/animated as one thing.
+  → After creating the parts, add a "group" op listing them (reference batch-created parts as "$0","$1",…). This is the default for any nameable object. Grouping is non-destructive — the user can ungroup anytime (pinepaper_group action:"ungroup"), so grouping is always the safe choice.
+  → Do NOT group a whole scene/infographic whose elements move independently — only group the parts that form ONE object. A scene may contain several groups (e.g. two separate cars).
+
+⚠️ MOVE vs ANIMATE — pick the tool from the user's intent:
+  • Reposition (no time, no path): "put X at (x',y')", "move X to the corner" → modify { x, y }. A single, instant position change — NOT an animation.
+  • Animated A→B move ("animate X moving to (x',y')", "slide it over 2s", "have it drift to the corner") → keyframe_animate with two keyframes: [{time:0, properties:{x,y}}, {time:T, properties:{x',y'}}]. Use this when the user wants the motion itself to be visible.
+  • Follow a multi-point PATH (the user lists several coordinates, or "make X follow this path / trace these points (x1,y1),(x2,y2),…") → relation moves_along_path with params.path = [{x,y},…] (speed, closed, easing optional). One coordinate list = one path-follow, not N separate moves.
+  When the request is ambiguous between a static move and an animated one, a one-shot reposition is the literal reading; only animate if motion/timing/path is implied.
 
 ─── ANIMATION (all in batch) ───
 
 Loop presets (animate): pulse, rotate, bounce, fade, wobble, slide, typewriter
 Keyframe (keyframe_animate): [{time, properties, easing}] → opacity, scale, scaleX, scaleY, x, y, rotation, fillColor, strokeColor, fontSize
-Relations (relation): orbits, follows, attached_to, points_at, mirrors, parallax, wave_through, morphs_to, group_morphs_to, moves_along_path (+ 9 more in batch_execute schema)
+Relations (relation): orbits, follows, attached_to, points_at, mirrors, parallax, wave_through, morphs_to, group_morphs_to, moves_along_path, is_midpoint_of, is_circumcenter_of, construction_reveal (+ geometric constraints & more in batch_execute schema)
 Masks (apply_mask): wipeLeft, wipeRight, wipeUp, wipeDown, iris, irisOut, star, heart, curtainHorizontal, curtainVertical, cinematic, diagonalWipe, revealUp, revealDown
 Effects (apply_effect): sparkle, blast
 
@@ -347,6 +363,11 @@ ITEM TYPES:
 - path: Custom path with segments or SVG data (properties: segments, pathData, strokeColor, fillColor, closed, smooth)
 - line: Line between two points (properties: from, to, strokeColor, strokeWidth)
 - arc: Curved arc through three points (properties: from, through, to, strokeColor)
+- pentagon: Regular 5-sided polygon (properties: radius, color)
+- hexagon: Regular 6-sided polygon (properties: radius, color)
+- diamond: 4-sided diamond/rhombus (properties: radius, color)
+- arrow: Right-pointing block arrow (properties: width, height, color)
+- heart: Heart shape (properties: color)
 
 PATH FOR CUSTOM SHAPES:
 Use itemType: "path" with either:
@@ -384,7 +405,7 @@ For glossy 3D spheres, use pinepaper_create_glossy_sphere instead. For diagonal
             properties: {
                 itemType: {
                     type: 'string',
-                    enum: ['text', 'circle', 'star', 'rectangle', 'triangle', 'polygon', 'ellipse', 'path', 'line', 'arc'],
+                    enum: ['text', 'circle', 'star', 'rectangle', 'triangle', 'polygon', 'ellipse', 'path', 'line', 'arc', 'pentagon', 'hexagon', 'diamond', 'arrow', 'heart'],
                     description: 'Type of item to create',
                 },
                 position: {
@@ -428,6 +449,14 @@ For glossy 3D spheres, use pinepaper_create_glossy_sphere instead. For diagonal
                     type: 'number',
                     description: 'Animation speed multiplier (for simple animations, default: 1.0)',
                 },
+                animationIntensity: {
+                    type: 'number',
+                    description: 'Loop animation amplitude (0.1 = ±10%, default 0.15); drives pulse/wobble/bounce/breathe amplitude and is honored by SVG/SMIL/widget export.',
+                },
+                animationDelay: {
+                    type: 'number',
+                    description: 'Loop animation start delay in seconds.',
+                },
                 keyframes: {
                     type: 'array',
                     description: "Keyframe array for inline keyframe animation (requires animationType: 'keyframe')",
@@ -486,7 +515,7 @@ GRADIENT OBJECT FORMAT:
 
 LETTER-COLLAGE PROPS (non-destructive — registry ids, animations, relations, effects, deformations all preserved):
 - palette (collage group): Swap palette name in-place. e.g. "wordle", "spring", "sunset", "magazine". Walks existing letters, rewrites tile + text fills. No geometry change.
-- collageStyle (collage group): Swap visual style — "tile" | "magazine" | "paperCut" | "fold" | "gradient" | "image". Geometry rebuilds; every registryId is preserved via graft.
+- collageStyle (collage group): Swap visual style — "tile" | "magazine" | "paperCut" | "fold" | "gradient" | "image" | "particle". Geometry rebuilds; every registryId is preserved via graft.
 - palette + collageStyle (collage group): Combine in one call to apply both atomically.
 - bgColor (single letter group, child of a collage): Tile/background fill for that one letter.
 - textColor (single letter group): PointText fill for that one letter.
@@ -1222,6 +1251,718 @@ EXAMPLE:
             },
         },
     },
+    {
+        name: 'pinepaper_geometry',
+        annotations: {
+            title: 'Geometry Construction',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Run an exact geometric construction (FxTool's app.geometry library) and optionally create a canvas item from the result. Use this instead of hand-computing vertices, intersections, or centers — it returns precise coordinates and never NaN (degenerate inputs return null with an explanatory error).
+
+Compose it with the create tools, e.g. compute a pentagon's vertices then drop them straight into a polygon. With createAs it does both in one call.
+
+OPERATIONS (args are positional; points are {x,y}, lines are {p1,p2}, circles are {center,radius}, angles in radians):
+- Points: point(x,y) · distance(a,b) · midpoint(a,b) · lerpPoint(a,b,t) · centroid([pts]) · translatePoint(p,dx,dy) · rotatePoint(p,center,angleRad) · scalePoint(p,center,factor)
+- Polygons (→ vertex list): regularPolygon(cx,cy,radius,sides,rotation?) · star(cx,cy,outerR,innerR,points,rotation?) · polygonFromVertices([pts])
+- Lines (→ {p1,p2}): lineThrough(a,b) · lineDirection(line) · lineIntersection(l1,l2) · projectPointToLine(p,line) · perpendicular(line,through) · parallel(line,through) · perpendicularBisector(a,b) · reflectPoint(p,line)
+- Angles: angle(a,b,c) → radians at vertex b · angleBisector(a,vertex,c) → line
+- Circles: circle(cx,cy,r) · pointOnCircle(circ,angleRad) · circumcenter(a,b,c) · circleThrough(a,b,c) → circumcircle · incenter(a,b,c) · tangentPointsFromExternal(circ,p) → up to 2 touch points
+
+createAs (optional): also create an item from the result — a vertex-list result → polygon, a circle result → circle, a point result → a small marker. Style keys (color/fillColor/strokeColor/strokeWidth) pass through to app.create. Omit for compute-only.
+
+RETURNS: { success, operation, result, itemId } — result is the raw geometry; itemId is set only when createAs created something. null/degenerate constructions return { success:false, ..., error }.
+
+EXAMPLES:
+- Pentagon: { operation: "regularPolygon", args: [400, 300, 120, 5], createAs: { fillColor: "#FF6B6B" } }
+- Circumcircle of a triangle: { operation: "circleThrough", args: [{x:100,y:100},{x:300,y:120},{x:200,y:300}], createAs: { strokeColor: "#333", fillColor: "transparent" } }
+- Intersection of two lines (compute only): { operation: "lineIntersection", args: [{p1:{x:0,y:0},p2:{x:100,y:100}}, {p1:{x:0,y:100},p2:{x:100,y:0}}] }
+
+For figures that must stay correct as anchors move (GeoGebra-style), use the geometric constraint relations on pinepaper_add_relation (is_midpoint_of, is_circumcenter_of, …) instead.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                operation: {
+                    type: 'string',
+                    enum: [...GEOMETRY_OPERATIONS],
+                    description: 'Which geometry construction helper to run.',
+                },
+                args: {
+                    type: 'array',
+                    description: 'Positional arguments in order. Points are {x,y} objects; lines {p1,p2}; circles {center,radius}; angles in radians.',
+                },
+                createAs: {
+                    type: 'object',
+                    description: 'When present, also create an item from the result (vertex list → polygon, circle → circle, point → marker). Style keys pass through to app.create. Optional itemType / radius for point markers.',
+                },
+            },
+            required: ['operation'],
+        },
+    },
+    {
+        name: 'pinepaper_equation_path',
+        annotations: {
+            title: 'Equation-Driven Path',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Create a path ITEM from a math equation (FxTool's app.createEquationPath, Expression IR — S10 B5). Deterministic: the math strings are PARSED (expr-to-ir, no eval) and sampled on the Expression IR, so the same input always yields the same curve. Use this instead of hand-computing points for a curve.
+
+KINDS:
+- function (default): y = f(variable). expr, e.g. "sin(x) * 80". variable defaults to 'x'.
+- parametric: x = fx(param), y = fy(param). xExpr + yExpr, e.g. xExpr "cos(3*t)*120", yExpr "sin(2*t)*80". param defaults to 't'.
+- fourier: sum of harmonics. harmonics: [{ freq, amp, phase? }, …].
+- preset: a curated curve. preset ∈ spiral | rose | lissajous | astroid | heart | spirograph (preset-specific tuning passed as top-level fields, e.g. { kind:"preset", preset:"rose", k:5, r:140 }).
+
+SAMPLING & PLACEMENT: min/max (sample range) · samples (default 200) · scale (multiply coords) · x/y (canvas origin, default canvas center) · flipY (math y-up → screen y-down, default true) · style (strokeColor/strokeWidth/fillColor forwarded to create).
+
+warp (optional): chained parametric warp(s) — displace each sampled point by { dx, dy }, expressions of x, y (point coords) and t (0..1 along the path). Pass one object or an array to chain.
+
+RETURNS: { success, kind, itemId } — itemId is the created path. Bad expressions / empty ranges return { success:false, error }.
+
+To make an item TRAVEL along an equation curve (instead of drawing it), use pinepaper_add_relation relationType moves_along_path with params.equation instead.
+
+EXAMPLES:
+- Sine wave: { kind: "function", expr: "sin(x/40) * 60", min: -300, max: 300, style: { strokeColor: "#4f46e5" } }
+- Lissajous: { kind: "parametric", xExpr: "cos(3*t)*120", yExpr: "sin(2*t)*80", min: 0, max: 6.2832 }
+- Rose preset: { kind: "preset", preset: "rose", k: 5, r: 140 }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                kind: { type: 'string', enum: ['function', 'parametric', 'fourier', 'preset'], description: "Equation kind (default 'function')" },
+                expr: { type: 'string', description: "y = f(variable) — kind 'function'" },
+                xExpr: { type: 'string', description: "x = fx(param) — kind 'parametric'" },
+                yExpr: { type: 'string', description: "y = fy(param) — kind 'parametric'" },
+                harmonics: { type: 'array', description: "kind 'fourier': [{ freq, amp, phase? }, …]" },
+                preset: { type: 'string', enum: ['spiral', 'rose', 'lissajous', 'astroid', 'heart', 'spirograph'], description: "kind 'preset': curated curve" },
+                variable: { type: 'string', description: "Sample variable for 'function' (default 'x')" },
+                param: { type: 'string', description: "Sample variable for 'parametric'/'preset' (default 't')" },
+                min: { type: 'number', description: 'Sample range start' },
+                max: { type: 'number', description: 'Sample range end' },
+                samples: { type: 'number', description: 'Sample count (default 200)' },
+                scale: { type: 'number', description: 'Multiply equation coords (default 1)' },
+                x: { type: 'number', description: 'Canvas origin x (default: canvas center)' },
+                y: { type: 'number', description: 'Canvas origin y (default: canvas center)' },
+                flipY: { type: 'boolean', description: 'Math y-up → screen y-down (default true)' },
+                style: { type: 'object', description: 'Path style forwarded to create (strokeColor, strokeWidth, fillColor, …)' },
+                warp: { description: 'Chained parametric warp(s): { dx, dy } expressions of x, y, t — one object or an array' },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_event',
+        annotations: {
+            title: 'Event Channel',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Manage the pp:event channel — the backbone of EVENT-DRIVEN SCENE CHAINS (FxTool S11). An event is a fireable channel; relations with an event as their source run when it fires. This is how you author a LONG scene as a graph of timed beats instead of a keyframe track.
+
+ACTIONS:
+- create: make an event. { name (required), payloadType?, x?, y? } → returns { eventId }. Use the eventId as the sourceId of on_event_* relations (pinepaper_add_relation).
+- pulse: fire an event now. { eventId (required), payload? }. Kicks off a chain.
+
+TYPICAL SCENE CHAIN:
+1. pinepaper_event create → e0, e1, e2 (one per beat).
+2. Chain them: add_relation on_event_fire_after from e0→e1 (params.delay, timeline:'canvas'), e1→e2, …
+3. Give each beat reactions: on_event_add_relation (spawn an orbit/path), on_event_set_color, on_event_set_property, on_event_set_visibility (all via pinepaper_add_relation, sourceId=the event).
+4. pinepaper_event pulse e0 to start. Canvas-timed fires are scrub/loop/replay-stable.
+
+RETURNS: create → { success, action, eventId }; pulse → { success, action, eventId }.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['create', 'pulse'], description: "'create' a pp:event · 'pulse' it to fire" },
+                name: { type: 'string', description: "Event name — required for action 'create'" },
+                payloadType: { type: 'string', description: "Payload type label (default 'Pulse') — action 'create'" },
+                x: { type: 'number', description: 'Canvas x for the event marker — action create' },
+                y: { type: 'number', description: 'Canvas y for the event marker — action create' },
+                eventId: { type: 'string', description: "Event id to fire — required for action 'pulse'" },
+                payload: { description: "Optional value forwarded to listeners — action 'pulse'" },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_construction_sequence',
+        annotations: {
+            title: 'Construction Sequence',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Reveal a geometric figure step by step (FxTool's app.constructionSequence, Layer 3). Each step hides its items and attaches a timeline-driven construction_reveal relation, so playing the timeline draws the construction one step at a time — replayable, scrubbable, and editable as relation graph data (not a one-shot script). Builds on the construction_reveal relation; pair it with pinepaper_geometry / the geometric constraint relations.
+
+ACTIONS:
+- build: { steps, stepDuration?, fadeIn? } — steps is an ordered array; each step is an array of item ids (or { items: [ids], label }) revealed together. Step i reveals at i * stepDuration seconds. Items are hidden until their step opens. Extends the keyframe timeline to fit. Returns { sequenceId, stepCount, totalDuration }.
+- play: { sequenceId?, loop?, duration? } — play the sequence on the timeline (defaults to the most recently built one).
+- clear: { sequenceId? } — remove the reveal relations and restore items to full opacity.
+- list: enumerate built sequences.
+
+EXAMPLE (reveal two points, then their midpoint, then a circle):
+{ action: "build", steps: [["pt_a","pt_b"], ["mid_ab"], ["circ"]], stepDuration: 1 }
+then { action: "play", loop: true }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['build', 'play', 'clear', 'list'],
+                    description: 'build a sequence, play it, clear it, or list sequences.',
+                },
+                steps: {
+                    type: 'array',
+                    description: 'For build: ordered steps; each is an array of item ids or { items: [ids], label }. Step i reveals at i * stepDuration seconds.',
+                },
+                stepDuration: { type: 'number', description: 'For build: seconds between steps (default 1).' },
+                fadeIn: { type: 'number', description: 'For build: per-step fade-in seconds (default 0.3).' },
+                sequenceId: { type: 'string', description: 'For play/clear: the cseq_ id from build (default = most recent).' },
+                loop: { type: 'boolean', description: 'For play: loop the timeline (default false).' },
+                duration: { type: 'number', description: 'For play: override total duration in seconds.' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_group',
+        annotations: {
+            title: 'Group / Ungroup',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Combine several items into ONE entity that selects, drags, and animates as a single unit — or ungroup one back into loose items.
+
+⚠️ GROUP THE PARTS OF A COMPOSITE OBJECT. When you build a specific named object out of multiple primitives — a car (body + wheels + windows), a robot, a house, a tree, a character — the pieces are independent until you group them. WITHOUT grouping, dragging the "car" only moves the one shape you grabbed; the wheels stay behind. After creating all the parts, group them so the object behaves as one thing. Grouping is non-destructive and always safe: the user (or you, via action "ungroup") can break it apart later. In a single pipeline, prefer the "group" operation inside pinepaper_agent_batch_execute (reference the parts as "$0","$1",… ) so the object is grouped the moment it's built.
+
+Do NOT group a whole scene/infographic whose elements are meant to move independently — only group the parts that form ONE object.
+
+ACTIONS:
+- group: combine itemIds (registry IDs) into a new group. Optional groupName. Returns { groupId, itemCount }.
+- ungroup: dissolve the group with groupId back into its individual items (which keep their own ids). Returns { ungrouped: true }.
+- break_apart: split an IMPORTED SVG / group / compound-path (itemId) into its individually movable sub-parts, re-wrapped as one group. Use this after pinepaper_import_asset / import_svg when the user wants to move or recolor the PARTS of an imported object (a wheel, a window) — an imported icon is a single opaque item until broken apart. Each part gets its own registry id. Returns { groupId, partIds, partCount }.
+
+EXAMPLES:
+- Group a car you built: { action: "group", itemIds: ["body_1","wheel_2","wheel_3","window_4"], groupName: "car" }
+- Ungroup it: { action: "ungroup", groupId: "group_17" }
+- Make an imported SVG's parts movable: { action: "break_apart", itemId: "svg_5" }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['group', 'ungroup', 'break_apart'],
+                    description: 'group: combine itemIds into one entity. ungroup: dissolve a group. break_apart: split an imported SVG/group/compound-path into movable parts.',
+                },
+                itemIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'For group: registry IDs of the items to combine.',
+                },
+                itemId: { type: 'string', description: 'For break_apart: registry ID of the imported SVG / group / compound-path to decompose.' },
+                groupName: { type: 'string', description: 'For group: optional name (e.g. "car", "robot").' },
+                groupId: { type: 'string', description: 'For ungroup: registry ID of the group to dissolve.' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_camera_director',
+        annotations: {
+            title: 'Camera Director',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Direct a cinematic camera walkthrough of the scene from a high-level SHOT LIST. Compiles to a single camera_animates keyframe track (one camera — WYSIWYG between the editor view and any export size). Great for "give me a camera tour", "pan across the scene", "zoom into each item in turn".
+
+ACTIONS:
+- auto: auto-generate a walkthrough — one medium push-in shot per top-level item, smooth eased moves. Options: order ("reading" default | "reverse" | "creation"), hold (dwell seconds), establishing (open on a wide shot of everything), loop. Returns the generated shots.
+- shots: apply an explicit shot list. Each shot: { subjects: "everything" | [itemIds], framing: "tight"|"medium"|"wide" (or a zoom number), hold, moveIn ("push-in"|"pan"), ease ("smooth"|"linear"|"settle"|"snap"), transition (seconds to travel in) }.
+
+Pair with pinepaper_agent_export (framing: "camera") to render the walkthrough as video.
+
+EXAMPLES:
+- Auto tour: { action: "auto", establishing: true, hold: 1.5, loop: true }
+- Explicit: { action: "shots", shots: [ { subjects: "everything", framing: "wide", hold: 1 }, { subjects: ["hero_1"], framing: "tight", moveIn: "push-in", hold: 2 } ] }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['auto', 'shots'], description: 'auto: generate a walkthrough. shots: apply an explicit shot list.' },
+                shots: {
+                    type: 'array',
+                    description: 'For "shots": ordered shot list. Each: { subjects, framing, hold, moveIn, ease, transition }.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            subjects: { description: '"everything" or an array of item registry IDs' },
+                            framing: { description: '"tight" | "medium" | "wide", or a zoom number' },
+                            hold: { type: 'number' },
+                            moveIn: { type: 'string' },
+                            ease: { type: 'string', enum: ['smooth', 'linear', 'settle', 'snap'] },
+                            transition: { type: 'number' },
+                        },
+                    },
+                },
+                order: { type: 'string', enum: ['reading', 'reverse', 'creation'], description: 'For "auto": item visiting order.' },
+                hold: { type: 'number', description: 'For "auto": per-shot dwell seconds.' },
+                establishing: { type: 'boolean', description: 'For "auto": open with a wide establishing shot.' },
+                loop: { type: 'boolean', description: 'Loop the walkthrough.' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_detect_objects',
+        annotations: {
+            title: 'Detect Objects',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Run on-device object detection (fully local — no upload) over an imported image and either draw labeled boxes or promote each detection to a design node. bbox detection, not pixel-mask segmentation.
+
+First import an image (pinepaper_import_image / pinepaper_import_asset), then call this on it.
+
+MODELS:
+- Default (no queries): DETR — fast, fixed 80 COCO classes (person, car, dog, chair, …).
+- queries given: OWL-ViT open-vocabulary (zero-shot) — finds WHATEVER you describe ("red umbrella", "traffic light", "logo"), not limited to 80 classes. Larger one-time on-device model download. Pass queries as a list or comma-separated string.
+
+MODES:
+- Default (asNodes omitted/false): draws a labeled rectangle over each detection. Returns { ok, drawn, detections: [{label, confidence}] }.
+- asNodes: true — RELATIONAL COMPOSITING. Instead of boxes, promotes each detection to a typed, image-anchored DESIGN NODE: a registered relation target carrying a pp:Detected* type aliased (rdfs:subClassOf) to a Wikidata entity, plus its confidence. Returns { ok, promoted, count, nodes: [{id, label, ppType, wikidata, confidence}] }. You can then bind a shape on/around/at a detected object with a relation (e.g. follows / attached_to) and it tracks the image as it moves.
+
+PARAMS: itemId (image; default = most recent image), threshold (0-1, default ~0.35), asNodes.
+
+EXAMPLE (relational compositing — put a hat on a detected person):
+1) { } → detect, or { asNodes: true } → get nodes [{ id: "det_3", label: "person", ... }]
+2) create the hat → pinepaper_add_relation { sourceId: hatId, targetId: "det_3", relationType: "follows" }
+
+NOTE: requires an FxTool build that exposes on-device detection (app.detectObjects). Returns { success: false, error } with a hint otherwise.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                itemId: { type: 'string', description: 'Registry ID of the image to scan (default: most recent image).' },
+                threshold: { type: 'number', description: 'Confidence threshold 0-1 (default ~0.35 DETR, ~0.1 open-vocab).' },
+                asNodes: { type: 'boolean', description: 'Promote each detection to a typed, image-anchored design node (relation target) instead of drawing a box.' },
+                queries: {
+                    description: 'Open-vocabulary search (OWL-ViT): a list of strings (or comma-separated string) describing what to find — e.g. ["red umbrella","logo"]. Omit for the default 80-class DETR detector.',
+                    oneOf: [
+                        { type: 'array', items: { type: 'string' } },
+                        { type: 'string' },
+                    ],
+                },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_extract_object',
+        annotations: {
+            title: 'Extract Object',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Detect objects in an imported image and crop the best match into a NEW item — e.g. pull the cat out of a photo. On-device, no upload.
+
+PARAMS: label (what to extract, e.g. "cat", "person"; default = highest-confidence detection), itemId (source image; default = most recent), x/y (optional hint to disambiguate which instance), threshold (0-1).
+
+RETURNS: { ok, object (matched label), extracted, itemId (the new item) }.
+
+EXAMPLE: { label: "cat" } — find the cat and crop it into its own movable item.
+
+NOTE: requires an FxTool build that exposes on-device detection (app.extractObject).`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                label: { type: 'string', description: 'What to extract (e.g. "cat", "person"). Default = highest-confidence detection.' },
+                itemId: { type: 'string', description: 'Registry ID of the source image (default: most recent image).' },
+                x: { type: 'number', description: 'Optional hint X (canvas coords) to disambiguate which detection to extract.' },
+                y: { type: 'number', description: 'Optional hint Y (canvas coords).' },
+                threshold: { type: 'number', description: 'Confidence threshold 0-1.' },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_arrange',
+        annotations: {
+            title: 'Arrange (Z-Order)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Change an item's stacking order (z-order) — which items draw on top of which.
+
+ACTIONS:
+- front: bring the item to the TOP of the stack (drawn over everything).
+- back: send it to the BOTTOM (behind everything; drops to the background layer if needed).
+- forward: move it up ONE step.
+- backward: move it down ONE step.
+
+USE WHEN:
+- A shape is hidden behind another and should be on top ("bring the logo to the front").
+- Layering a composition (move a background panel behind the text).
+
+EXAMPLE: { itemId: "circle_3", action: "front" }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                itemId: { type: 'string', description: 'Registry ID of the item to reorder.' },
+                action: {
+                    type: 'string',
+                    enum: ['front', 'back', 'forward', 'backward'],
+                    description: 'front: to top. back: to bottom. forward: up one. backward: down one.',
+                },
+            },
+            required: ['itemId', 'action'],
+        },
+    },
+    {
+        name: 'pinepaper_validate_scene',
+        annotations: {
+            title: 'Validate Scene',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Audit the LIVE canvas with FxTool's OntologyValidator and get structured, actionable diagnostics instead of console warnings. Each diagnostic is { code, severity, message, target, context, fix } — so you can re-plan from the feedback.
+
+CHECKS: unknown item types, dangling relation targets / missing anchors, unknown properties, malformed keyframes, and relation cycles.
+
+USE WHEN:
+- Confirming a scene is well-formed after a batch of edits
+- Diagnosing why a relation/animation isn't behaving
+- Pre-flighting proposed mutations before applying them
+
+MODES:
+- No args → audit the current scene. Returns { ok, diagnosticCount, diagnostics }.
+- ops → validate a batch of PROPOSED ops against the live scene WITHOUT applying them. Each op is { kind: "addRelation"|"create"|"modify"|"delete", ... }. Ids created earlier in the batch count as existing for later ops, so forward references don't false-error.
+
+This complements pinepaper_validate_design (which validates a definition object, not the live scene).
+
+EXAMPLE (pre-flight): { ops: [ { kind: "create", id: "c1", itemType: "circle" }, { kind: "addRelation", source: "c1", target: "missing", relationType: "orbits" } ] }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ops: {
+                    type: 'array',
+                    description: 'Optional: proposed ops to validate against the live scene instead of auditing the current scene. Each is { kind, ... }.',
+                },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_capture_frames',
+        annotations: {
+            title: 'Capture Frames (Deterministic)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Deterministically render the scene at a list of times and snapshot each frame (FxTool's app.captureFramesAt, S3). Math.random is seeded ONCE around the whole sequence and the scene is evaluated at each time via sceneAt(t), so the same scene + same { times, seed } produces identical frames every run — even with random generators/particles.
+
+By default returns a cheap per-frame hash + byte size (token-light), plus uniqueHashes / allIdentical, so you can:
+- Verify determinism: run twice with the same seed → identical hashes.
+- Detect motion: uniqueHashes > 1 means frames actually change over time (allIdentical: true on a multi-time capture usually means nothing is animating).
+
+Set includeDataUrls: true to also get each frame as a PNG data URL (large — only for a few frames).
+
+USE WHEN:
+- Verifying an animation is deterministic / reproducible
+- Checking whether a scene actually animates across a time range
+- Grabbing reproducible frames for a regression baseline
+
+EXAMPLE: { times: [0, 0.5, 1, 1.5, 2], seed: 42 }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                times: {
+                    type: 'array',
+                    items: { type: 'number' },
+                    description: 'Capture times in seconds, rendered in order.',
+                },
+                seed: {
+                    type: 'number',
+                    description: 'Seed for reproducible random generators/particles (default 0).',
+                },
+                includeDataUrls: {
+                    type: 'boolean',
+                    description: 'Include each frame as a PNG data URL (large). Default false → hashes only.',
+                },
+            },
+            required: ['times'],
+        },
+    },
+    {
+        name: 'pinepaper_media',
+        annotations: {
+            title: 'Media (Video / Audio)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        description: `Bring VIDEO and AUDIO onto the canvas from a URL, and control playback. Uploaded video is a first-class canvas item (drag, scale, animate, export like any shape); audio rides the timeline.
+
+ACTIONS:
+- upload_video: { url (required), position?, scale?, timeOffset? (timeline start, s), clipInPoint?, clipOutPoint? (trim, s) } → { id, duration, width, height, name }
+- upload_audio: { url (required), volume? (0–1, default 1), loop? (default true), muted?, timeOffset? } → { id, duration, name }
+- list: → all media [{ id, kind, duration, … }]
+- remove: { id } → removed boolean
+- set_playback_rate: { id, rate (0.25–4) } → applies to video or audio
+- set_clip: { id, inPoint, outPoint (media-time s, outPoint > inPoint) } → re-trim an ALREADY-uploaded clip (video or audio)
+
+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.
+
+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" },
+                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.' },
+                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.' },
+                position: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, description: 'Canvas position — upload_video.' },
+                scale: { type: 'number', description: 'Scale factor — upload_video.' },
+                timeOffset: { type: 'number', description: 'Timeline start offset (s) — upload_video / upload_audio.' },
+                clipInPoint: { type: 'number', description: 'Trim in-point (s) — upload_video.' },
+                clipOutPoint: { type: 'number', description: 'Trim out-point (s) — upload_video.' },
+                volume: { type: 'number', description: 'Volume 0–1 (default 1) — upload_audio.' },
+                loop: { type: 'boolean', description: 'Loop (default true) — upload_audio.' },
+                muted: { type: 'boolean', description: 'Start muted — upload_audio.' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_crop_image',
+        annotations: {
+            title: 'Crop Image',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Crop an imported image to a rectangle — one shot, no interactive session. The replacement raster KEEPS the item's registry id (relations, animations, and connectors stay attached).
+
+USE WHEN:
+- Trimming an imported photo/screenshot to the region that matters
+- Preparing an image before filters, detection, or chroma key (operations compose in any order)
+
+NOTES:
+- rect is in canvas coordinates (same space as item positions) and is clamped into the image bounds.
+- For non-rectangular crops use pinepaper_apply_custom_mask (shape masks) or pinepaper_lasso (freehand).
+
+EXAMPLE: { itemId: 'item_12', rect: { x: 340, y: 220, width: 320, height: 180 }, aspectRatio: '16:9' }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                itemId: { type: 'string', description: 'Registry id of the raster item (or a group containing one)' },
+                rect: {
+                    type: 'object',
+                    properties: {
+                        x: { type: 'number', description: 'Left edge (canvas coords)' },
+                        y: { type: 'number', description: 'Top edge (canvas coords)' },
+                        width: { type: 'number', description: 'Crop width' },
+                        height: { type: 'number', description: 'Crop height' },
+                    },
+                    required: ['x', 'y', 'width', 'height'],
+                    description: 'Crop rectangle in canvas coordinates',
+                },
+                aspectRatio: {
+                    type: 'string',
+                    enum: ['free', '1:1', '16:9', '9:16', '4:3', '3:4', '3:2', '2:3'],
+                    description: 'Optional aspect-ratio constraint',
+                },
+            },
+            required: ['itemId', 'rect'],
+        },
+    },
+    {
+        name: 'pinepaper_chroma_key',
+        annotations: {
+            title: 'Chroma Key (Remove Background Color)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Remove a background color from an imported image (green-screen style) — one shot, no interactive session. Pixels near the key color become transparent, with smoothed edges. The replacement raster KEEPS the item's registry id.
+
+USE WHEN:
+- Removing a green/blue screen from a photo
+- Knocking out a flat background color before compositing
+
+NOTES:
+- Omit threshold/smoothing to auto-estimate from the image's color histogram.
+- color accepts '#rrggbb' or a preset: green, chromaGreen, blue, chromaBlue, magenta (default: green).
+- For irregular subjects on busy backgrounds use pinepaper_lasso or pinepaper_extract_object instead.
+
+EXAMPLE: { itemId: 'item_7', color: 'green' }
+EXAMPLE: { itemId: 'item_7', color: '#00b140', threshold: 60, smoothing: 12 }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                itemId: { type: 'string', description: 'Registry id of the raster item (or a group containing one)' },
+                color: { type: 'string', description: "Key color: '#rrggbb' or preset (green, chromaGreen, blue, chromaBlue, magenta). Default green." },
+                threshold: { type: 'number', description: 'Color-distance threshold 0–255 for full transparency. Omit to auto-estimate.' },
+                smoothing: { type: 'number', description: 'Edge-smoothing range past the threshold. Omit to auto-estimate.' },
+            },
+            required: ['itemId'],
+        },
+    },
+    {
+        name: 'pinepaper_rigging',
+        annotations: {
+            title: 'Rigging (Skeleton / Bones / IK / Poses)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Rig and animate with SKELETONS — bones, IK chains, and pose keyframes (FxTool RiggingSystem). Build a skeleton, attach canvas items to bones, then drive it with poses. Includes the S12 "breakdown-pose" controls that turn robotic pose-to-pose into believable motion.
+
+WORKFLOW: create_skeleton → add_bone (×N, parent them into a hierarchy) → attach_item (bind shapes to bones) → optionally create_ik_chain → animate with add_pose_keyframe (or save_pose then reference it).
+
+ACTIONS:
+- create_skeleton: { name?, rootPosition? } → { skeletonId }
+- add_bone: { skeletonId, name?, parentBoneId? (omit for root), length? (80), angle? (deg), flexibility? (0 rigid…1), segments? } → { boneId }
+- attach_item: { skeletonId, boneId, itemId, attachPoint? (0 joint…1 tip, 0.5) }
+- create_ik_chain: { skeletonId, boneIds[] (≥2, ordered), solverType? (fabrik|two_bone|ccd), iterations?, tolerance?, strength?, poleVector? } → { chainId }
+- add_pose_keyframe: { skeletonId, time (s), pose (a saved pose id OR a { boneId: angleDeg } map), easing?, and BREAKDOWN controls: favor? (−1..1 spacing bias), breakdown? (flag), curve? ([x1,y1,x2,y2] cubic-bezier ease, overrides easing), boneOffsets? ({ boneId: 0..0.95 lag } for overlap/follow-through), movingHold? (drift a held pose toward the next key), holdDrift? }
+- 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)
+
+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' },
+                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.' },
+                chainId: { type: 'string', description: 'IK chain id — set_target_path.' },
+                name: { type: 'string', description: 'Name — create_skeleton / add_bone / create_ik_chain / save_pose / save_shape_key.' },
+                rootPosition: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, description: 'Skeleton root position — create_skeleton.' },
+                parentBoneId: { type: 'string', description: 'Parent bone id (omit for root) — add_bone.' },
+                length: { type: 'number', description: 'Bone length px (default 80) — add_bone.' },
+                angle: { type: 'number', description: 'Bone rest angle deg — add_bone.' },
+                flexibility: { type: 'number', description: '0 rigid…1 flexible — add_bone.' },
+                segments: { type: 'number', description: 'Curve segments (0 auto) — add_bone.' },
+                attachPoint: { type: 'number', description: 'Along-bone 0 joint…1 tip (0.5) — attach_item.' },
+                boneIds: { type: 'array', items: { type: 'string' }, description: 'Ordered bone ids (≥2) — create_ik_chain.' },
+                solverType: { type: 'string', enum: ['fabrik', 'two_bone', 'ccd'], description: 'IK solver (fabrik) — create_ik_chain.' },
+                iterations: { type: 'number', description: 'Solver iterations (10) — create_ik_chain.' },
+                tolerance: { type: 'number', description: 'Solver tolerance px (0.5) — create_ik_chain.' },
+                strength: { type: 'number', description: 'Chain strength 0..1 (1) — create_ik_chain.' },
+                poleVector: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, description: 'Pole vector hint — create_ik_chain.' },
+                time: { type: 'number', description: 'Keyframe time s — add_pose_keyframe.' },
+                pose: { description: 'Saved pose id (string) OR { boneId: angleDeg } map — add_pose_keyframe.' },
+                easing: { type: 'string', description: 'Named easing (linear) — add_pose_keyframe.' },
+                favor: { type: 'number', description: 'Breakdown spacing bias −1..1 — add_pose_keyframe.' },
+                breakdown: { type: 'boolean', description: 'Mark as breakdown pose — add_pose_keyframe.' },
+                curve: { type: 'array', items: { type: 'number' }, description: 'Cubic-bezier ease [x1,y1,x2,y2] — add_pose_keyframe.' },
+                boneOffsets: { type: 'object', description: 'Per-bone lag { boneId: 0..0.95 } — add_pose_keyframe.' },
+                movingHold: { type: 'boolean', description: 'Drift a held pose toward the next key — add_pose_keyframe.' },
+                holdDrift: { type: 'number', description: 'Moving-hold drift fraction (0.06) — add_pose_keyframe.' },
+                waypoints: { type: 'array', items: { type: 'object' }, description: 'IK path [{x,y,out?,in?}] — set_target_path.' },
+                duration: { type: 'number', description: 'Path duration s (1) — set_target_path.' },
+                loop: { type: 'boolean', description: 'Cycle the path — set_target_path.' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_instantiate_ontology',
+        annotations: {
+            title: 'Instantiate Ontology → Scene',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Compile a design ONTOLOGY (a pp:-namespaced JSON-LD graph of typed nodes + structural edges) into a real scene — the reverse of scene→graph extraction (FxTool S12-E3). "Author the graph, get the design."
+
+Give it typed nodes (pp:Circle, pp:Text, …) and STRUCTURAL edges (pp:onTopOf, pp:below, pp:beside, pp:inside, pp:centeredOn, pp:alignedWith, or their runtime names on_top_of/…). The compiler:
+- Places only ROOT nodes (never the source of a structural relation) at absolute coordinates, tiling connected components across the canvas. Every other node is positioned AT RUNTIME by its relations — move a root and its dependents follow.
+- Emits app.create + app.addRelation for the whole graph in one call, returns { itemIds, diagnostics, errors }.
+
+Accepts the DesignGraph.toJsonLd shape (pp:nodes / pp:edges), a plain { nodes, edges }, or nodes carrying inline pp: relation properties. Unknown @types fall back to a rectangle with a diagnostic (compilation never hard-fails).
+
+USE WHEN: you have a structured description of a composition (a graph) and want it built as a live, relation-driven scene rather than placing each item by hand.
+
+EXAMPLE doc: { "nodes": [ {"id":"bar","type":"pp:Rectangle","width":300,"height":40}, {"id":"glass","type":"pp:Circle","width":60,"height":60} ], "edges": [ {"type":"on_top_of","source":"glass","target":"bar","params":{"gap":2}} ] } → bar is placed; glass rides on top of it.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                doc: {
+                    type: 'object',
+                    description: 'The design graph: pp:nodes / pp:edges, or { nodes, edges }, or nodes with inline pp: relation properties.',
+                },
+                canvas: {
+                    type: 'object',
+                    properties: {
+                        width: { type: 'number' },
+                        height: { type: 'number' },
+                    },
+                    description: 'Canvas size used to tile component roots (default 1080×1080).',
+                },
+                defaultGeometry: {
+                    type: 'object',
+                    description: 'Per-type default { width, height } overrides, e.g. { "text": { "width": 300, "height": 60 } }.',
+                },
+            },
+            required: ['doc'],
+        },
+    },
+    {
+        name: 'pinepaper_lint_scene',
+        annotations: {
+            title: 'Lint Scene (Relational Density)',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Audit the LIVE scene's relational structure (FxTool S12-E2) — read-only, nothing is changed. Answers "is this scene composed with relations, or just a pile of absolutely-positioned items?" and proposes fixes.
+
+RETURNS:
+- density: { itemCount, relationalItemCount, relationalDensity (0..1 — fraction of items touching the relation graph), edgeCount, componentCount }. A low relationalDensity means items are placed by hardcoded coordinates and won't hold together if something moves.
+- suggestions: structural relations for unrelated item pairs that ALREADY sit in a structural configuration — [{ from, to, type (on_top_of/below/beside/inside/centered_on/aligned_with), params, confidence }], ranked by confidence. Apply the good ones with pinepaper_add_relation to make the layout robust.
+
+USE WHEN:
+- After building a scene, to check it's relation-driven rather than coordinate-driven
+- To discover which items SHOULD be related (labels on shapes, a badge on a card, stacked elements) but aren't
+- Before export, as a composition-quality gate
+
+PARAMS: { eps? (bounds-match tolerance px, default 4), cap? (max suggestions, default 20) }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                eps: { type: 'number', description: 'Bounds-match tolerance in px for structural-configuration detection (default 4).' },
+                cap: { type: 'number', description: 'Max suggestions to return, ranked by confidence (default 20).' },
+            },
+        },
+    },
     // ---------------------------------------------------------------------------
     // LAYER 2 — RULES: RELATION TOOLS (KEY FOR ANIMATION)
     // ---------------------------------------------------------------------------
@@ -1245,7 +1986,13 @@ USE WHEN:
 - "reflection mirrors original" → relationType: mirrors
 - "background moves with parallax" → relationType: parallax
 - "player stays in arena" → relationType: bounds_to
+- "M is the midpoint of A and B" → relationType: is_midpoint_of (params.other: B)
+- "O is the circumcenter of the triangle" → relationType: is_circumcenter_of
+- "reveal each step in turn" → relationType: construction_reveal (params.revealAt, fadeIn)
+- "bar height driven by the slider's x" / "tint the dot by the planet's position" → relationType: driven_by
+- "make it bob with sin(t)" / "property follows a math expression of time" → relationType: time_expression
 - Creating physics-based or behavioral animations
+- Building live geometric constructions (GeoGebra-style — dragging an anchor updates the dependent)
 
 RELATION TYPES:
 - orbits: Circular motion around target (params: radius, speed, direction, phase)
@@ -1266,7 +2013,39 @@ RELATION COMPATIBILITY:
   Text→Text: font blend
   Cross-type: particle denoising transition
 - group_morphs_to: pair-by-index morph between two paper.Groups (any two — graph vertices+edges, letter collages, dashboard clusters). Path.Line children deform via endpoints; other children translate; excess children fade. Params: duration, hold, loop, easing (linear|easeIn|easeOut|easeInOut), deformLines.
-- moves_along_path: self-relation (targetId=null); item is driven along a custom-drawn path stored in params.path (array of {x,y} or [x,y]). Params: path, speed, closed, phase, easing (linear|easeIn|easeOut|easeInOut|sine|bounce|pingpong).
+- moves_along_path: self-relation (targetId=null); item is driven along a path. Source the path EITHER from params.path (array of {x,y} or [x,y]) OR from params.equation (S10 B5) — a math curve the item TRAVERSES, sampled deterministically on the Expression IR: params.equation = { kind: function|parametric|fourier|preset, expr | xExpr/yExpr | harmonics | preset, min, max, samples, scale, cx, cy, flipY, warp } (same equation contract as pinepaper_equation_path, but origin is cx/cy, default 0). Params: path OR equation, speed, closed, phase, easing (linear|easeIn|easeOut|easeInOut|sine|bounce|pingpong).
+
+GEOMETRIC CONSTRUCTION CONSTRAINTS (Layer 2) — the source item is RE-DERIVED every frame from its anchor item(s), so dragging an anchor updates the dependent live (GeoGebra-style), and the construction persists as relation graph data (edit it by editing relations, not by re-running code). Anchor A is the relation target; extra anchors ride in params:
+- is_midpoint_of: source = midpoint(target, params.other). params.other = id of the second endpoint (B).
+- lies_on_line: source held on the line target→params.other at fraction params.t (0=A, 1=B; default 0.5). params.other (B), params.t.
+- is_centroid_of: source = centroid(target, ...params.others). params.others = array of the remaining point ids.
+- is_circumcenter_of: source = circumcenter(target, params.other1, params.other2); holds position when the three anchors are collinear. params.other1 (B), params.other2 (C).
+- concentric_with: source stays centered on the target (shared center).
+- construction_reveal: self-relation (targetId=null); opacity 0→1 starting at params.revealAt (timeline seconds) over params.fadeIn seconds — loop- and scrub-correct. Pair with pinepaper_construction_sequence to reveal a figure one step at a time.
+
+PROCEDURAL / DETERMINISTIC BINDING (Expression IR — S10 G1) — bind a property to another property or to a math function of time. Pass params.signal:true to route through the pure, seed/frame-deterministic signal interpreter (replay-stable — same time → identical output); omit it for the per-frame compute fallback.
+- driven_by: source's sourceProperty = target's targetProperty * multiplier + offset (optionally clamped). sourceProperty ∈ x|y|rotation|opacity|scale|strokeWidth|fillColor|strokeColor; targetProperty ∈ x|y|rotation|opacity|scale. For fillColor/strokeColor the (clamped 0..1) driven value interpolates colorFrom→colorTo — so a relation drives COLOR. NEEDS a target (the property source). params: sourceProperty, targetProperty, multiplier, offset, clamp {min,max}, colorFrom, colorTo, signal. e.g. tint a dot by a planet's x: sourceProperty 'fillColor', targetProperty 'x', colorFrom '#0055ff', colorTo '#ff3300', signal true.
+- time_expression: self-relation (targetId=null); the source's params.property is driven by a math expression of t (scene time) and v (params.baseValue). params: property (default 'y'), expression (e.g. 'sin(t*2)*50 + v'), baseValue, signal. With signal:true the expression is parsed into the Expression IR and evaluated as a pure f(t); it falls back to per-frame if it uses random() or an unknown symbol (non-deterministic).
+
+EVENT-DRIVEN SCENE CHAINS (S11) — build a LONG scene as a graph of timed events, not a keyframe track. First make events with pinepaper_event (action:'create' → eventId). The relations below have an EVENT as their sourceId; firing the event runs the reaction. Chain beats over animation time with on_event_fire_after (timeline:'canvas'), have beats mutate the scene with on_event_add_relation, then kick it off with pinepaper_event action:'pulse'. Because canvas-timed fires are on the animation clock, the whole chain is scrub-, loop-, and replay-stable.
+- on_event_fire_after: sourceId=event, targetId=the NEXT event. When source fires, pulse target after params.delay ms. params.timeline: 'canvas' (animation clock — use for scene chains) | 'wall' (real setTimeout). This is the chaining primitive.
+- on_event_add_relation: sourceId=event, targetId=the item to affect. When the event fires, ADD a relation FROM that item: params { type (relation type, e.g. orbits/moves_along_path/driven_by), target (id or null for self), params (that relation's params) }. The scene evolves itself — new orbits/paths appear on a beat.
+- on_event_remove_relation: sourceId=event, targetId=item. Tears down a previously-added relation: params { type, target }.
+- on_event_set_color: sourceId=event, targetId=item. params { color, which: 'fill'|'stroke' }.
+- on_event_set_property: sourceId=event, targetId=item. params { property, value } — set any item property (opacity, rotation, strokeWidth, …).
+- on_event_set_visibility: sourceId=event, targetId=item. params { visible } (default true).
+
+STRUCTURAL LAYOUT (S12) — express STATIC COMPOSITION as relations instead of hardcoded x/y. Placement is computed from the TARGET'S BOUNDS and re-derived every frame, so moving or resizing the target moves the dependent with it, and the layout survives as editable graph data. Reach for these whenever the intent is "on", "under", "next to", "inside", or "lined up with" — a create_item with literal coordinates cannot express that intent and silently breaks when the target moves. All six need a target; all accept params.signal (deterministic IR port) and params.window.
+- on_top_of: source's BOTTOM edge rests on the target's TOP edge — stacking (a cocktail on a bar). params { gap (px between edges, default 0), align: 'left'|'center'(default)|'right', overhang (extra signed x-offset) }.
+- below: mirror of on_top_of — source's TOP edge rests on the target's BOTTOM edge. params { gap, align, overhang }.
+- beside: source flanks the target horizontally. params { side: 'left'|'right' (default 'right'), gap, align: 'top'|'center'(default)|'bottom' }.
+- inside: source is placed within the target's bounds at a 9-way anchor. params { anchor: 'center'(default)|'top-left'|'top'|'top-right'|'left'|'right'|'bottom-left'|'bottom'|'bottom-right', padding (inset from the target edge) }. Contrast bounds_to, which CLAMPS a moving item; inside PLACES it.
+- centered_on: source center = target center + offset. params { offsetX, offsetY } — concentric rings at zero offset.
+- aligned_with: matches the target's center on ONE axis, leaving the other free (a partial write — use it to column-align a label while it still moves vertically). params { axis: 'x'|'y' — REQUIRED, the relation is inert without it, offset }.
+
+CURSOR / MOUSE AS TARGET — a relation can target the live pointer instead of an item by passing the reserved targetId 'cursor' (aliases 'mouse' / 'pointer'); collaborator cursors are 'cursor:<peerId>'. e.g. make an item flee the mouse: relationType 'repels', targetId 'cursor', params { returnSpeed: 0.08 }. The cursor is a virtual target (no canvas item) and its interactions are inspectable in FxTool's "Mouse / Cursor" registry section.
+
+TEMPORAL VALIDITY WINDOWS (temporal-model v1) — ANY relation may carry params.window = { start, end?, repeat? } (scene seconds) to gate WHEN it is active. The engine only applies the relation within [start, end) and feeds it window-relative local time (so an orbit/wave starts its phase at the window open, not at scene 0). repeat ∈ once (default) | loop | pingpong. Omit end for open-ended. Windowless relations are always active. e.g. params: { ...relationParams, window: { start: 2, end: 5 } } makes the relation live only from 2s to 5s.
 
 VERIFYING ANIMATION WORKS:
 After adding a relation, verify the animation is running:
@@ -1288,7 +2067,7 @@ Relations are COMPOSITIONAL - an item can have multiple relations that work toge
                 },
                 relationType: {
                     type: 'string',
-                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to', 'group_morphs_to', 'moves_along_path'],
+                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'construction_reveal', 'driven_by', 'time_expression', 'on_event_fire_after', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_visibility', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with'],
                     description: 'Type of relationship',
                 },
                 params: {
@@ -1322,7 +2101,7 @@ USE WHEN:
                 targetId: { type: 'string', description: 'Target item ID' },
                 relationType: {
                     type: 'string',
-                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to', 'group_morphs_to', 'moves_along_path'],
+                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'construction_reveal', 'driven_by', 'time_expression', 'on_event_fire_after', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_visibility', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with'],
                     description: 'Specific relation type to remove (optional - removes all if not specified)',
                 },
             },
@@ -1350,7 +2129,7 @@ USE WHEN:
                 itemId: { type: 'string', description: 'Item to query relations for' },
                 relationType: {
                     type: 'string',
-                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to', 'group_morphs_to', 'moves_along_path'],
+                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'construction_reveal', 'driven_by', 'time_expression', 'on_event_fire_after', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_visibility', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with'],
                     description: 'Filter by relation type (optional)',
                 },
                 direction: {
@@ -1530,6 +2309,14 @@ ANIMATION TYPES:
                     type: 'number',
                     description: 'Animation speed multiplier (default: 1.0)',
                 },
+                intensity: {
+                    type: 'number',
+                    description: 'Animation amplitude (0.1 = ±10%, default 0.15): drives pulse/wobble/bounce/breathe amplitude and is honored by SVG/SMIL/widget export.',
+                },
+                delay: {
+                    type: 'number',
+                    description: 'Animation start delay in seconds.',
+                },
             },
             required: ['itemId', 'animationType'],
         },
@@ -1584,6 +2371,7 @@ EXAMPLE — Reveal at 2s, skip first second of keyframe data, end at 4s of keyfr
             type: 'object',
             properties: {
                 itemId: { type: 'string', description: 'Registry ID of the item' },
+                timeUnits: { type: 'string', enum: ['seconds', 'ms'], description: "Explicit units for keyframe times/duration. Pass 'seconds' for long-form timelines — values over 100 are otherwise auto-read as milliseconds." },
                 keyframes: {
                     type: 'array',
                     items: {
@@ -1642,7 +2430,9 @@ EXAMPLE — Reveal at 2s, skip first second of keyframe data, end at 4s of keyfr
 USE WHEN:
 - Starting/stopping/pausing timeline playback
 - Seeking to specific time
-- Controlling animation state`,
+- Controlling animation state
+
+DETERMINISTIC SEEK: pass deterministic: true with action 'seek' to evaluate the WHOLE scene at the exact time via app.sceneAt(t) — keyframes + relations + generators all tick to t, so the same time always yields the same frame (paired with a seed in pinepaper_capture_frames for reproducible output). Plain seek only sets the keyframe playback state. Use deterministic seek before pinepaper_browser_screenshot to capture a reproducible frame.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -1663,6 +2453,10 @@ USE WHEN:
                     type: 'number',
                     description: 'Time to seek to (for seek action)',
                 },
+                deterministic: {
+                    type: 'boolean',
+                    description: 'For seek: evaluate the full scene at the exact time via app.sceneAt(t) — deterministic (same t → same frame). Default false.',
+                },
             },
             required: ['action'],
         },
@@ -2133,7 +2927,7 @@ EXAMPLE - Bouncing Balls:
 }
 
 SUPPORTED ITEM TYPES: text, circle, star, rectangle, triangle, polygon, ellipse, path, line, arc
-SUPPORTED RELATIONS: orbits, follows, attached_to, maintains_distance, points_at, mirrors, parallax, bounds_to, animates, grows_from, staggered_with, indicates, circumscribes, wave_through, camera_follows, camera_animates, morphs_to, group_morphs_to, moves_along_path
+SUPPORTED RELATIONS: orbits, follows, attached_to, maintains_distance, points_at, mirrors, parallax, bounds_to, animates, grows_from, staggered_with, indicates, circumscribes, wave_through, camera_follows, camera_animates, morphs_to, group_morphs_to, moves_along_path, is_midpoint_of, lies_on_line, is_centroid_of, is_circumcenter_of, concentric_with, construction_reveal
 SUPPORTED ANIMATIONS: pulse, rotate, bounce, fade, wobble, slide, typewriter`,
         inputSchema: {
             type: 'object',
@@ -2179,7 +2973,7 @@ SUPPORTED ANIMATIONS: pulse, rotate, bounce, fade, wobble, slide, typewriter`,
                             target: { type: 'string', description: 'Name of target item' },
                             type: {
                                 type: 'string',
-                                enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to', 'group_morphs_to', 'moves_along_path'],
+                                enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'construction_reveal', 'driven_by', 'time_expression', 'on_event_fire_after', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_visibility', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with'],
                             },
                             params: {
                                 type: 'object',
@@ -2464,7 +3258,8 @@ ACTIONS:
 - apply: Apply a single filter. Params: itemId, filterName, params
 - chain: Apply multiple filters in sequence. Params: itemId, filters (array of {name, params})
 
-Available filters: blur, brightness, contrast, saturate, grayscale, sepia, invert, hue-rotate, sharpen, emboss, edge-detect.`,
+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).
+(Scene-wide filters — sharpen/emboss/noise/vintage etc. — are a different surface: use pinepaper_add_filter.)`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -2791,6 +3586,7 @@ ACTIONS:
 - get_state: Get interaction state (score, progress, step)
 
 BEHAVIOR TYPES: repel, attract, follow, orbit, slingshot, physics_body, draggable_constrained
+- repel params: strength, maxDistance, minDistance, returnSpeed (0–1, default 0.08 — how fast the item eases back to its home position once the target/cursor leaves; returnSpeed: 0 freezes it scattered instead of reforming).
 
 ACTION TYPES: navigate, show, hide, animate, stopAnimation, setState, incrementScore, playTimeline, pauseTimeline, seekTimeline, showFeedback, complete`,
         inputSchema: {
@@ -3750,6 +4546,55 @@ ACTIONS:
             required: ['action'],
         },
     },
+    {
+        name: 'pinepaper_globe',
+        annotations: {
+            title: 'Map: Globe + World Tour',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Turn a loaded map into a spinning 3D globe and swing it on a cinematic world tour. Requires a map loaded via pinepaper_map { action: "load" } first; call action: "enable" to switch to globe (orthographic) mode.
+
+ACTIONS:
+- enable      — { rotation?: [lambda,phi,gamma], momentum?, showOcean? }     switch to globe mode
+- rotate_to   — { lon, lat, duration? }                                       versor-slerp the globe to face a coordinate
+- spin        — { speed?, axis?: "longitude"|"latitude", duration? }          continuous auto-rotation
+- world_tour  — { regions?: string[] | coords?: [lon,lat][], dwell?, travel?, tilt?, loop?, easing?, highlightColors?: string[], showLabels?, labelColor? }   the headline: the globe swings to each stop, highlighting it (requires regions OR coords)
+- stop_tour   — { id? }                                                       omit id to stop all tours
+- pin_item    — { itemId, lon, lat, hideOnFarSide? }                          pin a canvas item to the globe surface
+- tour_item   — { itemId, regions?: string[] | coords?: [lon,lat][], dwell?, travel?, loop?, orient? }   move a canvas item along the globe (requires regions OR coords)`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['enable', 'rotate_to', 'spin', 'world_tour', 'stop_tour', 'pin_item', 'tour_item'], description: 'Globe action' },
+                rotation: { type: 'array', items: { type: 'number' }, description: 'Initial rotation [lambda, phi, gamma] (enable)' },
+                momentum: { type: 'boolean', description: 'Drag-spin inertia (enable)' },
+                showOcean: { type: 'boolean', description: 'Render ocean sphere (enable)' },
+                lon: { type: 'number', description: 'Longitude (rotate_to, pin_item)' },
+                lat: { type: 'number', description: 'Latitude (rotate_to, pin_item)' },
+                duration: { type: 'number', description: 'Animation duration in seconds (rotate_to, spin)' },
+                speed: { type: 'number', description: 'Spin speed deg/sec (spin)' },
+                axis: { type: 'string', enum: ['longitude', 'latitude'], description: 'Spin axis (spin)' },
+                regions: { type: 'array', items: { type: 'string' }, description: 'Region IDs to visit (world_tour, tour_item)' },
+                coords: { type: 'array', items: { type: 'array', items: { type: 'number' } }, description: 'Coordinate stops [lon,lat][] (world_tour, tour_item)' },
+                dwell: { type: 'number', description: 'Seconds dwelling at each stop' },
+                travel: { type: 'number', description: 'Seconds travelling between stops' },
+                tilt: { type: 'number', description: 'Camera tilt per stop (world_tour)' },
+                loop: { type: 'boolean', description: 'Loop the tour' },
+                easing: { type: 'string', description: 'Swing easing curve (world_tour)' },
+                highlightColors: { type: 'array', items: { type: 'string' }, description: 'Highlight colors cycled per stop (world_tour)' },
+                showLabels: { type: 'boolean', description: 'Label each stop (world_tour)' },
+                labelColor: { type: 'string', description: 'Label text color (world_tour)' },
+                id: { type: 'string', description: 'Tour id to stop (stop_tour)' },
+                itemId: { type: 'string', description: 'Canvas item id (pin_item, tour_item)' },
+                hideOnFarSide: { type: 'boolean', description: 'Hide item on far side of globe (pin_item)' },
+                orient: { type: 'boolean', description: 'Orient item along travel direction (tour_item)' },
+            },
+            required: ['action'],
+        },
+    },
     // ---------------------------------------------------------------------------
     // DOMAIN: FONT TOOLS — single action-dispatched tool replaces 16 wrappers
     // ---------------------------------------------------------------------------
@@ -3848,6 +4693,7 @@ STYLE TYPES:
 - fold: Origami-style folded letters
 - gradient: Each letter with gradient fill (use with gradient palettes)
 - image: Letters filled with image
+- particle: Each glyph sampled into a cloud of colored dots (re-typable "particle font"); reuses tile palettes. Optional particleSpacing / particleDotSize tune density.
 
 TILE PALETTES:
 - Game: wordle, scrabble
@@ -3876,7 +4722,7 @@ EXAMPLES:
                 },
                 style: {
                     type: 'string',
-                    enum: ['tile', 'magazine', 'paperCut', 'fold', 'gradient', 'image'],
+                    enum: ['tile', 'magazine', 'paperCut', 'fold', 'gradient', 'image', 'particle'],
                     description: 'Style type (default: tile)',
                 },
                 palette: {
@@ -3931,6 +4777,14 @@ EXAMPLES:
                     type: 'boolean',
                     description: 'Enable drop shadows (default: true)',
                 },
+                particleSpacing: {
+                    type: 'number',
+                    description: 'Dot spacing for style="particle" (smaller = denser cloud; default ~fontSize*0.11)',
+                },
+                particleDotSize: {
+                    type: 'number',
+                    description: 'Base dot radius for style="particle" (default ~particleSpacing*0.44)',
+                },
             },
             required: ['text'],
         },
@@ -4048,6 +4902,25 @@ PineMath — Math/Science:
 - drawSpectrumAnalyzer: FFT signal visualization (waveform: sine|square|sawtooth|triangle|noise|composite, frequency, amplitude, sampleRate, window: none|hann|hamming|blackman, waveColor, spectrumColor)
 - draw3DSurface: 3D surfaces from equations (preset: torus|sphere|wave|klein|mobius|custom, xExpr, yExpr, zExpr, uSteps, vSteps, scale, rotateSpeed)
 
+S6 Procedural (seeded, OKLCH palettes, curated presets, optional Motion). All take: palette (ocean|neon|ember|slate|dusk|pastel|mint|lagoon…), colorMode (gradient|random|mono), bgColor, seed (same seed → identical output), animation (none|driftX|driftY|rotate|pulse), animationSpeed:
+- drawTruchet: Truchet tiles — interlocking arcs/diagonals (tileSize, lineWidth, variant: arcs|diagonals, lineColor). Presets: Ocean Maze, Neon Circuit, Ember Weave, Slate Diagonals.
+- drawHalftone: halftone dot field (toneMode: radial|noise|linear, dotSpacing, maxDotRadius, contrast, dotColor, opacity). Presets: Sunburst Dots, Noise Field, Pop Ramp, Soft Mono.
+- drawRibbons: flowing Bézier ribbons (ribbonCount, ribbonWidth, amplitude, waviness, opacity). Presets: Deep Current, Aurora, Silk, Mint Flow.
+
+GPU / GLSL math-art (transpiled to a fragment shader, 60fps; all take renderScale 0.25–1, transparentBg, speed):
+- drawFormulaArt: type a math expression in x,y,t → scalar mapped through a 3-stop palette (formula, domain, color1/color2/color3). Try sin(x*5+t)*cos(y*3).
+- drawParametricCollection: N circles or line segments indexed by k, expressions in k,N,t — Yeganeh-style (mode: circles|lines, count, xExpression/yExpression/radiusExpression or x1..y2Expression, scale, palette, bgColor).
+- drawShaderArt: paste your own GLSL fragment shader (fragmentSource; uniforms u_time, u_resolution, u_color1/2/3) or pick a preset.
+- drawYeganehMountains: GLSL port of Hamid Naderi Yeganeh's "Mountains" (mountainCount, timeOffset, skyTop, skyBottom, ridgeColor, valleyColor).
+
+OKLCH seeded backgrounds (palette + seed → reproducible):
+- drawBlobs: soft organic blobs (smoothed jittered circles). Dreamy/soft backgrounds.
+- drawLowPoly: triangulated low-poly facets (gradient-filled). Modern/geometric.
+- drawPeaks: stacked zig-zag mountain ridgeline bands.
+- drawStackedWaves: layered cubic-bézier wave bands — hero/section-divider background.
+- drawScatter: scattered field of small shapes (circles/triangles/squares), palette-colored.
+- draw3DParametricCurve: plot a 3D curve (x(t),y(t),z(t)) projected to canvas. Try Helix: sin(t),cos(t),t/4.
+
 COMMON PARAMS (all generators):
 - bgColor: Background color ("none"/"transparent" for no background)
 - interactive: Make generated items selectable/draggable (default false)
@@ -4065,6 +4938,9 @@ COMMON PARAMS (all generators):
                         'drawGlobeWireframe',
                         'drawFunctionPlot', 'drawParametricCurve', 'drawSimulation',
                         'drawSpectrumAnalyzer', 'draw3DSurface',
+                        'drawTruchet', 'drawHalftone', 'drawRibbons',
+                        'drawFormulaArt', 'drawParametricCollection', 'drawShaderArt', 'drawYeganehMountains',
+                        'drawBlobs', 'drawLowPoly', 'drawPeaks', 'drawScatter', 'drawStackedWaves', 'draw3DParametricCurve',
                     ],
                     description: 'Generator name',
                 },
@@ -4073,6 +4949,17 @@ COMMON PARAMS (all generators):
                     description: 'Generator-specific parameters',
                     additionalProperties: true,
                 },
+                region: {
+                    type: 'object',
+                    description: 'Optional sub-region {x, y, width, height} (canvas coords) — generator draws into a clipped, translated sub-group instead of full-canvas. Region runs imply preserve (won\'t wipe the canvas) and re-running the same generator replaces its prior region; different generators\' regions coexist. Invalid/zero-size regions fall back to full-canvas.',
+                    properties: {
+                        x: { type: 'number', description: 'Region top-left X in canvas coords' },
+                        y: { type: 'number', description: 'Region top-left Y in canvas coords' },
+                        width: { type: 'number', minimum: 1, description: 'Region width in pixels' },
+                        height: { type: 'number', minimum: 1, description: 'Region height in pixels' },
+                    },
+                    required: ['x', 'y', 'width', 'height'],
+                },
             },
             required: ['generatorName'],
         },
@@ -4118,7 +5005,7 @@ USE WHEN:
 - Celebration effects (confetti)
 - Enhancing visual impact (ripple, glow, electric)
 
-EFFECTS (15 total):
+EFFECTS (15 particle + 3 shader auras):
 - sparkle: Glitter/sparkle particles (color, speed, size)
 - blast: Explosion burst effect (color, radius, count)
 - smoke: Rising smoke plumes (color, speed, size, drift, height, growthRate)
@@ -4135,15 +5022,23 @@ EFFECTS (15 total):
 - shockwave: Expanding concentric rings — burst type (speed, maxRadius, count, thickness)
 - trail: Fading afterimages following movement (speed, count, size, fadeRate)
 
+SHADER AURAS (WebGL2, silhouette-clipped — same tool, routed to the aura system):
+- heatmap: Thermal shimmer aura (palette 0=Hot 1=Cool 2=Violet)
+- liquid_metal: Flowing metallic sheen (palette 0=Chrome 1=Gold 2=Copper)
+- gem_smoke: Crystalline smoke wisps
+Aura params: { intensity, radius, palette, mode ('inside'|'outside'|'overlay'), tint, tintStrength, offsetX, offsetY, channels: { a: {speed, curve}, b: {speed, curve} } } — curves: linear, sawtooth, sine, triangle, pulse, ease, bounce, noise.
+
 EXAMPLE — bubbles with magenta interior over a blue rim:
-{ effectType: "bubbles", params: { color: "#93c5fd", fill: "#ff00aa", fillOpacity: 0.4 } }`,
+{ effectType: "bubbles", params: { color: "#93c5fd", fill: "#ff00aa", fillOpacity: 0.4 } }
+EXAMPLE — gold liquid-metal aura outside a logo:
+{ effectType: "liquid_metal", params: { palette: 1, mode: "outside", intensity: 0.8 } }`,
         inputSchema: {
             type: 'object',
             properties: {
                 itemId: { type: 'string', description: 'Registry ID of the item' },
                 effectType: {
                     type: 'string',
-                    enum: ['sparkle', 'blast', 'smoke', 'fire', 'rain', 'snow', 'confetti', 'ripple', 'glow', 'electric', 'bubbles', 'dust', 'fireflies', 'shockwave', 'trail'],
+                    enum: ['sparkle', 'blast', 'smoke', 'fire', 'rain', 'snow', 'confetti', 'ripple', 'glow', 'electric', 'bubbles', 'dust', 'fireflies', 'shockwave', 'trail', 'heatmap', 'liquid_metal', 'gem_smoke'],
                     description: 'Type of effect',
                 },
                 params: {
@@ -4795,7 +5690,7 @@ WORKFLOW:
 1. pinepaper_agent_start_job → 2. pinepaper_agent_batch_execute (everything) → 3. pinepaper_agent_end_job (screenshot for validation)
 After validation: user reviews screenshot → feedback → modify/recreate as needed.
 
-OPERATION TYPES (12) — use in this order:
+OPERATION TYPES (13) — use in this order:
 
 CANVAS SETUP:
   set_canvas_size — {width, height} or {preset: "instagram"|"youtube"|"tiktok"|...}
@@ -4806,7 +5701,7 @@ CANVAS SETUP:
 
 ITEMS:
   create — {itemType, position: {x,y}, properties}
-    itemType: text, circle, rectangle, star, triangle, polygon, ellipse, path, line, arc
+    itemType: text, circle, rectangle, star, triangle, polygon, ellipse, path, line, arc, pentagon, hexagon, diamond, arrow, heart
     Properties per type:
       text: {content, fontSize, fontFamily, color, fontWeight}
       circle: {radius, color, strokeColor, strokeWidth}
@@ -4815,8 +5710,9 @@ ITEMS:
       ellipse: {radiusX, radiusY, color}
       triangle/polygon: {width/sides, height/radius, color}
     All: opacity, shadowColor, shadowBlur, blendMode, strokeColor, strokeWidth
-  modify — {itemId, properties}
+  modify — {itemId, properties} — instant reposition/restyle. To MOVE an item, set {x,y} here (a one-shot position change, not an animation).
   delete — {itemId}
+  group — {itemIds: ["$0","$1",...], groupName} — combine the parts of a composite object into ONE draggable/animatable entity. ALWAYS group a specific named object (car, robot, house, character) after creating its parts. Returns {groupId}; safe — user can ungroup. Do NOT group a whole scene whose pieces move independently.
 
 ANIMATION:
   animate — Loop animation: {itemId, animationType, animationOptions}
@@ -4827,6 +5723,8 @@ ANIMATION:
   relation — Behavioral link: {sourceId, targetId, relationType, relationOptions}
     relationType: orbits, follows, attached_to, points_at, mirrors, parallax, wave_through, morphs_to, group_morphs_to, moves_along_path (+ 9 more in schema)
 
+  MOVE vs ANIMATE vs PATH (pick by intent): instant reposition → modify {x,y}. Animated A→B move → keyframe_animate two keyframes [{time:0,{x,y}},{time:T,{x',y'}}]. Follow a multi-point path the user lists → relation moves_along_path {params:{path:[{x,y},…]}}.
+
 EFFECTS:
   apply_mask — Reveal effect: {itemId, maskPreset, maskOptions}
     maskPreset: wipeLeft, wipeRight, wipeUp, wipeDown, iris, irisOut, star, heart, curtainHorizontal, curtainVertical, cinematic, diagonalWipe, revealUp, revealDown
@@ -4867,7 +5765,7 @@ EXAMPLE — Animated sky scene with timed reveals:
                         properties: {
                             type: {
                                 type: 'string',
-                                enum: ['set_canvas_size', 'set_background', 'execute_generator', 'create', 'modify', 'delete', 'animate', 'keyframe_animate', 'relation', 'apply_mask', 'apply_effect', 'play_timeline'],
+                                enum: ['set_canvas_size', 'set_background', 'execute_generator', 'create', 'modify', 'delete', 'group', 'animate', 'keyframe_animate', 'relation', 'apply_mask', 'apply_effect', 'play_timeline'],
                                 description: 'Operation type',
                             },
                             // Canvas setup
@@ -4884,7 +5782,7 @@ EXAMPLE — Animated sky scene with timed reveals:
                             // Items
                             itemType: {
                                 type: 'string',
-                                enum: ['text', 'circle', 'rectangle', 'star', 'triangle', 'polygon', 'ellipse', 'path', 'line', 'arc'],
+                                enum: ['text', 'circle', 'rectangle', 'star', 'triangle', 'polygon', 'ellipse', 'path', 'line', 'arc', 'pentagon', 'hexagon', 'diamond', 'arrow', 'heart'],
                                 description: 'For create: item type',
                             },
                             position: {
@@ -4894,6 +5792,9 @@ EXAMPLE — Animated sky scene with timed reveals:
                             },
                             properties: { type: 'object', description: 'For create/modify: item properties' },
                             itemId: { type: 'string', description: 'Target item ID or $N reference' },
+                            // Group (combine composite-object parts into one entity)
+                            itemIds: { type: 'array', items: { type: 'string' }, description: 'For group: item IDs or $N refs to combine into one entity (the parts of a composite object).' },
+                            groupName: { type: 'string', description: 'For group: optional group name (e.g. "car").' },
                             // Loop animation
                             animationType: {
                                 type: 'string',
@@ -4921,7 +5822,7 @@ EXAMPLE — Animated sky scene with timed reveals:
                             targetId: { type: 'string', description: 'For relation: target item ID or $N' },
                             relationType: {
                                 type: 'string',
-                                enum: ['orbits', 'follows', 'attached_to', 'points_at', 'mirrors', 'parallax', 'animates', 'grows_from', 'staggered_with', 'wave_through', 'circumscribes', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'maintains_distance', 'bounds_to', 'indicates', 'camera_follows', 'camera_animates'],
+                                enum: ['orbits', 'follows', 'attached_to', 'points_at', 'mirrors', 'parallax', 'animates', 'grows_from', 'staggered_with', 'wave_through', 'circumscribes', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'maintains_distance', 'bounds_to', 'indicates', 'camera_follows', 'camera_animates', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'construction_reveal', 'driven_by', 'time_expression', 'on_event_fire_after', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_visibility', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with'],
                                 description: 'For relation: type',
                             },
                             relationOptions: { type: 'object', description: 'For relation: options' },
@@ -4936,7 +5837,7 @@ EXAMPLE — Animated sky scene with timed reveals:
                             // Effects
                             effectType: {
                                 type: 'string',
-                                enum: ['sparkle', 'blast', 'smoke', 'fire', 'rain', 'snow', 'confetti', 'ripple', 'glow', 'electric', 'bubbles', 'dust', 'fireflies', 'shockwave', 'trail'],
+                                enum: ['sparkle', 'blast', 'smoke', 'fire', 'rain', 'snow', 'confetti', 'ripple', 'glow', 'electric', 'bubbles', 'dust', 'fireflies', 'shockwave', 'trail', 'heatmap', 'liquid_metal', 'gem_smoke'],
                                 description: 'For apply_effect: effect type',
                             },
                             effectParams: { type: 'object', description: 'For apply_effect: parameters' },
@@ -5331,16 +6232,18 @@ USE WHEN:
         },
         description: `Validate and score a template definition against the PinePaper ontology.
 
-Two-phase analysis:
+Three-phase analysis:
 1. Schema validation — checks required fields, known item/relation types, keyframe structure, semantic vocabulary compliance
 2. Quality scoring — rates across 5 dimensions: completeness (0.20), animationDesign (0.25), semanticRichness (0.20), compositionUse (0.15), structuralDepth (0.20)
+3. Semantic diagnostics — FxTool's OntologyValidator (the same "one validator, two surfaces" library the Cloud pre-render gate runs), executed Node-side over the definition: dangling relation targets and unknown item/relation types (with nearest-id suggestions), duplicate edges, relation cycles, and keyframe order/easing issues. Returns { ok, diagnostics:[{code, severity, message, target, fix}], validatorVersion } under "diagnostics".
 
 Quality tiers: basic (<0.4), fair (0.4-0.6), good (0.6-0.8), excellent (>=0.8)
 
 USE WHEN:
 - Checking a template for structural issues before publishing
 - Comparing quality scores between template variants
-- Validating that all item/relation types are in the vocabulary`,
+- Validating that all item/relation types are in the vocabulary
+- Catching dangling references / cycles in a definition before it runs (use pinepaper_validate_scene for the LIVE canvas equivalent)`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -5352,6 +6255,54 @@ USE WHEN:
             required: ['definition'],
         },
     },
+    {
+        name: 'pinepaper_validate',
+        annotations: {
+            title: 'Validate Scene/Op',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Semantically validate the LIVE scene (or a proposed mutation before you apply it) and get back STRUCTURED diagnostics — not just pass/fail.
+
+Distinct from pinepaper_validate_design (which scores a template *definition* object). This runs against the live canvas and checks references, relation types, params, and reference cycles, returning:
+  { ok, diagnostics: [{ code, severity, message, target?, context?, fix? }] }
+
+Codes: TARGET_NOT_FOUND / SOURCE_NOT_FOUND (with a nearest-id "did you mean?" fix), UNKNOWN_RELATION, UNKNOWN_ITEM_TYPE, PARAM_TYPE, PARAM_ENUM / PARAM_RANGE (with a replace/clamp fix), RELATION_CYCLE (with the cycle path), DUPLICATE_RELATION. severity is error|warning|hint; ok is false only when an error is present. Advisory — it never mutates; fix.apply is a proposed op you may run.
+
+USE WHEN:
+- Before adding a relation, to confirm the target exists and the edge won't create a cycle (mode:'op')
+- After building a scene, to lint references/types/params (mode:'scene')
+- To recover from a failed op with an actionable suggestion instead of guessing
+
+mode:'scene' (default) audits the whole canvas. mode:'op' validates a single proposed mutation passed in 'op'.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                mode: {
+                    type: 'string',
+                    enum: ['scene', 'op'],
+                    description: "'scene' audits the whole live canvas (default); 'op' validates a proposed mutation before applying it",
+                },
+                op: {
+                    type: 'object',
+                    description: "Required when mode='op'. The proposed mutation: { kind:'addRelation'|'create'|'modify', from?, to?, relation?, params?, type?, id?, changes? }",
+                    properties: {
+                        kind: { type: 'string', enum: ['addRelation', 'create', 'modify'] },
+                        from: { type: 'string', description: 'Source item id (addRelation)' },
+                        to: { type: 'string', description: 'Target item id (addRelation)' },
+                        relation: { type: 'string', description: 'Relation type (addRelation)' },
+                        params: { type: 'object', description: 'Relation params (addRelation)' },
+                        type: { type: 'string', description: 'Item type (create)' },
+                        id: { type: 'string', description: 'Item id (modify)' },
+                        changes: { type: 'object', description: 'Property changes (modify)' },
+                    },
+                    required: ['kind'],
+                },
+            },
+        },
+    },
     {
         name: 'pinepaper_query_ontology',
         annotations: {