@pinepaper.studio/mcp-server 1.6.6 → 1.6.7

package/dist/tools/definitions.js

@@ -73,6 +73,10 @@ Choose based on mood:
 ─── ITEMS ───
 
 Shapes: circle, rectangle, star, ellipse, triangle, polygon, line, arc, path, pentagon, hexagon, diamond, arrow, heart
+Surfaces (render-time, evaluated per pixel — not shapes): shader, field
+  shader: a lit surface — water, liquid_metal, heatmap, gem_smoke. Set behind:true to put it UNDER the art, which is what scenery wants.
+  field:  one expression, many marks — xExpr/yExpr/count, re-evaluated every frame against t.
+  Both draw fully in a cloud render; locally they stand in as a flat plate.
 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
@@ -98,7 +102,7 @@ Photos / raster images (on-device, no upload):
 
 ─── ANIMATION (all in batch) ───
 
-Loop presets (animate): pulse, rotate, bounce, fade, wobble, slide, typewriter
+Loop presets (animate): bounce, breathe, fade, glow, jelly, path, pulse, rotate, scrollDown, scrollLeft, scrollRight, scrollUp, shake, slideLeftRight, slideUpDown, swing, typewriter, wobble
 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, 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
@@ -397,6 +401,24 @@ Items on the canvas can originate from multiple sources — all become first-cla
 - pinepaper_import_asset: Pre-made asset import → becomes a full item
 All imported items participate in the relation and animation systems just like natively created items.
 
+RENDER-TIME SURFACES — 'shader' and 'field':
+These are not shapes. A shape is built as an item and drawn from its geometry; a
+surface has no geometry — it is evaluated, per pixel or per sample, as each frame
+is drawn. Use them for things a vector cannot be: an open sea, a drifting field
+of marks, a lit material.
+- shader: pick one of water | liquid_metal | heatmap | gem_smoke, give it width
+  and height, and set behind:true to place it UNDER the vector art — which is
+  what scenery wants, a sea the boats float ON rather than a sheen over them.
+- field: xExpr/yExpr/count draw many marks from one expression, re-evaluated
+  every frame against t. rExpr and aExpr vary size and alpha per mark.
+Both draw fully in a cloud render; on a local canvas they stand in as a flat
+plate of their own colour so the layout still reads.
+
+LIFETIMES — bornAt and ttl, on any item:
+The only way to build a piece that CUTS between shots. Without them every item
+is on screen for the whole render, which is what makes a long piece read as one
+crowded frame instead of a sequence.
+
 WORKFLOW TIP:
 After creating items, use pinepaper_add_relation to animate them (e.g., orbits, follows, attached_to).
 For glossy 3D spheres, use pinepaper_create_glossy_sphere instead. For diagonal stripes, use pinepaper_create_diagonal_stripes.`,
@@ -405,8 +427,8 @@ 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', 'pentagon', 'hexagon', 'diamond', 'arrow', 'heart'],
-                    description: 'Type of item to create',
+                    enum: ['text', 'circle', 'star', 'rectangle', 'triangle', 'polygon', 'ellipse', 'path', 'line', 'arc', 'pentagon', 'hexagon', 'diamond', 'arrow', 'heart', 'shader', 'field'],
+                    description: "Type of item to create. 'shader' and 'field' are RENDER-TIME SURFACES drawn per pixel by the cloud renderer — locally they stand in as a flat plate. See the shader/field properties below.",
                 },
                 position: {
                     oneOf: [
@@ -429,7 +451,33 @@ For glossy 3D spheres, use pinepaper_create_glossy_sphere instead. For diagonal
                 },
                 properties: {
                     type: 'object',
-                    description: 'Type-specific properties (content, radius, color, fontSize, etc.)',
+                    description: `Type-specific properties (content, radius, color, fontSize, etc.)
+
+LIFETIME — on ANY item, and the only way to build a piece that CUTS between shots:
+- bornAt: seconds. The item does not exist before this instant.
+- ttl: seconds it lives for. Omit for "until the end".
+Without these every item is on screen for the whole render, which is what makes
+a long piece read as one crowded frame instead of a sequence of shots.
+
+SHADER (itemType 'shader') — a lit surface, drawn per pixel:
+- shader: 'water' (open sea, lit swell) | 'liquid_metal' (chrome) | 'heatmap' (thermal halo) | 'gem_smoke' (smoke) | 'electric_arc' (branching discharge, stepped flicker) | 'vortex' (hollow bright RING, sheared by differential rotation) | 'rain_veil' | 'caustics'
+- width, height: the quad it fills
+- shaderIntensity: 0..2, the effect's amplitude (water: chop)
+- shaderPalette: 0 day | 1 low sun | 2 night
+- behind: true draws it UNDER the vector art, which is what scenery needs —
+  a sea the boats float ON rather than a sheen laid over them. Default false.
+
+FIELD (itemType 'field') — one expression, many marks. The generative form:
+a whole surface as a function of the sample index and the clock, rather than
+thousands of authored items.
+- xExpr, yExpr: expressions for each mark's position
+- rExpr, aExpr: optional radius and alpha per mark. A radius <= 0 is skipped,
+  so subtracting a threshold draws only the crests of a wave.
+- count: how many marks (up to 200000)
+- Variables in scope: i (0..count-1), n (count), t (seconds), u (i/n), pi, e, tau.
+  Functions: sin cos tan asin acos atan sinh cosh tanh exp ln log10 log2 sqrt
+  cbrt abs floor ceil round sign atan2 min max pow hypot, and % for modulo.
+- Example — a rolling swell: xExpr "(i % 120) * 8", yExpr "400 + sin((i % 120) * 0.4 - t * 2) * 12", count 3600`,
                     additionalProperties: true,
                 },
                 data: {
@@ -443,7 +491,7 @@ For glossy 3D spheres, use pinepaper_create_glossy_sphere instead. For diagonal
                 },
                 animationType: {
                     type: 'string',
-                    description: "Animation type to apply on creation (e.g., 'pulse', 'bounce', 'rotate', 'fade', 'wobble', 'slide', 'typewriter', 'keyframe')",
+                    description: "Animation type to apply on creation (e.g., 'pulse', 'bounce', 'rotate', 'fade', 'slideLeftRight', 'scrollUp', 'typewriter', 'keyframe'). NOT 'slide' — that has never existed; the driver silently does nothing with an unknown type.",
                 },
                 animationSpeed: {
                     type: 'number',
@@ -509,6 +557,7 @@ MODIFIABLE PROPERTIES:
 - shadowBlur: Shadow blur radius
 - shadowOffset: Shadow offset [x, y]
 - blendMode: Blend mode (normal, multiply, screen, overlay, etc.)
+- pathData: SVG path data — RESHAPE the geometry itself, not just its styling. This is how you straighten a hand-drawn box or correct a traced outline without deleting and recreating the item, which would lose its id and every relation and keyframe pointing at it. Requires an FxTool build from 2026-08 or later: before that the property was silently dropped while the same call applied the fill and stroke and reported success.
 
 GRADIENT OBJECT FORMAT:
 {type: "linear"|"radial", stops: [{color: "#fff", offset: 0}, {color: "#000", offset: 1}], origin: [x,y], destination: [x,y]}
@@ -734,6 +783,56 @@ EXAMPLES:
     // ---------------------------------------------------------------------------
     // LAYER 1 — ATOMS: IMPORT TOOLS
     // ---------------------------------------------------------------------------
+    {
+        name: 'pinepaper_import_motion_capture',
+        annotations: {
+            title: 'Import Motion Capture (BVH)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        description: `Import a BVH motion-capture clip (CMU, Mixamo) as an animated skeleton, or retarget one onto a rig that already exists.
+
+TWO MODES, and picking the right one is the whole decision:
+- mode:'import'   → builds a NEW skeleton shaped like the capture file. Use when there is no character yet.
+- mode:'retarget' → drives an EXISTING rig named by skeletonId. Proportions stay the character's; only the MOTION comes from the clip. Use whenever the character already exists.
+
+USE WHEN:
+- The user supplies a .bvh clip, or asks for real captured motion rather than a simple animationType
+- A rigged character should perform a walk / run / gesture
+- Simple animation (pulse, bounce, rotate) is too coarse for the request
+
+DO NOT USE FOR:
+- Simple property animation → pinepaper_animate
+- Timed keyframe tracks you author yourself → pinepaper_keyframe_animate
+
+RESULT:
+- import   → { skeletonId, bones, poses, duration }
+- retarget → { skeletonId, matched, unmatchedSource, unmatchedTarget }
+
+BONE MATCHING: a BVH edge is named for the joint it ENDS at, so "LeftLeg" is the thigh and "LeftFoot" the shin — the alias table accounts for this. Anything it cannot place is reported in unmatchedSource/unmatchedTarget rather than silently driving half the rig; pass boneMap to resolve those explicitly.
+
+SAMPLING: CMU records at 120fps. fps defaults to 15 because 120 poses per second is unusable on a canvas timeline; fps:0 keeps every frame.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bvh: { type: 'string', description: 'BVH clip text.' },
+                mode: { type: 'string', enum: ['import', 'retarget'], description: "'import' = new skeleton from the file; 'retarget' = drive the existing rig in skeletonId, keeping its proportions. Default 'import'." },
+                skeletonId: { type: 'string', description: "Rig to drive. REQUIRED when mode='retarget'." },
+                fps: { type: 'number', description: 'Pose sampling rate; 0 keeps every frame. Default 15.' },
+                height: { type: 'number', description: 'Skeleton height on canvas in px (import mode). Default 320.' },
+                position: {
+                    type: 'object',
+                    description: 'Where the ROOT joint stands (import mode).',
+                    properties: { x: { type: 'number' }, y: { type: 'number' } },
+                },
+                name: { type: 'string', description: 'Name for the created skeleton (import mode).' },
+                boneMap: { type: 'object', description: "BVH edge name → this rig's bone name; overrides the alias table.", additionalProperties: { type: 'string' } },
+            },
+            required: ['bvh'],
+        },
+    },
     {
         name: 'pinepaper_import_svg',
         annotations: {
@@ -1349,7 +1448,10 @@ EXAMPLES:
                 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' },
+                warp: {
+                    anyOf: [{ type: 'object' }, { type: 'array', items: { type: 'object' } }],
+                    description: 'Chained parametric warp(s): { dx, dy } expressions of x, y, t — one object or an array',
+                },
             },
         },
     },
@@ -1384,7 +1486,10 @@ RETURNS: create → { success, action, eventId }; pulse → { success, action, e
                 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'" },
+                payload: {
+                    anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }, { type: 'object' }, { type: 'array' }],
+                    description: "Optional value forwarded to listeners — action 'pulse'",
+                },
             },
             required: ['action'],
         },
@@ -1798,7 +1903,10 @@ EXAMPLE: { action: 'apply_style', itemId: 'title_1', styleKey: 'arcade', fontFam
                 action: { type: 'string', enum: ['apply_style', 'set_font_axes', 'list_styles'], description: 'Text style operation' },
                 itemId: { type: 'string', description: 'Text item id — apply_style / set_font_axes.' },
                 styleKey: { type: 'string', description: 'apply_style: style name from list_styles.' },
-                palette: { description: 'apply_style: named colourway (string) or explicit color array.' },
+                palette: {
+                    anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
+                    description: 'apply_style: named colourway (string) or explicit color array.',
+                },
                 variant: { type: 'number', description: 'apply_style: variation index within the style.' },
                 content: { type: 'string', description: 'apply_style: replace the text while styling.' },
                 fontFamily: { type: 'string', description: "apply_style: font override; 'suggested' = the face the style was designed around." },
@@ -1808,6 +1916,131 @@ EXAMPLE: { action: 'apply_style', itemId: 'title_1', styleKey: 'arcade', fontFam
             required: ['action'],
         },
     },
+    {
+        name: 'pinepaper_design_medium',
+        annotations: {
+            title: 'Design Medium (What Makes The Marks)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `The THIRD design axis: the MEDIUM — what physically makes the marks.
+
+Register is which design language a piece speaks; level is how well it is executed; a medium is a set of physical constraints that produce characteristic marks. All three are independent: an embroidered schematic is a technical register at a refined level in a thread medium, and no single better/worse ranking can say that.
+
+READ THIS BEFORE PROMISING A MEDIUM. Naming a medium does not create its marks. Every medium declares a FIDELITY:
+- native — the characteristic marks ARE vector geometry (vector, thread, ink, cutPaper)
+- stylised — a recognisable impression; the limitation is stated on the entry (charcoal, oil)
+- absent — no vertex-level expression; the tool REFUSES with the reason instead of producing flat shapes in its colours (encaustic)
+
+Call resolve before telling a user you will render in a medium. "yes, but as an impression" is the true answer for half of them, and a flat approximation misrepresents a medium rather than approximating it.
+
+ACTIONS:
+- list_media: every medium with fidelity, definition and limitation. Read it rather than assuming a fixed set — the catalogue grows (hatch and watercolor are recent additions).
+- resolve: { medium } → { ok, fidelity, reason, markMaker }. ok:false with a reason is a real answer — pass it on rather than trying anyway.
+- list_stitches: the 4 thread stitches with their params.
+- apply_thread: render an item in thread. Its own silhouette is the region and its own fill is the thread colour, so an existing drawing becomes stitched rather than needing to be redrawn. The source is HIDDEN, not destroyed.
+- apply_hatch: rule an item with hatching. Same deal — silhouette is the region, source is hidden, re-hatching replaces.
+- list_flow_fields: the 7 fields that bend a hatch line.
+- list_hatch_options: the hatch defaults.
+
+THE DIRECTION FIELD IS THE WHOLE THING. Stitches that all lie the same way are hatching; stitches that follow the form are needlepainting. Use { kind: 'radial', cx, cy } for anything that radiates (a flower, an eye), { kind: 'spine', spine: [...] } to run them along a midrib or feather shaft, { kind: 'constant', angle } when you actually want flat hatch.
+
+STITCH CHOICE: longAndShort (default) is the shading fill — the length variance IS the blend. satin spans the shape edge to edge in one sheet, which is right for a petal or a letter stroke and wrong for a round shape. seed is texture, not direction. stem is an OUTLINE mark and leaves the interior bare — that is the stitch, not a bug.
+
+An unknown stitch is refused rather than defaulted, and re-stitching an item REPLACES its previous stitching instead of stacking.
+
+HATCHING STATES VALUE THROUGH LINE DENSITY, not colour. The same shape at distance 6 and at distance 3 reads as light and dark with nothing else changed — that is the whole medium, and it is why distance is the parameter to reach for rather than a lighter ink. gradient makes the density fall off across the shape, which is a shaded ramp rather than a flat tone.
+
+The straight ruling is what a printer makes; flowField is what makes it read as DRAWN. hand is the small correlated wander of a hand-drawn line, waves for water/hair/contours, spiral for wood grain around a knot, columns for rake marks. continuous joins the whole set into one serpentine path — a pen that never leaves the paper, and one item instead of many.
+
+Hatching needs a CLOSED outline. Text has none: convert it to glyph paths (pinepaper_text_style) and hatch the result. A group is hatched child by child, up to 40 paths; past that the result says so rather than quietly stopping.
+
+Note that a thread field and a hatch flowField are different things and are named differently for it: 'field' steers stitches around a form, 'flowField' bends a ruling line the way a hand drifts.
+
+EXAMPLE — a hatched shadow side, drawn rather than printed:
+{ "action": "apply_hatch", "itemId": "item_3", "distance": 3, "angle": 30, "flowField": "hand", "rand": 0.2 }
+
+EXAMPLE — a stitched leaf:
+{ "action": "apply_thread", "itemId": "item_3", "stitch": "longAndShort",
+  "field": { "kind": "spine", "spine": [{"x":400,"y":200},{"x":400,"y":520}] },
+  "stitchLen": 26, "variance": 0.45 }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['list_media', 'resolve', 'list_stitches', 'apply_thread', 'apply_hatch', 'list_flow_fields', 'list_hatch_options'], description: 'Medium operation' },
+                medium: { type: 'string', description: 'resolve: vector | thread | ink | cutPaper | charcoal | oil | encaustic' },
+                itemId: { type: 'string', description: 'apply_thread / apply_hatch: a closed path, compound path, or a group of them.' },
+                stitch: { type: 'string', enum: ['longAndShort', 'satin', 'seed', 'stem'], description: 'apply_thread: default longAndShort.' },
+                field: { type: 'object', description: "apply_thread: { kind: 'radial'|'spine'|'constant', cx, cy, angle, spine[], across } — default radial from the shape centre." },
+                stitchLen: { type: 'number', description: 'apply_thread: nominal stitch length px (default 18).' },
+                rowGap: { type: 'number', description: 'apply_thread: row spacing px; defaults from thread width so rows abut.' },
+                variance: { type: 'number', description: 'apply_thread: length jitter 0..1 (default 0.35) — the long-and-short shading.' },
+                width: { type: 'number', description: 'apply_thread: thread width px (default 2).' },
+                sheen: { type: 'boolean', description: 'apply_thread: highlight along each stitch (default true).' },
+                color: { type: 'string', description: "apply_thread: thread colour (defaults to the item's fill)." },
+                seed: { type: 'number', description: 'apply_thread: PRNG seed (default 1) — same seed stitches the same way.' },
+                count: { type: 'number', description: 'apply_thread: stitch count for seed/satin.' },
+                distance: { type: 'number', description: 'apply_hatch: line spacing px (default 6). THE VALUE CONTROL — 6 vs 3 is light vs dark.' },
+                angle: { type: 'number', description: 'apply_hatch: ruling angle in DEGREES (default 45).' },
+                gradient: { type: 'number', description: 'apply_hatch: 0..1 spacing growth per line (default 0, even) — a shaded ramp rather than a flat tone.' },
+                rand: { type: 'number', description: 'apply_hatch: jitter as a fraction of distance (default 0) — takes the mechanical evenness off.' },
+                continuous: { type: 'boolean', description: 'apply_hatch: join the lines into ONE serpentine path (default false).' },
+                flowField: {
+                    type: 'string',
+                    enum: ['hand', 'curved', 'zigzag', 'waves', 'seabed', 'spiral', 'columns'],
+                    description: 'apply_hatch: bend each line along a flow field — what makes it read as drawn rather than printed.',
+                },
+                t: { type: 'number', description: 'apply_hatch: flow-field time offset — advances the field without changing the seed.' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_text_effect',
+        annotations: {
+            title: 'Text Effects (37 Character-Level Animations)',
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Animate text CHARACTER BY CHARACTER — 37 effects (terminaltexteffects' vocabulary, reimplemented from source).
+
+⚠️ THIS REPLACES THE TEXT ITEM. Unlike pinepaper_text_style (which ADOPTS the text's registry id), this EXPLODES the text into one item per character and REMOVES the original. Any relation, keyframe, or handle pointing at the source id DIES with it. Pass keepSource: true to leave the original in place. The returned \`ids\` array is your entire new handle set.
+
+ACTIONS:
+- list: {} — the 37 effects as {key, label, definition}. Call this first; effect keys come from here.
+- apply: { itemId, effect, duration?, seed?, gradient?, gradientStops?, gradientDirection?, gradientSteps?, keepSource?, options? } — explode and animate.
+
+WHAT YOU GET: ordinary keyframe-animated items. It scrubs on the timeline, survives undo and session restore, and exports through the existing MP4 / SMIL / Lottie paths — this is not a frame-callback effect that renders on screen and vanishes from your export. Every effect ends AT REST, so \`duration\` is the settle time and the text is readable afterwards.
+
+COLOR: by default the resting characters are painted with a GRADIENT across the text block — that is what the upstream effects do and what their reference frames show. Pass gradient: false to keep the text's authored fill, or gradientStops to choose your own.
+
+DETERMINISM: seed defaults to 1, so the same text + effect + seed animates identically every run. Vary seed for a different scatter of the same effect.
+
+EFFECT KEYS (37): scattered, expand, spray, slice, bouncyballs, pour, slide, print, randomsequence, wipe, sweep, highlight, middleout, fireworks, blackhole, unstable, crumble, rings, swarm, orbittingvolley, overflow, decrypt, errorcorrect, matrix, binarypath, rain, burn, smoke, thunderstorm, bubbles, waves, beams, laseretch, spotlights, synthgrid, vhstape, colorshift.
+
+EXAMPLE: { action: 'apply', itemId: 'title_1', effect: 'decrypt', duration: 3, gradientStops: ['#00ff9c', '#0066ff'] }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['apply', 'list'], description: 'Text effect operation' },
+                itemId: { type: 'string', description: 'apply: the text item to animate (must have non-whitespace content).' },
+                effect: { type: 'string', description: "apply: effect key from 'list'." },
+                duration: { type: 'number', description: 'apply: seconds for the whole effect (default 2.5); ends at rest.' },
+                seed: { type: 'number', description: 'apply: PRNG seed (default 1) — same seed reproduces the animation exactly.' },
+                gradient: { type: 'boolean', description: "apply: false keeps the text's authored fill. Default true (gradient across the block)." },
+                gradientStops: { type: 'array', items: { type: 'string' }, description: 'apply: hex colors overriding the effect gradient.' },
+                gradientDirection: { type: 'string', enum: ['vertical', 'horizontal', 'radial', 'diagonal'], description: 'apply: gradient axis.' },
+                gradientSteps: { type: 'number', description: 'apply: quantization steps in the gradient ramp.' },
+                keepSource: { type: 'boolean', description: 'apply: keep the original text item — use when relations/keyframes reference its id.' },
+                options: { type: 'object', description: 'apply: per-effect knobs, passed through verbatim.' },
+            },
+            required: ['action'],
+        },
+    },
     {
         name: 'pinepaper_crop_image',
         annotations: {
@@ -1999,7 +2232,7 @@ ACTIONS:
 - add_actor: { actorId?, x, z, height?, sprite? (a canvas item id), live? } → { actorId }. live: true re-rasterizes the item as it animates — a RIGGED character (walk cycle, expressions) PERFORMS in the world instead of standing there as a photograph of itself.
 - remove_actor / list_actors / set_actor_pose: { actorId, pose: { x?, z?, angle? } } — the setter a timeline, sequencer or agent drives frame by frame.
 - set_camera: { camera: { mode: 'follow' | 'fixed' | 'orbit', target? (actorId), radius?, speed?, eye?, lookAt? } }
-- add_object: { object: { x, z, height?, color? } } (y defaults to sitting ON the terrain) / remove_object: { objectId }
+- add_object: { object: { x, z, height?, color?, metalness?, roughness?, emissiveIntensity? } } (y defaults to sitting ON the terrain) / remove_object: { objectId }
 - remove_world: {} — tears the world down; the Paper canvas was always its own layer and is untouched.
 
 RECIPE — a character walking through a forest: create {spec:'forest'} → import/rig a character on the canvas → add_actor {sprite: itemId, live: true} → set_camera {mode:'follow', target} → drive set_actor_pose over time (or let the built-in character control walk).`,
@@ -2007,8 +2240,14 @@ RECIPE — a character walking through a forest: create {spec:'forest'} → impo
             type: 'object',
             properties: {
                 action: { type: 'string', enum: ['create', 'describe', 'configure', 'add_actor', 'remove_actor', 'list_actors', 'set_actor_pose', 'set_camera', 'add_object', 'remove_object', 'remove_world'], description: 'World operation' },
-                spec: { description: "create: preset id ('forest'|'snowMountain'|'field'|'jungle') or a full spec object." },
-                character: { description: 'create: include the walkable character (boolean or config).' },
+                spec: {
+                    anyOf: [{ type: 'string' }, { type: 'object' }],
+                    description: "create: preset id ('forest'|'snowMountain'|'field'|'jungle') or a full spec object.",
+                },
+                character: {
+                    anyOf: [{ type: 'boolean' }, { type: 'object' }],
+                    description: 'create: include the walkable character (boolean or config).',
+                },
                 patch: { type: 'object', description: 'configure: partial world spec, validated against describe.' },
                 actorId: { type: 'string', description: 'Actor id.' },
                 x: { type: 'number', description: 'add_actor: world x.' },
@@ -2024,6 +2263,83 @@ RECIPE — a character walking through a forest: create {spec:'forest'} → impo
             required: ['action'],
         },
     },
+    {
+        name: 'pinepaper_character',
+        annotations: {
+            title: 'Character (place and direct a figure from the graph)',
+            readOnlyHint: false,
+            idempotentHint: false,
+        },
+        description: `Place a CHARACTER from the design graph and DIRECT it — no geometry, no bones, no poses.
+
+The knowledge of how a figure is built and how it moves lives in the graph; this asks for it by name and states WHAT happens. The alternative is thirty-odd exactly-right calls — create the skeleton, add each bone with the right parent and angle, create each shape, attach each to the right bone, then author poses — where one mistake anywhere leaves a broken figure.
+
+  { concept: "pp:Character", at: { x: 470, y: 250 }, height: 300,
+    beats: [ { at: 1.0, channel: "blink" },
+             { at: 1.8, channel: "say", until: 4.2 },
+             { at: 5.0, channel: "headTurn", value: -0.8 } ] }
+
+CHANNELS ARE DECLARED BY THE CONCEPT, not by you. Ask pinepaper_ontology for a concept to see the ones it has. Four kinds exist:
+- transform: one part deformed with an attack, a hold and a release — a blink is the eyes flattening in scaleY and easing back. This is what gives a gesture a MIDDLE; a swap between two drawings has only two ends and reads as flashing.
+- cycle: a repeating throw that runs for as long as you ask — a pigeon's head bob, a tail flick. Amplitude is a fraction of the part, so it means the same at any size.
+- shift: every part moved together, for a turn a flat drawing cannot rotate into.
+- alternate / speak: swaps between drawn states, for shapes that genuinely differ rather than deform.
+
+BEATS ARE INSTANTS OR SPANS. \`at\` is when it happens; \`until\` is how long for a channel that occupies time. \`value\` is how far, for channels that take a magnitude.
+
+WHAT YOU GET BACK: the items and keyframe tracks the beats compile to. They are ordinary scene items afterwards — modify, animate and relate them like anything else.
+
+NOT LIP SYNC. \`say\` opens and closes a mouth for the length of a line. Matching phonemes needs the word timings a voice track carries; pass \`timings\` if you have them and each entry drives one mouth opening.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                concept: {
+                    type: 'string',
+                    description: 'Concept id from the design graph, e.g. "pp:Character" or "pp:Pigeon". Its parts, rig and channels come with it.',
+                },
+                at: {
+                    type: 'object',
+                    properties: {
+                        x: { type: 'number', description: 'X of the figure\'s centre' },
+                        y: { type: 'number', description: 'Y of the figure\'s centre' },
+                    },
+                    description: 'Where the figure stands.',
+                },
+                height: { type: 'number', description: 'Drawn height in pixels. Every amplitude in the graph is a fraction, so the performance scales with it.' },
+                id: { type: 'string', description: 'Prefix for the created items (default: the concept name).' },
+                style: { type: 'string', description: 'Style id for the depiction (default: the concept\'s own).' },
+                variant: { type: 'string', description: 'Depiction variant (default: "default").' },
+                durationSeconds: { type: 'number', description: 'Length of the piece, so every track spans it. A track that starts late leaves the figure invisible until it does.' },
+                beats: {
+                    type: 'array',
+                    description: 'What happens, in order. Channels the concept does not declare are ignored rather than approximated.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            at: { type: 'number', description: 'When, in seconds' },
+                            channel: { type: 'string', description: 'A channel the concept declares — blink, say, headTurn, bob, tailFlick…' },
+                            until: { type: 'number', description: 'For a channel that occupies a span rather than an instant' },
+                            value: { type: 'number', description: 'How far, for a channel that takes a magnitude' },
+                        },
+                        required: ['at', 'channel'],
+                    },
+                },
+                timings: {
+                    type: 'array',
+                    description: 'Optional word or syllable timings from a voice track. Each entry drives one mouth opening, which is what turns the shape of speech into lip sync.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            at: { type: 'number', description: 'Start, in seconds' },
+                            until: { type: 'number', description: 'End, in seconds' },
+                        },
+                        required: ['at'],
+                    },
+                },
+            },
+            required: ['concept'],
+        },
+    },
     {
         name: 'pinepaper_rigging',
         annotations: {
@@ -2037,6 +2353,19 @@ RECIPE — a character walking through a forest: create {spec:'forest'} → impo
 
 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).
 
+POSE MOTION — build a performance out of saved poses:
+- START HERE on a rig you did not build yourself: list_bones gives the ids an inline pose needs ({ boneId: angleDeg }), and list_pose_libraries + load_pose_library give a fresh rig a stock walk/run/jump set to work with. A newly rigged character has ZERO saved poses, so without one of these there is nothing to sequence.
+- save_pose / list_poses / load_pose / interpolate_poses: the pose library. A pose is a snapshot of bone angles; everything below is a graph over these.
+- play_pose_sequence: one clip. Keys name a saved pose id or an inline { boneId: angleDeg } map. ONE sequence per skeleton — starting another replaces it.
+- stitch_poses: join CLIPS into one continuous performance (walk ×3 → jump → land → idle) and install it as a single sequence. This is how you get a transition rather than a cut.
+  · A cyclic clip (loop: true) is entered at the phase CLOSEST to where the previous clip ended, so the legs do not teleport mid-stride. matchPhase: false to disable.
+  · Every seam reports 'residual' — the angular mismatch, in degrees, that the blend could not remove. Near zero is a real match; a large number means the blend is HIDING a cut. Read it.
+  · plan: true returns the seams without touching the skeleton, so you can check the joins first.
+- move_root: a deterministic locomotion track, keyed in SCENE SECONDS on the same clock as the pose sequence. Without it a walk cycle is a march on the spot; with a last keyframe shorter than the performance, the figure arrives early and stands there.
+- auto_walk / auto_breath / auto_idle / auto_jump: one-call procedural layers. breath and idle find their bones BY NAME (spine/chest/body, head/hip/spine) and refuse with that list if the rig uses other names.
+- bake_animation: freeze the whole rig into plain item keyframes for export. Needs items ATTACHED to bones — a bare skeleton has no output.
+- add_secondary_motion: spring chains for tails, hair, cloth. skin_path: per-vertex deformation of a curved path.
+
 ACTIONS:
 - create_skeleton: { name?, rootPosition? } → { skeletonId }
 - add_bone: { skeletonId, name?, parentBoneId? (omit for root), length? (80), angle? (deg), flexibility? (0 rigid…1), segments? } → { boneId }
@@ -2054,7 +2383,7 @@ BREAKDOWN POSES (S12): a breakdown keyframe shapes the ARC + SPACING between key
         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', 'import_bvh', 'retarget_bvh', 'import_spine'], description: 'Rigging operation' },
+                action: { type: 'string', enum: ['create_skeleton', 'add_bone', 'attach_item', 'create_ik_chain', 'add_pose_keyframe', 'set_target_path', 'save_pose', 'save_shape_key', 'import_bvh', 'retarget_bvh', 'import_spine', 'list_skeletons', 'list_bones', 'list_pose_libraries', 'load_pose_library', 'list_poses', 'load_pose', 'interpolate_poses', 'play_pose_sequence', 'stop_pose_sequence', 'stitch_poses', 'apply_pose_transition', 'auto_walk', 'auto_breath', 'auto_idle', 'auto_jump', 'move_root', 'stop_root_track', 'add_secondary_motion', 'skin_path', 'bake_animation', 'list_shape_keys', 'load_shape_key'], description: 'Rigging operation' },
                 bvhText: { type: 'string', description: 'import_bvh / retarget_bvh: the .bvh file contents.' },
                 spineJson: { type: 'string', description: 'import_spine: the Spine JSON export, as a string.' },
                 view: { type: 'string', enum: ['side', 'front'], description: 'import_bvh: 3D→2D projection plane. CMU walks read best from the side (default).' },
@@ -2065,6 +2394,25 @@ BREAKDOWN POSES (S12): a breakdown keyframe shapes the ARC + SPACING between key
                 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.' },
+                poseId: { type: 'string', description: 'Saved pose id — load_pose.' },
+                libraryName: { type: 'string', description: 'Stock pose set — load_pose_library. list_pose_libraries for the names.' },
+                boneMap: { type: 'object', description: 'Bone NAME → bone id — load_pose_library. Omit to build it from list_bones.' },
+                poseIdA: { type: 'string', description: 'First pose — interpolate_poses.' },
+                poseIdB: { type: 'string', description: 'Second pose — interpolate_poses.' },
+                t: { type: 'number', description: 'Blend 0=A … 1=B — interpolate_poses.' },
+                sequence: { type: 'array', items: { type: 'object' }, description: 'Pose keys [{ t, pose | angles, ease }] — play_pose_sequence.' },
+                clips: { type: 'array', items: { type: 'object' }, description: 'Clips in order for stitch_poses: [{ keys | poses, duration, repeat, loop, blend, matchPhase }]. A clip key names a SAVED pose id or an inline { boneId: angleDeg } map.' },
+                blend: { type: 'number', description: 'Seam overlap in seconds (default 0.25) — stitch_poses.' },
+                blendSteps: { type: 'number', description: 'Keys emitted across a seam (default 6) — stitch_poses.' },
+                matchPhase: { type: 'boolean', description: 'Enter a cyclic clip at the phase closest to where the last one ended (default true) — stitch_poses.' },
+                plan: { type: 'boolean', description: 'stitch_poses: return the seams WITHOUT installing the result.' },
+                transitionName: { type: 'string', description: 'Named transition — apply_pose_transition.' },
+                poseIdMap: { type: 'object', description: 'Transition pose name → saved pose id — apply_pose_transition.' },
+                boneNames: { type: 'array', items: { type: 'string' }, description: 'Ordered bone names for a spring chain — add_secondary_motion.' },
+                keyframes: { type: 'array', items: { type: 'object' }, description: 'World root positions [{ t, x, y, ease }] — move_root. `t` is SCENE SECONDS on the same clock as the pose sequence, not a 0..1 fraction: match the last keyframe to the performance duration or the figure arrives early and stands still for the rest.' },
+                shapeKeyId: { type: 'string', description: 'Saved shape key id — load_shape_key.' },
+                weight: { type: 'number', description: 'Shape key weight (default 1) — load_shape_key.' },
+                options: { type: 'object', description: 'Pass-through options — auto_* / bake_animation / move_root / skin_path / play_pose_sequence.' },
                 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.' },
@@ -2079,7 +2427,10 @@ BREAKDOWN POSES (S12): a breakdown keyframe shapes the ARC + SPACING between key
                 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.' },
+                pose: {
+                    anyOf: [{ type: 'string' }, { type: 'object', additionalProperties: { type: 'number' } }],
+                    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.' },
@@ -2198,7 +2549,7 @@ USE WHEN:
 - Building live geometric constructions (GeoGebra-style — dragging an anchor updates the dependent)
 
 RELATION TYPES:
-- orbits: Circular motion around target (params: radius, speed, direction, phase)
+- orbits: Circular motion around target (params: radius, speed, direction, phaseDegrees). Use phaseDegrees. 'phase' is the one parameter in the whole relation vocabulary measured in RADIANS — the documented exception to "angles are DEGREES", kept only for scenes that already set it. phaseDegrees wins when both are given.
 - follows: Move toward target with smoothing (params: offset, smoothing, delay)
 - attached_to: Fixed offset from target (params: offset, inherit_rotation)
 - maintains_distance: Stay fixed distance from target (params: distance, strength)
@@ -2206,6 +2557,35 @@ RELATION TYPES:
 - mirrors: Mirror position across axis (params: axis, center)
 - parallax: Move relative by depth (params: depth, origin)
 - bounds_to: Stay within bounds (params: padding, bounce)
+- anchored_in_world: Pin the item to a 3D world position so it tracks the world camera.
+- spring_follow: Follow with spring dynamics rather than smoothing — it overshoots and settles.
+- repels: Move away from the target inside a radius and ease back when it leaves (params: force, maxDistance, minDistance, returnSpeed). Crowd avoidance, and reacting to a cursor without being dragged by it.
+- wiggle: Continuous procedural noise on the item. Richer than a sine: it does not repeat visibly.
+- syncs_with: Run the source's animation on the TARGET's timeline (params: offset, speedRatio) — they share a clock and stay in step even when the target's timing changes, which merely starting together does not give you.
+- triggers_animation: Start the target's animation on a condition (params: trigger, delay, atTime). The declarative "and then": sequencing in the graph instead of in a callback nobody can query.
+- tours / synced_to_audio: Move through a sequence of targets; bind playback to an audio track.
+- connects_to: Diagram edge (params: via, sourcePort, targetPort, label).
+- attached_to_tail / head_points_to: Bind a connector's tail / head to a diagram port (params: port). Together they are why a connector stays connected when a flowchart is rearranged.
+- expresses: Play a facial expression over a root's part_of children (params: expression — blink|smile|surprise…, interval, duration, easing). No interval means sustained. It walks part_of from the ROOT, so parts with roles but no parent are INERT: the relation applies to nothing and reports success, which is what makes an unparented pair of eyes look finished while being unable to blink.
+- part_of: Semantic membership with a named role (params: role, offset, structural). structural: true records the part WITHOUT driving its position — the right choice when the parent is a group that already transforms its children, since driving it too would fight the group.
+- staggered_with: Delay an item's animation by its place in a sequence (params: index, stagger, effect). For a SHAPED stagger — outward from the centre, converging from the edges, across a grid — also pass count (required: without it there is no "end" to measure distance from), plus from (start|end|center|edges|random), amount (total seconds for the whole run, overrides stagger), grid ("rows,cols" or "auto"), axis (x|y) and distributeEase. Plain index x stagger still works and is taken first. To stagger items directly rather than through a relation, use pinepaper_stagger.
+
+INTERACTIVE RELATIONS — the state machine lives in the graph.
+An event channel (pinepaper_event) is the hub: something FIRES it, and reactions bound to it run. Nothing here is a callback; it is all queryable graph, so it scrubs, exports and survives a reload.
+
+- Input triggers (item → event): on_click_fire, on_pointer_enter_fire, on_pointer_exit_fire, on_key_fire (params: key, modifiers, global, preventDefault). { key: 'Enter' } makes Enter activate a button exactly as a click does. The chord is matched EXACTLY in both directions — { key: 'Enter' } does NOT fire on Ctrl+Enter, and { key: 's' } does not steal the browser's Ctrl+S; ask for a modifier with modifiers: { ctrl: true }. Listens only while the source item has focus unless global: true, so it will not take keys from the rest of the page.
+- Event reactions (event → item), params in common: property, value, key, by, color, template, delay, timeline.
+  · on_event_set_property / _set_color / _set_visibility / _set_data — write a value.
+  · on_event_set_property_from_template — write a value built from a '{token}' TEMPLATE read off item.data, so the text can quote live state ("Score: {score}") instead of a literal fixed when you authored it.
+  · on_event_increment (params: property, by) / on_event_toggle — counters and flip-flops.
+  · on_event_fire_after (params: delay, timeline) — chain one beat to the next.
+  · on_event_fire_if — the only reaction that TESTS graph state rather than mutating it; params.predicate is an ExpressionIR program.
+  · on_event_add_relation / on_event_remove_relation — the scene rewires itself.
+  · on_event_store_set / on_event_store_increment / restores_from — persistent state. The target is a store node whose id is the storage SCOPE, so two stores in a scene and two widgets on a page do not collide. restores_from is the read half and fires ONCE at load.
+- Proximity (pointer over an item): on_enter_* / on_exit_* mirror the on_event_* reactions above (set_color, set_property, set_property_from_template, set_visibility, set_data, increment, toggle) — hover states without a single line of script.
+- Exclusive state: exclusive_group makes at most one member active (on_event_set_active is how you activate one — tabs, steppers, quiz cards). menubar_group is the same grouping WITHOUT the mutex.
+
+There are 80 relation types and this list names the families rather than every member. For the live catalogue — what exists in THIS build, with definitions — call pinepaper_query_capabilities { kind: 'relation' }, which reads the engine's registry rather than a list written down here.
 
 RELATION COMPATIBILITY:
 - Universal relations (position-based) work with ALL item types including imported SVGs/images:
@@ -2270,7 +2650,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', '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'],
+                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'anchored_in_world', 'spring_follow', 'repels', 'wiggle', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'construction_reveal', 'triggers_animation', 'syncs_with', 'tours', 'synced_to_audio', 'expresses', 'camera_follows', 'camera_animates', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'driven_by', 'time_expression', 'on_click_fire', 'on_pointer_enter_fire', 'on_pointer_exit_fire', 'on_key_fire', 'on_event_fire_after', 'on_event_fire_if', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_property_from_template', 'on_event_set_visibility', 'on_event_set_active', 'on_event_set_data', 'on_event_increment', 'on_event_toggle', 'on_event_store_set', 'on_event_store_increment', 'on_enter_set_color', 'on_enter_set_property', 'on_enter_set_property_from_template', 'on_enter_set_visibility', 'on_enter_set_data', 'on_enter_increment', 'on_enter_toggle', 'on_exit_set_color', 'on_exit_set_property', 'on_exit_set_property_from_template', 'on_exit_set_visibility', 'on_exit_set_data', 'on_exit_increment', 'on_exit_toggle', 'exclusive_group', 'menubar_group', 'restores_from', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with', 'part_of', 'connects_to', 'attached_to_tail', 'head_points_to'],
                     description: 'Type of relationship',
                 },
                 params: {
@@ -2304,7 +2684,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', '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'],
+                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'anchored_in_world', 'spring_follow', 'repels', 'wiggle', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'construction_reveal', 'triggers_animation', 'syncs_with', 'tours', 'synced_to_audio', 'expresses', 'camera_follows', 'camera_animates', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'driven_by', 'time_expression', 'on_click_fire', 'on_pointer_enter_fire', 'on_pointer_exit_fire', 'on_key_fire', 'on_event_fire_after', 'on_event_fire_if', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_property_from_template', 'on_event_set_visibility', 'on_event_set_active', 'on_event_set_data', 'on_event_increment', 'on_event_toggle', 'on_event_store_set', 'on_event_store_increment', 'on_enter_set_color', 'on_enter_set_property', 'on_enter_set_property_from_template', 'on_enter_set_visibility', 'on_enter_set_data', 'on_enter_increment', 'on_enter_toggle', 'on_exit_set_color', 'on_exit_set_property', 'on_exit_set_property_from_template', 'on_exit_set_visibility', 'on_exit_set_data', 'on_exit_increment', 'on_exit_toggle', 'exclusive_group', 'menubar_group', 'restores_from', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with', 'part_of', 'connects_to', 'attached_to_tail', 'head_points_to'],
                     description: 'Specific relation type to remove (optional - removes all if not specified)',
                 },
             },
@@ -2332,7 +2712,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', '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'],
+                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'anchored_in_world', 'spring_follow', 'repels', 'wiggle', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'construction_reveal', 'triggers_animation', 'syncs_with', 'tours', 'synced_to_audio', 'expresses', 'camera_follows', 'camera_animates', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'driven_by', 'time_expression', 'on_click_fire', 'on_pointer_enter_fire', 'on_pointer_exit_fire', 'on_key_fire', 'on_event_fire_after', 'on_event_fire_if', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_property_from_template', 'on_event_set_visibility', 'on_event_set_active', 'on_event_set_data', 'on_event_increment', 'on_event_toggle', 'on_event_store_set', 'on_event_store_increment', 'on_enter_set_color', 'on_enter_set_property', 'on_enter_set_property_from_template', 'on_enter_set_visibility', 'on_enter_set_data', 'on_enter_increment', 'on_enter_toggle', 'on_exit_set_color', 'on_exit_set_property', 'on_exit_set_property_from_template', 'on_exit_set_visibility', 'on_exit_set_data', 'on_exit_increment', 'on_exit_toggle', 'exclusive_group', 'menubar_group', 'restores_from', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with', 'part_of', 'connects_to', 'attached_to_tail', 'head_points_to'],
                     description: 'Filter by relation type (optional)',
                 },
                 direction: {
@@ -2483,7 +2863,8 @@ USE WHEN:
 - "bouncing text" → animationType: bounce
 - "fading effect" → animationType: fade
 - "wobbling button" → animationType: wobble
-- "sliding header" → animationType: slide
+- "sliding header" → animationType: slideLeftRight (or slideUpDown)
+- "scrolling banner" → animationType: scrollLeft (also scrollRight/Up/Down)
 - "typewriter effect" → animationType: typewriter (text only)
 
 DO NOT USE WHEN:
@@ -2491,21 +2872,30 @@ DO NOT USE WHEN:
 - User wants sequential animations ("first fade, then rotate") → Use keyframe animation
 - User describes relationships ("orbit around") → Use relations
 
-ANIMATION TYPES:
+ANIMATION TYPES (18 — the list the driver actually switches on):
 - pulse: Scale up/down rhythmically
+- breathe: A slower, softer pulse
 - rotate: Continuous rotation
+- swing: Pendulum rotation about the top
 - bounce: Vertical bouncing motion
-- fade: Opacity cycling
+- jelly: Squash-and-stretch wobble
+- shake: Rapid small displacement
 - wobble: Side-to-side wobbling
-- slide: Horizontal sliding
-- typewriter: Character-by-character reveal`,
+- fade: Opacity cycling
+- glow: Cycling luminance
+- slideLeftRight / slideUpDown: Sliding on one axis
+- scrollLeft / scrollRight / scrollUp / scrollDown: Continuous scroll, wrapping
+- path: Travel along an assigned path
+- typewriter: Character-by-character reveal
+
+There is NO 'slide'. An unknown type is stored and then ignored — the item sits still while its data claims otherwise, and the call still reports success — so use the exact names above.`,
         inputSchema: {
             type: 'object',
             properties: {
                 itemId: { type: 'string', description: 'Registry ID of the item' },
                 animationType: {
                     type: 'string',
-                    enum: ['pulse', 'rotate', 'bounce', 'fade', 'wobble', 'slide', 'typewriter'],
+                    enum: ['bounce', 'breathe', 'fade', 'glow', 'jelly', 'path', 'pulse', 'rotate', 'scrollDown', 'scrollLeft', 'scrollRight', 'scrollUp', 'shake', 'slideLeftRight', 'slideUpDown', 'swing', 'typewriter', 'wobble'],
                     description: 'Type of animation',
                 },
                 speed: {
@@ -2635,15 +3025,45 @@ USE WHEN:
 - Seeking to specific time
 - 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.`,
+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.
+
+RATE (set_time_scale / get_time_scale): 1 is real time, 0.5 half speed, 0 freezes the clock WITHOUT stopping playback, and a negative rate runs the scene backwards. Changing it preserves the current position — the clock is rebased, so the playhead does not jump. Export is deliberately unaffected: a scene watched at 0.5x still exports its real duration rather than a file twice as long.
+
+PROGRESS (get_progress / set_progress): the timeline as 0..1, which is the unit a scrubber or a progress bar actually has. set_progress returns the seconds it landed on.
+
+SCROLL (bind_scroll / unbind_scroll / list_scrub_anchors): drive the timeline from how far the reader has scrolled instead of from a clock — what makes a scroll-told story a story rather than a video that happens to be on the page. Anchors ('top bottom' = the moment the element appears, 'bottom top' = the moment it is gone) say where the range starts and ends; scrub is a smoothing time constant so the playhead chases the scroll instead of snapping to it. Chiefly for embeds and generated code — nothing scrolls a headless page. ALWAYS unbind before rebinding or navigating away: the listener holds the scene alive. bind_scroll releases a previous binding for you, and unbind_scroll on nothing bound answers { bound: false } rather than failing.`,
         inputSchema: {
             type: 'object',
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['play', 'pause', 'stop', 'seek'],
+                    enum: [
+                        'play', 'pause', 'stop', 'seek',
+                        'set_time_scale', 'get_time_scale',
+                        'get_progress', 'set_progress',
+                        'bind_scroll', 'unbind_scroll', 'list_scrub_anchors',
+                    ],
                     description: 'Playback action',
                 },
+                rate: {
+                    type: 'number',
+                    description: 'set_time_scale: 1 real time, 0.5 half speed, 0 freezes without stopping, negative runs backwards. Export is unaffected.',
+                },
+                progress: {
+                    type: 'number',
+                    description: 'set_progress: how far through the timeline, 0..1',
+                },
+                scroll: {
+                    type: 'object',
+                    properties: {
+                        elementId: { type: 'string', description: 'DOM id of the element to track (defaults to the canvas)' },
+                        start: { type: 'string', description: "Anchor where the range begins, e.g. 'top bottom' — see list_scrub_anchors" },
+                        end: { type: 'string', description: "Anchor where the range ends, e.g. 'bottom top'" },
+                        scrub: { type: 'number', description: 'Seconds of smoothing so the playhead chases the scroll (default 0.3; 0 snaps)' },
+                        range: { type: 'array', items: { type: 'number' }, description: '[from, to] seconds — drive only a sub-range of the timeline' },
+                    },
+                    description: 'bind_scroll options',
+                },
                 duration: {
                     type: 'number',
                     description: 'Duration for play action',
@@ -3131,7 +3551,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, 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`,
+SUPPORTED ANIMATIONS: bounce, breathe, fade, glow, jelly, path, pulse, rotate, scrollDown, scrollLeft, scrollRight, scrollUp, shake, slideLeftRight, slideUpDown, swing, typewriter, wobble`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -3176,7 +3596,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', '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'],
+                                enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'anchored_in_world', 'spring_follow', 'repels', 'wiggle', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'construction_reveal', 'triggers_animation', 'syncs_with', 'tours', 'synced_to_audio', 'expresses', 'camera_follows', 'camera_animates', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'driven_by', 'time_expression', 'on_click_fire', 'on_pointer_enter_fire', 'on_pointer_exit_fire', 'on_key_fire', 'on_event_fire_after', 'on_event_fire_if', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_property_from_template', 'on_event_set_visibility', 'on_event_set_active', 'on_event_set_data', 'on_event_increment', 'on_event_toggle', 'on_event_store_set', 'on_event_store_increment', 'on_enter_set_color', 'on_enter_set_property', 'on_enter_set_property_from_template', 'on_enter_set_visibility', 'on_enter_set_data', 'on_enter_increment', 'on_enter_toggle', 'on_exit_set_color', 'on_exit_set_property', 'on_exit_set_property_from_template', 'on_exit_set_visibility', 'on_exit_set_data', 'on_exit_increment', 'on_exit_toggle', 'exclusive_group', 'menubar_group', 'restores_from', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with', 'part_of', 'connects_to', 'attached_to_tail', 'head_points_to'],
                             },
                             params: {
                                 type: 'object',
@@ -3196,7 +3616,7 @@ SUPPORTED ANIMATIONS: pulse, rotate, bounce, fade, wobble, slide, typewriter`,
                             target: { type: 'string', description: 'Name of item to animate' },
                             type: {
                                 type: 'string',
-                                enum: ['pulse', 'rotate', 'bounce', 'fade', 'wobble', 'slide', 'typewriter'],
+                                enum: ['bounce', 'breathe', 'fade', 'glow', 'jelly', 'path', 'pulse', 'rotate', 'scrollDown', 'scrollLeft', 'scrollRight', 'scrollUp', 'shake', 'slideLeftRight', 'slideUpDown', 'swing', 'typewriter', 'wobble'],
                             },
                             speed: { type: 'number', description: 'Animation speed (default: 1.0)' },
                             params: {
@@ -3334,6 +3754,361 @@ EXAMPLE — Slideshow:
             required: ['action'],
         },
     },
+    {
+        name: 'pinepaper_sequence',
+        annotations: {
+            title: 'Timeline Sequencing (Relative Positions)',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Work out WHEN clips start, said relative to each other instead of in absolute seconds. A pure planner — it computes times and touches nothing on the canvas. (For revealing a geometric construction step by step, that is pinepaper_construction_sequence, a different tool.)
+
+Nobody thinks "the subtitle starts at 1.85s"; they think "a quarter of a second after the title finishes". This resolves the second into the first, and re-resolves it when an earlier clip changes length.
+
+ACTIONS:
+- place: thread a whole run of clips, each resolved against the ones before it. Returns { placed: [{start, end, duration}], labels, duration }.
+- resolve: answer a single position spec against a context you supply.
+- list_forms: the accepted grammar, each form with what it means.
+
+POSITION FORMS:
+- 3 — exactly 3s from the start of the timeline
+- "<" / ">" — when the previous clip STARTED / ENDED
+- "<2" / ">2" — 2s after the previous clip started / ended
+- "+=1" / "-=1" — 1s after the timeline ends (a gap) / 1s before it (an overlap)
+- "intro" / "intro+=0.5" — at a label, or half a second after it
+- omitted — append at the end, which is what appending has always meant
+
+THE ONE THING TO GET RIGHT: a percentage means different things in different forms.
+- "-=25%" and "+=25%" scale against the clip BEING INSERTED — "overlap the previous clip by a quarter of MY length".
+- "<25%" and ">25%" scale against the PREVIOUS clip — "start a quarter of the way THROUGH it".
+They agree only when the two clips are the same length, which is rarely, and getting it backwards yields timings that look almost right.
+
+A label names the moment a clip STARTS, so "label+=0" lands on the clip rather than skipping it. The timeline only ever grows — placing something early with "-=" never pulls the end back.
+
+EXAMPLE:
+{
+  "action": "place",
+  "clips": [
+    { "id": "title",    "duration": 2, "label": "intro" },
+    { "id": "subtitle", "duration": 4, "position": "-=25%" },
+    { "id": "cta",      "duration": 1, "position": "intro+=0.5" }
+  ]
+}`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['place', 'resolve', 'list_forms'],
+                    description: 'place (a run of clips), resolve (one position), or list_forms (default: place)',
+                },
+                clips: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string', description: 'Your own name for the clip — echoed back on the placement' },
+                            duration: { type: 'number', description: 'How long the clip runs, in seconds' },
+                            position: {
+                                anyOf: [{ type: 'number' }, { type: 'string' }],
+                                description: 'Where it starts. Omit to append at the end of the run so far.',
+                            },
+                            label: { type: 'string', description: 'Name this moment for later clips to position against. Marks where the clip STARTS.' },
+                        },
+                        required: ['duration'],
+                    },
+                    description: 'place: the run of clips, in order',
+                },
+                position: {
+                    anyOf: [{ type: 'number' }, { type: 'string' }],
+                    description: 'resolve: the single position spec to resolve',
+                },
+                context: {
+                    type: 'object',
+                    properties: {
+                        timelineEnd: { type: 'number', description: 'Where the timeline currently ends — what "+=1" counts from' },
+                        prevStart: { type: 'number', description: 'Start of the most recent clip — what "<" means' },
+                        prevEnd: { type: 'number', description: 'End of the most recent clip — what ">" means' },
+                        insertDuration: { type: 'number', description: 'Duration of the clip being placed — the basis for a "+=25%" percentage' },
+                    },
+                    description: 'resolve: what the spec is measured against',
+                },
+                labels: {
+                    type: 'object',
+                    additionalProperties: { type: 'number' },
+                    description: 'Named moments in seconds, addressable as "name" or "name+=0.5"',
+                },
+                startAt: { type: 'number', description: 'place: where the run begins (default 0)' },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_stagger',
+        annotations: {
+            title: 'Stagger',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Shape a delay across many items. What makes a stagger read as designed rather than as a queue is where it STARTS and how it SPREADS — a grid lighting up outward from the centre, a row converging from both edges.
+
+Delays are written to the channel the engine and the SMIL exporter already read, so a staggered scene scrubs, exports and restores. Nothing here is playback-only.
+
+ACTIONS:
+- apply: write the delays onto real items, in the order you list them (row-major for a grid).
+- preview: the delays for a count, without touching the canvas.
+- list_origins: the origins, each with what it means.
+
+each VS amount — alternatives, not a pair:
+- each fixes the gap between NEIGHBOURS, so more items make a longer sequence.
+- amount fixes the TOTAL, so more items crowd together. It overrides each.
+
+ORIGINS (from):
+- start — the first item goes first, in order. The plain queue.
+- end — the last goes first; the sequence runs backwards.
+- center — spreads outward from the middle of the run or grid.
+- edges — starts at both ends at once and converges on the middle.
+- random — a shuffled ORDER, not random delays: every item still lands on one of the same slots, so the rhythm survives. Seeded.
+from also takes an item index, or [fx, fy] fractions for a grid ([0.5, 0.5] is the centre).
+
+ease distributes the START TIMES. It is not the items' own animation curve.
+
+EXAMPLE — a 3x3 grid lighting up from the middle:
+{ "action": "apply", "itemIds": ["a","b","c","d","e","f","g","h","i"], "opts": { "each": 0.1, "from": "center", "grid": [3, 3] } }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['apply', 'preview', 'list_origins'],
+                    description: 'apply (to items), preview (delays only), or list_origins (default: apply)',
+                },
+                itemIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'apply: registry IDs in the order the stagger should follow (row-major for a grid)',
+                },
+                count: { type: 'number', description: 'preview: how many items to compute delays for' },
+                opts: {
+                    type: 'object',
+                    properties: {
+                        each: { type: 'number', description: 'Seconds between neighbours (default 0.1)' },
+                        amount: { type: 'number', description: 'Total seconds for the whole run — overrides each' },
+                        from: {
+                            anyOf: [
+                                { type: 'string', enum: ['start', 'end', 'center', 'edges', 'random'] },
+                                { type: 'number' },
+                                { type: 'array', items: { type: 'number' } },
+                            ],
+                            description: 'Named origin, an item index, or [fx, fy] fractions for a grid',
+                        },
+                        grid: { type: 'array', items: { type: 'number' }, description: '[rows, columns] for a 2D stagger' },
+                        axis: { type: 'string', enum: ['x', 'y'], description: 'Restrict a grid stagger to one axis' },
+                        ease: {
+                            type: 'string',
+                            enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'easeInCubic', 'easeOutCubic'],
+                            description: "Curve that distributes the START TIMES — not the items' own animation",
+                        },
+                        seed: { type: 'number', description: "from: 'random' — same seed, same shuffle (default 1)" },
+                    },
+                    description: 'Shape of the stagger',
+                },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_flip',
+        annotations: {
+            title: 'Flip (Derived Transition)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Animate a layout change WITHOUT describing the motion. Every other animation tool asks you to say what the movement is; this asks the opposite — record where things are, rearrange them however you like, and the transition is derived from the difference.
+
+That is what makes it usable for changes nobody could enumerate in advance: a re-sort, an auto-layout pass, a filter, a drag.
+
+THE ORDER MATTERS:
+1. action: 'record' — capture the current positions.
+2. Rearrange, with any tools you like (move, align, sort, re-layout).
+3. action: 'apply' — the motion between the two states is worked out and written.
+
+Recording after the change, or skipping step 2, produces nothing to animate.
+
+It writes ordinary keyframes, so the transition scrubs on the timeline, exports through the MP4 / SMIL / Lottie paths, and survives a reload. Only properties that ACTUALLY changed are written — a track that also pinned the unchanged ones would fight anything else animating them, and a flip of position would quietly freeze an item's own pulse.
+
+Rotation is compared on the shortest arc: 359 to 1 degrees is a two-degree move, not a near-full spin the wrong way.
+
+READ THE RESULT: 'entered' are items that appeared during the change and were given an entrance rather than popping in. 'left' are items that went away — they cannot be animated out, because they are already gone. Remove things AFTER the flip, not before.
+
+EXAMPLE:
+{ "action": "apply", "duration": 0.6, "easing": "easeInOut", "stagger": { "each": 0.05, "from": "center" } }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['record', 'apply'],
+                    description: "'record' before the change, 'apply' after it (default: record)",
+                },
+                itemIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'record: which items to capture (defaults to everything on the item layer)',
+                },
+                duration: { type: 'number', description: 'apply: seconds the transition runs' },
+                easing: { type: 'string', description: 'apply: named easing for the generated keyframes' },
+                enter: { type: 'string', description: 'apply: entrance preset for items that appeared during the change' },
+                stagger: {
+                    type: 'object',
+                    properties: {
+                        each: { type: 'number', description: 'Seconds between neighbours' },
+                        amount: { type: 'number', description: 'Total seconds for the whole run — overrides each' },
+                        from: {
+                            anyOf: [
+                                { type: 'string', enum: ['start', 'end', 'center', 'edges', 'random'] },
+                                { type: 'number' },
+                                { type: 'array', items: { type: 'number' } },
+                            ],
+                            description: 'Named origin, an item index, or [fx, fy] fractions for a grid',
+                        },
+                        grid: { type: 'array', items: { type: 'number' }, description: '[rows, columns]' },
+                        axis: { type: 'string', enum: ['x', 'y'], description: 'Restrict a grid stagger to one axis' },
+                        ease: {
+                            type: 'string',
+                            enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'easeInCubic', 'easeOutCubic'],
+                            description: 'Curve that distributes the START TIMES',
+                        },
+                        seed: { type: 'number', description: 'Seed for the random origin' },
+                    },
+                    description: "apply: stagger the transition across the items, in the items' own order",
+                },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_scene_graph',
+        annotations: {
+            title: 'Scene Graph (Interactive Stories / Quizzes)',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Create an interactive multi-node story or quiz card graph. Compiles cards, answer buttons, click-to-event routing, exclusive-group mutex visibility, and scoring into native items and relations.
+
+ACTIONS:
+- create (default): build the graph on the canvas.
+- validate: run the same structural check WITHOUT drawing anything. Returns errors, warnings, the nodes reachable from start, and any cycles. Cheap — use it on a graph you generated before committing a canvas full of cards to it.
+
+HOW IT WORKS:
+1. Provide a graph with nodes and choices (start node, question cards with answers pointing to other node IDs, end cards with outcome text).
+2. The engine compiles the card stack, creates panel rectangles and styled text items, wires on_click_fire -> event -> on_event_set_active relations, and binds active card mutex state.
+3. If scoreItemId is provided, correct answers automatically wire on_event_increment to track score.
+
+TWO WAYS OUT OF A CARD: 'answers' waits for a click (a quiz). 'next' advances on its own after 'duration' seconds (a linear story beat). Every non-terminal node needs one or the other, or the player is stuck; mark outcome cards kind: 'end'.
+
+READ THE RESULT: 'failed' counts relations that did not wire. A graph can render completely and still be inert, and that count is the only thing that says so. 'cycles' reports loops — legitimate for a retry, an accidental one is a game that never ends.
+
+EXAMPLE — Interactive Quiz:
+{
+  "graph": {
+    "start": "q1",
+    "nodes": [
+      {
+        "id": "q1",
+        "prompt": "Which planet is known as the Red Planet?",
+        "answers": [
+          { "text": "Mars", "correct": true, "to": "win" },
+          { "text": "Venus", "to": "lose" }
+        ]
+      },
+      { "id": "win", "kind": "end", "text": "Correct! Mars is rich in iron oxide." },
+      { "id": "lose", "kind": "end", "text": "Not quite! Mars is the Red Planet." }
+    ]
+  },
+  "opts": {
+    "style": { "panelColor": "#1E1B4B", "textColor": "#F8FAFC", "answerColor": "#93C5FD" }
+  }
+}`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['create', 'validate'],
+                    description: "'create' builds it (default) · 'validate' checks it without drawing",
+                },
+                graph: {
+                    type: 'object',
+                    properties: {
+                        start: { type: 'string', description: 'Initial active node id' },
+                        nodes: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    id: { type: 'string', description: 'Unique node id' },
+                                    prompt: { type: 'string', description: 'Prompt text for question cards' },
+                                    text: { type: 'string', description: 'Text for message/end cards' },
+                                    kind: { type: 'string', enum: ['node', 'card', 'end'], description: "Card kind: 'node'/'card' (content) or 'end' (terminal)" },
+                                    answers: {
+                                        type: 'array',
+                                        items: {
+                                            type: 'object',
+                                            properties: {
+                                                text: { type: 'string', description: 'Answer button text' },
+                                                correct: { type: 'boolean', description: 'Is correct answer' },
+                                                to: { type: 'string', description: 'Destination node id' },
+                                            },
+                                            required: ['text', 'to'],
+                                        },
+                                        description: 'Interactive answer buttons — the card waits for a click',
+                                    },
+                                    next: { type: 'string', description: 'Unconditional destination — the card auto-advances instead of waiting for a click. Use INSTEAD of answers.' },
+                                    duration: { type: 'number', description: 'Seconds the card holds before `next` fires (default 3). Ignored without `next`.' },
+                                    outcome: { type: 'string', enum: ['win', 'lose'], description: 'Force a terminal node\u2019s outcome. Without it the engine infers it from the wording, which only works in English.' },
+                                },
+                                required: ['id'],
+                            },
+                            description: 'List of graph nodes',
+                        },
+                    },
+                    required: ['nodes'],
+                    description: 'Scene graph definition',
+                },
+                opts: {
+                    type: 'object',
+                    properties: {
+                        width: { type: 'number', description: 'Layout width' },
+                        height: { type: 'number', description: 'Layout height' },
+                        centerX: { type: 'number', description: 'Center X coordinate' },
+                        centerY: { type: 'number', description: 'Center Y coordinate' },
+                        groupName: { type: 'string', description: 'Seed / prefix for IDs' },
+                        scoreItemId: { type: 'string', description: 'Scoreboard item ID to increment on correct answers' },
+                        subject: { type: 'string', description: "Theme of the piece, folded into each card's text-effect selection (e.g. 'space exploration')" },
+                        plain: { type: 'boolean', description: 'Plain mode without entrance/text effects' },
+                        style: {
+                            type: 'object',
+                            properties: {
+                                panelColor: { type: 'string', description: 'Card panel background color' },
+                                textColor: { type: 'string', description: 'Card text color' },
+                                answerColor: { type: 'string', description: 'Answer button text color' },
+                                headlineSize: { type: 'number', description: 'Prompt font size' },
+                                bodySize: { type: 'number', description: 'Answer/body font size' },
+                            },
+                        },
+                    },
+                    description: 'Layout and styling options',
+                },
+            },
+            required: ['graph'],
+        },
+    },
     // ---------------------------------------------------------------------------
     // LAYER 4 — COMPOSITIONS: SELECTION, TRANSFORM & HISTORY TOOLS
     // ---------------------------------------------------------------------------
@@ -3464,6 +4239,11 @@ flags as a badly-composed scene, and they do not survive an artboard change.`,
         inputSchema: {
             type: 'object',
             properties: {
+                register: { type: 'string', enum: ['naive', 'playful', 'poster', 'editorial', 'technical'], description: 'Which design language. Resolves gutter, margin, hue budget and type scale together; an explicit craft still overrides it.' },
+                level: { type: 'number', description: 'Craft level 1-4 within the register: sketch, competent, refined, art-directed.' },
+                medium: { type: 'string', enum: ['vector', 'thread'], description: "What makes the marks. 'thread' stitches every closed path AFTER arranging; photographs and text cannot be stitched and return in medium.skipped with the reason. Other media are refused with their own reason rather than faked." },
+                stitch: { type: 'string', enum: ['longAndShort', 'satin', 'seed', 'stem'], description: 'Which stitch when medium is thread (default longAndShort).' },
+                stitchBudget: { type: 'number', description: 'Total marks across the composition (default 6000); the stitch scales to fit rather than the fill being cut short.' },
                 action: { type: 'string', enum: ['list_patterns', 'list_treatments', 'apply', 'set_treatment'] },
                 pattern: { type: 'string', description: 'Pattern key from list_patterns' },
                 itemIds: { type: 'array', items: { type: 'string' }, description: 'Items in slot order' },
@@ -3566,7 +4346,10 @@ Overrides are the point: an instance can differ from its master and still receiv
                 },
                 componentKey: { type: 'string', description: 'Which part of the component to override' },
                 prop: { type: 'string', description: 'Property to override, e.g. fillColor or content' },
-                value: { description: 'Override value' },
+                value: {
+                    anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }, { type: 'object' }, { type: 'array' }],
+                    description: 'Override value',
+                },
                 overrides: { type: 'object', description: 'Overrides applied at instantiate time' },
             },
             required: ['action'],
@@ -4006,6 +4789,83 @@ ACTIONS:
             required: ['action'],
         },
     },
+    {
+        name: 'pinepaper_query_capabilities',
+        annotations: {
+            title: 'Query Capabilities',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Discover and match capabilities across the engine — text styles, character-level text effects, generators, vertex deforms, and behavioral relations.
+
+ACTIONS:
+- list: List all available capabilities or filter by kind (style, effect, generator, deform, relation, etc.).
+- choose: Mood- and context-weighted recommendation based on subject/prompt words and target feeling.
+- coverage: Report total indexable and describable capabilities across categories.
+- find: Direct lookup of a capability by key to inspect its description and how to apply it (applyWith).
+
+MOOD VOCABULARY FOR CHOOSE:
+- reveal: resolve, reveal, appear, emerge, decode, decrypt, unscramble, form, assemble
+- triumphant: burst, launch, firework, bloom, spark, explode, shine, glow, celebrate, rise
+- failure: crumble, fall, collapse, burn, decay, dissolve, break, shatter, sink, error
+- calm: drift, float, gentle, slow, settle, fade, wave, ripple, pour
+- technical: binary, matrix, grid, scan, code, digital, circuit, data, print, terminal
+- energetic: bounce, swarm, spray, shoot, fast, rapid, scatter, slam, volley
+
+EXAMPLE — Choose effect for a victory card:
+{
+  "action": "choose",
+  "kind": "effect",
+  "mood": "triumphant",
+  "subject": "celebrate correct answer",
+  "seed": "quiz_q1"
+}`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'choose', 'coverage', 'find'],
+                    description: 'Query mode: list, choose, coverage, or find (default: list)',
+                },
+                kind: {
+                    anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
+                    description: 'Filter by capability kind (style, effect, deform, entrance, animation, generator, collage, palette, mask, cutout, relation)',
+                },
+                mood: {
+                    anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
+                    description: "Target feeling for choose: reveal, triumphant, failure, calm, technical, energetic",
+                },
+                subject: {
+                    type: 'string',
+                    description: 'Contextual prompt/subject text to score against capability definitions',
+                },
+                avoid: {
+                    anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
+                    description: 'Mood keys to penalize — only the six vocabulary keys above are matched, arbitrary words are ignored',
+                },
+                seed: {
+                    type: 'string',
+                    description: 'Deterministic seed string for reproducible selection',
+                },
+                key: {
+                    type: 'string',
+                    description: 'Capability key to look up (for find action)',
+                },
+                exclude: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Keys to exclude from choose recommendation',
+                },
+                warm: {
+                    type: 'boolean',
+                    description: 'Load the lazy registries before answering (default true). Generators and the rigging/blending/deform relation rules only exist once touched, so a cold answer omits them — pass false only to cheaply re-read what is already resident.',
+                },
+            },
+        },
+    },
     // ---------------------------------------------------------------------------
     // DEFORMATION, SPRITE SHEETS, INTERACTION
     // ---------------------------------------------------------------------------
@@ -4428,6 +5288,10 @@ RETURNS:
         inputSchema: {
             type: 'object',
             properties: {
+                id: {
+                    type: 'string',
+                    description: 'Stable ID for the connector. Assign your own and reuse it as `connectorId` in pinepaper_update_connector / pinepaper_remove_connector — creation does not return an ID you can rely on. Without one the engine mints a timestamp-based ID that no caller can predict.',
+                },
                 sourceItemId: {
                     type: 'string',
                     description: 'Registry ID of the source item (where arrow starts)',
@@ -4521,6 +5385,10 @@ Same as pinepaper_connect: routing, lineColor, lineWidth, lineStyle, headStyle,
         inputSchema: {
             type: 'object',
             properties: {
+                id: {
+                    type: 'string',
+                    description: 'Stable ID for the connector. Assign your own and reuse it as `connectorId` in pinepaper_update_connector / pinepaper_remove_connector — creation does not return an ID you can rely on. Without one the engine mints a timestamp-based ID that no caller can predict.',
+                },
                 sourceItemId: {
                     type: 'string',
                     description: 'Registry ID of the source item',
@@ -5554,7 +6422,7 @@ USE WHEN:
 - Celebration effects (confetti)
 - Enhancing visual impact (ripple, glow, electric)
 
-EFFECTS (15 particle + 3 shader auras):
+EFFECTS (15 particle + 7 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)
@@ -5575,6 +6443,10 @@ SHADER AURAS (WebGL2, silhouette-clipped — same tool, routed to the aura syste
 - 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
+- electric_arc: Branching discharge filaments with a hot core and inverse-square bloom. Stepped flicker, not a sine — a stroke is a train of return strokes, which reads far more electric than a smooth pulse.
+- vortex: The bright band is a RING, not a disc — condensation tracks the steepest pressure gradient, so the core is hollow, and differential rotation shears the field rather than spinning one picture round.
+- rain_veil: Drifting sheets of falling rain across the silhouette.
+- caustics: Refracted light patterns, as through moving water.
 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:
@@ -5587,7 +6459,7 @@ EXAMPLE — gold liquid-metal aura outside a logo:
                 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', 'heatmap', 'liquid_metal', 'gem_smoke'],
+                    enum: ['sparkle', 'blast', 'smoke', 'fire', 'rain', 'snow', 'confetti', 'ripple', 'glow', 'electric', 'bubbles', 'dust', 'fireflies', 'shockwave', 'trail', 'heatmap', 'liquid_metal', 'gem_smoke', 'electric_arc', 'vortex', 'rain_veil', 'caustics'],
                     description: 'Type of effect',
                 },
                 params: {
@@ -6347,7 +7219,7 @@ EXAMPLE — Animated sky scene with timed reveals:
                             // Loop animation
                             animationType: {
                                 type: 'string',
-                                enum: ['pulse', 'rotate', 'bounce', 'fade', 'wobble', 'slide', 'typewriter'],
+                                enum: ['bounce', 'breathe', 'fade', 'glow', 'jelly', 'path', 'pulse', 'rotate', 'scrollDown', 'scrollLeft', 'scrollRight', 'scrollUp', 'shake', 'slideLeftRight', 'slideUpDown', 'swing', 'typewriter', 'wobble'],
                                 description: 'For animate: loop animation type',
                             },
                             animationOptions: { type: 'object', description: 'For animate: {speed, amplitude, direction}' },
@@ -6371,7 +7243,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', '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'],
+                                enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'anchored_in_world', 'spring_follow', 'repels', 'wiggle', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'construction_reveal', 'triggers_animation', 'syncs_with', 'tours', 'synced_to_audio', 'expresses', 'camera_follows', 'camera_animates', 'is_midpoint_of', 'lies_on_line', 'is_centroid_of', 'is_circumcenter_of', 'concentric_with', 'driven_by', 'time_expression', 'on_click_fire', 'on_pointer_enter_fire', 'on_pointer_exit_fire', 'on_key_fire', 'on_event_fire_after', 'on_event_fire_if', 'on_event_add_relation', 'on_event_remove_relation', 'on_event_set_color', 'on_event_set_property', 'on_event_set_property_from_template', 'on_event_set_visibility', 'on_event_set_active', 'on_event_set_data', 'on_event_increment', 'on_event_toggle', 'on_event_store_set', 'on_event_store_increment', 'on_enter_set_color', 'on_enter_set_property', 'on_enter_set_property_from_template', 'on_enter_set_visibility', 'on_enter_set_data', 'on_enter_increment', 'on_enter_toggle', 'on_exit_set_color', 'on_exit_set_property', 'on_exit_set_property_from_template', 'on_exit_set_visibility', 'on_exit_set_data', 'on_exit_increment', 'on_exit_toggle', 'exclusive_group', 'menubar_group', 'restores_from', 'on_top_of', 'below', 'beside', 'inside', 'centered_on', 'aligned_with', 'part_of', 'connects_to', 'attached_to_tail', 'head_points_to'],
                                 description: 'For relation: type',
                             },
                             relationOptions: { type: 'object', description: 'For relation: options' },
@@ -6386,7 +7258,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', 'heatmap', 'liquid_metal', 'gem_smoke'],
+                                enum: ['sparkle', 'blast', 'smoke', 'fire', 'rain', 'snow', 'confetti', 'ripple', 'glow', 'electric', 'bubbles', 'dust', 'fireflies', 'shockwave', 'trail', 'heatmap', 'liquid_metal', 'gem_smoke', 'electric_arc', 'vortex', 'rain_veil', 'caustics'],
                                 description: 'For apply_effect: effect type',
                             },
                             effectParams: { type: 'object', description: 'For apply_effect: parameters' },