@pinepaper.studio/mcp-server 1.6.5 → 1.6.7

package/dist/types/schemas.js

@@ -98,6 +98,18 @@ export const ItemTypeSchema = z.enum([
     'diamond',
     'arrow',
     'heart',
+    // RENDER-TIME SURFACES. These two are not Paper items and never enter the
+    // scene tree: they are drawn per pixel by the cloud rasterizer, straight from
+    // the scene document. They are here because a capability nobody can name is a
+    // capability nobody has — the cloud has drawn shaders and fields for months
+    // and no tool has ever offered them, so the only way to reach one was to
+    // hand-write a scene file.
+    //
+    // In the browser they degrade to a flat plate of their own colour (see
+    // generateCreateItemCode) so a composition built with one still reads
+    // locally; the shaded surface appears in a cloud render.
+    'shader',
+    'field',
 ]);
 // Text item properties
 export const TextPropertiesSchema = z.object({
@@ -182,14 +194,32 @@ export const ArcPropertiesSchema = z.object({
 // =============================================================================
 // ANIMATION TYPES
 // =============================================================================
+// The loop animations the engine's driver can actually run.
+//
+// Pinned to the engine by animation-type-parity.test.ts. It offered 'slide',
+// which has NEVER existed — the real ones are slideLeftRight and slideUpDown.
+// The engine stored the unknown value and the driver's switch fell through, so
+// the item sat still while its data claimed a slide, and nothing anywhere said
+// so. It also hid twelve types that do work.
 export const SimpleAnimationTypeSchema = z.enum([
-    'pulse',
-    'rotate',
     'bounce',
+    'breathe',
     'fade',
-    'wobble',
-    'slide',
+    'glow',
+    'jelly',
+    'path',
+    'pulse',
+    'rotate',
+    'scrollDown',
+    'scrollLeft',
+    'scrollRight',
+    'scrollUp',
+    'shake',
+    'slideLeftRight',
+    'slideUpDown',
+    'swing',
     'typewriter',
+    'wobble',
 ]).describe('Simple loop animation type');
 // Keyframe schema
 export const KeyframeSchema = z.object({
@@ -200,7 +230,20 @@ export const KeyframeSchema = z.object({
 // =============================================================================
 // RELATION TYPES
 // =============================================================================
+// The relation vocabulary the engine can actually run.
+//
+// Held in step with the engine by relation-parity.test.ts, against a fixture of
+// the registry's own map. This list is a hard gate: a name missing from it is
+// REJECTED at validation, so for 95 live relations the engine could do it and
+// no agent could name it — and for a model those are the same condition. The
+// whole interactive vocabulary sat on the wrong side of that line.
+//
+// Relations a dedicated tool emits (deform_*, effect_*, geo_*, bone_*, …) are
+// deliberately absent: the agent authors those THROUGH that tool, and a second
+// name here would be a worse way to do the same thing. The test file holds that
+// exclusion list, with the reason.
 export const RelationTypeSchema = z.enum([
+    // --- Motion, spatial and transform ---
     'orbits',
     'follows',
     'attached_to',
@@ -209,61 +252,99 @@ export const RelationTypeSchema = z.enum([
     'mirrors',
     'parallax',
     'bounds_to',
+    'anchored_in_world',
+    'spring_follow',
+    'repels',
+    'wiggle',
+    // --- Animation and sequencing ---
     'animates',
-    // Manim-inspired animation relations
     'grows_from',
     'staggered_with',
     'indicates',
     'circumscribes',
     'wave_through',
-    'camera_follows',
-    'camera_animates',
     'morphs_to',
-    // Pair-by-index group morph; same call shape works for any two paper.Groups
     'group_morphs_to',
-    // Self-relation; item moves along a custom-drawn path stored in params
     'moves_along_path',
-    // Geometric construction constraints (Layer 2) — the source is RE-DERIVED each
-    // frame from its anchor item(s), so dragging an anchor updates it live
-    // (GeoGebra-style). Anchor A is the relation target; extra anchors ride in params.
-    'is_midpoint_of', // source = midpoint(target, params.other)
-    'lies_on_line', // source on line target→params.other at fraction params.t
-    'is_centroid_of', // source = centroid(target, ...params.others)
-    'is_circumcenter_of', // source = circumcenter(target, params.other1, params.other2)
-    'concentric_with', // source shares the target's center
-    'construction_reveal', // self-relation: opacity 0→1 at params.revealAt over params.fadeIn (timeline-driven)
-    // Procedural / deterministic property binding (Expression IR — FxTool S10 G1).
-    // params.signal:true routes through the pure, seed/frame-deterministic signal
-    // interpreter (replay-stable), else the per-frame compute fallback runs.
-    'driven_by', // source property = target property * multiplier + offset (+clamp); drives color/stroke/opacity/scale/pos. Needs a target.
-    'time_expression', // self-relation: source property driven by a math expression f(t, v) — t=time, v=params.baseValue
-    // Event-driven scene chains (FxTool S11). The source is a pp:event (make one
-    // with pinepaper_event); firing it runs these reactions. on_event_fire_after
-    // chains events over canvas/wall time; on_event_add_relation mutates the graph
-    // (the scene evolves itself). Kick a chain off with pinepaper_event pulse.
-    'on_event_fire_after', // event→event: when source fires, pulse target after params.delay (timeline: wall|canvas)
-    'on_event_add_relation', // event→item: add params.type relation from item to params.target when the event fires
-    'on_event_remove_relation', // event→item: remove params.type relation from item to params.target
-    'on_event_set_color', // event→item: set fill/stroke to params.color
-    'on_event_set_property', // event→item: set item[params.property] = params.value
-    'on_event_set_visibility', // event→item: show/hide (params.visible, default true)
-    // Structural layout relations (FxTool S12-E1) — STATIC composition as graph edges.
-    // Placement is derived from the TARGET'S BOUNDS and re-derived each frame, so
-    // dragging or resizing the target moves the dependent live. Use these instead of
-    // hardcoding x/y when the intent is "on", "under", "next to", "inside".
-    'on_top_of', // source bottom edge rests on target top edge (params: gap, align, overhang)
-    'below', // source top edge rests on target bottom edge (params: gap, align, overhang)
-    'beside', // source flanks the target left/right (params: side, gap, align)
-    'inside', // source anchored inside the target's bounds (params: anchor, padding)
-    'centered_on', // source center = target center + (offsetX, offsetY)
-    'aligned_with', // source matches target on ONE axis only — the other stays free (params: axis, offset)
+    'construction_reveal',
+    'triggers_animation',
+    'syncs_with',
+    'tours',
+    'synced_to_audio',
+    'expresses',
+    // --- Camera ---
+    'camera_follows',
+    'camera_animates',
+    // --- Geometry ---
+    'is_midpoint_of',
+    'lies_on_line',
+    'is_centroid_of',
+    'is_circumcenter_of',
+    'concentric_with',
+    // --- Procedural / expression ---
+    'driven_by',
+    'time_expression',
+    // --- Input triggers — a user action FIRES an event channel ---
+    'on_click_fire',
+    'on_pointer_enter_fire',
+    'on_pointer_exit_fire',
+    'on_key_fire',
+    // --- Event reactions — an event fires and something happens ---
+    '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',
+    // --- Proximity — the pointer entering or leaving an item ---
+    '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 state — at most one member active ---
+    'exclusive_group',
+    'menubar_group',
+    'restores_from',
+    // --- Structural and diagram ---
+    'on_top_of',
+    'below',
+    'beside',
+    'inside',
+    'centered_on',
+    'aligned_with',
+    'part_of',
+    'connects_to',
+    'attached_to_tail',
+    'head_points_to',
 ]).describe('Type of relationship between items');
 // Relation parameter schemas
 export const OrbitsParamsSchema = z.object({
     radius: z.number().optional().default(100).describe('Orbit radius'),
     speed: z.number().optional().default(1).describe('Rotation speed'),
     direction: z.enum(['clockwise', 'counterclockwise']).optional().default('counterclockwise'),
-    phase: z.number().optional().default(0).describe('Starting angle offset'),
+    // The one angle in the relation vocabulary that is NOT degrees. Kept because
+    // changing it outright would silently re-time every scene that sets it — a 57x
+    // error of exactly the kind the "angles are DEGREES" convention exists to stop.
+    phase: z.number().optional().default(0).describe('Starting angle in RADIANS — the documented exception to the degrees convention, kept for existing scenes. Prefer phaseDegrees.'),
+    phaseDegrees: z.number().optional().describe('Starting angle in DEGREES, matching the convention every other angle uses. Takes precedence over phase when set.'),
 });
 export const FollowsParamsSchema = z.object({
     offset: PointArraySchema.optional().default([0, 0]).describe('Position offset from target'),
@@ -308,8 +389,19 @@ export const GrowsFromParamsSchema = z.object({
 });
 export const StaggeredWithParamsSchema = z.object({
     index: z.number().describe('0-based position in the stagger sequence'),
-    stagger: z.number().optional().default(0.1).describe('Delay between items in seconds'),
-    effect: z.enum(['fadeIn', 'fadeOut', 'growIn', 'slideIn', 'popIn']).optional().default('fadeIn').describe('Stagger effect type'),
+    stagger: z.number().optional().default(0.1).describe('Seconds between neighbours. Ignored when amount is set.'),
+    // Shape params (pp:Stagger). The plain index x stagger path is taken first and
+    // unchanged; these only engage when a shape is actually asked for AND count is
+    // known — there is no "end" to measure from without it, so an origin like
+    // 'center' would have nothing to mean.
+    count: z.number().optional().describe('How many items are in the stagger. Required by any origin other than "start".'),
+    from: z.enum(['start', 'end', 'center', 'edges', 'random']).optional().default('start').describe('Where the stagger begins — what turns a delay into a direction. Requires count.'),
+    amount: z.number().optional().describe('Total seconds for the WHOLE sequence, split among the items. Overrides stagger.'),
+    grid: z.string().optional().describe('Rows and columns as "rows,cols" (or "auto") for a 2D stagger. Requires count.'),
+    axis: z.enum(['x', 'y']).optional().describe('Restrict a grid stagger to one axis.'),
+    distributeEase: z.enum(['linear', 'easeIn', 'easeOut', 'easeInOut', 'easeInCubic', 'easeOutCubic']).optional().default('linear')
+        .describe("Curve that distributes the START TIMES — not the items' own animation curve."),
+    effect: z.enum(['fadeIn', 'fadeOut', 'growIn', 'slideIn', 'popIn', 'typewriter']).optional().default('fadeIn').describe('Stagger effect type'),
 });
 export const IndicatesParamsSchema = z.object({
     scale: z.number().optional().default(1.3).describe('Max scale during indication'),
@@ -856,6 +948,10 @@ export const EffectTypeSchema = z.enum([
     'heatmap',
     'liquid_metal',
     'gem_smoke',
+    'electric_arc',
+    'vortex',
+    'rain_veil',
+    'caustics',
 ]).describe('Visual effect type (particle effects + shader auras)');
 export const SparkleParamsSchema = z.object({
     color: ColorSchema.optional().default('#fbbf24').describe('Sparkle color'),
@@ -923,7 +1019,7 @@ export const CreateItemInputSchema = z.object({
     itemType: ItemTypeSchema,
     position: PositionSchema.optional().default({ x: 400, y: 300 }),
     properties: z.record(z.unknown()).optional().default({}),
-    animationType: z.string().optional().describe('Inline animation to apply on creation. Loop presets (pulse, rotate, bounce, fade, wobble, slide, typewriter) or "keyframe" with keyframes array. Equivalent to a follow-up pinepaper_animate / pinepaper_keyframe_animate call.'),
+    animationType: z.string().optional().describe('Inline animation to apply on creation. Loop presets (bounce, breathe, fade, glow, jelly, path, pulse, rotate, scrollDown, scrollLeft, scrollRight, scrollUp, shake, slideLeftRight, slideUpDown, swing, typewriter, wobble) or "keyframe" with keyframes array. Equivalent to a follow-up pinepaper_animate / pinepaper_keyframe_animate call.'),
     animationSpeed: z.number().optional().describe('Speed multiplier for loop animations (default: 1.0). Ignored when animationType is "keyframe".'),
     animationIntensity: z.number().optional().describe('Loop animation amplitude (0.1 = ±10%, default 0.15). Drives pulse/wobble/bounce/breathe amplitude; honored by SVG/SMIL/widget export.'),
     animationDelay: z.number().optional().describe('Loop animation start delay in seconds.'),
@@ -1007,6 +1103,28 @@ export const KeyframeAnimateInputSchema = z.object({
     clipInPoint: z.number().optional().describe('Skip the first N seconds of keyframe data — clip head trim.'),
     clipOutPoint: z.number().optional().describe('Stop at N seconds into the keyframe data — clip tail trim. Default: lastKeyframeTime.'),
 });
+// Motion Capture (BVH)
+//
+// FxTool exposes two distinct operations and the difference is the whole point:
+//   importBVH   builds a NEW skeleton shaped like the capture file
+//   retargetBVH drives an EXISTING rig — proportions stay yours, only MOTION comes from the clip
+// Angles transfer as bind-pose deltas (target.rest + (source(t) - source(rest))), so a T-posed CMU
+// rest is not slammed onto a rig with a relaxed stance. Bone matching carries the BVH child-joint
+// shift ("LeftLeg" is the thigh); anything unmatched is REPORTED, never silently half-driven.
+export const ImportMotionCaptureInputSchema = z.object({
+    bvh: z.string().describe('BVH clip text (CMU / Mixamo export). Required.'),
+    mode: z.enum(['import', 'retarget']).optional().default('import')
+        .describe("'import' builds a new skeleton from the file; 'retarget' drives an existing rig named by skeletonId — use retarget when the character already exists, so its proportions are preserved and only the motion is taken from the capture."),
+    skeletonId: z.string().optional()
+        .describe("Rig to drive. REQUIRED when mode='retarget'; ignored for 'import'."),
+    fps: z.number().optional().describe('Pose sampling rate. CMU records at 120fps and nobody wants 120 poses a second; 0 keeps every frame. Default 15.'),
+    height: z.number().optional().describe('Skeleton height on the canvas in px (import mode). Default 320.'),
+    position: z.object({ x: z.number(), y: z.number() }).optional()
+        .describe('Where the ROOT joint stands (import mode). Defaults to canvas centre, 70% down.'),
+    name: z.string().optional().describe('Name for the created skeleton (import mode).'),
+    boneMap: z.record(z.string(), z.string()).optional()
+        .describe('BVH edge name → this rig\'s bone name. Overrides the alias table when a clip uses non-standard joint names; check unmatchedSource/unmatchedTarget in the result to see what needs mapping.'),
+});
 // Execute Generator
 //
 // Region (added FxTool c81781c): when set, the generator draws into a clipped
@@ -1042,7 +1160,13 @@ export const GetItemsInputSchema = z.object({
 });
 // Play Timeline
 export const PlayTimelineInputSchema = z.object({
-    action: z.enum(['play', 'pause', 'stop', 'seek']),
+    action: z.enum([
+        'play', 'pause', 'stop', 'seek',
+        // pp:TimeScale — the rate the scene clock runs at.
+        'set_time_scale', 'get_time_scale',
+        // pp:InputDrivenPlayback — progress driven by an input instead of a clock.
+        'get_progress', 'set_progress', 'bind_scroll', 'unbind_scroll', 'list_scrub_anchors',
+    ]),
     duration: z.number().optional().describe('Duration for play action'),
     loop: z.boolean().optional(),
     time: z.number().optional().describe('Time to seek to'),
@@ -1050,6 +1174,22 @@ export const PlayTimelineInputSchema = z.object({
         .boolean()
         .optional()
         .describe('For seek: evaluate the scene at the exact time via app.sceneAt(t) — ticks keyframes + relations + generators deterministically (same t → same frame), not just the keyframe state. Use before a screenshot for a reproducible frame.'),
+    // Deliberately unclamped: 0 freezes the clock without stopping playback, and a
+    // negative rate runs the scene backwards. Both are things the engine supports
+    // and a min(0) would quietly forbid.
+    rate: z.number().optional()
+        .describe('set_time_scale: 1 is real time, 0.5 half speed, 0 freezes without stopping, negative runs backwards. Export is unaffected — a scene watched at 0.5x still exports its real duration.'),
+    progress: z.number().min(0).max(1).optional()
+        .describe('set_progress: how far through the timeline, 0..1 — the unit a scrubber or a progress bar actually has.'),
+    scroll: z.object({
+        elementId: z.string().optional().describe('DOM id of the element to track (defaults to the canvas)'),
+        start: z.string().optional().describe("Anchor where the range begins, e.g. 'top bottom' (the moment the element appears). See list_scrub_anchors."),
+        end: z.string().optional().describe("Anchor where the range ends, e.g. 'bottom top' (the moment it is gone)."),
+        scrub: z.number().min(0).optional()
+            .describe('Seconds of smoothing — the played position chases the scroll instead of snapping to it (default 0.3). 0 snaps.'),
+        range: z.array(z.number()).length(2).optional()
+            .describe('[from, to] in seconds — drive only a sub-range of the timeline instead of the whole thing.'),
+    }).optional().describe('bind_scroll options'),
 });
 // Canvas Control
 export const SetBackgroundColorInputSchema = z.object({
@@ -1187,7 +1327,7 @@ export const SceneAnimationSchema = z.object({
     /** Reference name of the item to animate */
     target: z.string().describe('Name of the item to animate'),
     /** Type of animation */
-    type: z.enum(['pulse', 'rotate', 'bounce', 'fade', 'wobble', 'slide', 'typewriter']),
+    type: z.enum(['bounce', 'breathe', 'fade', 'glow', 'jelly', 'path', 'pulse', 'rotate', 'scrollDown', 'scrollLeft', 'scrollRight', 'scrollUp', 'shake', 'slideLeftRight', 'slideUpDown', 'swing', 'typewriter', 'wobble']),
     /** Animation speed (default: 1.0) */
     speed: z.number().optional(),
     /** Animation parameters */
@@ -1346,6 +1486,7 @@ export const CreateDiagramShapeInputSchema = z.object({
  * Connect items input
  */
 export const ConnectInputSchema = z.object({
+    id: z.string().optional().describe('Stable connector ID. Assign your own and reuse it as `connectorId` in update/remove — the engine otherwise mints a Date.now()-based ID no caller can predict'),
     sourceItemId: z.string().describe('Registry ID of source item'),
     targetItemId: z.string().describe('Registry ID of target item'),
     routing: ConnectorRoutingSchema.optional().default('orthogonal'),
@@ -1363,6 +1504,7 @@ export const ConnectInputSchema = z.object({
  * Connect specific ports input
  */
 export const ConnectPortsInputSchema = z.object({
+    id: z.string().optional().describe('Stable connector ID. Assign your own and reuse it as `connectorId` in update/remove — the engine otherwise mints a Date.now()-based ID no caller can predict'),
     sourceItemId: z.string().describe('Registry ID of source item'),
     sourcePort: PortPositionSchema.describe('Port position on source'),
     targetItemId: z.string().describe('Registry ID of target item'),
@@ -2208,6 +2350,29 @@ export const QueryOntologyInputSchema = z.object({
     category: z.string().optional(),
     includeAbstract: z.boolean().optional().default(false),
 });
+// Capabilities query schema: discover and match capabilities across text styles, text effects, generators, deforms, relations, etc.
+export const QueryCapabilitiesInputSchema = z.object({
+    action: z.enum(['list', 'choose', 'coverage', 'find']).default('list')
+        .describe("'list' (all capabilities or filtered by kind) · 'choose' (context/mood-weighted recommendation) · 'coverage' (breakdown of indexable capabilities) · 'find' (lookup by key)"),
+    kind: z.union([
+        z.string(),
+        z.array(z.string()),
+    ]).optional().describe("Filter by capability kind: 'style'|'effect'|'deform'|'entrance'|'animation'|'generator'|'collage'|'palette'|'mask'|'cutout'|'relation'"),
+    mood: z.union([
+        z.string(),
+        z.array(z.string()),
+    ]).optional().describe("For choose: target feeling ('reveal'|'triumphant'|'failure'|'calm'|'technical'|'energetic')"),
+    subject: z.string().optional().describe('For choose: contextual subject keywords / prompt text to score against capability definitions'),
+    avoid: z.union([
+        z.string(),
+        z.array(z.string()),
+    ]).optional().describe('For choose: mood terms or feelings to penalize'),
+    seed: z.string().optional().describe('For choose: deterministic seed string for reproducible selection'),
+    key: z.string().optional().describe('For find: exact capability key to look up'),
+    exclude: z.array(z.string()).optional().describe('For choose: list of capability keys to exclude from recommendation'),
+    warm: z.boolean().optional()
+        .describe('Load the lazy registries before answering (default true). The generator registry and the rigging/blending/deform relation rules only exist once touched, so a cold answer omits them — pass false only to re-read what is already resident, cheaply.'),
+});
 // =============================================================================
 // SCENE MANAGEMENT SCHEMAS
 // =============================================================================
@@ -2232,6 +2397,175 @@ export const ScenePlaybackInputSchema = z.object({
     index: z.number().optional(),
 });
 // =============================================================================
+// RELATIVE TIMING, STAGGERS, FLIP  (GSAP's vocabulary, PinePaper's engine)
+// =============================================================================
+// pp:TimelinePosition — saying WHEN relative to something else.
+//
+// The position spec is a number or one of the string forms; it stays loose on
+// purpose, because the grammar is open ("intro+=0.5" names a caller's label) and
+// an enum here could only ever be a stale subset of it. list_forms is the
+// discoverable list.
+export const SequenceInputSchema = z.object({
+    action: z.enum(['place', 'resolve', 'list_forms']).default('place')
+        .describe("'place' threads a run of clips, each resolved against the ones before it · 'resolve' answers a single position · 'list_forms' returns the accepted grammar with what each form means"),
+    clips: z.array(z.object({
+        id: z.string().optional().describe('Your own name for the clip — echoed back on the placement'),
+        duration: z.number().min(0).describe('How long the clip runs, in seconds'),
+        position: z.union([z.number(), z.string()]).optional()
+            .describe('Where it starts. Omit to append at the end of the timeline so far.'),
+        label: z.string().optional().describe('Name this moment so later clips can position against it. A label marks where the clip STARTS.'),
+    })).optional().describe('place: the run of clips, in order'),
+    position: z.union([z.number(), z.string()]).optional().describe('resolve: the single position spec to resolve'),
+    context: z.object({
+        timelineEnd: z.number().optional().describe('Where the timeline currently ends — what a bare "+=1" counts from'),
+        prevStart: z.number().optional().describe('Start of the most recently added clip — what "<" means'),
+        prevEnd: z.number().optional().describe('End of the most recently added clip — what ">" means'),
+        insertDuration: z.number().optional().describe('Duration of the clip being placed — the basis for a "+=25%" / "-=25%" percentage'),
+    }).optional().describe('resolve: what the spec is measured against'),
+    labels: z.record(z.string(), z.number()).optional().describe('Named moments in seconds, addressable as "name" or "name+=0.5"'),
+    startAt: z.number().optional().describe('place: where the run begins (default 0)'),
+});
+// pp:Stagger — the shape of a delay across many items.
+const StaggerOptsSchema = z.object({
+    // `each` and `amount` are 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.
+    each: z.number().min(0).optional().describe('Seconds between neighbours (default 0.1). More items ⇒ a longer sequence.'),
+    amount: z.number().min(0).optional().describe('Total seconds for the WHOLE run, split among the items. Overrides each — more items ⇒ they crowd together.'),
+    from: z.union([
+        z.enum(['start', 'end', 'center', 'edges', 'random']),
+        z.number(),
+        z.array(z.number()).length(2),
+    ]).optional().describe("Where the stagger begins: a named origin, an item index, or [fx, fy] fractions for a grid ([0.5, 0.5] is the centre)."),
+    grid: z.array(z.number()).length(2).optional().describe('[rows, columns] for a 2D stagger. Items are read row-major.'),
+    axis: z.enum(['x', 'y']).optional().describe('Restrict a grid stagger to one axis.'),
+    ease: z.enum(['linear', 'easeIn', 'easeOut', 'easeInOut', 'easeInCubic', 'easeOutCubic']).optional()
+        .describe("Curve that distributes the START TIMES — not the items' own animation curve."),
+    seed: z.number().optional().describe("from: 'random' — same seed, same shuffle (default 1)."),
+});
+export const StaggerInputSchema = z.object({
+    action: z.enum(['apply', 'preview', 'list_origins']).default('apply')
+        .describe("'apply' writes the delays onto real items · 'preview' returns the delays for a count without touching the canvas · 'list_origins' names the origins"),
+    itemIds: z.array(z.string()).optional().describe('apply: registry ids IN THE ORDER the stagger should follow (row-major for a grid)'),
+    count: z.number().int().min(0).optional().describe('preview: how many items to compute delays for'),
+    opts: StaggerOptsSchema.optional().describe('Shape of the stagger'),
+});
+// pp:Flip — a transition DERIVED from a change rather than described.
+export const FlipInputSchema = z.object({
+    action: z.enum(['record', 'apply']).default('record')
+        .describe("'record' captures where things are NOW · 'apply' animates from that record to wherever they have since been moved"),
+    itemIds: z.array(z.string()).optional()
+        .describe('record: which items to capture (defaults to everything on the item layer, which is the usual case for a re-layout)'),
+    duration: z.number().min(0).optional().describe('apply: seconds the transition runs (engine default)'),
+    easing: z.string().optional().describe('apply: named easing for the generated keyframes'),
+    enter: z.string().optional().describe('apply: entrance preset for items that appeared during the change, so they animate in rather than popping'),
+    stagger: StaggerOptsSchema.optional().describe("apply: stagger the transition across the items, in the items' own order"),
+});
+// Scene graph: interactive multi-node story/quiz state graphs (cards, answers, mutex, event wiring)
+//
+// The node and opts fields below mirror what the engine's compiler actually
+// reads (js/core/SceneGraph.js). zod strips unknown keys, so a field missing
+// here is not "passed through" — it is silently dropped on the way to an engine
+// that would have honoured it. `next`, `duration`, `outcome` and `subject` were
+// each unreachable for that reason.
+const SceneGraphNodeSchema = z.object({
+    id: z.string().describe('Unique node id (e.g., "q1", "win", "lose")'),
+    prompt: z.string().optional().describe('Prompt or headline text for question cards'),
+    text: z.string().optional().describe('Text for message/end cards'),
+    kind: z.enum(['node', 'card', 'end']).optional()
+        .describe("'node'/'card' (question or content) or 'end' (terminal/outcome). Anything that is not 'end' is a card."),
+    answers: z.array(z.object({
+        text: z.string().describe('Answer button text'),
+        correct: z.boolean().optional().describe('Whether this is the correct answer (increments score when scoreItemId given)'),
+        to: z.string().min(1).describe('Destination node id when clicked'),
+    })).optional().describe('Interactive answer choices (for question cards)'),
+    next: z.string().min(1).optional()
+        .describe('Unconditional destination — a linear story beat that auto-advances instead of waiting for a click. Use INSTEAD of answers, not alongside a lone fake button.'),
+    duration: z.number().positive().optional()
+        .describe('Seconds this card holds before `next` fires (default 3). Ignored without `next`.'),
+    outcome: z.enum(['win', 'lose']).optional()
+        .describe('Force the outcome of a terminal node. Without it the engine infers win/lose from the wording, which only works in English.'),
+});
+export const SceneGraphInputSchema = z.object({
+    action: z.enum(['create', 'validate']).default('create')
+        .describe("'create' builds the graph on the canvas · 'validate' runs the same check WITHOUT drawing anything, returning errors, warnings, unreachable nodes and cycles"),
+    graph: z.object({
+        start: z.string().optional().describe('Node id of the initial active card (defaults to the first node)'),
+        nodes: z.array(SceneGraphNodeSchema).min(1).describe('Array of scene graph nodes'),
+    })
+        // Structural integrity, checked HERE because in code mode there is no engine
+        // to catch it: the snippet is handed to the caller and fails silently later.
+        // Duplicate ids in particular are invisible engine-side — `indexNodes` keys a
+        // Map by id, so the second node quietly replaces the first.
+        .superRefine((graph, ctx) => {
+        const seen = new Set();
+        graph.nodes.forEach((node, i) => {
+            if (seen.has(node.id)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['nodes', i, 'id'],
+                    message: `duplicate node id "${node.id}" — the later node silently replaces the earlier one`,
+                });
+            }
+            seen.add(node.id);
+        });
+        const has = (id) => seen.has(id);
+        if (graph.start !== undefined && !has(graph.start)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['start'],
+                message: `start node "${graph.start}" does not exist`,
+            });
+        }
+        graph.nodes.forEach((node, i) => {
+            (node.answers || []).forEach((answer, a) => {
+                if (!has(answer.to)) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ['nodes', i, 'answers', a, 'to'],
+                        message: `node "${node.id}" points at "${answer.to}", which does not exist — clicking it would do nothing`,
+                    });
+                }
+            });
+            if (node.next !== undefined && !has(node.next)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['nodes', i, 'next'],
+                    message: `node "${node.id}" advances to "${node.next}", which does not exist`,
+                });
+            }
+            // Mirrors the engine's own refusal: a non-terminal card with no edge is
+            // a dead end the player can never leave.
+            if (node.kind !== 'end' && !node.answers?.length && node.next === undefined) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['nodes', i],
+                    message: `node "${node.id}" is not terminal but has no way out — give it answers, a next, or kind: 'end'`,
+                });
+            }
+        });
+    })
+        .describe('The declarative scene graph definition'),
+    opts: z.object({
+        width: z.number().optional().describe('Layout width (defaults to view width or canvas width)'),
+        height: z.number().optional().describe('Layout height (defaults to view height or canvas height)'),
+        centerX: z.number().optional().describe('Center X position for card stack'),
+        centerY: z.number().optional().describe('Center Y position for card stack'),
+        groupName: z.string().optional().describe('Prefix / seed namespace for generated IDs and effect selection'),
+        scoreItemId: z.string().optional().describe('Optional scoreboard text item id to increment on correct answers'),
+        subject: z.string().optional()
+            .describe("Extra context folded into each card's text-effect selection — the theme of the piece, e.g. 'space exploration'."),
+        plain: z.boolean().optional().describe('Opt out of rich effects/entrances for a bare structural graph'),
+        style: z.object({
+            panelColor: z.string().optional().describe('Background panel fill color (default #1E1B4B)'),
+            textColor: z.string().optional().describe('Headline/prompt text color (default #F8FAFC)'),
+            answerColor: z.string().optional().describe('Answer text color (default #93C5FD)'),
+            headlineSize: z.number().optional().describe('Font size for headline/prompt (default 34)'),
+            bodySize: z.number().optional().describe('Font size for body/answers (default 24)'),
+        }).optional().describe('Visual styling options for generated cards and text'),
+    }).optional().describe('Layout, style, and scoring options'),
+});
+// =============================================================================
 // SELECTION, TRANSFORM & HISTORY TOOLS
 // =============================================================================
 export const SelectionInputSchema = z.object({
@@ -2364,6 +2698,24 @@ export const ComposeInputSchema = z.object({
     audio: z.string().optional(),
     /** With audio: snap to an even tempo grid instead of raw onsets. */
     grid: z.boolean().optional(),
+    /**
+     * WHICH DESIGN LANGUAGE. Resolves the craft — gutter, margin, hue budget,
+     * type scale, alignment discipline — so those move together instead of being
+     * chosen one at a time. A default, not a handcuff: an explicit `craft` still
+     * wins. naive | playful | poster | editorial | technical.
+     */
+    register: z.string().optional().describe('Design register — naive, playful, poster, editorial, technical. Sets the craft; an explicit `craft` still overrides it.'),
+    level: z.number().int().min(1).max(4).optional().describe('Craft level 1-4 WITHIN the register (sketch, competent, refined, art-directed). Climbing never widens a budget — restraint is the direction of craft.'),
+    /**
+     * WHAT MAKES THE MARKS. Only media a whole composition can be rendered in
+     * are accepted: `vector` (what composing already produces) and `thread`
+     * (needlepainting, stitched after the arrangement). The rest are refused
+     * with the medium's own reason rather than composed as flat shapes in its
+     * colours.
+     */
+    medium: z.enum(['vector', 'thread']).optional().describe("Render the composition in a medium. 'thread' stitches every closed path; photographs and text CANNOT be stitched and come back in `medium.skipped` with the reason, so read that count — a composition can render completely and be entirely unstitched."),
+    stitch: z.enum(['longAndShort', 'satin', 'seed', 'stem']).optional().describe('Which stitch, when medium is thread. Default longAndShort.'),
+    stitchBudget: z.number().int().min(200).max(20000).optional().describe('Total marks across the composition (default 6000). The stitch is scaled to fit rather than the fill being truncated — a half-stitched shape looks broken, coarser thread does not.'),
 });
 export const AudioBeatsInputSchema = z.object({
     action: z.enum(['analyze', 'animate_to_beat']),
@@ -2760,6 +3112,93 @@ export const TextStyleInputSchema = z.object({
 })
     .refine((v) => v.action !== 'apply_style' || (!!v.itemId && !!v.styleKey), { message: 'apply_style requires itemId and styleKey', path: ['styleKey'] })
     .refine((v) => v.action !== 'set_font_axes' || (!!v.itemId && !!v.axes && Object.keys(v.axes).length > 0), { message: 'set_font_axes requires itemId and at least one axis', path: ['axes'] });
+/**
+ * pinepaper_text_effect — the 37 character-level text effects
+ * (terminaltexteffects' vocabulary, reimplemented in FxTool from source).
+ *
+ * The contract that separates this from `pinepaper_text_style`, and the one
+ * thing a caller must know: this tool EXPLODES the text item into one item per
+ * character and REMOVES the original. `text_style` ADOPTS the text's registry
+ * id; this DESTROYS it. Relations, keyframes and agent handles pointing at the
+ * source id die with it — `keepSource: true` leaves the original in place if
+ * they matter.
+ *
+ * `effect` is a free string, not an enum: the engine owns the vocabulary, its
+ * own error names every valid key, and `action: 'list'` is authoritative. An
+ * enum here would pin the server to today's 37 and go stale on the 38th.
+ *
+ * The planner is pure and emits KEYFRAMES, so the result is ordinary animated
+ * items — it scrubs, survives undo/session restore, and exports through the
+ * existing MP4/SMIL/Lottie paths rather than needing a per-exporter animator.
+ */
+/**
+ * The MEDIUM axis — what makes the marks, as distinct from which design
+ * language (register) and how well executed (level).
+ *
+ * Every medium declares a fidelity, and the tool refuses an `absent` one with
+ * the reason rather than producing flat shapes in its colours. Ask
+ * `list_media` before promising a medium in prose.
+ */
+export const DesignMediumInputSchema = z.object({
+    action: z.enum(['list_media', 'resolve', 'list_stitches', 'apply_thread', 'apply_hatch', 'list_flow_fields', 'list_hatch_options'])
+        .describe("'list_media' (7 media with fidelity + limitation) · 'resolve' (can this medium be made here, and how honestly) · 'list_stitches' · 'apply_thread' (render an item in thread) · 'apply_hatch' (rule an item with hatching — value through line density) · 'list_flow_fields' · 'list_hatch_options'"),
+    medium: z.string().optional().describe("resolve: medium key — vector, thread, hatch, watercolor, ink, cutPaper, charcoal, oil, encaustic. Call list_media for the live set with each one's fidelity; the catalogue grows."),
+    itemId: z.string().optional().describe('apply_thread / apply_hatch: a closed path, compound path, or a group of them. Its own silhouette is the region and its fill is the ink colour.'),
+    stitch: z.enum(['longAndShort', 'satin', 'seed', 'stem']).optional()
+        .describe("apply_thread: default longAndShort (the needlepainting fill). 'satin' spans the shape edge to edge — right for a narrow shape, wrong for a round one. 'seed' is texture. 'stem' is an outline mark and leaves the interior bare."),
+    field: z.object({
+        kind: z.enum(['radial', 'spine', 'constant']),
+        cx: z.number().optional(), cy: z.number().optional(),
+        angle: z.number().optional(),
+        spine: z.array(PositionSchema).optional(),
+        across: z.boolean().optional(),
+    }).optional().describe("apply_thread: the direction field — the thing that makes it needlepainting rather than hatching. Default radial from the shape centre. 'spine' runs stitches along a midrib or feather shaft; 'constant' is flat hatch."),
+    stitchLen: z.number().positive().optional().describe('apply_thread: nominal stitch length px (default 18).'),
+    rowGap: z.number().positive().optional().describe('apply_thread: row spacing px. Defaults from the thread width so the rows abut; setting it wider is what makes a fill read as hatching.'),
+    variance: z.number().min(0).max(1).optional().describe('apply_thread: length jitter 0..1 (default 0.35) — the variance IS the long-and-short shading.'),
+    width: z.number().positive().optional().describe('apply_thread: thread width px (default 2).'),
+    sheen: z.boolean().optional().describe('apply_thread: draw the highlight along each stitch (default true) — thread is not matte.'),
+    color: z.string().optional().describe("apply_thread: thread colour, defaulting to the item's own fill."),
+    seed: z.number().int().optional().describe('apply_thread: PRNG seed (default 1). Same seed stitches the same way.'),
+    count: z.number().int().positive().optional().describe('apply_thread: stitch count for seed/satin.'),
+    // --- Hatching (pp: the p5.brush marks, as vector) ---
+    //
+    // `field` above is the THREAD direction field (radial/spine/constant) and is
+    // a different thing from `flowField` here (hand/curved/waves/…). Separate
+    // names because one steers stitches around a form and the other bends a
+    // ruling line the way a hand would drift; sharing a key would silently apply
+    // one where the other was meant.
+    distance: z.number().positive().optional()
+        .describe('apply_hatch: spacing between lines in px (default 6). THIS IS THE VALUE CONTROL — the same shape at 6px and 3px reads as light and dark with no change of colour.'),
+    angle: z.number().optional().describe('apply_hatch: ruling angle in DEGREES (default 45).'),
+    gradient: z.number().min(0).max(1).optional()
+        .describe('apply_hatch: 0..1 spacing growth per line (default 0, even). Non-zero makes the density fall off across the shape — a shaded ramp rather than a flat tone.'),
+    rand: z.number().min(0).max(1).optional()
+        .describe('apply_hatch: jitter as a fraction of distance (default 0) — takes the mechanical evenness off.'),
+    continuous: z.boolean().optional()
+        .describe('apply_hatch: join the lines into ONE serpentine path (default false) — a pen that never leaves the paper, and a single item instead of many.'),
+    flowField: z.enum(['hand', 'curved', 'zigzag', 'waves', 'seabed', 'spiral', 'columns']).optional()
+        .describe('apply_hatch: bend each line along a flow field. The straight scanline is the ruling; the field is what makes it read as drawn rather than printed. See list_flow_fields.'),
+    t: z.number().optional().describe('apply_hatch: flow-field time offset — advances the field without changing the seed.'),
+})
+    .refine((v) => v.action !== 'apply_thread' || !!v.itemId, { message: 'apply_thread requires itemId', path: ['itemId'] })
+    .refine((v) => v.action !== 'resolve' || !!v.medium, { message: 'resolve requires medium', path: ['medium'] })
+    .refine((v) => v.action !== 'apply_hatch' || !!v.itemId, { message: 'apply_hatch requires itemId', path: ['itemId'] });
+export const TextEffectInputSchema = z.object({
+    action: z.enum(['apply', 'list'])
+        .describe("'apply' (explode a text item into animated characters) · 'list' (the 37 effects with key/label/definition, for a picker)"),
+    itemId: z.string().optional().describe('apply: the text item to animate. Must be a text item with non-whitespace content.'),
+    effect: z.string().optional().describe("apply: effect key from 'list' (e.g. scattered, decrypt, matrix, burn, fireworks, rain, blackhole)."),
+    duration: z.number().positive().optional().describe('apply: seconds for the whole effect (default 2.5). Every effect ends AT REST, so this is the settle time.'),
+    seed: z.number().int().optional().describe('apply: PRNG seed (default 1). Same seed + same text = identical animation, so exports are reproducible.'),
+    gradient: z.boolean().optional().describe("apply: false keeps each character's authored fill. Default TRUE — the upstream effects all end by painting the block with a gradient, which is what their reference frames show."),
+    gradientStops: z.array(z.string()).optional().describe('apply: hex colors overriding the effect\'s own gradient.'),
+    gradientDirection: z.enum(['vertical', 'horizontal', 'radial', 'diagonal']).optional().describe('apply: gradient axis across the text block.'),
+    gradientSteps: z.number().int().positive().optional().describe('apply: quantization steps in the gradient ramp.'),
+    keepSource: z.boolean().optional().describe('apply: leave the original text item in place instead of removing it — the escape hatch when relations/keyframes reference its id.'),
+    options: z.record(z.string(), z.unknown()).optional().describe('apply: per-effect knobs, passed through verbatim (each of the 37 has its own). Spread FIRST, so named fields above win on collision.'),
+})
+    .refine((v) => v.action !== 'apply' || (!!v.itemId && !!v.effect), { message: 'apply requires itemId and effect', path: ['effect'] });
 /**
  * pinepaper_shatter_image — split a raster into a grid of per-tile rasters.
  * Deliberately INERT on its own: the pieces sit exactly where the picture was
@@ -2852,7 +3291,7 @@ export const World3DInputSchema = z.object({
     live: z.boolean().optional().describe('add_actor: re-rasterize the item as it animates — a rigged character PERFORMS in the world instead of standing there as a photograph of itself.'),
     pose: z.record(z.string(), z.unknown()).optional().describe('set_actor_pose: { x?, z?, angle?, … } — the setter a timeline or agent drives.'),
     camera: z.record(z.string(), z.unknown()).optional().describe("set_camera: { mode: 'follow'|'fixed'|'orbit', target?, radius?, speed?, eye?, lookAt? }."),
-    object: z.record(z.string(), z.unknown()).optional().describe('add_object: { x, z, height?, color?, y? (defaults to sitting on the terrain) }.'),
+    object: z.record(z.string(), z.unknown()).optional().describe('add_object: { x, z, height?, color?, y?, metalness?, roughness?, emissiveIntensity? } (defaults to sitting on the terrain).'),
     objectId: z.string().optional().describe('remove_object: the object id.'),
 })
     .refine((v) => v.action !== 'configure' || !!v.patch, { message: 'configure requires patch', path: ['patch'] })
@@ -2892,7 +3331,71 @@ export const RiggingInputSchema = z.object({
         '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',
+        // ── Pose motion. The engine has had these for releases; nothing could
+        // reach them, which is not the same as their not existing.
+        'list_skeletons', 'list_bones', 'list_poses', 'load_pose', 'interpolate_poses',
+        'list_pose_libraries', 'load_pose_library',
+        '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',
     ]).describe('Rigging operation'),
+    // ── Pose motion ────────────────────────────────────────────────────────
+    poseId: z.string().optional().describe('Saved pose id — load_pose.'),
+    poseIdA: z.string().optional().describe('First pose — interpolate_poses.'),
+    poseIdB: z.string().optional().describe('Second pose — interpolate_poses.'),
+    t: z.number().min(0).max(1).optional().describe('Blend 0=A … 1=B — interpolate_poses.'),
+    /**
+     * A pose sequence: keys over normalized time, each naming a SAVED pose or an
+     * inline { boneId: angleDeg } map. The saved-pose form is the point — an
+     * animation that is literally a graph over the poses in the Poses panel.
+     */
+    sequence: z.array(z.object({
+        t: z.number().describe('Time (normalized within the clip unless duration is given).'),
+        pose: z.string().optional().describe('Saved pose id.'),
+        angles: z.record(z.string(), z.number()).optional().describe('Inline { boneId: angleDeg }.'),
+        ease: z.string().optional(),
+    })).optional().describe('Pose keys — play_pose_sequence.'),
+    /**
+     * Clips to STITCH into one continuous performance. Each clip is a sequence
+     * plus how it joins: `repeat` plays it N times, `loop` marks it cyclic (only
+     * a cyclic clip can be phase-matched), `blend` is the seam overlap.
+     */
+    clips: z.array(z.object({
+        keys: z.array(z.object({
+            t: z.number().optional(),
+            pose: z.string().optional(),
+            angles: z.record(z.string(), z.number()).optional(),
+            ease: z.string().optional(),
+        })).optional(),
+        poses: z.array(z.object({
+            pose: z.string().optional(),
+            angles: z.record(z.string(), z.number()).optional(),
+        })).optional().describe('Bare list — spread evenly across the clip.'),
+        duration: z.number().positive().optional(),
+        repeat: z.number().int().min(1).max(200).optional(),
+        loop: z.boolean().optional().describe('Cyclic: can be entered at any phase.'),
+        blend: z.number().min(0).optional().describe('Override the seam overlap into this clip.'),
+        matchPhase: z.boolean().optional(),
+    })).optional().describe('Clips in order — stitch_poses.'),
+    blend: z.number().min(0).optional().describe('Seam overlap in seconds (default 0.25) — stitch_poses.'),
+    blendSteps: z.number().int().min(2).max(64).optional().describe('Keys emitted across a seam (default 6) — stitch_poses.'),
+    matchPhase: z.boolean().optional().describe('Enter a cyclic clip at the phase closest to where the last one ended (default true) — stitch_poses.'),
+    plan: z.boolean().optional().describe('Return the seams WITHOUT installing the result — stitch_poses. Read `residual` per seam: it is the mismatch the blend is hiding, in degrees.'),
+    libraryName: z.string().optional().describe("Stock pose set — load_pose_library. The LIBRARIES are rig shapes: humanoid, quadruped, bird, fish. Loading one saves its poses (idle, walk_00…walk_07, walk_contact_L, run_*, …) against your bones. The walk/run/flap SEQUENCES are transitions, not libraries — play those with apply_pose_transition once the library is loaded. list_pose_libraries returns both lists."),
+    boneMap: z.record(z.string(), z.string()).optional().describe('Bone NAME → bone id — load_pose_library. Omit and it is built from list_bones, which is what you want unless the rig uses non-standard names.'),
+    transitionName: z.string().optional().describe('Named pose transition — apply_pose_transition.'),
+    poseIdMap: z.record(z.string(), z.string()).optional().describe('Transition pose name → saved pose id — apply_pose_transition.'),
+    boneNames: z.array(z.string()).optional().describe('Ordered bone names for a spring chain — add_secondary_motion.'),
+    keyframes: z.array(z.object({
+        t: z.number().describe('SCENE SECONDS, not a 0..1 fraction.'),
+        x: z.number(), y: z.number(), ease: z.string().optional(),
+    })).optional().describe('World root positions over SCENE TIME — move_root. This is what makes a figure travel instead of walking on the spot. `t` is in seconds on the same clock as the pose sequence, so match the last keyframe to the performance duration or the figure arrives early and stands there. Pass options.loop with options.period to cycle it.'),
+    shapeKeyId: z.string().optional().describe('Saved shape key id — load_shape_key.'),
+    weight: z.number().optional().describe('Shape key weight 0..1 (default 1) — load_shape_key.'),
+    options: z.record(z.string(), z.unknown()).optional().describe('Pass-through options for auto_* / bake_animation / move_root / skin_path / play_pose_sequence.'),
     // ── Mocap / rig import (import_bvh, retarget_bvh, import_spine) ──
     // The file CONTENTS travel in the call (MCP has no filesystem): .bvh text for
     // BVH, the exported .json for Spine. import_bvh builds a NEW stick-figure rig