@pinepaper.studio/mcp-server 1.6.20 → 1.6.22

package/dist/tools/definitions.js

@@ -9,6 +9,7 @@
  */
 import { COMPACT_DESCRIPTIONS } from './compact-descriptions.js';
 import { MINIMAL_DESCRIPTIONS } from './minimal-descriptions.js';
+import { craftToolDefinitions } from './craft-tools.js';
 import { STICK_GAITS, STICK_POSES, STICK_SEQUENCES, STICK_EXPRESSIONS, STICK_PROPS } from './stick-vocabulary.js';
 import { AgentBatchOperationTypeSchema, GeneratorNameSchema, ItemTypeSchema } from '../types/schemas.js';
 import { DESIGN_MEDIA, DESIGN_MEDIA_APPLY, FILTER_TYPES, FILTER_DOCS, LINEAGE_KINDS, STYLED_SCENE_STYLES, STYLED_SCENE_STYLE_INFO } from './engine-lists.js';
@@ -143,7 +144,7 @@ Shapes: circle, rectangle, star, ellipse, triangle, polygon, line, arc, path, pe
 Surfaces (render-time, evaluated per pixel — not shapes): shader, field
   shader: a lit surface — water, liquid_metal, heatmap, gem_smoke. Set behind:true to put it UNDER the art, which is what scenery wants.
   field:  one expression, many marks — xExpr/yExpr/count, re-evaluated every frame against t.
-  Both draw fully in a cloud render; locally they stand in as a flat plate.
+  Both draw in the studio (live, stills, every export) and in a cloud render.
 Text: text (content, fontSize, fontFamily, color, fontWeight)
   Dynamic text: set contentType on text items → clock (live time), timer (elapsed), countdown (from N seconds), stopwatch (pauseable)
 All items: opacity, shadowColor, shadowBlur, blendMode, strokeColor, strokeWidth
@@ -600,7 +601,7 @@ For glossy 3D spheres, use pinepaper_create_glossy_sphere instead. For diagonal
                 itemType: {
                     type: 'string',
                     enum: ['text', 'circle', 'star', 'rectangle', 'triangle', 'polygon', 'ellipse', 'path', 'line', 'arc', 'pentagon', 'hexagon', 'diamond', 'arrow', 'heart', 'disk', 'circle-outline', 'arrow-right', 'speech-bubble', 'speech-bubble-square', 'speech-bubble-pointed', 'thought-bubble', 'double-bubble', 'quote-bubble', 'comment-box', 'callout-box', 'shader', 'field'],
-                    description: "Type of item to create. 'shader' and 'field' are RENDER-TIME SURFACES drawn per pixel by the cloud renderer — locally they stand in as a flat plate. See the shader/field properties below.",
+                    description: "Type of item to create. 'shader' and 'field' are RENDER-TIME SURFACES drawn per pixel, in the studio and in a cloud render. See the shader/field properties below.",
                 },
                 position: {
                     oneOf: [
@@ -627,14 +628,15 @@ For glossy 3D spheres, use pinepaper_create_glossy_sphere instead. For diagonal
 
 LIFETIME — on ANY item, and the only way to build a piece that CUTS between shots:
 - bornAt: seconds. The item does not exist before this instant.
-- ttl: seconds it lives for. Omit for "until the end".
+- ttl: seconds it lives for. Omit for "until the end". A numeric lifetime is
+  read as ttl, except on an emitter, where lifetime is each particle's life.
 Without these every item is on screen for the whole render, which is what makes
 a long piece read as one crowded frame instead of a sequence of shots.
 They set the item's VISIBILITY for [bornAt, bornAt + ttl) — not its opacity —
 so they compose with any keyframes, opacity fades included. Re-timing with
 pinepaper_modify_item {bornAt, ttl} replaces the previous lifetime — pass both.
-The result's lifetime field says whether it was applied; it is runtime-only
-until the studio reads bornAt / ttl itself, so re-time a reopened scene.
+The result's lifetime field says whether it was applied, and persists: true
+when it is saved with the scene; without that, re-time a reopened scene.
 
 SHADER (itemType 'shader') — a lit surface, drawn per pixel:
 - shader: 'water' (open sea, lit swell) | 'liquid_metal' (chrome) | 'heatmap' (thermal halo) | 'gem_smoke' (smoke) | 'electric_arc' (branching discharge, stepped flicker) | 'vortex' (hollow bright RING, sheared by differential rotation) | 'rain_veil' | 'caustics' | 'ink_bleed'
@@ -5927,6 +5929,109 @@ PHASES: sin, blink, linear, pingpong, once, elastic, heartbeat, stepped`,
             required: ['action'],
         },
     },
+    {
+        name: 'pinepaper_hand_drawn',
+        annotations: {
+            title: 'Hand-Drawn Line',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Give a path a hand-drawn look: a rough, bowed outline (sketchy), or a stroke that draws itself on (reveal).
+
+USE WHEN:
+- "give it a hand-drawn / sketchy / rough outline"
+- "draw the line on like ink" (reveal)
+
+STYLES:
+- 'sketchy' (default): one-time seeded jitter of the path's points and curve handles. Saved with the scene; exports as drawn.
+- 'reveal' (alias 'ink_reveal'): keyframes the item's stroke trimEnd 0 -> 1 over duration seconds, merged with any keyframes it already has. Needs itemId.
+- 'wobble', 'stop_motion': refused, nothing changed. A line that boils frame to frame in exports is pinepaper_design_medium medium 'ink'; the refusal returns that call, with fps as the boil rate.
+
+PARAMETERS:
+- itemId: target item registry id (sketchy falls back to the selection)
+- style / mode: 'sketchy' | 'reveal' | 'ink_reveal' | 'wobble' | 'stop_motion'
+- roughness: point jitter in px (default 2)
+- bowing: curve handle jitter factor (default 1)
+- seed: same seed, same jitter (default 1)
+- duration: reveal seconds (default 2)
+- fps / posterizeFps: boil rate passed on in the wobble/stop_motion refusal (default 12)`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                itemId: { type: 'string', description: 'Target item registry ID (or current selection if omitted)' },
+                style: {
+                    type: 'string',
+                    enum: ['sketchy', 'reveal', 'ink_reveal', 'wobble', 'stop_motion'],
+                    description: "Hand-drawn style (default: sketchy). wobble and stop_motion are refused with the pinepaper_design_medium call that does it",
+                },
+                mode: {
+                    type: 'string',
+                    enum: ['sketchy', 'reveal', 'ink_reveal', 'wobble', 'stop_motion'],
+                    description: 'Alias for style',
+                },
+                roughness: { type: 'number', description: 'Noise magnitude in pixels (default: 2)' },
+                bowing: { type: 'number', description: 'Line bowing curve handle factor (default: 1)' },
+                fps: { type: 'number', description: 'wobble/stop_motion: the boil rate handed to pinepaper_design_medium (default: 12)' },
+                posterizeFps: { type: 'number', description: 'Alias for fps' },
+                seed: { type: 'number', description: 'Random seed for deterministic vertex displacement (default: 1)' },
+                duration: { type: 'number', description: 'reveal: seconds to draw the stroke on (default: 2)' },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_pen_figure',
+        annotations: {
+            title: 'Pen Figure',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Draw a mathematical figure with a pen: the tip travels the figure and the ink appears behind it, in the editor and in every export.
+
+USE WHEN:
+- "draw a Lorenz attractor / Lissajous / Hilbert curve being drawn"
+- "a pen plotting a curve", "a harmonograph drawing itself"
+
+The figures are the studio's catalogue of declarative maths (parametric and polar curves, ODE attractors, iterated maps, L-systems). action 'list' returns it: id, title, kind. A figure is fitted into its box by one uniform scale, so it is the same figure on any canvas size.
+
+ACTIONS:
+- create (default): { figure, box?, margin?, duration?, delay?, loop?, pen?, strokeColor?, penColor?, strokeWidth? } → { inkId, penId, title, strokes }. The ink is a group, one child per pen stroke; the pen is a circle joined to it by the draws_figure relation. pen: false draws the ink complete, with no pen and no animation. An unknown figure is refused with the catalogue's ids.
+- list: the catalogue.
+
+To draw a static curve from your own equation, use pinepaper_equation_path.
+
+EXAMPLES:
+- { figure: 'lorenz', duration: 8 }
+- { figure: 'hilbert', box: { x: 100, y: 100, width: 600, height: 600 }, strokeColor: '#0f766e' }
+- { figure: 'harmonograph', pen: false }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['create', 'list'], description: "'create' (default) draws a figure; 'list' returns the catalogue." },
+                figure: {
+                    anyOf: [{ type: 'string' }, { type: 'object' }],
+                    description: "create: a catalogue id from action 'list' (e.g. 'lorenz', 'lissajous', 'hilbert', 'harmonograph'), or an inline figure spec object.",
+                },
+                box: {
+                    type: 'object',
+                    properties: { x: { type: 'number' }, y: { type: 'number' }, width: { type: 'number' }, height: { type: 'number' } },
+                    required: ['x', 'y', 'width', 'height'],
+                    description: 'Where to draw, in canvas px (default: the whole canvas).',
+                },
+                margin: { type: 'number', description: 'Fraction of the box left clear (default 0.06).' },
+                duration: { type: 'number', description: 'Seconds the pen takes for the whole figure, pen-up travel included (default 6).' },
+                delay: { type: 'number', description: 'Seconds before the pen starts (default 0).' },
+                loop: { type: 'boolean', description: 'Draw the figure again after it finishes (default false: it stays drawn).' },
+                pen: { type: 'boolean', description: 'false: the ink only, fully drawn, no animation (default true).' },
+                strokeColor: { type: 'string', description: "Ink colour (default '#1e293b')." },
+                penColor: { type: 'string', description: "Pen tip colour (default '#e11d48')." },
+                strokeWidth: { type: 'number', description: 'Ink width in px (default 2).' },
+            },
+        },
+    },
     {
         name: 'pinepaper_sprite_sheet',
         annotations: {
@@ -8557,7 +8662,7 @@ ITEMS:
 ANIMATION:
   animate — Loop animation: {itemId, animationType, animationOptions}
     animationType: ${SIMPLE_ANIMATION_TYPES_LIST}
-  keyframe_animate — Timed animation: {itemId, keyframes: [{time, properties, easing}], duration, loop}
+  keyframe_animate — Timed animation: {itemId, keyframes: [{time, properties, easing}], duration, loop, append}. Replaces the item's track unless append: true; two ops on one item in a batch are merged into one.
     Animatable properties: opacity, scale, scaleX, scaleY, x, y, rotation, fillColor, strokeColor, strokeWidth, width, height, radius, fontSize, trimStart/trimEnd/trimOffset (path draw-on)
     Easing (on the keyframe being moved TO): ${KEYFRAME_EASINGS_LIST}
   relation — Behavioral link: {sourceId, targetId, relationType, relationOptions}
@@ -8613,6 +8718,7 @@ EXAMPLE — Animated sky scene with timed reveals:
                             height: { type: 'number', description: 'Canvas height for set_canvas_size (100-16384)' },
                             preset: { type: 'string', description: 'Canvas preset for set_canvas_size' },
                             backgroundColor: { type: 'string', description: 'For set_background: hex color' },
+                            color: { type: 'string', description: 'For set_background: same as backgroundColor. For create: same as fillColor.' },
                             generatorName: {
                                 type: 'string',
                                 enum: [...GeneratorNameSchema.options],
@@ -8659,6 +8765,7 @@ EXAMPLE — Animated sky scene with timed reveals:
                             },
                             duration: { type: 'number', description: 'Duration in seconds for keyframe_animate or play_timeline' },
                             loop: { type: 'boolean', description: 'Loop for keyframe_animate or play_timeline' },
+                            append: { type: 'boolean', description: "For keyframe_animate: add these keys to the item's existing track instead of replacing it (a key at the same time merges, the new values win). Without it the op replaces the track; the op's result says which happened." },
                             // Relations
                             sourceId: { type: 'string', description: 'For relation: source item ID or $N' },
                             targetId: { type: 'string', description: 'For relation: target item ID or $N' },
@@ -9662,8 +9769,11 @@ ACTIONS:
         },
     },
     // ---------------------------------------------------------------------------
-    // STITCHCRAFT PROCEDURAL EMBROIDERY & THREAD
+    // STITCHCRAFT PROCEDURAL EMBROIDERY & THREAD, SUBDIVISION, UI KIT
+    // The cloud's craft tools, shared: schemas vendored from mcp-cloud, local
+    // words and behaviour in craft-tools.ts.
     // ---------------------------------------------------------------------------
+    ...craftToolDefinitions(),
 ];
 /**
  * Get a tool definition by name