@pinepaper.studio/mcp-server 1.6.23 → 1.6.24

package/dist/tools/definitions.js

@@ -81,6 +81,8 @@ The generated code is shown in tool responses and can be copied into PinePaper's
 
 ${CHOOSE_THE_DOOR}
 
+THE AGENT LANE — when the job is a scene of shapes, text, keyframes and relations exported to a file (a data animation, a title card, a motion test), and no craft tool above is wanted: PINEPAPER_TOOLKIT=lane (or pinepaper_set_toolkit {toolkit: "lane"}) serves five tools — pinepaper_agent_batch_execute, pinepaper_keyframe_animate, pinepaper_pattern, pinepaper_agent_export, pinepaper_lint_scene — whose descriptions carry the rules that otherwise cost a failed build (the keyframe shape, an item's words and look inside properties, position is the centre). The whole contract is under 10k tokens. Use the full surface for characters, styled scenes, maps, diagrams and sound.
+
 WORKFLOW — Create → Validate → Iterate:
 
 1. pinepaper_agent_start_job (clearCanvas: true, canvasPreset)
@@ -4825,6 +4827,57 @@ EXAMPLE:
             },
         },
     },
+    {
+        name: 'pinepaper_pattern',
+        annotations: {
+            title: 'Pattern',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Move many items with ONE stored declaration instead of a keyframe track on each: a wave running through a row of letters, a stagger spreading across a grid. The pattern is kept as a node: change its amplitude once and every member follows; remove it and the members go back to where they were. It is saved with the scene, undone as one step and restored on load.
+
+KINDS:
+- phase_wave — members move on a sine, each a phase later than the one before. params: property ('y' default, 'x', 'rotation', 'opacity'), amplitude (px, degrees or 0..1), period (seconds per cycle), wavelength (members per full cycle), phase (radians). window { from, to } limits when it plays; time counts from \`from\`.
+- stagger — each member's animationDelay, derived from its place. params: step (s between neighbours), start (s), order: index | reverse | center | edges.
+
+MEMBERS — by names (a '*' matches any run: "letter-*"), ids, or a tag, in the order they are given; an array is taken as ids or names. A name that matches nothing is reported in the result, not ignored.
+
+ACTIONS: create (needs id, kind, members) · modify (id + params, members or window) · remove (id) · list · get (id: the pattern and the items it holds).
+
+EXAMPLE — a word waving, letter after letter:
+{ "action": "create", "id": "wave", "kind": "phase_wave", "members": { "names": "letter-*" }, "params": { "amplitude": 12, "period": 1.2, "wavelength": 6 } }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['create', 'modify', 'remove', 'list', 'get'], description: 'create · modify · remove · list · get' },
+                id: { type: 'string', description: "the pattern's name; required except for list" },
+                kind: { type: 'string', enum: ['phase_wave', 'stagger'], description: 'create: phase_wave or stagger' },
+                members: {
+                    description: 'which items: an array of ids or names, or { ids, names, tag }',
+                    oneOf: [
+                        { type: 'array', items: { type: 'string' } },
+                        {
+                            type: 'object',
+                            properties: {
+                                ids: { type: 'array', items: { type: 'string' } },
+                                names: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
+                                tag: { type: 'string' },
+                            },
+                        },
+                    ],
+                },
+                params: { type: 'object', description: 'phase_wave: property, amplitude, period, wavelength, phase · stagger: step, start, order' },
+                window: {
+                    type: ['object', 'null'],
+                    properties: { from: { type: 'number' }, to: { type: 'number' } },
+                    description: 'phase_wave: when it plays, in scene seconds',
+                },
+            },
+            required: ['action'],
+        },
+    },
     {
         name: 'pinepaper_stagger',
         annotations: {
@@ -7993,7 +8046,7 @@ ACTIONS:
 SPEC:
 - mode: 'burst' (default) — bursts: [{ t, x, y, count, …per-burst overrides }]: a pop of particles at scene time t.
 - mode: 'trail' (or give target) — target (an item id), rate (per second), emitWindows [[t0, t1], …], window, offset: particles shed from a moving item.
-- look and physics (per emitter or per burst): shape ('circle' | 'rect' | 'dash' | 'star' | 'confetti', or an array), palette [colours], size / sizes / sizeEnd, speed + angle ranges or velocities, gravity (px/s², +down), drag, friction, lifetime, fadeIn / fadeOut, spin, opacity, jitter, jitterGrow, seed.
+- look and physics (per emitter or per burst): shape ('circle' | 'rect' | 'dash' | 'star' | 'confetti', or an array), palette [colours], size / sizes / sizeEnd, speed + angle ranges or velocities ([[vx, vy], …] px/s, or [{x, y}, …]; particle i takes velocities[i % length], so give one per particle — the reply warns when count and the list differ), gravity (px/s², +down), drag, friction, lifetime, fadeIn / fadeOut, spin, opacity, jitter, jitterGrow, seed.
 UNITS (a number, or a [min, max] range picked per particle where it says range):
 - count: particles per burst, at most 10000 on the current studio (2000 on older studios) — a larger count is drawn at the cap and the reply warns with the number drawn. For more, add a second burst at the same t.
 - speed: px/s (range). angle: degrees, 0 = right, 90 = down (range). gravity: px/s². lifetime: seconds (range, > 0). size: px (range).
@@ -8688,6 +8741,8 @@ ANIMATION:
   keyframe_animate — Timed animation: {itemId, keyframes: [{time, properties, easing}], duration, loop, append}. Replaces the item's track unless append: true (or mode: 'merge', the studio's spelling); 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}
+  timeline — GSAP's timeline as JSON, compiled onto keyframe tracks (nothing is evaluated): {defaults: {ease, duration}, tweens: [{to: name | id | "$N" | [...] | "bar-*", vars: end values, from: start values, duration, delay, at: seconds | "<" | ">" | "+=0.2" | label, stagger: N | {each, from}, ease: "power2.out" | "none" | "back.out" | …, repeat, yoyo, repeatDelay}], duration?, labels?}. x/y are OFFSETS from where the item was created (as in GSAP); scale/scaleY on a bottom-anchored item (or transformOrigin "bottom") holds its edge; drawSVG "0%"→"100%" draws a path on; fill/color → fillColor. Every track is as long as the timeline. A tween it cannot carry is refused by name; the result has a receipt per tween.
+    {type: "timeline", defaults: {ease: "power2.out"}, tweens: [{to: "bar-*", from: {scaleY: 0}, vars: {scaleY: 1}, duration: 0.8, at: 0.5, stagger: 0.15}, {to: "ring", vars: {rotation: 480}, duration: 8, ease: "none", at: 0}]}
   relation — Behavioral link: {sourceId, targetId, relationType, relationOptions}
     relationType: orbits, follows, attached_to, points_at, mirrors, parallax, wave_through, morphs_to, group_morphs_to, moves_along_path (+ 9 more in schema)
 
@@ -8733,8 +8788,8 @@ EXAMPLE — Animated sky scene with timed reveals:
                         properties: {
                             type: {
                                 type: 'string',
-                                enum: ['set_canvas_size', 'set_background', 'execute_generator', 'create', 'modify', 'delete', 'group', 'animate', 'keyframe_animate', 'relation', 'apply_mask', 'apply_effect', 'play_timeline'],
-                                description: 'Operation type',
+                                enum: ['set_canvas_size', 'set_background', 'execute_generator', 'create', 'modify', 'delete', 'group', 'animate', 'keyframe_animate', 'relation', 'apply_mask', 'apply_effect', 'play_timeline', 'ring', 'grid', 'orbit', 'stagger', 'patch', 'timeline'],
+                                description: 'Operation type. timeline compiles a GSAP-shaped timeline onto keyframe tracks. ring / grid make many items in one op (each a create, so each fills a $N slot in order), orbit binds an orbits relation (making the orbiting item when itemType is given), stagger plays the same keyframes on itemIds one after another, patch changes the item with that name (refused when several items hold it).',
                             },
                             // Canvas setup
                             width: { type: 'number', description: 'Canvas width for set_canvas_size (100-16384)' },
@@ -8821,8 +8876,32 @@ EXAMPLE — Animated sky scene with timed reveals:
                                 description: 'For play_timeline: action',
                             },
                             time: { type: 'number', description: 'For play_timeline seek: time in seconds' },
+                            // Macros
+                            count: { type: 'integer', minimum: 1, maximum: 200, description: 'ring: how many items (default 12)' },
+                            center: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, description: 'ring: the centre {x, y} (default 400, 300)' },
+                            radius: { type: 'number', description: 'ring: the circle the items sit on (default 150). orbit: the orbit radius.' },
+                            startAngle: { type: 'number', description: 'ring: degrees of the first item, clockwise from 3 o\'clock (default -90, the top)' },
+                            orient: { type: 'boolean', description: 'ring: turn each item to face out from the centre' },
+                            period: { type: 'number', description: 'ring: seconds for the stagger to travel once round (stagger = period / count)' },
+                            stagger: { type: 'number', description: 'ring, grid, stagger: seconds between one item\'s keyframes and the next' },
+                            rows: { type: 'integer', minimum: 1, description: 'grid: rows' },
+                            cols: { type: 'integer', minimum: 1, description: 'grid: columns (rows × cols up to 200)' },
+                            origin: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, description: 'grid: the first item {x, y} (default 100, 100)' },
+                            spacing: { oneOf: [{ type: 'number' }, { type: 'array', items: { type: 'number' }, minItems: 2, maxItems: 2 }], description: 'grid: gap between centres, or [dx, dy] (default 50)' },
+                            name: { type: 'string', description: 'ring, grid: name prefix (items are name_0, name_1 … or name_row_col). orbit: the made item\'s name. patch: the item to change.' },
+                            speed: { type: 'number', description: 'orbit: the orbits relation\'s speed (its own units; omit for the studio default)' },
+                            phaseDegrees: { type: 'number', description: 'orbit: starting angle in degrees' },
+                            // GSAP-shaped timeline (src/tools/timeline.ts)
+                            tweens: { type: 'array', items: { type: 'object' }, description: 'For timeline: [{to, vars, from, duration, delay, at, stagger, ease, repeat, yoyo, repeatDelay}]' },
+                            defaults: { type: 'object', description: 'For timeline: {ease, duration} for tweens that give none' },
+                            labels: { type: 'object', description: 'For timeline: {name: seconds}, for at: "name" or "name+=0.5"' },
                         },
                         required: ['type'],
+                        // Open, as the zod schema is (.passthrough()): a create op takes its
+                        // properties flat (content, fontSize, x, y …) and a keyframe op takes
+                        // timeOffset / timeUnits / clipInPoint / clipOutPoint at the top.
+                        // create_item's own check still names a property the studio ignores.
+                        additionalProperties: true,
                     },
                     description: 'Array of operations to execute in order',
                 },
@@ -9507,6 +9586,8 @@ USE WHEN: You need full parameter docs, examples, or workflow guidance — espec
 
 PREFER RESOURCES WHERE POSSIBLE: The full AI Agent Guide is also available via the MCP resources API at pinepaper://docs/agent-guide — clients that support resources should pull it that way rather than calling this tool. Per-domain references live at pinepaper://docs/{generators,relations,masks,diagrams,maps,effects-and-filters,fonts,custom-paths,paperjs-in-pinepaper,templates,customization,getting-started}. Use this tool when the client doesn't support resources or when you want a specific tool's verbose description.
 
+THE AGENT LANE: for a scene built from shapes, text, keyframes and relations and exported to a file, a five-tool lane carries the whole contract in its descriptions (no guide, no lessons file): start the server with PINEPAPER_TOOLKIT=lane, or pinepaper_set_toolkit {toolkit: "lane"}.
+
 MODES:
 - No args → returns the full AI Agent Guide (same content as pinepaper://docs/agent-guide)
 - tool: "pinepaper_agent_batch_execute" → returns that tool's full verbose description
@@ -9553,6 +9634,7 @@ PROFILES:
 - map: Map/choropleth tools
 - font: Font creation tools
 - minimal: Bare essentials
+- lane: the agent lane — five tools (batch_execute, keyframe_animate, pattern, agent_export, lint_scene) whose descriptions carry everything needed to build and export a shape/text/keyframe scene; set it for a scripted build that needs nothing else. It lists no way back: set it last.
 
 VERBOSITY:
 - verbose: Full descriptions
@@ -9563,8 +9645,8 @@ VERBOSITY:
             properties: {
                 toolkit: {
                     type: 'string',
-                    description: 'Toolkit profile: full, agent, diagram, map, font, minimal',
-                    enum: ['full', 'agent', 'diagram', 'map', 'font', 'minimal'],
+                    description: 'Toolkit profile: full, agent, diagram, map, font, minimal, lane',
+                    enum: ['full', 'agent', 'diagram', 'map', 'font', 'minimal', 'lane'],
                 },
                 verbosity: {
                     type: 'string',