@pinepaper.studio/mcp-server 1.5.4 → 1.6.0

package/dist/types/schemas.js

@@ -92,6 +92,12 @@ export const ItemTypeSchema = z.enum([
     'path',
     'line',
     'arc',
+    // Named shape variants (regular polygons + paths) — createable directly by name
+    'pentagon',
+    'hexagon',
+    'diamond',
+    'arrow',
+    'heart',
 ]);
 // Text item properties
 export const TextPropertiesSchema = z.object({
@@ -217,6 +223,40 @@ export const RelationTypeSchema = z.enum([
     '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)
 ]).describe('Type of relationship between items');
 // Relation parameter schemas
 export const OrbitsParamsSchema = z.object({
@@ -337,19 +377,207 @@ export const GroupMorphsToParamsSchema = z.object({
     easing: z.enum(['linear', 'easeIn', 'easeOut', 'easeInOut']).optional().default('easeInOut').describe('Easing for the position interpolation'),
     deformLines: z.boolean().optional().default(true).describe('Path.Line children deform via segment endpoints instead of rigid translation'),
 });
+// =============================================================================
+// EQUATION-DRIVEN PATHS (Expression IR — FxTool S10 B5)
+// Deterministic: math strings are parsed via expr-to-ir (no eval), sampled on
+// the Expression IR. Shared by pinepaper_equation_path (geometry) and the
+// moves_along_path `equation` motion source.
+// =============================================================================
+// Curated curve library (curvePreset). Each is a parametric preset.
+export const CurvePresetSchema = z.enum(['spiral', 'rose', 'lissajous', 'astroid', 'heart', 'spirograph'])
+    .describe('Curated curve preset');
+// One Fourier term for kind:"fourier".
+export const HarmonicSchema = z.object({
+    freq: z.number().describe('Harmonic frequency'),
+    amp: z.number().describe('Amplitude'),
+    phase: z.number().optional().describe('Phase offset (radians)'),
+});
+// Chained parametric warp — displaces each sampled point by (dx, dy),
+// expressions of x, y (point coords) and t (0..1 along the path).
+export const EquationWarpSchema = z.object({
+    dx: z.string().optional().describe('x displacement expression of x, y, t (0..1)'),
+    dy: z.string().optional().describe('y displacement expression of x, y, t (0..1)'),
+});
+// The math-source fields common to both equation surfaces (no placement).
+const equationSpecShape = {
+    kind: z.enum(['function', 'parametric', 'fourier', 'preset']).optional().default('function').describe("'function' y=f(variable) · 'parametric' x=fx(param),y=fy(param) · 'fourier' harmonics · 'preset' curated curve"),
+    expr: z.string().optional().describe("y = f(variable) — kind 'function', e.g. 'sin(x)*80'"),
+    xExpr: z.string().optional().describe("x = fx(param) — kind 'parametric'"),
+    yExpr: z.string().optional().describe("y = fy(param) — kind 'parametric'"),
+    harmonics: z.array(HarmonicSchema).optional().describe("Fourier terms — kind 'fourier'"),
+    preset: CurvePresetSchema.optional().describe("Curated curve — kind 'preset'"),
+    variable: z.string().optional().default('x').describe("Sample variable for kind 'function'"),
+    param: z.string().optional().default('t').describe("Sample variable for kind 'parametric'/'preset'"),
+    min: z.number().optional().describe('Sample range start'),
+    max: z.number().optional().describe('Sample range end'),
+    samples: z.number().optional().default(200).describe('Number of samples along the range'),
+    scale: z.number().optional().default(1).describe('Multiply equation coords before placing'),
+    flipY: z.boolean().optional().default(true).describe('Math y-up → screen y-down'),
+    warp: z.union([EquationWarpSchema, z.array(EquationWarpSchema)]).optional().describe('Chained parametric warp(s) applied to the sampled points'),
+};
 // Self-relation: item is driven along a custom-drawn path stored in params.
 // In the editor the Relations picker offers a drag-to-draw capture mode; via
 // MCP / agent code, pass the points array explicitly.
+// Equation motion source for moves_along_path (S10 B5): the item TRAVERSES a
+// math curve instead of a drawn point list. Origin is cx/cy (default 0) —
+// distinct from pinepaper_equation_path's x/y (canvas-center default).
+// .passthrough(): preset tuning params (e.g. rose's k/r, spiral's turns) ride on
+// the top-level object — FxTool does curvePreset(eq.preset, eq) — so they must
+// survive validation instead of being stripped.
+export const MovesAlongPathEquationSchema = z.object({
+    ...equationSpecShape,
+    cx: z.number().optional().describe('Canvas origin x for the sampled curve (default 0)'),
+    cy: z.number().optional().describe('Canvas origin y for the sampled curve (default 0)'),
+}).passthrough();
 export const MovesAlongPathParamsSchema = z.object({
+    // path OR equation — one is required. equation overrides path when both are set.
     path: z.array(z.union([
         z.object({ x: z.number(), y: z.number() }),
         z.tuple([z.number(), z.number()]),
-    ])).describe('Path points: array of {x,y} objects or [x,y] tuples'),
+    ])).optional().describe('Path points: array of {x,y} objects or [x,y] tuples (omit when using `equation`)'),
+    equation: MovesAlongPathEquationSchema.optional().describe('Equation motion source (S10 B5): traverse a math curve instead of a drawn path — deterministic, sampled on the Expression IR'),
     speed: z.number().optional().default(1).describe('Speed multiplier (1 ≈ 150 px/s)'),
     closed: z.boolean().optional().default(true).describe('Loop back to start at end of path'),
     phase: z.number().optional().default(0).describe('Starting position along path (0–1)'),
     easing: z.enum(['linear', 'easeIn', 'easeOut', 'easeInOut', 'sine', 'bounce', 'pingpong']).optional().default('linear').describe('Motion curve mapping normalized time → progress along path'),
 });
+// pinepaper_equation_path input — creates a path ITEM from a math equation.
+// Placement is x/y (canvas center default) + style, on top of the shared spec.
+// .passthrough(): preset tuning params (rose's k/r, spiral's turns, …) ride on
+// the top-level object — FxTool does curvePreset(opts.preset, opts.presetParams
+// || opts) — so they must survive validation.
+export const EquationPathInputSchema = z.object({
+    ...equationSpecShape,
+    x: z.number().optional().describe('Canvas origin x (default: canvas center)'),
+    y: z.number().optional().describe('Canvas origin y (default: canvas center)'),
+    style: z.record(z.unknown()).optional().describe('Path style forwarded to create (strokeColor, strokeWidth, fillColor, …)'),
+}).passthrough();
+// Procedural / deterministic property binding (Expression IR — FxTool S10 G1).
+// driven_by: source's `sourceProperty` = target's `targetProperty` * multiplier
+// + offset (optionally clamped). For fillColor/strokeColor the driven value
+// (clamped 0..1) interpolates colorFrom→colorTo — a relation that drives COLOR.
+// signal:true evaluates via the pure IR signal interpreter (frame-deterministic,
+// x/y target props track a moving target); else the per-frame compute runs.
+export const DrivenByParamsSchema = z.object({
+    sourceProperty: z.enum(['x', 'y', 'rotation', 'opacity', 'scale', 'strokeWidth', 'fillColor', 'strokeColor']).optional().default('opacity').describe('Property on the SOURCE item to drive'),
+    targetProperty: z.enum(['x', 'y', 'rotation', 'opacity', 'scale']).optional().default('x').describe('Property on the TARGET item to read'),
+    multiplier: z.number().optional().default(1).describe('Scale factor applied to the target value'),
+    offset: z.number().optional().default(0).describe('Offset added after the multiplier'),
+    clamp: z.object({ min: z.number().optional(), max: z.number().optional() }).optional().describe('Optional {min, max} clamp on the result'),
+    colorFrom: z.string().optional().default('#000000').describe('Color at driven value 0 (fillColor/strokeColor sourceProperty)'),
+    colorTo: z.string().optional().default('#ffffff').describe('Color at driven value 1 (fillColor/strokeColor sourceProperty)'),
+    signal: z.boolean().optional().default(false).describe('Deterministic IR-signal mode — replay-stable; x/y target props track a moving target'),
+});
+// time_expression: self-relation (targetId=null). The source's `property` is
+// driven by a math expression of t (scene time) and v (baseValue). signal:true
+// parses the expression into the Expression IR and evaluates a pure f(t)
+// (replay-stable), falling back to per-frame if it uses random()/unknown symbols.
+export const TimeExpressionParamsSchema = z.object({
+    property: z.string().optional().default('y').describe('Property to drive: x, y, rotation, opacity, scale'),
+    expression: z.string().optional().default('sin(t * 2) * 50 + 300').describe('Math expression of t (time) and v (baseValue), e.g. "sin(t*2)*50 + v"'),
+    baseValue: z.number().optional().default(0).describe('Base value accessible as v in the expression'),
+    signal: z.boolean().optional().default(false).describe('Deterministic IR mode — parse expression to IR, evaluate as pure f(t)'),
+});
+// =============================================================================
+// EVENT-DRIVEN SCENE CHAINS (FxTool S11). Source of each is a pp:event.
+// =============================================================================
+// on_event_fire_after (event→event): chain a delayed pulse. timeline 'canvas'
+// schedules on the animation clock (pauses/seeks/loops with the timeline) — use
+// it for scene chains; 'wall' is real-world setTimeout ms.
+export const OnEventFireAfterParamsSchema = z.object({
+    delay: z.number().min(0).optional().default(1000).describe('Delay before pulsing the target event (milliseconds)'),
+    timeline: z.enum(['wall', 'canvas']).optional().default('wall').describe("'canvas' = animation-clock time (scrub/loop-stable) · 'wall' = real setTimeout ms"),
+});
+// on_event_add_relation (event→item): when the event fires, add a relation FROM
+// the target item TO params.target of type params.type. The scene mutates itself.
+export const OnEventAddRelationParamsSchema = z.object({
+    type: z.string().describe('Relation type to add (e.g. orbits, moves_along_path, driven_by)'),
+    target: z.string().nullish().describe('Target item id for the added relation (null for self-relations)'),
+    params: z.record(z.unknown()).optional().default({}).describe('Params for the added relation'),
+});
+// on_event_remove_relation (event→item): tear down a relation added earlier.
+export const OnEventRemoveRelationParamsSchema = z.object({
+    type: z.string().describe('Relation type to remove'),
+    target: z.string().nullish().describe('Target item id (null for self-relations)'),
+});
+// on_event_set_color (event→item).
+export const OnEventSetColorParamsSchema = z.object({
+    color: z.string().describe('Color to apply when the event fires'),
+    which: z.enum(['fill', 'stroke']).optional().default('fill').describe('Which color channel to set'),
+});
+// on_event_set_property (event→item): set an arbitrary property.
+export const OnEventSetPropertyParamsSchema = z.object({
+    property: z.string().describe('Item property to set (e.g. opacity, rotation, strokeWidth)'),
+    value: z.unknown().describe('Value to assign'),
+});
+// on_event_set_visibility (event→item).
+export const OnEventSetVisibilityParamsSchema = z.object({
+    visible: z.boolean().optional().default(true).describe('Show (true) or hide (false) the item'),
+});
+// pinepaper_event tool — manage the pp:event channel.
+//   create → app.createEvent(name, {payloadType,x,y}) → returns eventId
+//   pulse  → app.pulseEvent(eventId, payload) → kicks off a chain
+export const EventInputSchema = z.object({
+    action: z.enum(['create', 'pulse']).describe("'create' a pp:event · 'pulse' it to fire listeners/chains"),
+    name: z.string().optional().describe("Event name — required for action 'create'"),
+    payloadType: z.string().optional().describe("Payload type label (default 'Pulse') — action 'create'"),
+    x: z.number().optional().describe('Canvas x for the event marker — action create'),
+    y: z.number().optional().describe('Canvas y for the event marker — action create'),
+    eventId: z.string().optional().describe("Event id to fire — required for action 'pulse'"),
+    payload: z.unknown().optional().describe("Optional value forwarded to listeners — action 'pulse'"),
+}).refine((v) => v.action !== 'create' || !!v.name, { message: "action 'create' requires name", path: ['name'] })
+    .refine((v) => v.action !== 'pulse' || !!v.eventId, { message: "action 'pulse' requires eventId", path: ['eventId'] });
+// =============================================================================
+// STRUCTURAL LAYOUT RELATIONS (FxTool S12-E1)
+// =============================================================================
+// Placement expressed as a graph edge rather than baked-in coordinates. Every
+// compute reads the TARGET'S bounds and the SOURCE'S own bounds, and re-runs each
+// frame — move or resize the target and the dependent follows. All six need a
+// target. `signal: true` routes through the pure Expression-IR port, which FxTool
+// keeps bit-identical to the live compute.
+// on_top_of: source bottom edge rests on the target's top edge.
+//   y = T.y - target.height/2 - gap - source.height/2
+export const OnTopOfParamsSchema = z.object({
+    gap: z.number().optional().default(0).describe('Pixels between the two edges'),
+    align: z.enum(['left', 'center', 'right']).optional().default('center').describe('Horizontal alignment relative to the target'),
+    overhang: z.number().optional().default(0).describe('Extra signed x-offset in px'),
+    signal: z.boolean().optional().default(false).describe('Deterministic mode — route through the pure Expression-IR port'),
+});
+// below: the mirror of on_top_of — source top edge rests on the target's bottom edge.
+export const BelowParamsSchema = z.object({
+    gap: z.number().optional().default(0).describe('Pixels between the two edges'),
+    align: z.enum(['left', 'center', 'right']).optional().default('center').describe('Horizontal alignment relative to the target'),
+    overhang: z.number().optional().default(0).describe('Extra signed x-offset in px'),
+    signal: z.boolean().optional().default(false).describe('Deterministic mode — route through the pure Expression-IR port'),
+});
+// beside: source flanks the target horizontally, aligned vertically.
+export const BesideParamsSchema = z.object({
+    side: z.enum(['left', 'right']).optional().default('right').describe('Which side of the target'),
+    gap: z.number().optional().default(0).describe('Pixels between the two edges'),
+    align: z.enum(['top', 'center', 'bottom']).optional().default('center').describe('Vertical alignment relative to the target'),
+    signal: z.boolean().optional().default(false).describe('Deterministic mode — route through the pure Expression-IR port'),
+});
+// inside: source placed fully within the target's bounds at a 9-way anchor.
+export const InsideParamsSchema = z.object({
+    anchor: z.enum(['center', 'top-left', 'top', 'top-right', 'left', 'right', 'bottom-left', 'bottom', 'bottom-right'])
+        .optional().default('center').describe('Where inside the target to anchor the source'),
+    padding: z.number().optional().default(0).describe('Inset from the target edge in px'),
+    signal: z.boolean().optional().default(false).describe('Deterministic mode — route through the pure Expression-IR port'),
+});
+// centered_on: source center = target center + offset (concentric when offset is 0).
+export const CenteredOnParamsSchema = z.object({
+    offsetX: z.number().optional().default(0).describe('Signed x-offset from the target center'),
+    offsetY: z.number().optional().default(0).describe('Signed y-offset from the target center'),
+    signal: z.boolean().optional().default(false).describe('Deterministic mode — route through the pure Expression-IR port'),
+});
+// aligned_with: ONE axis of the source center matches the target's; the other axis
+// is left untouched (FxTool writes only the returned component). `axis` is required —
+// FxTool's compute returns undefined (relation does nothing) without it.
+export const AlignedWithParamsSchema = z.object({
+    axis: z.enum(['x', 'y']).describe('Which axis to align (required — the relation is inert without it)'),
+    offset: z.number().optional().default(0).describe('Signed offset along that axis'),
+    signal: z.boolean().optional().default(false).describe('Deterministic mode — route through the pure Expression-IR port'),
+});
 // =============================================================================
 // CUSTOM RELATION REGISTRATION
 // =============================================================================
@@ -439,6 +667,22 @@ export const GeneratorNameSchema = z.enum([
     'drawSimulation',
     'drawSpectrumAnalyzer',
     'draw3DSurface',
+    // S6 seeded procedural generators (curated presets + Motion group)
+    'drawTruchet',
+    'drawHalftone',
+    'drawRibbons',
+    // GPU / GLSL math-art generators
+    'drawFormulaArt',
+    'drawParametricCollection',
+    'drawShaderArt',
+    'drawYeganehMountains',
+    // OKLCH seeded backgrounds + 3D parametric curve
+    'drawBlobs',
+    'drawLowPoly',
+    'drawPeaks',
+    'drawScatter',
+    'drawStackedWaves',
+    'draw3DParametricCurve',
 ]).describe('Background generator name');
 // ---------------------------------------------------------------------------
 // Generator parameter schemas — Phase 1 (enhanced existing)
@@ -607,7 +851,12 @@ export const EffectTypeSchema = z.enum([
     'fireflies',
     'shockwave',
     'trail',
-]).describe('Visual effect type');
+    // Shader auras (WebGL2 silhouette-clipped) — routed to ItemAuraSystem by
+    // the same app.applyEffect entry point as the particle types.
+    'heatmap',
+    'liquid_metal',
+    'gem_smoke',
+]).describe('Visual effect type (particle effects + shader auras)');
 export const SparkleParamsSchema = z.object({
     color: ColorSchema.optional().default('#fbbf24').describe('Sparkle color'),
     speed: z.number().optional().default(1).describe('Animation speed'),
@@ -674,6 +923,8 @@ export const CreateItemInputSchema = z.object({
     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.'),
     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.'),
     keyframes: z.array(KeyframeSchema).optional().describe('Required when animationType is "keyframe". Inline keyframe array attached at creation.'),
 });
 // Light direction for 3D effects
@@ -719,7 +970,7 @@ export const DeleteItemInputSchema = z.object({
 // Add Relation
 export const AddRelationInputSchema = z.object({
     sourceId: z.string().describe('Registry ID of the source item'),
-    targetId: z.string().optional().describe('Registry ID of the target item (can be null for self-animations)'),
+    targetId: z.string().nullish().describe('Registry ID of the target item; null/omitted for self-relations (animates, moves_along_path, construction_reveal, time_expression)'),
     relationType: RelationTypeSchema,
     params: z.record(z.unknown()).optional().default({}),
 });
@@ -740,6 +991,8 @@ export const AnimateItemInputSchema = z.object({
     itemId: z.string().describe('Registry ID of the item'),
     animationType: SimpleAnimationTypeSchema,
     speed: z.number().optional().default(1).describe('Animation speed multiplier'),
+    intensity: z.number().optional().describe('Animation amplitude (animationIntensity): 0.1 = ±10%, 0.2 = ±20% (default 0.15). Drives pulse/wobble/bounce/breathe amplitude and is now honored by SVG/SMIL/widget export.'),
+    delay: z.number().optional().describe('Animation start delay in seconds (animationDelay).'),
 });
 // Keyframe Animate
 export const KeyframeAnimateInputSchema = z.object({
@@ -748,13 +1001,27 @@ export const KeyframeAnimateInputSchema = z.object({
     duration: z.number().optional().describe('Total animation duration'),
     loop: z.boolean().optional().default(false),
     timeOffset: z.number().optional().describe('Shift the whole clip in canvas time (seconds). The animation only runs while canvas time is in [timeOffset, timeOffset + (clipOutPoint - clipInPoint)].'),
+    timeUnits: z.enum(['seconds', 'ms']).optional().describe("Explicit units for keyframe times/duration. 'seconds' disables the legacy >100→ms auto-detect — REQUIRED for long-form timelines with second values over 100."),
     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.'),
 });
 // Execute Generator
+//
+// Region (added FxTool c81781c): when set, the generator draws into a clipped
+// sub-group translated to (x,y) sized (width × height). Region runs imply
+// preserve (won't wipe the canvas) and re-running the same generator replaces
+// its prior region. Different generators' regions coexist. Invalid/zero-size
+// regions fall back to full-canvas FxTool-side.
+export const GeneratorRegionSchema = z.object({
+    x: z.number().describe('Region top-left X in canvas coords'),
+    y: z.number().describe('Region top-left Y in canvas coords'),
+    width: z.number().positive().describe('Region width in pixels'),
+    height: z.number().positive().describe('Region height in pixels'),
+}).describe('Optional sub-region {x, y, width, height} the generator draws into.');
 export const ExecuteGeneratorInputSchema = z.object({
     generatorName: GeneratorNameSchema,
     params: z.record(z.unknown()).optional().default({}),
+    region: GeneratorRegionSchema.optional(),
 });
 // Apply Effect
 export const ApplyEffectInputSchema = z.object({
@@ -777,6 +1044,10 @@ export const PlayTimelineInputSchema = z.object({
     duration: z.number().optional().describe('Duration for play action'),
     loop: z.boolean().optional(),
     time: z.number().optional().describe('Time to seek to'),
+    deterministic: z
+        .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.'),
 });
 // Canvas Control
 export const SetBackgroundColorInputSchema = z.object({
@@ -1333,7 +1604,7 @@ export const AgentResetInputSchema = z.object({
  */
 export const AgentBatchOperationTypeSchema = z.enum([
     'set_canvas_size', 'set_background', 'execute_generator',
-    'create', 'modify', 'delete',
+    'create', 'modify', 'delete', 'group',
     'animate', 'keyframe_animate', 'relation',
     'apply_mask', 'apply_effect',
     'play_timeline',
@@ -1352,6 +1623,9 @@ export const AgentBatchOperationSchema = z.object({
     properties: z.record(z.unknown()).optional().describe('Properties for create/modify operations'),
     // Modify/Animate/Delete/Keyframe/Mask/Effect target
     itemId: z.string().optional().describe('Target item ID or $N reference'),
+    // Group operation fields
+    itemIds: z.array(z.string()).optional().describe('Item IDs or $N references to combine for a "group" operation (the parts of a composite object).'),
+    groupName: z.string().optional().describe('Optional name for the group created by a "group" operation (e.g. "car").'),
     // Animate operation fields
     animationType: z.string().optional().describe('Animation type for animate operations'),
     animationOptions: z.record(z.unknown()).optional().describe('Animation options'),
@@ -1365,6 +1639,7 @@ export const AgentBatchOperationSchema = z.object({
     // Execute generator fields
     generatorName: z.string().optional().describe('Generator name for execute_generator'),
     generatorParams: z.record(z.unknown()).optional().describe('Generator parameters'),
+    generatorRegion: GeneratorRegionSchema.optional().describe('Optional sub-region {x, y, width, height} for execute_generator'),
     // Set canvas size fields
     width: z.number().min(100).max(4096).optional().describe('Canvas width for set_canvas_size (100-4096)'),
     height: z.number().min(100).max(4096).optional().describe('Canvas height for set_canvas_size (100-4096)'),
@@ -1388,6 +1663,57 @@ export const AgentBatchOperationSchema = z.object({
     action: z.string().optional().describe('Timeline action for play_timeline (play, stop, seek)'),
     time: z.number().optional().describe('Seek time for play_timeline'),
 }).describe('Single batch operation');
+// Group / ungroup — combine the parts of a composite object into ONE draggable entity
+// (a car's body + wheels + windows), or break a group back into loose items.
+export const GroupInputSchema = z.object({
+    action: z.enum(['group', 'ungroup', 'break_apart']).describe('group: combine itemIds into one entity. ungroup: dissolve a group back into loose items. break_apart: split an imported SVG / group / compound-path into individually movable parts (re-grouped as one).'),
+    itemIds: z.array(z.string()).optional().describe('For group: registry IDs of the items to combine.'),
+    itemId: z.string().optional().describe('For break_apart: registry ID of the imported SVG / group / compound-path to decompose into parts.'),
+    groupName: z.string().optional().describe('For group: optional name (e.g. "car", "robot").'),
+    groupId: z.string().optional().describe('For ungroup: registry ID of the group to dissolve.'),
+});
+// Camera director — compile a high-level SHOT LIST into one camera_animates walkthrough
+// (FxTool's DirectorCompiler). 'auto' derives a shot per item; 'shots' takes an explicit list.
+export const CameraDirectorInputSchema = z.object({
+    action: z.enum(['auto', 'shots']).describe("auto: generate a default walkthrough (one shot per item). shots: apply an explicit shot list."),
+    shots: z
+        .array(z.object({
+        subjects: z.union([z.literal('everything'), z.array(z.string())]).describe("'everything' or item registry IDs the shot frames"),
+        framing: z.union([z.enum(['tight', 'medium', 'wide']), z.number()]).optional().describe('Framing tightness (or an explicit zoom number). Default medium.'),
+        hold: z.number().optional().describe('Seconds to dwell on the shot (default 1.2).'),
+        moveIn: z.string().optional().describe("Move style, e.g. 'push-in' | 'pan'."),
+        ease: z.enum(['smooth', 'linear', 'settle', 'snap']).optional().describe('Easing between shots (default smooth).'),
+        transition: z.number().optional().describe('Seconds to travel into this shot (default 1.0).'),
+    }))
+        .optional()
+        .describe('For action "shots": ordered shot list. Each shot frames its subjects at the given tightness.'),
+    order: z.enum(['reading', 'reverse', 'creation']).optional().describe('For action "auto": item visiting order (default reading).'),
+    hold: z.number().optional().describe('For action "auto": per-shot dwell seconds.'),
+    establishing: z.boolean().optional().describe('For action "auto": open with a wide establishing shot of everything.'),
+    loop: z.boolean().optional().describe('Loop the camera walkthrough.'),
+});
+// On-device object detection (FxTool ImageWorkflow / DETR·YOLO). Find objects in an
+// imported image; optionally promote each detection to a typed, image-anchored design
+// node (pp:Detected*, Wikidata-aliased) so relations can bind a shape to it.
+export const DetectObjectsInputSchema = z.object({
+    itemId: z.string().optional().describe('Registry ID of the image to scan (default: the most recent image on the canvas).'),
+    threshold: z.number().min(0).max(1).optional().describe('Confidence threshold 0-1 (default ~0.35 for DETR, ~0.1 for open-vocabulary).'),
+    asNodes: z.boolean().optional().describe('true → promote each detection to a typed, image-anchored design NODE (a relation target: pp:Detected* aliased to a Wikidata entity) instead of drawing a labeled box. Enables relational compositing (bind a shape on/around/at the object; it tracks the image).'),
+    queries: z.union([z.array(z.string()), z.string()]).optional().describe('OPEN-VOCABULARY detection (OWL-ViT, zero-shot): a list (or comma-separated string) of things to find by description — e.g. ["red umbrella","traffic light"]. Finds whatever you describe instead of the fixed 80 COCO classes. Omit to use the default DETR detector. The OWL-ViT model is a large one-time on-device download.'),
+});
+// Extract the best-matching detected region from an image as a NEW item.
+export const ExtractObjectInputSchema = z.object({
+    label: z.string().optional().describe('What to extract (e.g. "cat", "person"). Picks the best-matching detection; default = highest-confidence.'),
+    itemId: z.string().optional().describe('Registry ID of the source image (default: most recent image).'),
+    x: z.number().optional().describe('Optional hint X (canvas coords) to disambiguate which detection to extract.'),
+    y: z.number().optional().describe('Optional hint Y (canvas coords).'),
+    threshold: z.number().min(0).max(1).optional().describe('Confidence threshold 0-1.'),
+});
+// Z-order / arrange — move an item up or down the stacking order.
+export const ArrangeInputSchema = z.object({
+    itemId: z.string().describe('Registry ID of the item to reorder.'),
+    action: z.enum(['front', 'back', 'forward', 'backward']).describe('front: bring to top of the stack. back: send to bottom. forward: move up one. backward: move down one.'),
+});
 /**
  * Batch execute input schema
  */
@@ -1405,6 +1731,7 @@ export const AgentExportInputSchema = z.object({
     quality: z.enum(['draft', 'standard', 'high']).optional().default('standard').describe('Export quality level'),
     includeRecommendations: z.boolean().optional().default(true).describe('Include alternative format recommendations'),
     framing: z.enum(['canvas', 'camera']).optional().default('canvas').describe('Output framing: "canvas" (full canvas, default) or "camera" (camera_animates first-keyframe viewport — fails if no walkthrough exists). Camera animation still drives motion within the fixed output frame.'),
+    duration: z.number().min(0.5).max(60).optional().default(5).describe('Video duration in seconds for animated formats (mp4/webm/gif). Default 5. Max 60. Static formats (png/svg/pdf) ignore this.'),
 }).describe('Smart export options');
 /**
  * Analyze content input schema
@@ -1477,35 +1804,6 @@ export const TriggerActionSchema = z.object({
     points: z.number().optional().describe('Points to add'),
     delay: z.number().optional().default(0).describe('Delay before action in ms'),
 }).describe('Action to execute');
-/**
- * Add trigger input
- */
-export const AddTriggerInputSchema = z.object({
-    itemId: z.string().describe('Registry ID of the item'),
-    event: TriggerEventSchema,
-    time: z.number().optional().describe('Time in seconds for timeline triggers'),
-    timelineOffset: z.number().optional().describe('Time offset in ms for timeline triggers'),
-    conditions: z.array(TriggerConditionSchema).optional().describe('Conditions that must be met'),
-    condition: z.string().optional().describe('Optional condition expression (e.g., "$score > 10")'),
-    actions: z.array(TriggerActionSchema).min(1).describe('Actions to execute'),
-    once: z.boolean().optional().default(false).describe('Fire only once'),
-}).describe('Add trigger to item');
-/**
- * Remove trigger input
- */
-export const RemoveTriggerInputSchema = z.object({
-    itemId: z.string().describe('Registry ID of the item'),
-    triggerId: z.string().optional().describe('Specific trigger ID to remove'),
-    event: TriggerEventSchema.optional().describe('Remove all triggers of this event type'),
-    removeAll: z.boolean().optional().describe('Remove all triggers from item'),
-}).describe('Remove triggers from item');
-/**
- * Query triggers input
- */
-export const QueryTriggersInputSchema = z.object({
-    itemId: z.string().optional().describe('Filter by item ID'),
-    event: TriggerEventSchema.optional().describe('Filter by event type'),
-}).describe('Query triggers');
 // =============================================================================
 // QUIZ / LMS SCHEMAS
 // =============================================================================
@@ -1563,33 +1861,6 @@ export const QuizQuestionSchema = z.object({
     onCorrectActions: z.array(TriggerActionSchema).optional(),
     onIncorrectActions: z.array(TriggerActionSchema).optional(),
 }).describe('Quiz question');
-/**
- * Create quiz input
- */
-export const CreateQuizInputSchema = z.object({
-    id: z.string().optional().describe('Quiz ID'),
-    title: z.string().optional().describe('Quiz title'),
-    questions: z.array(QuizQuestionSchema).min(1),
-    shuffleQuestions: z.boolean().optional().default(false),
-    shuffleOptions: z.boolean().optional().default(false),
-    showFeedback: z.enum(['immediate', 'after-submit', 'never']).optional().default('immediate'),
-    showScore: z.boolean().optional().default(true).describe('Display score during quiz'),
-    passingScore: z.number().optional().describe('Minimum score to pass (percentage)'),
-    allowRetry: z.boolean().optional().default(true),
-    trackProgress: z.boolean().optional().default(true),
-}).describe('Create quiz input');
-/**
- * Get quiz state input
- */
-export const GetQuizStateInputSchema = z.object({
-    quizId: z.string().optional().describe('Quiz ID (uses active quiz if not specified)'),
-}).describe('Get quiz state');
-/**
- * Reset quiz input
- */
-export const ResetQuizInputSchema = z.object({
-    quizId: z.string().optional().describe('Quiz ID to reset (uses active quiz if not specified)'),
-}).describe('Reset quiz');
 // =============================================================================
 // LETTER COLLAGE SCHEMAS
 // =============================================================================
@@ -1600,6 +1871,7 @@ export const LetterCollageStyleSchema = z.enum([
     'fold',
     'gradient',
     'image',
+    'particle',
 ]).describe('Style type for letter collage');
 export const TilePaletteSchema = z.enum([
     // Game
@@ -1640,6 +1912,8 @@ export const CreateLetterCollageInputSchema = z.object({
     gradientDirection: GradientDirectionSchema.optional().default('vertical').describe('Gradient direction (for style="gradient")'),
     cornerRadius: z.number().optional().default(4).describe('Corner radius for tile backgrounds'),
     shadowEnabled: z.boolean().optional().default(true).describe('Enable drop shadows'),
+    particleSpacing: z.number().optional().describe('Dot spacing for style="particle" (smaller = denser cloud; default ~fontSize*0.11)'),
+    particleDotSize: z.number().optional().describe('Base dot radius for style="particle" (default ~particleSpacing*0.44)'),
 }).describe('Create letter collage input');
 export const AnimateLetterCollageInputSchema = z.object({
     collageId: z.string().describe('Collage ID from create_letter_collage'),
@@ -1647,11 +1921,6 @@ export const AnimateLetterCollageInputSchema = z.object({
     staggerDelay: z.number().optional().default(0.1).describe('Delay between each letter animation start (seconds)'),
     animationSpeed: z.number().optional().default(1).describe('Animation speed multiplier'),
 }).describe('Animate letter collage input');
-export const GetLetterCollageOptionsInputSchema = z.object({}).describe('Get letter collage options input (no parameters)');
-// =============================================================================
-// CANVAS PRESETS SCHEMA
-// =============================================================================
-export const GetCanvasPresetsInputSchema = z.object({}).describe('Get canvas presets input (no parameters)');
 // =============================================================================
 // MAP SCHEMAS
 // =============================================================================
@@ -1800,6 +2069,54 @@ export const DeselectMapRegionsInputSchema = z.object({
 }).describe('Deselect map regions input');
 export const GetHighlightedMapRegionsInputSchema = z.object({}).describe('Get highlighted map regions input (no parameters)');
 // =============================================================================
+// GLOBE + WORLD TOUR SCHEMAS
+// =============================================================================
+export const GlobeEnableInputSchema = z.object({
+    rotation: z.tuple([z.number(), z.number(), z.number()]).optional().describe('Initial rotation angles [lambda, phi, gamma]'),
+    momentum: z.boolean().optional().describe('Enable momentum/inertia on drag-spin'),
+    showOcean: z.boolean().optional().describe('Render the ocean sphere backdrop'),
+}).describe('Enable globe (orthographic) mode input');
+export const GlobeRotateToInputSchema = z.object({
+    lon: z.number().describe('Target longitude to rotate to face the viewer'),
+    lat: z.number().describe('Target latitude to rotate to face the viewer'),
+    duration: z.number().optional().describe('Animation duration in seconds (versor slerp)'),
+}).describe('Rotate globe to coordinate input');
+export const GlobeSpinInputSchema = z.object({
+    speed: z.number().optional().describe('Rotation speed (degrees per second)'),
+    axis: z.enum(['longitude', 'latitude']).optional().describe('Axis to spin around'),
+    duration: z.number().optional().describe('Spin duration in seconds (omit for continuous)'),
+}).describe('Continuous globe spin input');
+export const WorldTourInputSchema = z.object({
+    regions: z.array(z.string()).optional().describe('Region IDs to visit in order'),
+    coords: z.array(z.tuple([z.number(), z.number()])).optional().describe('Coordinate stops [lon, lat][] to visit in order'),
+    dwell: z.number().optional().describe('Seconds to dwell at each stop'),
+    travel: z.number().optional().describe('Seconds to travel between stops'),
+    tilt: z.number().optional().describe('Camera tilt applied at each stop'),
+    loop: z.boolean().optional().describe('Loop the tour continuously'),
+    easing: z.string().optional().describe('Easing curve for the swing between stops'),
+    highlightColors: z.array(z.string()).optional().describe('Highlight colors cycled per stop'),
+    showLabels: z.boolean().optional().describe('Show a label at each stop'),
+    labelColor: z.string().optional().describe('Label text color'),
+}).describe('World tour input (requires regions or coords)');
+export const StopWorldTourInputSchema = z.object({
+    id: z.string().optional().describe('Tour id to stop (omit to stop all tours)'),
+}).describe('Stop world tour input');
+export const PinToGlobeInputSchema = z.object({
+    itemId: z.string().describe('ID of the canvas item to pin to the globe surface'),
+    lon: z.number().describe('Longitude to pin the item at'),
+    lat: z.number().describe('Latitude to pin the item at'),
+    hideOnFarSide: z.boolean().optional().describe('Hide the item when its coordinate rotates to the far side'),
+}).describe('Pin item to globe input');
+export const TourItemInputSchema = z.object({
+    itemId: z.string().describe('ID of the canvas item to move along the tour'),
+    regions: z.array(z.string()).optional().describe('Region IDs to tour the item across'),
+    coords: z.array(z.tuple([z.number(), z.number()])).optional().describe('Coordinate stops [lon, lat][] to move the item along'),
+    dwell: z.number().optional().describe('Seconds to dwell at each stop'),
+    travel: z.number().optional().describe('Seconds to travel between stops'),
+    loop: z.boolean().optional().describe('Loop the item tour continuously'),
+    orient: z.boolean().optional().describe('Orient the item along its direction of travel'),
+}).describe('Tour item along coords/regions input (requires regions or coords)');
+// =============================================================================
 // TEMPLATE SCHEMAS
 // =============================================================================
 export const TemplateCategorySchema = z.enum([
@@ -1832,6 +2149,23 @@ export const AnalyzeDesignInputSchema = z.object({
 export const ValidateDesignInputSchema = z.object({
     definition: z.object({}).passthrough().describe('A template or scene definition object to validate and score'),
 }).describe('Validate design input');
+// Semantic scene/op validator (OntologyValidator in FxTool) — distinct from
+// ValidateDesign (which scores a template definition server-side). Runs in the
+// browser against the live scene and returns structured diagnostics.
+export const ValidateInputSchema = z.object({
+    mode: z.enum(['scene', 'op']).default('scene')
+        .describe("'scene' audits the whole live canvas; 'op' validates a proposed mutation before applying it"),
+    op: z.object({
+        kind: z.enum(['addRelation', 'create', 'modify']).describe('The kind of mutation being validated'),
+        from: z.string().optional().describe('Source item id (addRelation)'),
+        to: z.string().optional().describe('Target item id (addRelation)'),
+        relation: z.string().optional().describe('Relation type (addRelation)'),
+        params: z.record(z.unknown()).optional().describe('Relation params (addRelation)'),
+        type: z.string().optional().describe('Item type (create)'),
+        id: z.string().optional().describe('Item id (modify)'),
+        changes: z.record(z.unknown()).optional().describe('Property changes (modify)'),
+    }).optional().describe("Required when mode='op': the proposed mutation to validate"),
+}).describe('Semantic validation input');
 export const QueryOntologyInputSchema = z.object({
     query: z.enum([
         'list_types', 'list_edges', 'list_generators', 'list_effects',
@@ -1924,11 +2258,6 @@ export const PrecompInputSchema = z.object({
     precompId: z.string().optional(),
     itemId: z.string().optional(),
 });
-export const ViewInputSchema = z.object({
-    action: z.enum(['fit', 'get_state']),
-    mode: z.enum(['content', 'canvas']).optional(),
-    padding: z.number().optional(),
-});
 export const BackgroundInputSchema = z.object({
     action: z.enum(['set', 'clear', 'get']),
     mode: z.enum(['color', 'pattern', 'generator']).optional(),
@@ -2003,15 +2332,6 @@ export const SpriteSheetInputSchema = z.object({
     format: z.enum(['png', 'webp']).optional(),
 });
 // =============================================================================
-// STORAGE TOOLS
-// =============================================================================
-export const StorageInputSchema = z.object({
-    action: z.enum(['save', 'load', 'list', 'delete']),
-    projectId: z.string().optional(),
-    name: z.string().optional(),
-    thumbnail: z.boolean().optional(),
-});
-// =============================================================================
 // INTERACTION TOOLS
 // =============================================================================
 export const InteractionInputSchema = z.object({
@@ -2090,4 +2410,200 @@ export const MeasurementInputSchema = z.object({
     enabled: z.boolean().optional(),
     itemId: z.string().optional(),
 });
+// Geometry construction helpers (Layer 1) — pure functions exposed by FxTool's
+// app.geometry (GeometryConstruction). The server computes a construction and
+// optionally creates an item from the result, mirroring:
+//   app.create('polygon', { points: app.geometry.regularPolygon(cx, cy, r, 5) });
+export const GEOMETRY_OPERATIONS = [
+    // points
+    'point', 'distance', 'midpoint', 'lerpPoint', 'centroid',
+    'translatePoint', 'rotatePoint', 'scalePoint',
+    // polygons
+    'regularPolygon', 'star', 'polygonFromVertices',
+    // lines
+    'lineThrough', 'lineDirection', 'lineIntersection', 'projectPointToLine',
+    'perpendicular', 'parallel', 'perpendicularBisector', 'reflectPoint',
+    // angles
+    'angle', 'angleBisector',
+    // circles
+    'circle', 'pointOnCircle', 'circumcenter', 'circleThrough', 'incenter',
+    'tangentPointsFromExternal',
+];
+export const GeometryInputSchema = z.object({
+    operation: z.enum(GEOMETRY_OPERATIONS).describe('Which app.geometry.* construction helper to run'),
+    args: z.array(z.any()).default([]).describe('Positional arguments for the operation, in order. Points are {x,y} objects (or [x,y] arrays where a vertex list is accepted); lines are {p1,p2}; circles are {center,radius}. Angles are in radians. e.g. regularPolygon → [cx, cy, radius, sides, rotation?]'),
+    createAs: z
+        .object({
+        itemType: z.string().optional().describe('Override item type for point results (default "circle").'),
+        color: z.string().optional(),
+        fillColor: z.string().optional(),
+        strokeColor: z.string().optional(),
+        strokeWidth: z.number().optional(),
+        radius: z.number().optional().describe('Marker radius for point results (default 6).'),
+    })
+        .passthrough()
+        .optional()
+        .describe('When provided, also create a canvas item from the result: a vertex-list result → polygon, a circle result → circle, a point result → a small marker. Extra keys pass through to app.create. Omit for compute-only.'),
+});
+// Construction sequences (Layer 3) — step-by-step reveal of a geometric figure,
+// wrapping FxTool's app.constructionSequence. Each step hides its items and attaches
+// a timeline-driven construction_reveal relation, so playback reveals the figure one
+// step at a time (replayable, scrubbable, editable as relation graph data).
+export const ConstructionSequenceInputSchema = z.object({
+    action: z.enum(['build', 'play', 'clear', 'list']).describe('build a sequence, play it on the timeline, clear (restore items), or list sequences'),
+    steps: z
+        .array(z.union([
+        z.array(z.string()),
+        z.object({ items: z.array(z.string()), label: z.string().optional() }),
+    ]))
+        .optional()
+        .describe('For build: ordered steps; each step is an array of item ids (or {items, label}) revealed together. Step i reveals at i * stepDuration seconds.'),
+    stepDuration: z.number().positive().optional().describe('For build: seconds between steps (default 1).'),
+    fadeIn: z.number().min(0).optional().describe('For build: per-step fade-in duration in seconds (default 0.3).'),
+    sequenceId: z.string().optional().describe('For play/clear: the cseq_ id returned by build. Defaults to the most recently built sequence.'),
+    loop: z.boolean().optional().describe('For play: loop the timeline (default false).'),
+    duration: z.number().positive().optional().describe('For play: override total play duration in seconds (default = sequence total).'),
+});
+// Live-scene semantic validation (OntologyValidator / S2) — structured diagnostics
+// over the actual canvas (dangling refs, unknown types/props, keyframe issues, cycles).
+export const ValidateSceneInputSchema = z.object({
+    ops: z
+        .array(z.record(z.string(), z.any()))
+        .optional()
+        .describe('Optional: validate a batch of PROPOSED ops ({ kind: "addRelation"|"create"|"modify"|"delete", ... }) against the live scene before applying them, instead of auditing the current scene. Ids created earlier in the batch count as existing for later ops.'),
+});
+// Deterministic headless frame capture (S3) — evaluate the scene at each time via
+// sceneAt(t) with Math.random seeded once around the whole sequence, then snapshot.
+export const CaptureFramesInputSchema = z.object({
+    times: z.array(z.number()).min(1).describe('Capture times in seconds, rendered in order.'),
+    seed: z.number().optional().describe('Seed Math.random once around the whole sequence so random generators/particles are reproducible (default 0).'),
+    includeDataUrls: z.boolean().optional().describe('Include each frame as a PNG data URL (large — token-heavy). Default false → returns a cheap per-frame hash + byte size only.'),
+});
+// Ontology→scene compiler (S12-E3). Compiles a pp:-namespaced JSON-LD design graph
+// (typed nodes + structural edges like pp:onTopOf) into a real scene. Compilation
+// runs server-side (deterministic, testable); only the resulting create/addRelation
+// ops are emitted. Only ROOT nodes get coordinates — the rest are placed at runtime
+// by their structural relations.
+export const InstantiateOntologyInputSchema = z.object({
+    doc: z.record(z.string(), z.unknown()).describe('The design graph: pp:nodes / pp:edges (DesignGraph.toJsonLd shape), or { nodes, edges }, or nodes carrying inline pp: relation properties.'),
+    canvas: z.object({
+        width: z.number().positive(),
+        height: z.number().positive(),
+    }).optional().describe('Canvas size used to tile component roots (default 1080×1080).'),
+    defaultGeometry: z.record(z.string(), z.object({
+        width: z.number(),
+        height: z.number(),
+    })).optional().describe('Per-type default { width, height } overrides (e.g. { text: { width: 300, height: 60 } }).'),
+});
+// Relational-density lint of the LIVE scene (S12-E2). Reports how much of the scene
+// participates in the relation graph and suggests structural relations for unrelated
+// items already sitting in a structural configuration. Advisory (nothing applied).
+export const LintSceneInputSchema = z.object({
+    eps: z.number().positive().optional().describe('Bounds-match tolerance in px for structural-configuration detection (default 4).'),
+    cap: z.number().int().positive().optional().describe('Max number of suggestions to return, ranked by confidence (default 20).'),
+});
+// Media (video/audio) via window.PinePaperAgent. Agent-facing surface is URL-based
+// (the agent can't hand over a File). Uploaded media are first-class canvas items.
+export const MediaInputSchema = z.object({
+    action: z.enum(['upload_video', 'upload_audio', 'list', 'remove', 'set_playback_rate', 'set_clip'])
+        .describe("'upload_video' / 'upload_audio' (from a URL) · 'list' media · 'remove' by id · 'set_playback_rate' · 'set_clip' (re-trim an existing clip)"),
+    url: z.string().url().optional().describe('Media URL — required for upload_video / upload_audio (fetched then imported).'),
+    id: z.string().optional().describe('Media id — required for remove / set_playback_rate / set_clip.'),
+    rate: z.number().min(0.25).max(4).optional().describe('Playback rate 0.25–4 — required for set_playback_rate.'),
+    inPoint: z.number().min(0).optional().describe('Clip in-point in media-time seconds — required for set_clip.'),
+    outPoint: z.number().min(0).optional().describe('Clip out-point in media-time seconds — required for set_clip.'),
+    // upload_video placement
+    position: PositionSchema.optional().describe('Canvas position — upload_video.'),
+    scale: z.number().positive().optional().describe('Scale factor — upload_video.'),
+    timeOffset: z.number().optional().describe('Start offset on the timeline in seconds — upload_video / upload_audio.'),
+    clipInPoint: z.number().optional().describe('Trim in-point in seconds — upload_video.'),
+    clipOutPoint: z.number().optional().describe('Trim out-point in seconds — upload_video.'),
+    // upload_audio
+    volume: z.number().min(0).max(1).optional().describe('Volume 0–1 (default 1) — upload_audio.'),
+    loop: z.boolean().optional().describe('Loop playback (default true) — upload_audio.'),
+    muted: z.boolean().optional().describe('Start muted (default false) — upload_audio.'),
+})
+    .refine((v) => !(v.action === 'upload_video' || v.action === 'upload_audio') || !!v.url, { message: 'upload requires url', path: ['url'] })
+    .refine((v) => !(v.action === 'remove' || v.action === 'set_playback_rate' || v.action === 'set_clip') || !!v.id, { message: 'this action requires id', path: ['id'] })
+    .refine((v) => v.action !== 'set_playback_rate' || v.rate !== undefined, { message: 'set_playback_rate requires rate', path: ['rate'] })
+    .refine((v) => v.action !== 'set_clip' || (v.inPoint !== undefined && v.outPoint !== undefined && v.outPoint > v.inPoint), { message: 'set_clip requires inPoint and outPoint with outPoint > inPoint', path: ['outPoint'] });
+// =============================================================================
+// ONE-SHOT IMAGE OPS (crop / chroma key — Track A agent parity, 2026-07-31)
+// =============================================================================
+export const CropImageInputSchema = z.object({
+    itemId: z.string().describe('Registry id of the raster item (or a group containing one).'),
+    rect: z.object({
+        x: z.number().describe('Left edge, canvas coordinates'),
+        y: z.number().describe('Top edge, canvas coordinates'),
+        width: z.number().positive().describe('Crop width in canvas units'),
+        height: z.number().positive().describe('Crop height in canvas units'),
+    }).describe('Crop rectangle in project (canvas) coordinates — clamped into the image bounds.'),
+    aspectRatio: z.enum(['free', '1:1', '16:9', '9:16', '4:3', '3:4', '3:2', '2:3']).optional()
+        .describe('Optional aspect-ratio constraint applied to the rect.'),
+});
+export const ChromaKeyInputSchema = z.object({
+    itemId: z.string().describe('Registry id of the raster item (or a group containing one).'),
+    color: z.string().optional()
+        .describe("Key color: '#rrggbb' or preset name (green, chromaGreen, blue, chromaBlue, magenta). Default: pure green."),
+    threshold: z.number().min(0).max(255).optional()
+        .describe('Color-distance threshold for full transparency. Omit to auto-estimate from the image.'),
+    smoothing: z.number().min(0).max(100).optional()
+        .describe('Edge-smoothing range past the threshold. Omit to auto-estimate.'),
+});
+// Rigging (skeletons, bones, IK, breakdown-pose keyframes) via app.riggingSystem.
+// One consolidated tool: build a skeleton, then pose/animate it. The S12 breakdown-pose
+// options (favor/breakdown/curve/boneOffsets/movingHold/holdDrift) ride add_pose_keyframe.
+export const RiggingInputSchema = z.object({
+    action: z.enum([
+        'create_skeleton', 'add_bone', 'attach_item', 'create_ik_chain',
+        'add_pose_keyframe', 'set_target_path', 'save_pose', 'save_shape_key',
+    ]).describe('Rigging operation'),
+    // identifiers
+    skeletonId: z.string().optional().describe('Skeleton id — required for every action except create_skeleton.'),
+    boneId: z.string().optional().describe('Bone id — attach_item.'),
+    itemId: z.string().optional().describe('Canvas item id — attach_item.'),
+    chainId: z.string().optional().describe('IK chain id — set_target_path.'),
+    name: z.string().optional().describe('Name — create_skeleton / add_bone / create_ik_chain / save_pose / save_shape_key.'),
+    // create_skeleton
+    rootPosition: PositionSchema.optional().describe('Skeleton root position (default {x:400,y:300}) — create_skeleton.'),
+    // add_bone
+    parentBoneId: z.string().optional().describe('Parent bone id (omit for root) — add_bone.'),
+    length: z.number().positive().optional().describe('Bone length px (default 80) — add_bone.'),
+    angle: z.number().optional().describe('Bone rest angle in degrees — add_bone.'),
+    flexibility: z.number().min(0).max(1).optional().describe('0 rigid … 1 fully flexible — add_bone.'),
+    segments: z.number().int().min(0).optional().describe('Curve segments (0 = auto) — add_bone.'),
+    // attach_item
+    attachPoint: z.number().min(0).max(1).optional().describe('Position along bone 0=joint…1=tip (default 0.5) — attach_item.'),
+    // create_ik_chain
+    boneIds: z.array(z.string()).min(2).optional().describe('Ordered bone ids (≥2) — create_ik_chain.'),
+    solverType: z.enum(['fabrik', 'two_bone', 'ccd']).optional().describe('IK solver (default fabrik) — create_ik_chain.'),
+    iterations: z.number().int().positive().optional().describe('Solver iterations (default 10) — create_ik_chain.'),
+    tolerance: z.number().positive().optional().describe('Solver tolerance px (default 0.5) — create_ik_chain.'),
+    strength: z.number().optional().describe('Chain strength 0..1 (default 1) — create_ik_chain.'),
+    poleVector: PositionSchema.optional().describe('Pole vector hint — create_ik_chain.'),
+    // add_pose_keyframe
+    time: z.number().optional().describe('Keyframe time in seconds — add_pose_keyframe.'),
+    pose: z.union([z.string(), z.record(z.string(), z.number())]).optional().describe('A saved pose id, or a { boneId: angleDeg } map — add_pose_keyframe.'),
+    easing: z.string().optional().describe('Named easing (default linear) — add_pose_keyframe.'),
+    favor: z.number().min(-1).max(1).optional().describe('Breakdown spacing bias −1..1 (− favors prev key, + favors next) — add_pose_keyframe.'),
+    breakdown: z.boolean().optional().describe('Mark as a breakdown pose (vs a storytelling key) — add_pose_keyframe.'),
+    curve: z.array(z.number()).optional().describe('Per-segment cubic-bezier ease [x1,y1,x2,y2] (overrides named easing) — add_pose_keyframe.'),
+    boneOffsets: z.record(z.string(), z.number()).optional().describe('Per-bone lag { boneId: 0..0.95 } for overlap/follow-through — add_pose_keyframe.'),
+    movingHold: z.boolean().optional().describe('Hold drifts toward the next key instead of dead-stopping — add_pose_keyframe.'),
+    holdDrift: z.number().optional().describe('Fraction toward the next key the moving hold drifts (default 0.06) — add_pose_keyframe.'),
+    // set_target_path
+    waypoints: z.array(z.object({
+        x: z.number(), y: z.number(),
+        out: PositionSchema.optional(),
+        in: PositionSchema.optional(),
+    })).optional().describe('IK effector path waypoints with optional bezier tangents — set_target_path.'),
+    duration: z.number().positive().optional().describe('Seconds to traverse the path (default 1) — set_target_path.'),
+    loop: z.boolean().optional().describe('Cycle the path — set_target_path.'),
+})
+    .refine((v) => v.action === 'create_skeleton' || !!v.skeletonId, { message: 'this action requires skeletonId', path: ['skeletonId'] })
+    .refine((v) => v.action !== 'add_bone' || v.skeletonId != null, { message: 'add_bone requires skeletonId', path: ['skeletonId'] })
+    .refine((v) => v.action !== 'attach_item' || (!!v.boneId && !!v.itemId), { message: 'attach_item requires boneId and itemId', path: ['boneId'] })
+    .refine((v) => v.action !== 'create_ik_chain' || (!!v.boneIds && v.boneIds.length >= 2), { message: 'create_ik_chain requires boneIds (≥2)', path: ['boneIds'] })
+    .refine((v) => v.action !== 'add_pose_keyframe' || (v.time !== undefined && v.pose !== undefined), { message: 'add_pose_keyframe requires time and pose', path: ['pose'] })
+    .refine((v) => v.action !== 'set_target_path' || (!!v.chainId && !!v.waypoints), { message: 'set_target_path requires chainId and waypoints', path: ['waypoints'] });
 //# sourceMappingURL=schemas.js.map