@pinepaper.studio/mcp-server 1.6.7 → 1.6.8

package/dist/types/schemas.js

@@ -98,6 +98,32 @@ export const ItemTypeSchema = z.enum([
     'diamond',
     'arrow',
     'heart',
+    // THE REST OF THE ENGINE'S SHAPE REGISTRY — same argument as the two below,
+    // applied to shapes that were already being drawn.
+    //
+    // js/shapes/index.js registers 34 shapes across five modules. Flowchart, UML
+    // and network route through pinepaper_create_diagram_shape, so 23 were
+    // reachable. These eleven were reachable from NOTHING: three basic shapes,
+    // and the whole `comment` module — every speech bubble, thought bubble and
+    // callout the engine can draw.
+    //
+    // The engine was never the limit. PinePaper.create() delegates any registry
+    // type — "basic shapes, comment/bubble shapes, etc." in its own comment —
+    // and already forwards `tailDirection` and `tailSize`, which exist only for
+    // bubbles. It has been able to draw a speech bubble the whole time; no tool
+    // could name one, so an agent asked for a comic panel or an annotated
+    // diagram had to hand-build the outline or decline.
+    'disk',
+    'circle-outline',
+    'arrow-right',
+    'speech-bubble',
+    'speech-bubble-square',
+    'speech-bubble-pointed',
+    'thought-bubble',
+    'double-bubble',
+    'quote-bubble',
+    'comment-box',
+    'callout-box',
     // 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
@@ -242,6 +268,7 @@ export const KeyframeSchema = z.object({
 // 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.
+/** Engine parity ENFORCED BY src/__tests__/unit/relation-parity.test.ts (fixture: engine-relations.txt). */
 export const RelationTypeSchema = z.enum([
     // --- Motion, spatial and transform ---
     'orbits',
@@ -255,6 +282,7 @@ export const RelationTypeSchema = z.enum([
     'anchored_in_world',
     'spring_follow',
     'repels',
+    'attracts',
     'wiggle',
     // --- Animation and sequencing ---
     'animates',
@@ -540,6 +568,13 @@ export const MovesAlongPathParamsSchema = z.object({
 // || opts) — so they must survive validation.
 export const EquationPathInputSchema = z.object({
     ...equationSpecShape,
+    solveOde: z.object({
+        equations: z.union([z.string(), z.array(z.string())]).describe("The derivative(s), as expressions — e.g. 'y' for dy/dt = y, or ['v', '-9.8'] for a falling body."),
+        initialState: z.array(z.number()).describe('The state at t = 0, one number per equation.'),
+        tEnd: z.number().optional().describe('How far to integrate (default 10).'),
+        dt: z.number().optional().describe('Step size (default 0.01). Smaller is more accurate and slower.'),
+        method: z.enum(['rk4', 'euler']).optional().describe("Integrator (default 'rk4' — fourth-order Runge-Kutta). 'euler' is faster and visibly wrong on anything stiff."),
+    }).optional().describe('Numerically integrate an ODE instead of plotting a closed-form expression, and return the SOLUTION rather than drawing it. The trajectory comes back as data, so a caller can inspect it, feed it to a path, or drive keyframes with it.'),
     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, …)'),
@@ -563,12 +598,22 @@ export const DrivenByParamsSchema = z.object({
 // 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.
+// (replay-stable).
+//
+// THERE IS NO LONGER A PER-FRAME FALLBACK FOR random(). The engine used to
+// build a `new Function` from the scene's own text on the per-frame path, which
+// made the authoring language JavaScript rather than the grammar the other
+// renderers speak — `^` was bitwise XOR there and exponentiation everywhere
+// else, so one scene string drew two different pictures, and `random()` could
+// not be refused, so a scene could never be baked or exported deterministically.
+// Both paths now go through the same parser, `random` is rejected by name, and
+// `^` is exponentiation. This comment said "falls back to per-frame" until
+// 2026-09-15; it described behaviour the engine had removed.
 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"'),
+    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". `^` is exponentiation, not XOR. Available: sin cos tan asin acos atan sinh cosh tanh abs floor ceil round trunc sign sqrt cbrt exp log log2 log10 · pow min max atan2 hypot clamp mod · fract pingpong inverseLerp remap noise sec csc cot · easeInQuad easeOutQuad easeInOutQuad easeInCubic easeOutCubic easeInOutCubic · constants PI, E, TAU. `random()` is REJECTED by name on both the signal and per-frame paths — a scene that cannot render the same way twice can never be baked or exported deterministically.'),
     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)'),
+    signal: z.boolean().optional().default(false).describe('Deterministic IR mode — parse expression to IR, evaluate as pure f(t). Both modes now use the same parser and the same grammar; signal additionally makes the result bakeable as a pure function of time.'),
 });
 // =============================================================================
 // EVENT-DRIVEN SCENE CHAINS (FxTool S11). Source of each is a pp:event.
@@ -701,6 +746,7 @@ export const ExecuteCustomCodeInputSchema = z.object({
 // =============================================================================
 // GENERATOR TYPES
 // =============================================================================
+/** Engine parity ENFORCED BY src/__tests__/unit/preflight-gate-parity.test.ts (fixture: engine-generators.txt). */
 export const GeneratorNameSchema = z.enum([
     // Classic generators
     'drawSunburst',
@@ -775,6 +821,24 @@ export const GeneratorNameSchema = z.enum([
     'drawScatter',
     'drawStackedWaves',
     'draw3DParametricCurve',
+    // THE GATE WAS NARROWER THAN THE ENGINE, and generatorName is a hard
+    // preflight gate — an unlisted name is rejected before the browser sees
+    // it. The engine registers 74 generators and this offered 64, so these
+    // ten were live and uncallable. Seven are the GPU field generators, which
+    // is the expensive half: create_item's `field` type, design_medium's flow
+    // fields and the design graph's own recipe example all name drawGPUTunnel,
+    // so a captured scene recording `generator: 'drawGPUTunnel'` could not be
+    // replayed through the tool that exists to replay it.
+    'draw3DWorld',
+    'drawCharacterEyes',
+    'drawGPUCaustics',
+    'drawGPUClouds',
+    'drawGPUOcean',
+    'drawGPUPlasma',
+    'drawGPUStarfield',
+    'drawGPUTunnel',
+    'drawGPUVoronoi',
+    'drawRiggedCharacter',
 ]).describe('Background generator name');
 // ---------------------------------------------------------------------------
 // Generator parameter schemas — Phase 1 (enhanced existing)
@@ -927,6 +991,7 @@ export const NoiseTextureParamsSchema = z.object({
 // =============================================================================
 // EFFECT TYPES
 // =============================================================================
+/** Engine parity ENFORCED BY src/__tests__/unit/preflight-gate-parity.test.ts (fixture: engine-effects.txt). */
 export const EffectTypeSchema = z.enum([
     'sparkle',
     'blast',
@@ -952,6 +1017,13 @@ export const EffectTypeSchema = z.enum([
     'vortex',
     'rain_veil',
     'caustics',
+    // ink_bleed was the LAST aura and the gate rejected it. The engine's own
+    // comment says it 'has shipped unroutable through applyEffect since it was
+    // added' — past tense, describing a bug it then fixed: _publishNames()
+    // publishes every aura definition, and PinePaper.applyEffect warms the
+    // subsystem before routing, so all eight route now. Reading the comment
+    // would have kept it out; reading the mechanism put it in.
+    'ink_bleed',
 ]).describe('Visual effect type (particle effects + shader auras)');
 export const SparkleParamsSchema = z.object({
     color: ColorSchema.optional().default('#fbbf24').describe('Sparkle color'),
@@ -1069,8 +1141,26 @@ export const DeleteItemInputSchema = z.object({
 export const AddRelationInputSchema = z.object({
     sourceId: z.string().describe('Registry ID of the source item'),
     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,
+    relationType: RelationTypeSchema.optional().describe('The relation to create. Required unless presetId is given.'),
     params: z.record(z.unknown()).optional().default({}),
+    presetId: z.string().optional()
+        .describe("Apply a community relation PRESET instead of naming a type and params yourself — a tuned motion someone already got right, with its symbols exposed as knobs. List them with pinepaper_query_capabilities { action: 'catalogue', catalogue: 'relation_presets' }. The preset decides the relationType, so relationType is not needed and is ignored if sent."),
+    presetValues: z.record(z.number()).optional()
+        .describe('presetId: symbol → number. Any symbol you omit takes the midpoint of its declared range, so a preset applies sensibly with no values at all.'),
+})
+    .refine((v) => !!v.relationType || !!v.presetId, { message: 'relationType is required unless presetId is given', path: ['relationType'] })
+    // A PRESET IS A SELF-RELATION and has no target slot. applyRelationPreset
+    // takes (item, presetId, values) — pass a targetId alongside one and the
+    // emitted call has nowhere to put it, so a caller adopting a preset for a
+    // two-item relation silently got a self-relation with no diagnostic.
+    // Refused here rather than dropped there.
+    .refine((v) => !v.presetId || v.targetId == null, {
+    message: 'presetId cannot be combined with targetId — a relation preset applies to one item. Name the relationType directly for a two-item relation.',
+    path: ['targetId'],
+})
+    .refine((v) => !v.presetId || !v.relationType, {
+    message: 'presetId cannot be combined with relationType — the preset decides its own type. Send one or the other.',
+    path: ['relationType'],
 });
 // Remove Relation
 export const RemoveRelationInputSchema = z.object({
@@ -1103,6 +1193,41 @@ 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.'),
 });
+// Character — a symbol and some beats, expanded against the design graph.
+//
+// Mirrors `pinepaper_character`'s inputSchema field for field. Only `concept`
+// is required: everything else has a defensible default, and the point of the
+// tool is that a caller who knows nothing but the name of a figure gets one.
+export const CharacterBeatSchema = z.object({
+    at: z.number().describe('When, in seconds'),
+    channel: z.string().describe('A channel the concept declares — blink, say, headTurn, bob, tailFlick…'),
+    until: z.number().optional().describe('For a channel that occupies a span rather than an instant'),
+    value: z.number().optional().describe('How far, for a channel that takes a magnitude'),
+});
+export const CharacterInputSchema = z.object({
+    concept: z.string().describe('Concept id from the design graph, e.g. "pp:Character" or "pp:Pigeon".'),
+    at: z.object({ x: z.number().optional(), y: z.number().optional() }).optional().describe('Where the figure stands.'),
+    height: z.number().optional().describe('Drawn height in pixels.'),
+    id: z.string().optional().describe('Prefix for the created items (default: the concept name).'),
+    style: z.string().optional().describe('Style id for the depiction (default: the concept\'s own).'),
+    variant: z.string().optional().describe('Depiction variant (default: "default").'),
+    durationSeconds: z.number().optional().describe('Length of the piece, so every track spans it.'),
+    beats: z.array(CharacterBeatSchema).optional().describe('What happens, in order.'),
+    timings: z.array(z.object({ at: z.number(), until: z.number().optional() })).optional()
+        .describe('Word or syllable timings from a voice track; each entry drives one mouth opening.'),
+    // THESE WERE HANDLED AND UNDECLARED. resolveCharacter reads all four and its
+    // own comment says a call written the way the rest of the vocabulary reads
+    // must not land dead-centre at the default size — but zod strips unknown
+    // keys, so `{concept, position, scale}` did exactly that, silently.
+    position: z.object({ x: z.number().optional(), y: z.number().optional() }).optional()
+        .describe('Where the figure stands. A synonym for `at`, because the rest of this surface says position; `at` wins if both are sent.'),
+    scale: z.number().optional()
+        .describe('Size as a multiplier of the 300px default, for callers who think in scale rather than pixels. `height` wins if both are sent.'),
+    palette: z.record(z.string(), z.string()).optional()
+        .describe("Override the depiction's own colours: part id → colour. Only the parts you name change."),
+    ink: z.string().optional()
+        .describe("Ink colour for the stroked copies that make the figure read as drawn rather than filled. The style supplies its own; this overrides it."),
+});
 // Motion Capture (BVH)
 //
 // FxTool exposes two distinct operations and the difference is the whole point:
@@ -1703,6 +1828,10 @@ export const AgentPlatformSchema = z.enum([
  */
 export const AgentExportFormatSchema = z.enum([
     'svg', 'png', 'gif', 'mp4', 'webm', 'pdf',
+    // AUDIO-ONLY. The soundtrack on its own, with no frames rendered — so
+    // platform dimensions, framing and quality do not apply to it, and no
+    // platform preset resolves to it. It has to be asked for by name.
+    'wav',
 ]).describe('Export file format');
 /**
  * Screenshot policy for agent jobs
@@ -1881,6 +2010,17 @@ export const AgentBatchExecuteInputSchema = z.object({
  * could not. This brings the two in line.
  */
 export const GIF_MAX_DURATION_S = 15;
+/**
+ * Longest mp4/webm export the tool will accept, in seconds.
+ *
+ * Was 60. A ten-minute export is only reachable because the bytes no longer
+ * cross the browser→server bridge as one base64 string: above an inline
+ * ceiling the studio keeps the file in its export store and the handler pages
+ * it out in chunks. On a studio with no export store the emitted code refuses
+ * by name with the numbers instead, so raising this cap cannot turn into an
+ * out-of-memory — it turns into a message naming the ceiling and what to do.
+ */
+export const VIDEO_MAX_DURATION_S = 600;
 /**
  * Smart export input schema
  */
@@ -1890,10 +2030,29 @@ 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 for mp4/webm, max ${GIF_MAX_DURATION_S} for gif (GIF is not codec-bounded, so file size scales with frames × dimensions). Static formats (png/svg/pdf) ignore this.`),
-    estimateOnly: z.boolean().optional().default(false).describe('Preflight only: return the estimated file size for these EXACT settings and render nothing. Use before a long or high-quality export to check the size first. Modeled for mp4/webm/gif; png/pdf/svg return confidence "none" because no dimension-based model exists for them.'),
+    duration: z.number().min(0.5).max(VIDEO_MAX_DURATION_S).optional().default(5).describe(`Video duration in seconds for animated formats (mp4/webm/gif). Default 5. Max ${VIDEO_MAX_DURATION_S} for mp4/webm, max ${GIF_MAX_DURATION_S} for gif (GIF is not codec-bounded, so file size scales with frames × dimensions, and it cannot stream to the export store). Static formats (png/svg/pdf) ignore this. Past roughly a minute the export is held in the studio's export store and paged back to a file rather than returned inline; a studio without that store refuses by name and says so.`),
+    estimateOnly: z.boolean().optional().default(false).describe('Preflight only: return the estimated file size for these EXACT settings and render nothing. Use before a long or high-quality export to check the size first. Modeled for mp4/webm/gif; png/pdf/svg return confidence "none" because no dimension-based model exists for them; wav is reported as "exact", because uncompressed PCM size is arithmetic rather than a guess.'),
+    sampleRate: z.number().int().positive().optional().describe('wav only: samples per second (default 48000). Ignored by every other format.'),
+    bitDepth: z.union([z.literal(16), z.literal(32)]).optional().describe('wav only: 16 (default) or 32-bit float. Ignored by every other format.'),
 }).describe('Smart export options')
     .superRefine((val, ctx) => {
+    // wav carries no picture, so the visual knobs are not merely ignored — a
+    // caller who set them believes something about the output that is not
+    // true. Said once, rather than silently dropped.
+    if (val.format === 'wav' && val.framing === 'camera') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['framing'],
+            message: 'framing does not apply to a wav export — it renders no frames. Drop framing, or export mp4/webm if you want the picture with the sound.',
+        });
+    }
+    if (val.format !== 'wav' && (val.sampleRate !== undefined || val.bitDepth !== undefined)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['sampleRate'],
+            message: `sampleRate and bitDepth apply only to format "wav" (got "${val.format}").`,
+        });
+    }
     if (val.format === 'gif' && val.duration > GIF_MAX_DURATION_S) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
@@ -2352,8 +2511,12 @@ export const QueryOntologyInputSchema = z.object({
 });
 // 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)"),
+    action: z.enum(['list', 'choose', 'coverage', 'find', 'catalogue', 'studio']).default('list')
+        .describe("'list' (all capabilities or filtered by kind) · 'choose' (context/mood-weighted recommendation) · 'coverage' (breakdown of indexable capabilities) · 'find' (lookup by key) · 'catalogue' (the registries the aggregate does NOT gather — see `catalogue`) · 'studio' (which engine METHODS this studio has, so you learn what will refuse BEFORE calling it)"),
+    catalogue: z.enum([
+        'rig_presets', 'shader_effects', 'stroke_decorations', 'precomps', 'images',
+        'segment_edit_kinds', 'shatter_orders', 'world_meshes', 'relation_presets',
+    ]).optional().describe("action 'catalogue': which registry to read. These sit OUTSIDE app.getCapabilities' aggregate — that one already covers styles, effects, deforms, entrances, animations, collages, palettes, masks, maskShapes and cutouts, and 'list' reaches all of those. Use this for the ones it does not gather: rig presets, shader effects, stroke decorations, the precomp list, the image library, segment-edit kinds, shatter orders and world meshes."),
     kind: z.union([
         z.string(),
         z.array(z.string()),
@@ -2663,6 +2826,28 @@ export const ProvenanceInputSchema = z.object({
     sourceRef: z.string().optional(),
     meta: z.record(z.string(), z.unknown()).optional(),
 });
+/**
+ * The stitches the thread medium publishes — ONE list, because it had four copies.
+ *
+ * Mirrors FxTool's `STITCH_OPS` in js/core/ThreadPainting.js — ENFORCED BY
+ * src/__tests__/unit/preflight-gate-parity.test.ts against the fixture
+ * src/__tests__/fixtures/engine-stitches.txt, both directions, with a
+ * guard-the-guard that plants a seventh stitch and asserts the comparison
+ * fails. A parity claim that cites the test enforcing it is checkable in one
+ * command; one that does not is a memory of someone having checked once, and
+ * this sentence was that memory for six commits. The table is
+ * vocabulary `applyThreadPainting` dispatches on; it refuses an unknown name
+ * rather than falling through to a default fill.
+ *
+ * There were four copies of this list here — two Zod enums and their two JSON
+ * mirrors — and fixing one left `pinepaper_compose` unable to ask for two
+ * stitches `apply_thread` could. The engine had the identical split for the
+ * identical reason: `MEDIA.thread.stitches` was hardcoded to the same stale
+ * four while STITCH_OPS published six (FxTool 6aaa9069). Two repos, four
+ * copies, one list, drifted the same direction on the same day — so it is
+ * declared once here and spread everywhere it is needed.
+ */
+export const THREAD_STITCHES = ['longAndShort', 'satin', 'seed', 'stem', 'runningSeam', 'crossStitch'];
 export const SceneDiffInputSchema = z.object({
     /** 'history' compares two undo states; 'version' compares live vs a saved version. */
     action: z.enum(['history', 'version']),
@@ -2714,7 +2899,7 @@ export const ComposeInputSchema = z.object({
      * 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.'),
+    stitch: z.enum(THREAD_STITCHES).optional().describe('Which stitch, when medium is thread. Default longAndShort. The same six pinepaper_design_medium offers — call its list_stitches for each one.'),
     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({
@@ -3095,8 +3280,17 @@ export const MediaInputSchema = z.object({
  * platform impossibility, not an omission.
  */
 export const TextStyleInputSchema = z.object({
-    action: z.enum(['apply_style', 'set_font_axes', 'list_styles'])
-        .describe("'apply_style' (stacked-layer display style) · 'set_font_axes' (variable-font weight/width/slant) · 'list_styles' (styles + palettes + axes, for pickers)"),
+    action: z.enum(['apply_style', 'set_font_axes', 'list_styles', 'cursive', 'wrap', 'unwrap', 'to_collage'])
+        .describe("'apply_style' (stacked-layer display style) · 'set_font_axes' (variable-font weight/width/slant) · 'list_styles' (styles + palettes + axes, for pickers) · 'cursive' (draw text as STROKED handwriting — a path, not a glyph, so it can be drawn on over time) · 'wrap' / 'unwrap' (break a text item to a width, reversibly) · 'to_collage' (turn an EXISTING text item into a letter collage, keeping its place)"),
+    text: z.string().optional().describe('cursive: the words to write. to_collage: the text to build the collage from, if it differs from the item.'),
+    maxWidth: z.number().optional().describe('wrap: the width to break at, in canvas units. unwrap restores the original single line, so this is not destructive.'),
+    cursiveOptions: z.object({
+        x: z.number().optional(), y: z.number().optional(),
+        scale: z.number().optional().describe('Size multiplier (default 1).'),
+        strokeColor: z.string().optional().describe("Ink colour (default '#ffffff')."),
+        strokeWidth: z.number().optional().describe('Pen width (default 2).'),
+    }).optional().describe('cursive: where and how it is written. The result is a STROKED PATH, so pinepaper_animate\'s draw-on and pinepaper_path\'s outline_stroke both apply to it — which is the reason to prefer it over a script font.'),
+    collageOptions: z.record(z.string(), z.unknown()).optional().describe('to_collage: style, palette and the rest, same vocabulary as pinepaper_create_letter_collage.'),
     itemId: z.string().optional().describe('Text item id — apply_style / set_font_axes.'),
     styleKey: z.string().optional().describe("apply_style: style name from list_styles (e.g. 'stacked', 'arcade' — the pixel/arcade styles suggest their own face)."),
     palette: z.union([z.string(), z.array(z.string())]).optional().describe('apply_style: a named colourway or an explicit color array.'),
@@ -3144,8 +3338,8 @@ export const DesignMediumInputSchema = z.object({
         .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."),
+    stitch: z.enum(THREAD_STITCHES).optional()
+        .describe("Which stitch, when the medium is thread. Default longAndShort. These six are THE_STITCH_OPS the engine publishes — call 'list_stitches' for each one's description and its own parameters. An unknown name is refused by the engine rather than quietly stitched as a default fill."),
     field: z.object({
         kind: z.enum(['radial', 'spine', 'constant']),
         cx: z.number().optional(), cy: z.number().optional(),
@@ -3161,6 +3355,17 @@ export const DesignMediumInputSchema = z.object({
     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.'),
+    // THE OPTIONS THE ENGINE READS AND NOTHING NAMED. ThreadPainting.paint reads
+    // every one of these; apply_thread passed ten of its eighteen, so eight
+    // controls existed and were unreachable — the same gap that made the stick
+    // kit's options source-only.
+    slant: z.number().optional().describe('apply_thread: stitch slant in DEGREES — satin (default 0) and stem (default 22). A satin fill laid at a slant is what separates embroidery from ruling.'),
+    overlap: z.number().min(0).optional().describe('apply_thread: how far consecutive stem stitches overlap (default 0.4) — what makes a stem outline read as rope rather than a dashed line.'),
+    stagger: z.number().min(0).max(1).optional().describe('apply_thread: offsets alternate longAndShort rows (default 0.5) — stops stitch ends lining up into seams down the fill.'),
+    gapLen: z.number().positive().optional().describe('apply_thread: gap between runningSeam stitches, px (default 4). With stitchLen, this is the dash rhythm of a machine seam.'),
+    gridSize: z.number().positive().optional().describe('apply_thread: crossStitch grid pitch, px (default 12) — the size of each X, and so the resolution of the whole fill.'),
+    roughness: z.number().min(0).optional()
+        .describe('apply_thread: hand wobble. Jitters every point of every stitch after the engine lays them, so the fill reads as sewn rather than plotted. 0 is machine-exact. Reproducible for a given seed. This one is applied by the tool, not the engine.'),
     // --- Hatching (pp: the p5.brush marks, as vector) ---
     //
     // `field` above is the THREAD direction field (radial/spine/constant) and is
@@ -3278,8 +3483,19 @@ export const GameInputSchema = z.object({
  * itself — the tool does not restate it, so it cannot drift.
  */
 export const World3DInputSchema = z.object({
-    action: z.enum(['create', 'describe', 'configure', 'add_actor', 'remove_actor', 'list_actors', 'set_actor_pose', 'set_camera', 'add_object', 'remove_object', 'remove_world'])
-        .describe("'create' (a preset world) · 'describe' (every parameter with type/range — CALL THIS before configure) · 'configure' (live deep-merge patch, schema-validated) · actor ops · 'set_camera' (follow|fixed|orbit) · object ops · 'remove_world'"),
+    action: z.enum([
+        'create', 'describe', 'configure', 'add_actor', 'remove_actor', 'list_actors', 'set_actor_pose',
+        'set_camera', 'add_object', 'remove_object', 'remove_world',
+        'extrude_path', 'lathe_path', 'list_meshes', 'remove_mesh',
+        'add_light', 'set_light', 'remove_light', 'list_lights',
+        'add_material', 'set_material', 'remove_material', 'list_materials',
+        'import_obj', 'import_gltf', 'list_mesh_clips', 'set_mesh_clip',
+        'set_nav_target', 'get_nav_target', 'ground_height', 'raycast',
+        'dolly_camera', 'pan_camera', 'world_to_canvas', 'canvas_to_ground',
+        'add_body', 'remove_body', 'list_bodies', 'step_physics', 'impulse', 'set_velocity', 'fire_projectile',
+        'line_of_sight', 'set_mesh_instances',
+    ])
+        .describe("'create' (a preset world) · 'describe' (every parameter with type/range — CALL THIS before configure) · 'configure' (live deep-merge patch, schema-validated) · actor ops · 'set_camera' (follow|fixed|orbit) · object ops · 'remove_world' · MESH AUTHORING: 'extrude_path' / 'lathe_path' turn a canvas path into real geometry, 'list_meshes', 'remove_mesh' · 'add_light' / 'set_light' / 'remove_light' / 'list_lights' (at most 8 point lights) · 'add_material' / 'set_material' / 'remove_material' / 'list_materials'"),
     spec: z.union([z.string(), z.record(z.string(), z.unknown())]).optional().describe("create: a preset id ('forest', 'snowMountain', …) or a full world spec object."),
     character: z.union([z.boolean(), z.record(z.string(), z.unknown())]).optional().describe('create: include the walkable character (true/config).'),
     patch: z.record(z.string(), z.unknown()).optional().describe('configure: partial world spec, deep-merged and validated — a wrong key errors naming the right one.'),
@@ -3291,18 +3507,372 @@ 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?, metalness?, roughness?, emissiveIntensity? } (defaults to sitting on the terrain).'),
+    object: z.record(z.string(), z.unknown()).optional().describe("add_object: { x, z, height?, color?, y? } (defaults to sitting on the terrain). metalness and roughness are ACCEPTED AND IGNORED here: a plain object is drawn by the prop shader, which has no such uniform, so they are stored and listed and never reach a pixel. They render on the MESH path only — 'extrude_path' / 'lathe_path' and imported geometry. Use a material there instead of setting them here and seeing nothing."),
     objectId: z.string().optional().describe('remove_object: the object id.'),
+    // --- Mesh authoring: a canvas path becomes real geometry -----------------
+    pathId: z.string().optional().describe("extrude_path / lathe_path: the canvas path to turn into geometry. Extrude sweeps it along depth; lathe revolves its profile around the Y axis. The path is unchanged — the mesh is new."),
+    mesh: z.object({
+        id: z.string().optional().describe('Mesh id (generated if omitted).'),
+        depth: z.number().optional().describe('extrude_path: how far to sweep, in world units.'),
+        unitsPerPixel: z.number().optional().describe('Canvas pixels → world units. The whole scale relationship between the drawing and the world.'),
+        caps: z.boolean().optional().describe('extrude_path: close the two ends. A capped extrude is a solid; an uncapped one is a ribbon.'),
+        segments: z.number().optional().describe('extrude_path: segments along the sweep · lathe_path: segments around the revolution.'),
+        arc: z.number().optional().describe('lathe_path: how far round to revolve, in degrees. 360 is a full solid of revolution; less leaves it open.'),
+        flatness: z.number().optional().describe('Curve flattening tolerance when the path is sampled into rings — smaller is finer and heavier.'),
+        x: z.number().optional().describe('Placement in world space.'),
+        y: z.number().optional().describe('Placement in world space (omit to let it sit where the terrain puts it).'),
+        z: z.number().optional().describe('Placement in world space.'),
+        rotY: z.number().optional().describe('Rotation about the Y axis, in RADIANS — the value is stored raw and fed straight to cos()/sin() in the shader, with no conversion anywhere on the path. This is an exception to the degrees convention every other angle in this surface follows; pass rotYDegrees instead if you would rather write degrees. (`arc` on lathe_path IS degrees — the engine converts that one.)'),
+        rotYDegrees: z.number().optional().describe('Rotation about the Y axis in degrees, converted to radians for you. Convenience only — the engine and the mesh provenance record both speak rotY in radians, so a round-tripped capture uses rotY.'),
+        scale: z.number().optional().describe('Uniform scale applied after the geometry is built.'),
+        doubleSided: z.boolean().optional().describe('Draw back faces too. An uncapped extrude usually wants this.'),
+    }).optional().describe("extrude_path / lathe_path options. These field names ARE the ones the engine records as the mesh's provenance, so a mesh captured in a design graph can be rebuilt by spreading its meshProvenance.opts straight back in here."),
+    meshId: z.string().optional().describe('remove_mesh: the mesh id.'),
+    // --- Lights ---------------------------------------------------------------
+    light: z.object({
+        id: z.string().optional().describe('Light id (generated if omitted).'),
+        x: z.number().optional().describe('World-space x (default 0).'),
+        y: z.number().optional().describe('World-space y (default 3 — above the ground, not on it).'),
+        z: z.number().optional().describe('World-space z (default 0).'),
+        color: z.array(z.number()).length(3).optional().describe('Linear RGB, each component ≥ 0 (default [1, 0.86, 0.62], a warm lamp).'),
+        intensity: z.number().optional().describe('Brightness (default 6).'),
+        range: z.number().optional().describe('How far the light reaches, in world units (default 20).'),
+    }).optional().describe('add_light / set_light: the light spec. At most 8 point lights exist at once — the shader array is fixed-size, so a ninth is refused by name rather than ignored.'),
+    lightId: z.string().optional().describe('set_light / remove_light: the light id.'),
+    // --- Materials ------------------------------------------------------------
+    material: z.object({
+        id: z.string().optional().describe('Material id (generated if omitted).'),
+        color: z.array(z.number()).length(3).optional().describe('Base colour, linear RGB (default [0.8, 0.8, 0.82]).'),
+        emissive: z.array(z.number()).length(3).optional().describe('Light the surface emits regardless of the scene (default [0, 0, 0]).'),
+        metalness: z.number().min(0).max(1).optional().describe('0 dielectric → 1 metal.'),
+        roughness: z.number().min(0).max(1).optional().describe('0 mirror → 1 fully diffuse. Floored at 0.045: a true zero is a numerically unstable mirror.'),
+        emissiveIntensity: z.number().min(0).optional().describe('Scales `emissive` before the frame is built, so it reaches every path that draws emissive.'),
+        clearcoat: z.number().min(0).max(1).optional().describe('A lacquer layer over the base — car paint, varnished wood.'),
+        clearcoatRoughness: z.number().min(0).max(1).optional().describe("The coat's own roughness. NOT floored like the base, so a mirror-smooth lacquer stays expressible."),
+        sheenColor: z.array(z.number()).length(3).optional().describe('Retroreflective sheen colour — cloth, velvet.'),
+        sheenRoughness: z.number().min(0).max(1).optional().describe('How broad the sheen lobe is.'),
+    }).optional().describe("add_material / set_material: a NAMED, SHARED surface referenced by many objects, so one edit restyles all of them. metalness and roughness reach the shader on the MESH path only. There are no aoMapIntensity / normalScale / envMapIntensity knobs: each scales a map that does not exist, and a knob that scales nothing is worse than a missing one."),
+    materialId: z.string().optional().describe('set_material / remove_material: the material id.'),
+    // --- Import ---------------------------------------------------------------
+    source: z.string().optional().describe('import_obj: the OBJ file TEXT. import_gltf: a URL, or a data: URI of the .glb bytes.'),
+    importOptions: z.record(z.string(), z.unknown()).optional().describe('import_obj / import_gltf: placement and scale options, passed through to the engine.'),
+    clip: z.string().optional().describe('set_mesh_clip: which imported animation clip a skinned mesh plays.'),
+    crossfade: z.number().optional().describe('set_mesh_clip: seconds to blend out of the clip that was playing. The blend happens in LOCAL pose space — a palette cannot be blended after the fact.'),
+    // --- Navigation, picking and the camera ----------------------------------
+    navTarget: z.enum(['2d', '3d']).optional().describe("set_nav_target: which layer the pointer drives — '2d' the Paper canvas, '3d' the world."),
+    point: z.object({ x: z.number(), y: z.number(), z: z.number().optional() }).optional()
+        .describe('ground_height / canvas_to_ground / world_to_canvas: the point to convert. ground_height and canvas_to_ground read x and y (canvas) or x and z (world); world_to_canvas takes a world point.'),
+    origin: z.array(z.number()).length(3).optional().describe('raycast: ray origin in world space, [x, y, z].'),
+    direction: z.array(z.number()).length(3).optional().describe('raycast: ray direction in world space, [x, y, z]. Need not be normalised.'),
+    multiplier: z.number().optional().describe('dolly_camera: greater than 1 moves away, less than 1 moves closer.'),
+    dx: z.number().optional().describe('pan_camera: horizontal pan in SCREEN pixels.'),
+    dy: z.number().optional().describe('pan_camera: vertical pan in SCREEN pixels.'),
+    // --- Physics in the world -------------------------------------------------
+    body: z.record(z.string(), z.unknown()).optional()
+        .describe('add_body / fire_projectile: the body spec. Deliberately NARROW — a sphere or a capsule under gravity, colliding with the world (terrain, objects, actors, imported meshes). There is no stacking solver and no joints; for those use pinepaper_physics, which is the 2D world.'),
+    bodyId: z.string().optional().describe('remove_body / impulse / set_velocity: the body id.'),
+    vector: z.array(z.number()).length(3).optional().describe('impulse: the impulse to apply, [x, y, z]. set_velocity: the velocity to set, [x, y, z].'),
+    dt: z.number().optional().describe('step_physics: seconds to advance. Returns the contacts made and the bodies removed in that step.'),
+    from: z.array(z.number()).length(3).optional().describe('line_of_sight: the eye point, [x, y, z].'),
+    to: z.array(z.number()).length(3).optional().describe('line_of_sight: the target point, [x, y, z].'),
+    instances: z.array(z.array(z.number())).optional()
+        .describe('set_mesh_instances: one entry per copy, six numbers each — x, y, z, scale, rotY (RADIANS), and a free variant a shader may read for per-instance colour or phase.'),
 })
     .refine((v) => v.action !== 'configure' || !!v.patch, { message: 'configure requires patch', path: ['patch'] })
     .refine((v) => !['remove_actor', 'set_actor_pose'].includes(v.action) || !!v.actorId, { message: 'this action requires actorId', path: ['actorId'] })
     .refine((v) => v.action !== 'set_actor_pose' || !!v.pose, { message: 'set_actor_pose requires pose', path: ['pose'] })
     .refine((v) => v.action !== 'set_camera' || !!v.camera, { message: 'set_camera requires camera', path: ['camera'] })
     .refine((v) => v.action !== 'add_object' || !!v.object, { message: 'add_object requires object', path: ['object'] })
-    .refine((v) => v.action !== 'remove_object' || !!v.objectId, { message: 'remove_object requires objectId', path: ['objectId'] });
+    .refine((v) => v.action !== 'remove_object' || !!v.objectId, { message: 'remove_object requires objectId', path: ['objectId'] })
+    .refine((v) => !['extrude_path', 'lathe_path'].includes(v.action) || !!v.pathId, { message: 'this action requires pathId — the canvas path to turn into geometry', path: ['pathId'] })
+    .refine((v) => v.action !== 'remove_mesh' || !!v.meshId, { message: 'remove_mesh requires meshId', path: ['meshId'] })
+    .refine((v) => v.action !== 'add_light' || !!v.light, { message: 'add_light requires light', path: ['light'] })
+    .refine((v) => v.action !== 'set_light' || (!!v.lightId && !!v.light), { message: 'set_light requires lightId and light', path: ['lightId'] })
+    .refine((v) => v.action !== 'remove_light' || !!v.lightId, { message: 'remove_light requires lightId', path: ['lightId'] })
+    .refine((v) => v.action !== 'add_material' || !!v.material, { message: 'add_material requires material', path: ['material'] })
+    .refine((v) => v.action !== 'set_material' || (!!v.materialId && !!v.material), { message: 'set_material requires materialId and material', path: ['materialId'] })
+    .refine((v) => v.action !== 'remove_material' || !!v.materialId, { message: 'remove_material requires materialId', path: ['materialId'] })
+    .refine((v) => !['import_obj', 'import_gltf'].includes(v.action) || !!v.source, { message: 'this action requires source', path: ['source'] })
+    .refine((v) => !['list_mesh_clips', 'set_mesh_clip'].includes(v.action) || !!v.meshId, { message: 'this action requires meshId', path: ['meshId'] })
+    .refine((v) => v.action !== 'set_mesh_clip' || !!v.clip, { message: 'set_mesh_clip requires clip', path: ['clip'] })
+    .refine((v) => v.action !== 'set_nav_target' || !!v.navTarget, { message: 'set_nav_target requires navTarget', path: ['navTarget'] })
+    .refine((v) => !['ground_height', 'canvas_to_ground', 'world_to_canvas'].includes(v.action) || !!v.point, { message: 'this action requires point', path: ['point'] })
+    .refine((v) => v.action !== 'raycast' || (!!v.origin && !!v.direction), { message: 'raycast requires origin and direction', path: ['origin'] })
+    .refine((v) => v.action !== 'dolly_camera' || v.multiplier !== undefined, { message: 'dolly_camera requires multiplier', path: ['multiplier'] })
+    .refine((v) => v.action !== 'pan_camera' || (v.dx !== undefined && v.dy !== undefined), { message: 'pan_camera requires dx and dy', path: ['dx'] })
+    .refine((v) => !['add_body', 'fire_projectile'].includes(v.action) || !!v.body, { message: 'this action requires body', path: ['body'] })
+    .refine((v) => !['remove_body', 'impulse', 'set_velocity'].includes(v.action) || !!v.bodyId, { message: 'this action requires bodyId', path: ['bodyId'] })
+    .refine((v) => !['impulse', 'set_velocity'].includes(v.action) || !!v.vector, { message: 'this action requires vector', path: ['vector'] })
+    .refine((v) => v.action !== 'step_physics' || v.dt !== undefined, { message: 'step_physics requires dt', path: ['dt'] })
+    .refine((v) => v.action !== 'line_of_sight' || (!!v.from && !!v.to), { message: 'line_of_sight requires from and to', path: ['from'] })
+    .refine((v) => v.action !== 'set_mesh_instances' || (!!v.meshId && !!v.instances), { message: 'set_mesh_instances requires meshId and instances', path: ['meshId'] });
 // =============================================================================
 // ONE-SHOT IMAGE OPS (crop / chroma key — Track A agent parity, 2026-07-31)
 // =============================================================================
+/**
+ * pinepaper_design_system — the design vocabulary, as data an agent can read.
+ *
+ * TWO DIFFERENT THINGS, deliberately not merged, because the upstream is
+ * explicit that they are not the same:
+ *
+ *  - A DESIGN SYSTEM is a real, licensed, versioned product — Material 3,
+ *    IBM Carbon, Polaris, Fluent 2, USWDS, GOV.UK. Its tokens are facts with a
+ *    licence attached, expressed in the W3C DTCG format ($value, $type,
+ *    $description). Where a motion token had to be filled in because the
+ *    published system does not specify one, it is marked
+ *    `pinepaper:authored` — so a caller can tell a vendor's curve from ours.
+ *  - An AESTHETIC STYLE is a look: Bauhaus, Art Deco, Swiss, vaporwave,
+ *    risograph. It carries no licence and no vendor. Eighteen of them can
+ *    COMPOSE a scene rather than only describe one.
+ *
+ * These run in this server, not in the browser. The generators are pure
+ * functions over numbers, so the scene is computed here and arrives as items;
+ * nothing about a design vocabulary needs the canvas to be open to decide it.
+ */
+export const DesignSystemInputSchema = z.object({
+    action: z.enum(['list_systems', 'get_system', 'list_easings', 'list_styles', 'compose'])
+        .describe("'list_systems' every licensed design system with its vendor, licence and version · 'get_system' one system's full DTCG tokens · 'list_easings' every motion curve across all of them as named easings, with provenance · 'list_styles' the aesthetic styles and which can compose · 'compose' build a scene in a style."),
+    systemId: z.string().optional().describe("get_system: which system, e.g. 'material_3', 'ibm_carbon', 'uswds'. Call list_systems for the ids."),
+    tokenType: z.enum(['dimension', 'duration', 'cubicBezier', 'color', 'fontFamily', 'fontWeight', 'number', 'shadow', 'grid']).optional()
+        .describe('get_system: return only tokens of this DTCG type.'),
+    style: z.string().optional().describe("compose: the aesthetic style, e.g. 'bauhaus_geometric', 'art_deco_geometric', 'vaporwave_retro'. Call list_styles for the ones that can compose."),
+    title: z.string().optional().describe('compose: the headline. Most styles are poster-shaped and build around it.'),
+    subtitle: z.string().optional().describe('compose: the supporting line.'),
+    body: z.string().optional().describe('compose: optional body copy, where the style has somewhere to put it.'),
+    width: z.number().optional().describe('compose: canvas width (the style picks its own default otherwise).'),
+    height: z.number().optional().describe('compose: canvas height.'),
+    variant: z.string().optional().describe("compose: a style-specific variant where one exists, e.g. art deco's emerald colourway."),
+    draw: z.boolean().optional().default(true)
+        .describe('compose: draw the scene on the canvas (default). false returns the computed scene as DATA and draws nothing — the same distinction story\'s `distill` makes, and for the same reason: a caller should be able to read a composition before committing to it.'),
+    authoredOnly: z.boolean().optional().describe('list_easings: return only the curves PinePaper authored to fill a gap, or only the ones a vendor actually publishes, rather than both mixed together.'),
+})
+    .refine((v) => v.action !== 'get_system' || !!v.systemId, { message: 'get_system requires systemId — call list_systems for the ids', path: ['systemId'] })
+    .refine((v) => v.action !== 'compose' || !!v.style, { message: 'compose requires style — call list_styles for the ones that can compose', path: ['style'] })
+    .refine((v) => v.action !== 'compose' || !!v.title, { message: 'compose requires title', path: ['title'] });
+/**
+ * pinepaper_stick — the vendored stick-figure kit.
+ *
+ * A different construction from pinepaper_character, which places a figure
+ * from the design graph by concept. This is the stick kit: a rigged figure
+ * posed, walking, travelling, holding a prop, with a garment and hair — plus
+ * `set`, which builds the furniture it stands on and among.
+ *
+ * The geometry is vendored from mcp-cloud, so this is a three-repo artifact:
+ * a change to the kit lands there first and is re-vendored into FxTool.
+ */
+export const StickInputSchema = z.object({
+    action: z.enum(['figure', 'set']).describe("'figure' a posed, walking or travelling stick figure · 'set' the floor, wall and objects it stands on and among."),
+    id: z.string().optional().describe('Prefix for the created items.'),
+    kind: z.string().optional().describe("figure: which figure. set: which piece of the scene kit ('floor', 'wall', a named object) — list-free, because the kit is vendored and grows there."),
+    at: z.object({ x: z.number().optional(), y: z.number().optional() }).optional().describe('Where it goes.'),
+    scale: z.number().optional().describe('Size multiplier.'),
+    facing: z.enum(['left', 'right']).optional().describe('Which way the figure looks.'),
+    pose: z.string().optional().describe("figure: a named pose from the kit's POSES."),
+    poseAt: z.number().optional().describe('figure: the time, in seconds, at which that pose is struck.'),
+    expression: z.string().optional().describe("figure: a single facial expression from the kit's EXPRESSIONS."),
+    expressions: z.array(z.object({ at: z.number(), name: z.string() })).optional().describe('figure: expressions over time, each at a moment.'),
+    walk: z.union([z.boolean(), z.record(z.string(), z.unknown())]).optional().describe('figure: a walk cycle — true for the default, or a config.'),
+    travel: z.record(z.string(), z.unknown()).optional().describe('figure: move the figure across the scene while it walks, rather than walking in place.'),
+    prop: z.string().optional().describe('figure: something held in hand.'),
+    propSide: z.enum(['left', 'right']).optional().describe('figure: which hand holds it.'),
+    garment: z.string().optional().describe('figure: clothing.'),
+    trouser: z.string().optional().describe('figure: legwear.'),
+    hair: z.string().optional().describe('figure: hair style.'),
+    withHair: z.boolean().optional().describe('figure: draw hair at all.'),
+    groundY: z.number().optional().describe('The y the figure stands on.'),
+    surfaceY: z.number().optional().describe('The y of the surface an object sits on.'),
+    durationSeconds: z.number().optional().describe('figure: length of the performance, so every track spans it.'),
+    object: z.record(z.string(), z.unknown()).optional().describe('set: the object spec.'),
+    items: z.array(z.record(z.string(), z.unknown())).optional().describe('set: several pieces at once.'),
+    floor: z.union([z.boolean(), z.record(z.string(), z.unknown())]).optional().describe('set: draw a floor.'),
+    wall: z.union([z.boolean(), z.record(z.string(), z.unknown())]).optional().describe('set: draw a wall.'),
+});
+/**
+ * pinepaper_story — a piece of prose becomes a scene.
+ *
+ * `distill` reduces an article to its beats WITHOUT drawing anything, which is
+ * the half worth having on its own: a caller can read what the distiller made
+ * of the text, edit it, and only then assemble. `from_text` does both in one
+ * call, `apply_spec` assembles a spec you already have, and `plan_book` lays
+ * images out as pages.
+ */
+export const StoryInputSchema = z.object({
+    action: z.enum(['distill', 'from_text', 'apply_spec', 'plan_book'])
+        .describe("'distill' text → story beats, drawing NOTHING · 'from_text' distill and assemble in one call · 'apply_spec' assemble a spec you already have · 'plan_book' lay images out as pages."),
+    text: z.string().optional().describe('distill / from_text: the prose.'),
+    spec: z.record(z.string(), z.unknown()).optional().describe('apply_spec: the story spec — usually one from `distill`, edited.'),
+    images: z.array(z.union([z.string(), z.record(z.string(), z.unknown())])).optional().describe('plan_book: the images to lay out, as ids or specs.'),
+    options: z.record(z.string(), z.unknown()).optional().describe('Assembly or layout options, passed through.'),
+})
+    .refine((v) => !['distill', 'from_text'].includes(v.action) || !!v.text, { message: 'this action requires text', path: ['text'] })
+    .refine((v) => v.action !== 'apply_spec' || !!v.spec, { message: 'apply_spec requires spec', path: ['spec'] })
+    .refine((v) => v.action !== 'plan_book' || (Array.isArray(v.images) && v.images.length > 0), { message: 'plan_book requires images', path: ['images'] });
+/**
+ * pinepaper_interchange — the formats other tools read and write.
+ *
+ * pinepaper_agent_export covers the PLATFORM formats: png, svg, mp4, webm,
+ * gif, pdf, sized for Instagram or YouTube. These are the interchange ones —
+ * a Lottie an app plays, a GLB a 3D tool opens, a BVH a rig imports, a PNG
+ * sequence an editor ingests — and they had no tool at all.
+ *
+ * Import is here too, because a format you can only write is half a bridge.
+ */
+export const InterchangeInputSchema = z.object({
+    action: z.enum(['export_lottie', 'export_dotlottie', 'import_lottie', 'export_glb', 'export_bvh', 'export_png_sequence'])
+        .describe("'export_lottie' (JSON) · 'export_dotlottie' (the zipped .lottie) · 'import_lottie' (a Lottie or .lottie back onto the canvas) · 'export_glb' (the perspective 3D objects — needs some to exist) · 'export_bvh' (a skeleton's motion — needs a rig) · 'export_png_sequence' (one file per frame)."),
+    options: z.record(z.string(), z.unknown()).optional().describe('Format options, passed through to the exporter: frame range, dimensions, fps, naming.'),
+    data: z.union([z.string(), z.record(z.string(), z.unknown())]).optional()
+        .describe('import_lottie: the Lottie JSON — an object, a JSON string, or a URL.'),
+    skeletonId: z.string().optional().describe('export_bvh: which skeleton to write. A BVH is one skeleton\'s motion, so this is not optional in practice.'),
+})
+    .refine((v) => v.action !== 'import_lottie' || v.data !== undefined, { message: 'import_lottie requires data', path: ['data'] })
+    .refine((v) => v.action !== 'export_bvh' || !!v.skeletonId, { message: 'export_bvh requires skeletonId — a BVH is one skeleton\'s motion', path: ['skeletonId'] });
+/**
+ * pinepaper_sound — synthesis, and the drawing that is the same object.
+ *
+ * The engine carries a whole audio graph: tones, chords, named percussion and
+ * SFX, plain-language sound descriptions, and — the part worth the tool — a
+ * two-way bridge between a sound and a Paper path. `create` draws a sound as a
+ * waveform path you can then edit; `timbre_from_path` reads any drawn path
+ * back as a timbre. A curve someone drew becomes the harmonic content of a
+ * note.
+ *
+ * None of it was reachable. `pinepaper_audio_beats` analyses audio that
+ * already exists; this makes audio.
+ */
+export const SoundInputSchema = z.object({
+    action: z.enum([
+        'list_instruments', 'list_percussion', 'list_sfx',
+        'play_tone', 'play_chord', 'chord_frequencies', 'play_percussion', 'play_sfx',
+        'play_spec', 'from_text', 'play_from_text',
+        'create', 'timbre_from_path', 'set_placement', 'remove', 'stop_all',
+        'define_instrument', 'define_percussion', 'define_sfx', 'render_soundtrack',
+    ]).describe("Catalogues: 'list_instruments' · 'list_percussion' · 'list_sfx'. Play: 'play_tone' · 'play_chord' · 'play_percussion' · 'play_sfx' · 'play_spec' · 'play_from_text'. Read without playing: 'chord_frequencies' · 'from_text' (a plain-language description resolved to a spec) · 'timbre_from_path'. Canvas: 'create' (a sound drawn AS a waveform path) · 'set_placement' · 'remove' · 'stop_all'. Define: 'define_instrument' · 'define_percussion' · 'define_sfx' — the six built-in instruments are a starting set, not a claim that music contains six; anything missing can be defined here and is then first-class, listed by the list_* actions and playable by name. Render: 'render_soundtrack' — mix every placed sound to a WAV file offline, with no Web Audio and no playback."),
+    note: z.string().optional().describe("play_tone: scientific pitch, e.g. 'A4' or 'C#3'."),
+    root: z.string().optional().describe("play_chord / chord_frequencies: the root note, e.g. 'C4'."),
+    chord: z.string().optional().default('major').describe("play_chord / chord_frequencies: the chord kind, e.g. 'major', 'minor', 'maj7', 'dim'. Call the engine rather than guessing at exotic names."),
+    name: z.string().optional().describe("play_percussion / play_sfx: the named drum or effect — list them first (SFX include beep, pop, wind, whoosh, zap). define_*: the name to register under. It is NORMALISED to [a-z][a-z0-9_-]{0,31}, so 'Rhodes' registers as 'rhodes' — the response returns the canonical name the engine chose, and that is the name to play."),
+    partials: z.array(z.object({
+        h: z.number().positive().describe('Harmonic number — 1 is the fundamental, 2 the octave above.'),
+        amp: z.number().min(0).describe('Relative amplitude of this partial.'),
+    })).optional().describe("define_*: the harmonic table that IS the timbre. Required for define_instrument — a melodic instrument with no partials renders pure silence, and the engine refuses rather than handing back a note nobody can hear. Percussion and SFX may use noise instead."),
+    envelope: z.object({
+        attack: z.number().min(0).optional(),
+        decay: z.number().min(0).optional(),
+        sustain: z.number().min(0).max(1).optional(),
+        release: z.number().min(0).optional(),
+    }).optional().describe('define_*: ADSR shape, in seconds except sustain which is a level (0-1).'),
+    gain: z.number().min(0).max(1).optional().describe('define_*: output level. Defaults differ by kind — 0.8 instrument, 0.85 percussion, 0.65 sfx.'),
+    aliases: z.array(z.string()).optional().describe("define_*: extra names reaching the same sound, so 'rhodes' can also answer to 'electric piano'. An alias NEVER shadows a real catalogue entry — the table is consulted first — so aliasing an existing name is silently ignored rather than overriding it."),
+    noise: z.number().min(0).max(1).optional().describe('define_percussion / define_sfx: noise content. A hat, a clap, wind and whoosh are pure noise, so these two kinds accept a partial table OR noise > 0; with neither the engine refuses, because the result is silent.'),
+    noiseFreq: z.number().positive().optional().describe('define_percussion / define_sfx: centre frequency of the noise band, in Hz.'),
+    hz: z.number().positive().optional().describe('define_percussion / define_sfx: base frequency in Hz.'),
+    pitch: z.object({
+        from: z.number().positive().describe('Starting frequency in Hz.'),
+        tau: z.number().positive().max(5).describe('Glide time constant in seconds (max 5).'),
+    }).optional().describe("define_percussion / define_sfx: the pitch glide, which is what makes a kick a kick — the engine's own note is that the glide IS the drum. Omit it and a defined kick comes out a beep."),
+    sampleRate: z.number().int().positive().optional().describe('render_soundtrack: samples per second (default 48000).'),
+    bitDepth: z.union([z.literal(16), z.literal(32)]).optional().describe('render_soundtrack: 16 (default) or 32-bit float.'),
+    text: z.string().optional().describe("from_text / play_from_text: a plain-language description, e.g. 'a soft warm bell on A4'. 'from_text' resolves it to a spec WITHOUT playing, so a caller can inspect or edit before committing."),
+    spec: z.record(z.string(), z.unknown()).optional().describe('play_spec / create: the sound spec — partials, envelope, duration. Usually one you got from from_text or a catalogue entry rather than wrote by hand.'),
+    options: z.record(z.string(), z.unknown()).optional().describe('Playback options for the play_* actions: duration, gain, pan, and the rest the audio graph accepts.'),
+    itemId: z.string().optional().describe('timbre_from_path: the path whose SHAPE becomes the harmonic content. set_placement / remove: the sound item.'),
+    samples: z.number().int().positive().optional().describe('timbre_from_path: how many points to sample along the path (default 256). More is a finer timbre and a slower read.'),
+    placement: z.record(z.string(), z.unknown()).optional().describe('set_placement: where and when the sound sits on the timeline.'),
+    visual: z.object({
+        width: z.number().optional().describe('Waveform path width in canvas units (default 220).'),
+        height: z.number().optional().describe('Waveform path height in canvas units (default 64).'),
+        position: z.object({ x: z.number(), y: z.number() }).optional(),
+        color: z.string().optional(),
+    }).optional().describe('create: how the waveform path is drawn. The sound IS this item — edit the path and the timbre changes with it.'),
+})
+    .refine((v) => v.action !== 'play_tone' || !!v.note, { message: 'play_tone requires note', path: ['note'] })
+    .refine((v) => !['play_chord', 'chord_frequencies'].includes(v.action) || !!v.root, { message: 'this action requires root', path: ['root'] })
+    .refine((v) => !['play_percussion', 'play_sfx'].includes(v.action) || !!v.name, { message: 'this action requires name — list the catalogue first', path: ['name'] })
+    .refine((v) => !['from_text', 'play_from_text'].includes(v.action) || !!v.text, { message: 'this action requires text', path: ['text'] })
+    .refine((v) => v.action !== 'play_spec' || !!v.spec, { message: 'play_spec requires spec', path: ['spec'] })
+    .refine((v) => !['timbre_from_path', 'set_placement', 'remove'].includes(v.action) || !!v.itemId, { message: 'this action requires itemId', path: ['itemId'] })
+    .refine((v) => v.action !== 'set_placement' || !!v.placement, { message: 'set_placement requires placement', path: ['placement'] })
+    .refine((v) => !['define_instrument', 'define_percussion', 'define_sfx'].includes(v.action) || !!v.name, { message: 'defining a sound requires name', path: ['name'] })
+    // The engine's own rule, stated here so the refusal arrives before the round
+    // trip: a melodic instrument needs partials, while percussion and SFX may be
+    // pure noise. Mirrored rather than tightened — tightening it would refuse a
+    // hat, which is exactly the sound that has no partials.
+    .refine((v) => v.action !== 'define_instrument' || (v.partials?.length ?? 0) > 0, { message: 'define_instrument requires at least one partial — an instrument with none renders silence', path: ['partials'] })
+    .refine((v) => !['define_percussion', 'define_sfx'].includes(v.action)
+    || (v.partials?.length ?? 0) > 0 || (v.noise ?? 0) > 0, { message: 'this action needs a partial table or noise > 0 — with neither the sound is silent', path: ['noise'] })
+    // Bound by the scene, like every other timed export.
+    .refine((v) => v.action !== 'render_soundtrack' || (v.options?.duration ?? 1) <= VIDEO_MAX_DURATION_S, { message: `render_soundtrack duration is capped at ${VIDEO_MAX_DURATION_S}s, the same ceiling as video`, path: ['options'] });
+/**
+ * pinepaper_motion — the generators' Animation knob, pointed at anything.
+ *
+ * The same engine every generator's own animation runs on, reachable for any
+ * group or list of items. Two kinds: a GROUP motion (drift, sway, rotate,
+ * pulse, wave, bounce) moves the target as one; a FIELD motion (ripple,
+ * breathe, undulate) sweeps a crest through the children from an origin, with
+ * a chosen waveform. The field kind is the one nothing else here can do.
+ *
+ * `list` first. The catalogue is the engine's own and names every motion,
+ * waveform and origin it will accept — the alternative is guessing at an enum
+ * that moves.
+ */
+export const MotionInputSchema = z.object({
+    action: z.enum(['list', 'apply']).describe("'list' every motion, waveform and origin the engine offers · 'apply' one to a target."),
+    itemId: z.string().optional().describe('apply: a group or single item to move.'),
+    itemIds: z.array(z.string()).optional().describe('apply: several items, wrapped in a new group that becomes the motion host. The members keep their own identity and ids.'),
+    motion: z.string().optional().describe("apply: the motion name — a GROUP motion (drift, sway, rotate, pulse, wave, bounce) moves the target as one; a FIELD motion (ripple, breathe, undulate) sweeps a crest through its children. Call 'list' for the engine's own set rather than guessing."),
+    speed: z.number().optional().describe('apply: cycles per second, roughly. Higher is faster.'),
+    intensity: z.number().optional().describe('apply: amplitude. 0.15 is the usual default elsewhere in this surface.'),
+    waveform: z.enum(['sine', 'triangle', 'square', 'sawtooth', 'spike']).optional()
+        .describe("apply: the shape of one cycle. 'spike' is a narrow bump — it was called 'pulse' until the engine noticed one word was naming both a waveform and an animation; the old spelling is still accepted on the way in, but 'spike' is the name."),
+    origin: z.enum(['center', 'topLeft', 'topRight', 'bottomLeft', 'bottomRight', 'left', 'right', 'top', 'bottom', 'random', 'roam']).optional()
+        .describe("apply, FIELD motions only: where the crest starts and sweeps from. 'random' gives every element its own phase (a twinkle rather than a wave); 'roam' hops between the corners and the centre."),
+    seed: z.number().optional().describe('apply: makes a random origin reproducible — the same seed lays out the same phases every run.'),
+})
+    .refine((v) => v.action !== 'apply' || !!v.itemId || (Array.isArray(v.itemIds) && v.itemIds.length > 0), { message: 'apply requires itemId or itemIds', path: ['itemId'] })
+    .refine((v) => v.action !== 'apply' || !!v.motion, { message: "apply requires motion — call action 'list' for the names the engine accepts", path: ['motion'] });
+/**
+ * pinepaper_path — the destructive path operations Paper.js has always had and
+ * nothing here could reach: booleans, simplify, outline-stroke, open/close,
+ * repeat patterns, plus read-back geometry and a lock.
+ *
+ * Every one of these REPLACES or ADDS items rather than restyling them, which
+ * is why they live together and away from `pinepaper_modify_item`: a boolean
+ * consumes its operands, and an outlined stroke is a new filled shape where a
+ * stroked line used to be. The engine refuses each by name — "a boolean needs
+ * at least two paths", "that path has no stroke to outline" — and those
+ * refusals are passed through rather than reworded.
+ */
+export const PathOpInputSchema = z.object({
+    action: z.enum(['boolean', 'simplify', 'outline_stroke', 'toggle_closed', 'pattern', 'get_geometry', 'set_locked', 'unlock_all'])
+        .describe("'boolean' (unite|subtract|intersect|exclude|divide, consumes its operands) · 'simplify' (fewer segments, same shape) · 'outline_stroke' (a stroked line becomes a filled shape) · 'toggle_closed' · 'pattern' (repeat an item: concentric|radial|grid|extrude) · 'get_geometry' (read segments back) · 'set_locked' / 'unlock_all'"),
+    itemId: z.string().optional().describe('The item to operate on — every action except boolean and unlock_all.'),
+    itemIds: z.array(z.string()).optional().describe('boolean: at least two paths. The FIRST is the base; the rest are applied to it in order.'),
+    op: z.enum(['unite', 'subtract', 'intersect', 'exclude', 'divide']).optional().default('unite')
+        .describe("boolean: 'unite' merges · 'subtract' removes the later shapes from the first · 'intersect' keeps the overlap · 'exclude' keeps everything but the overlap · 'divide' splits into every region."),
+    tolerance: z.number().positive().optional()
+        .describe('simplify: how far the new curve may stray, in canvas units (default 2.5 — higher is fewer points and a looser shape). outline_stroke: flattening tolerance (defaults to an eighth of the stroke radius).'),
+    kind: z.enum(['concentric', 'radial', 'grid', 'extrude']).optional().default('radial')
+        .describe("pattern: 'concentric' rings outward · 'radial' around a circle · 'grid' rows and columns · 'extrude' a depth-wise stack."),
+    pattern: z.object({
+        count: z.number().optional().describe('concentric / radial / extrude: how many copies.'),
+        radius: z.number().optional().describe('radial / concentric: distance from the original.'),
+        angle: z.number().optional().describe('radial: total sweep in DEGREES (360 is a full ring).'),
+        phase: z.number().optional().describe('radial: where the first copy starts, in DEGREES.'),
+        rows: z.number().optional().describe('grid: row count.'),
+        cols: z.number().optional().describe('grid: column count.'),
+        gapX: z.number().optional().describe('grid: horizontal spacing in canvas units.'),
+        gapY: z.number().optional().describe('grid: vertical spacing in canvas units.'),
+        step: z.number().optional().describe('extrude / concentric: spacing between successive copies.'),
+        depth: z.number().optional().describe('extrude: total depth the stack spans.'),
+        rotateItems: z.boolean().optional().describe('radial: turn each copy to face along the ring instead of keeping its original angle.'),
+        shade: z.boolean().optional().describe('extrude: darken copies with depth, so the stack reads as receding.'),
+        shadeStrength: z.number().optional().describe('extrude: how strong that darkening is.'),
+    }).optional().describe('pattern options. Copies are capped — past a few hundred this stops being a drawing aid and becomes a generator, which is a different tool.'),
+    locked: z.boolean().optional().default(true).describe('set_locked: true locks (also clearing selectable and draggable, so it cannot be grabbed), false unlocks.'),
+})
+    .refine((v) => v.action !== 'boolean' || (Array.isArray(v.itemIds) && v.itemIds.length >= 2), { message: 'boolean requires itemIds with at least two paths', path: ['itemIds'] })
+    .refine((v) => ['boolean', 'unlock_all'].includes(v.action) || !!v.itemId, { message: 'this action requires itemId', path: ['itemId'] });
 export const CropImageInputSchema = z.object({
     itemId: z.string().describe('Registry id of the raster item (or a group containing one).'),
     rect: z.object({