@pinepaper.studio/mcp-server 1.6.10 → 1.6.12

package/dist/tools/definitions.js

@@ -9,6 +9,8 @@
  */
 import { COMPACT_DESCRIPTIONS } from './compact-descriptions.js';
 import { MINIMAL_DESCRIPTIONS } from './minimal-descriptions.js';
+import { STICK_GAITS, STICK_POSES, STICK_SEQUENCES, STICK_EXPRESSIONS, STICK_PROPS } from './stick-vocabulary.js';
+import { GeneratorNameSchema, ItemTypeSchema } from '../types/schemas.js';
 import { EffectTypeSchema, SimpleAnimationTypeSchema, GEOMETRY_OPERATIONS, THREAD_STITCHES, } from '../types/schemas.js';
 /**
  * Vocabulary lists derived from Zod schemas so tool descriptions stay in
@@ -75,6 +77,22 @@ Choose based on mood:
   Abstract:     drawGeometricAbstract, drawFluidFlow, drawNoiseTexture
   Decorative:   drawPattern, drawStackedCircles
 
+Generators paint the canvas WITHOUT fully registering what they paint — by
+design, so a large procedural field does not cost memory per path. How much is
+registered varies by generator: drawSunsetScene registers 6 of its 27 objects,
+drawSunburst 1 of 18, drawPattern none of 15. So get_items, modify and the
+ontology see a partial view or nothing at all after one runs. Ask
+app.config.currentBackgroundGenerator and generatorParams for what actually
+ran. To go beyond the parameters, write your own generator function — see
+pinepaper_execute_generator.
+
+Writing your own also hands you the registration decision, which is what makes
+a thing EDITABLE. app.registerItem(item, type, props) gives an item a registry
+id: the user can select it and change its colour, and tools can modify,
+animate, keyframe and relate it. Without that it is pixels — it exports the
+same and can never be touched again. Register what a person might want to
+change; leave the dense decorative bulk unregistered.
+
 ─── ITEMS ───
 
 Shapes: circle, rectangle, star, ellipse, triangle, polygon, line, arc, path, pentagon, hexagon, diamond, arrow, heart
@@ -364,13 +382,64 @@ For requests like "draw a witch", "draw a cat face", "draw a person", or any det
 - DO NOT attempt pixel-level character drawing with paths
 
 ITEM TYPES:
+
+EVERY type below also takes an anchor, which says WHICH CORNER your x/y meant.
+Position is the bounding-box CENTRE by default. Anything that computed a layout
+box — a design system, or any CSS-shaped mental model — authored the TOP-LEFT
+instead, and passing those coordinates straight in displaces every item by half
+its own size. anchor: 'top-left' (also top-right, bottom-left, bottom-right,
+center; origin is an alias for the parameter) fixes that without you computing
+bounds you cannot know until the item exists. It is applied after size and
+rotation, so it uses the item's real box.
+
+EVERY type below also takes a label, which wraps the item in a labelled group —
+you do not need a second create call and a hand-computed position to caption a
+shape. A string is the short form; the object form places and styles it:
+label: { content: 'Start', position: 'top', offset: [0, 10], fontSize: 14,
+fontFamily: 'Inter, sans-serif', color: '#ffffff', backgroundColor: null }.
+position takes center (default), top, bottom, left, right or a corner. Use
+label.position for placement: it works here today, and where the sibling
+labelPosition spelling is also accepted, label.position wins.
+Labelling a text item gives you TWO text items in the group — the body and the
+label. That is what you want for a caption; it is a surprise if you expected
+the label to replace the content.
+
 - text: Text content with font styling (properties: content, fontSize, color, fontFamily)
 - circle: Circular shape (properties: radius, color, strokeColor, strokeWidth)
 - star: Star shape (properties: radius1, radius2, points, color)
+  radius1 is the OUTER radius and is what sizes the star; radius or
+  width/height size it equally well. radius2 is read ONLY as a ratio to
+  radius1 (inner/outer, default 0.4), so radius2 passed WITHOUT radius1 is
+  ignored completely and you get the default waist. innerRadiusRatio sets that
+  same waist directly and needs no radii at all. points defaults to 5.
+  A star is always radially symmetric — given width and height it uses the
+  smaller — and the size you give is the radius BOX, the circle the tips
+  touch. The visible bounds are never larger than that box and usually
+  smaller — they fill it only when points is a multiple of 4.
 - rectangle: Rectangle (properties: width, height, color, cornerRadius)
-- triangle: Triangular shape (properties: color)
+- triangle: Triangular shape (properties: width, height, color, angles, kind)
+  Defaults to a 100x86 isosceles. For any OTHER triangle, do not hand-build it
+  from a path — name it: kind: 'right' | 'equilateral' | 'isosceles' |
+  'obtuse' | 'acute' | 'scalene', or give exact interior angles in degrees,
+  angles: [30, 60] (the third is inferred) or [30, 60, 90]. Angles that nearly
+  sum to 180 are normalized, so rounding is safe. With angles or kind the
+  triangle scales UNIFORMLY into the width x height box — the angles are fixed
+  and win, so one axis comes out smaller than requested. That is the only way
+  to keep a 'right' triangle actually right.
+  An angle set the engine cannot use — fewer than two entries, or any angle
+  outside 0.5-179.5 degrees — falls back to the default isosceles SILENTLY,
+  with no error. If you asked for a right triangle and got an isosceles one,
+  the angles were rejected.
 - polygon: Regular polygon with N sides (properties: sides, radius, color)
-- ellipse: Oval shape (properties: color)
+  points additionally accepts an explicit VERTEX LIST — [[x, y], ...] or
+  [{x, y}, ...], three or more, in canvas coordinates — which builds that
+  exact, possibly IRREGULAR polygon and ignores sides. Reach for this before
+  path when the outline is straight-edged. A plain number in points is not a
+  vertex list and falls through to sides (default 6).
+  In the vertex-list form the coordinates are ABSOLUTE canvas coordinates and
+  position is ignored — the polygon lands where its points say, not where you
+  positioned it. Offset the points yourself, or use sides + radius + position.
+- ellipse: Oval shape (properties: width, height, color) — defaults to 100x60
 - path: Custom path with segments or SVG data (properties: segments, pathData, strokeColor, fillColor, closed, smooth)
 - line: Line between two points (properties: from, to, strokeColor, strokeWidth)
 - arc: Curved arc through three points (properties: from, through, to, strokeColor)
@@ -378,18 +447,27 @@ ITEM TYPES:
 - hexagon: Regular 6-sided polygon (properties: radius, color)
 - diamond: 4-sided diamond/rhombus (properties: radius, color)
 - arrow: Right-pointing block arrow (properties: width, height, color)
-- heart: Heart shape (properties: color)
+- heart: Heart shape (properties: width, height, color) — defaults to 80x80
 - disk: Filled disk — the region inside a circle (properties: radius, color)
 - circle-outline: The circle CURVE — stroked, no interior (properties: radius,
   strokeColor, strokeWidth)
 - arrow-right: Alias for arrow — the same definition under the name the shape
-  grids use. Identical output; both are listed because both are accepted.
+  grids use. Identical output and the same width, height and color; both are
+  listed because both are accepted.
 
 SPEECH AND ANNOTATION SHAPES — the engine draws these; use one instead of
 hand-building an outline from a path. All take width, height and color, and the
-descriptions below are the engine's own. The six with a tail also take
-tailDirection (bottom-left | bottom-right | bottom | top-left | top-right | top
-| left | right) and tailSize (0-1, default 0.35):
+descriptions below are the engine's own. Three further parameters are each
+read by six of these eight shapes, and THE THREE SIXES ARE NOT THE SAME SIX —
+a shape missing from a list ignores that parameter silently, so check before
+you pass it:
+  cornerRadius — speech-bubble, speech-bubble-pointed, comment-box,
+    callout-box, double-bubble, quote-bubble
+  tailDirection (bottom-left | bottom-right | bottom | top-left | top-right |
+    top | left | right) — speech-bubble, speech-bubble-square,
+    speech-bubble-pointed, thought-bubble, comment-box, callout-box
+  tailSize (0-1, default 0.35) — speech-bubble, speech-bubble-square,
+    speech-bubble-pointed, comment-box, callout-box, double-bubble
 - speech-bubble: Classic round speech bubble with triangular tail.
 - speech-bubble-square: Rectangular speech bubble with sharp corners and
   pointed tail.
@@ -2262,7 +2340,7 @@ TWO DIFFERENT THINGS, kept apart on purpose:
 
 A DESIGN SYSTEM is a real, licensed, versioned product — Material Design 3, IBM Carbon, Shopify Polaris, Fluent 2, Adobe Spectrum, GitHub Primer, USWDS, GOV.UK, Shadcn/Radix, SLDS 2, Tailwind, Chakra and more. Its tokens are facts with a licence attached, in the W3C DTCG format ($value, $type, $description). Twenty-one of them are here. Where a motion curve had to be filled in because the published system does not specify one, the token is marked "pinepaper:authored" — so you can tell a vendor's curve from ours instead of treating both as equally official.
 
-An AESTHETIC STYLE is a look: Bauhaus, Art Deco, Swiss typographic, De Stijl, vaporwave, risograph, brutalist, Memphis, claymorphism, op art, pixel art. No licence, no vendor. Thirty-one are named; eighteen can COMPOSE a scene rather than only be described, and 'list_styles' says which.
+An AESTHETIC STYLE is a look: Bauhaus, Art Deco, Swiss typographic, De Stijl, vaporwave, risograph, brutalist, Memphis, claymorphism, op art, pixel art. No licence, no vendor. Thirty-three are named; eighteen can COMPOSE a scene rather than only be described, and 'list_styles' says which.
 
 - list_systems / get_system: the licensed systems and their tokens, filterable by token type.
 - list_easings: every motion curve across every system as a named easing, with its licence and whether it was authored here. Use these to make a motion match a system it has to sit beside.
@@ -2294,7 +2372,9 @@ A partial composition reports as a failure with the elements that did not create
         name: 'pinepaper_stick',
         description: `The vendored stick-figure kit — a rigged figure posed, walking, travelling, holding a prop, with a garment and hair, plus the set it stands on and among.
 
-A different construction from pinepaper_character, which places a figure from the DESIGN GRAPH by concept ("pp:Pigeon"). This is the stick kit specifically, and its options — pose, walk, travel, prop, garment, trouser, hair, expression and a timeline of expressions — were discoverable only by reading the engine's source.
+A different construction from pinepaper_character, which places a figure from the DESIGN GRAPH by concept ("pp:Pigeon"). This is the stick kit specifically.
+
+TO MAKE IT ACT, not just stand: gait is how it walks and is never just walking; poses is the body over time, [{at, pose}]; sequence is a named track of those. Pass gait and travel in the SAME call to cross the frame — they share one track and two calls fight over it. A mistyped gait, pose or sequence comes back NAMED in warnings with the valid list, and the figure is still built.
 
 action 'figure' builds the figure. action 'set' builds the floor, the wall and the objects around it, so a figure has somewhere to be.
 
@@ -2307,26 +2387,48 @@ The geometry is vendored from mcp-cloud, which makes this a three-repo artifact:
                 kind: { type: 'string', description: 'figure: which figure. set: which piece of the kit.' },
                 at: { type: 'object', description: '{ x?, y? } — where it goes.' },
                 scale: { type: 'number', description: 'Size multiplier.' },
-                facing: { type: 'string', enum: ['left', 'right'], description: 'Which way the figure looks.' },
-                pose: { type: 'string', description: "figure: a named pose from the kit's POSES." },
+                facing: { type: 'string', enum: ['left', 'right'], description: "set: which way a CHAIR faces. A figure has none and passing it here is refused — a figure faces the way it travels." },
+                pose: { type: 'string', enum: [...STICK_POSES], description: 'figure: ONE pose, held.' },
                 poseAt: { type: 'number', description: 'figure: seconds at which that pose is struck.' },
-                expression: { type: 'string', description: 'figure: one facial expression.' },
-                expressions: { type: 'array', items: { type: 'object' }, description: 'figure: [{ at, name }] — expressions over time.' },
-                walk: { anyOf: [{ type: 'boolean' }, { type: 'object' }], description: 'figure: a walk cycle.' },
-                travel: { type: 'object', description: 'figure: move across the scene while walking, rather than walking in place.' },
-                prop: { type: 'string', description: 'figure: something held in hand.' },
-                propSide: { type: 'string', enum: ['left', 'right'], description: 'figure: which hand.' },
-                garment: { type: 'string', description: 'figure: clothing.' },
-                trouser: { type: 'string', description: 'figure: legwear.' },
-                hair: { type: 'string', description: 'figure: hair style.' },
+                poses: {
+                    type: 'array',
+                    description: 'figure: THE BODY OVER TIME — [{at: seconds, pose: name}]. The counterpart of expressions, and the difference between a figure that acts and one that holds a single attitude while captions do the work.',
+                    items: { type: 'object', properties: { at: { type: 'number' }, pose: { type: 'string', enum: [...STICK_POSES] } }, required: ['at', 'pose'] },
+                },
+                gait: { type: 'string', enum: [...STICK_GAITS], description: 'figure: HOW it walks, and it is never just walking — trudge leans away from where it is going, sneak crouches, tiptoe raises the cadence. Pass travel in the SAME call to cross the frame; they share one track.' },
+                gaitSeconds: { type: 'number', description: 'figure: how long the gait runs. Defaults to durationSeconds.' },
+                gaitFrom: { type: 'number', description: 'figure: when the gait starts, in seconds.' },
+                sequence: { type: 'string', enum: [...STICK_SEQUENCES], description: 'figure: a named pose track. Shorthand that resolves to beats and joins any poses you also pass.' },
+                sequenceFrom: { type: 'number', description: 'figure: when the sequence starts (default 0).' },
+                sequenceSeconds: { type: 'number', description: 'figure: how long it spans (default 4).' },
+                expression: { type: 'string', enum: [...STICK_EXPRESSIONS], description: 'figure: one face. An unknown name costs the face, not the figure.' },
+                expressions: {
+                    type: 'array',
+                    description: 'figure: faces over time — [{at: seconds, expression: name}]. Pass durationSeconds with these or the last face lasts one second.',
+                    items: { type: 'object', properties: { at: { type: 'number' }, expression: { type: 'string', enum: [...STICK_EXPRESSIONS] } }, required: ['at', 'expression'] },
+                },
+                walk: {
+                    anyOf: [{ type: 'boolean' }, { type: 'array', items: { type: 'object', properties: { seconds: { type: 'number' }, from: { type: 'number' } } } }],
+                    description: 'figure: walk cycles — true for one default cycle, or [{seconds, from}] for several. For anything other than a plain walk, use gait.',
+                },
+                travel: {
+                    type: 'array',
+                    description: 'figure: waypoints [{t, x, y}] carrying the figure across the scene rather than walking in place. FEWER THAN TWO IS IGNORED. Pass walk or gait in the same call or it slides without moving its legs.',
+                    items: { type: 'object', properties: { t: { type: 'number' }, x: { type: 'number' }, y: { type: 'number' } }, required: ['t', 'x', 'y'] },
+                },
+                prop: { type: 'string', enum: [...STICK_PROPS], description: 'figure: something held in hand.' },
+                propSide: { type: 'string', enum: ['L', 'R'], description: "figure: which hand. 'left'/'right' are accepted and normalised." },
+                garment: { type: 'string', description: 'figure: clothing colour.' },
+                trouser: { type: 'string', description: 'figure: legwear colour.' },
+                hair: { type: 'string', description: 'figure: hair colour.' },
                 withHair: { type: 'boolean', description: 'figure: draw hair at all.' },
-                groundY: { type: 'number', description: 'The y the figure stands on.' },
-                surfaceY: { type: 'number', description: 'The y a set object sits on.' },
-                durationSeconds: { type: 'number', description: 'figure: length of the performance.' },
-                object: { type: 'object', description: 'set: the object spec.' },
-                items: { type: 'array', items: { type: 'object' }, description: 'set: several pieces at once.' },
-                floor: { anyOf: [{ type: 'boolean' }, { type: 'object' }], description: 'set: draw a floor.' },
-                wall: { anyOf: [{ type: 'boolean' }, { type: 'object' }], description: 'set: draw a wall.' },
+                groundY: { type: 'number', description: 'set: the y a ROOM floor sits at.' },
+                surfaceY: { type: 'number', description: 'set: the y a TABLETOP object sits on.' },
+                durationSeconds: { type: 'number', description: 'figure: when the tracks end, on the same clock as expressions, poses and travel.' },
+                object: { type: 'string', description: "set: the NAME of the thing to put on a surface, with kind 'tabletop'." },
+                items: { type: 'number', description: 'set: how many things stand on a shelf (default 3). A COUNT, not a list.' },
+                floor: { type: 'string', description: "set: the floor COLOUR, for kind 'room'." },
+                wall: { type: 'string', description: "set: the wall COLOUR, for kind 'room'." },
             },
             required: ['action'],
         },
@@ -3130,6 +3232,8 @@ WHAT THE CHEAP ROUTE COSTS, so the choice is deliberate: items built and animate
 AVAILABLE GLOBALS:
 - app: PinePaper application instance
   - app.create(type, params): Create items
+  - app.executeGenerator(name, params): Run a generator — including a CUSTOM one you defined as app.<name> = function(params, options) { ...draw with paper... }. That is the whole draw contract: no registration step is required
+  - app.registerItem(item, type, properties): THE DECISION THAT MATTERS when you draw your own. It returns a registry id and makes that item a first-class object: the USER can click it, select it and change its colour, and you can address it afterwards with modify_item, animate it, keyframe it, point a relation at it, or read it back through get_items and the ontology. An UNregistered path is pixels — it renders and exports identically, and nothing can ever touch it again without redrawing the scene. So register what someone might want to change (the kettle, the title, the sun) and leave the bulk unregistered (a thousand snow specks, a hatch field), which is exactly why generator output is only partly registered: it is a memory decision, and when you write the generator it is YOUR decision
   - app.addAnimation(itemId, keyframes, options): Attach keyframe TRACKS programmatically — the other half of a procedural scene, and what makes the loop route cheap: the keyframes are generated, not typed. Accepts an id or the item itself; options.timeUnits ('seconds'|'ms') overrides the ms auto-detect, which long-form timelines need
   - app.animate(item, params): Attach a LOOP animation (pulse, bounce, wobble, …) — the other kind of motion, and not what addAnimation does
   - app.addRelation(sourceId, targetId, type, params): Add relations
@@ -3573,12 +3677,17 @@ Requires maskType and keyframes array.`,
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: `[Utility] MASK properties only, despite the name: which properties each MASK TYPE can animate.
+        description: `Which properties can be animated — on an ITEM, or on each mask type.
+
+- With { itemId }: what THAT item can animate, filtered by its type, from the engine's own table. Each entry carries an 'interpolates' flag, and two of them are FALSE: content and blendMode are DISCRETE — they hold until the next keyframe rather than blending toward it. Treating content as tweenable is what makes every word in a cycler land half a beat early. The result also reports the default easing and every easing name the engine accepts.
+- With no itemId: the older MASK-TYPE table.
 
-If you are asking what you can animate on a canvas ITEM, this is the wrong tool and its name will not tell you so. The item-side list lives in pinepaper_keyframe_animate's ANIMATABLE PROPERTIES section, and two entries there are DISCRETE rather than interpolated - content and blendMode hold their value until the next keyframe instead of blending toward it. Treating content as tweenable is what makes every word in a cycler appear half a beat early.`,
+Needs a studio that publishes the item-side table; without one, the tool says so and pinepaper_keyframe_animate's own ANIMATABLE PROPERTIES section is the fallback.`,
         inputSchema: {
             type: 'object',
-            properties: {},
+            properties: {
+                itemId: { type: 'string', description: 'Ask about THIS item rather than the mask-type table. Answers what its own type can animate, and which of those are discrete.' },
+            },
         },
     },
     {
@@ -6608,6 +6717,11 @@ EXAMPLES:
     // ---------------------------------------------------------------------------
     // DOMAIN: GENERATOR TOOLS
     // ---------------------------------------------------------------------------
+    // @engine-surface-exempt drawMyArt — it is the ILLUSTRATIVE NAME in the draw
+    // contract example below, not a call. Exempted narrowly rather than by
+    // exempting tool descriptions wholesale: descriptions DO name real engine
+    // methods, and checking them is what caught app.setTimeOffset being taught in
+    // the agent guide when no such method exists.
     {
         name: 'pinepaper_execute_generator',
         annotations: {
@@ -6619,6 +6733,16 @@ EXAMPLES:
         },
         description: `Execute a background generator to create procedural patterns.
 
+CUSTOM GENERATORS — the draw contract. Define one as an app method through pinepaper_execute_custom_code:
+  app.drawMyArt = function(params, options) { ...draw with paper... };
+then invoke it with await app.executeGenerator('drawMyArt', params) in custom code, or through the batch execute_generator op with skipValidation:true. NO REGISTRATION IS REQUIRED — that is the whole contract. If you do register with app.generatorRegistry.register(), definition.fn (or the legacy onGenerate) is mandatory and a {draw} shape is refused by name.
+
+THIS TOOL cannot invoke a custom generator: it hard-rejects any name outside its enum, deliberately, because the enum is what makes the built-ins discoverable and typo-proof. The two routes above are how you run your own.
+
+Generator output is only PARTLY registered — drawSunsetScene registers 6 of its 27 objects, drawPattern none of 15 — so pinepaper_get_items and ontology queries see a partial view or nothing. The engine records the invocation instead: re-invoke with new params to "edit".
+
+WHEN YOU WRITE THE GENERATOR, THAT IS YOUR CHOICE TO MAKE, and it is the important one. app.registerItem(item, type, properties) returns an id and makes the item selectable by the USER and addressable by you — colour changes, modify_item, keyframes, relations, ontology. Unregistered output is pixels: identical on screen and in the export, and untouchable afterwards without redrawing. Register the handful anyone might want to edit; leave the dense decorative bulk out, which is the memory reason the built-ins do the same.
+
 USE WHEN:
 - "add a sunburst background", "bokeh effect", "gradient mesh"
 - "create wave pattern", "wind field", "fluid flow"
@@ -6691,18 +6815,7 @@ COMMON PARAMS (all generators):
             properties: {
                 generatorName: {
                     type: 'string',
-                    enum: [
-                        'drawSunburst', 'drawSunsetScene', 'drawGrid', 'drawStackedCircles',
-                        'drawCircuit', 'drawWaves', 'drawPattern',
-                        'drawBokeh', 'drawGradientMesh', 'drawGeometricAbstract', 'drawWindField',
-                        'drawFluidFlow', 'drawOrganicFlow', 'drawNoiseTexture',
-                        'drawGlobeWireframe',
-                        'drawFunctionPlot', 'drawParametricCurve', 'drawSimulation',
-                        'drawSpectrumAnalyzer', 'draw3DSurface',
-                        'drawTruchet', 'drawHalftone', 'drawRibbons',
-                        'drawFormulaArt', 'drawParametricCollection', 'drawShaderArt', 'drawYeganehMountains',
-                        'drawBlobs', 'drawLowPoly', 'drawPeaks', 'drawScatter', 'drawStackedWaves', 'draw3DParametricCurve',
-                    ],
+                    enum: [...GeneratorNameSchema.options],
                     description: 'Generator name',
                 },
                 params: {
@@ -6890,10 +7003,12 @@ Filters can be stacked - call multiple times to combine effects.`,
         description: `[Utility] Get all or filtered items from the canvas.
 
 USE WHEN:
-- Listing what's on the canvas
+- Listing REGISTERED items
 - Finding items by type
 - Checking animated items
-- Scene inspection`,
+- Scene inspection
+
+AFTER A GENERATOR, THIS IS A PARTIAL VIEW. A generator may register some, all or none of what it paints: measured on a cleared canvas, drawSunsetScene registers 6 of its 27 objects, drawSunburst 1 of 18, and drawPattern none of its 15. That is by design — a large procedural field would cost memory per path — but it means the canvas can look partly addressable while the rest is silently absent, which is worse for a caller than either extreme. Do not infer canvas contents from this after running a generator; ask app.config.currentBackgroundGenerator / generatorParams for what ran.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -7461,7 +7576,7 @@ OPERATION TYPES (13) — use in this order:
 CANVAS SETUP:
   set_canvas_size — {width, height} or {preset: "instagram"|"youtube"|"tiktok"|...}
   set_background — {backgroundColor: "#hex"}
-  execute_generator — {generatorName, generatorParams} → fills canvas with procedural art
+  execute_generator — {generatorName, generatorParams} → fills canvas with procedural art (paints WITHOUT fully registering items — see get_items; custom generator names need skipValidation:true)
     Generators: drawBokeh, drawGradientMesh, drawWaves, drawSunburst, drawSunsetScene, drawGrid, drawCircuit, drawPattern, drawStackedCircles, drawGeometricAbstract, drawWindField, drawFluidFlow, drawOrganicFlow, drawNoiseTexture, drawGlobeWireframe
     PineMath: drawFunctionPlot (y=f(x) plots), drawParametricCurve (x(t),y(t)), drawSimulation (pendulum, Lorenz, spring-mass), drawSpectrumAnalyzer (FFT), draw3DSurface (torus, sphere, Klein bottle)
 
@@ -7541,14 +7656,14 @@ EXAMPLE — Animated sky scene with timed reveals:
                             backgroundColor: { type: 'string', description: 'For set_background: hex color' },
                             generatorName: {
                                 type: 'string',
-                                enum: ['drawSunburst', 'drawSunsetScene', 'drawGrid', 'drawWaves', 'drawCircuit', 'drawStackedCircles', 'drawPattern', 'drawBokeh', 'drawGradientMesh', 'drawGeometricAbstract', 'drawWindField', 'drawFluidFlow', 'drawOrganicFlow', 'drawNoiseTexture', 'drawGlobeWireframe'],
+                                enum: [...GeneratorNameSchema.options],
                                 description: 'For execute_generator: generator name',
                             },
                             generatorParams: { type: 'object', description: 'For execute_generator: parameters' },
                             // Items
                             itemType: {
                                 type: 'string',
-                                enum: ['text', 'circle', 'rectangle', 'star', 'triangle', 'polygon', 'ellipse', 'path', 'line', 'arc', 'pentagon', 'hexagon', 'diamond', 'arrow', 'heart'],
+                                enum: [...ItemTypeSchema.options],
                                 description: 'For create: item type',
                             },
                             position: {
@@ -7714,14 +7829,16 @@ EXAMPLES:
 - {platform: "instagram", format: "mp4"} — force MP4
 - {platform: "web", format: "svg"} — animated SVG
 - {platform: "youtube", format: "mp4", framing: "camera"} — render only what the camera frames during the walkthrough
-- {platform: "youtube", format: "mp4", duration: 30, estimateOnly: true} — how big would that be? (renders nothing)`,
+- {platform: "youtube", format: "mp4", duration: 30, estimateOnly: true} — how big would that be, and what would it lose? (renders nothing)
+
+Every export answers the second question too: where this scene loses something to the format you chose, the result carries "fidelity" naming it. Its ABSENCE means this scene has nothing that format would drop — not that the format is lossless.`,
         inputSchema: {
             type: 'object',
             properties: {
                 platform: {
                     type: 'string',
-                    enum: ['instagram', 'instagram-story', 'tiktok', 'youtube', 'youtube-thumbnail', 'twitter', 'linkedin', 'web', 'print-a4', 'print-letter'],
-                    description: 'Target platform for export',
+                    enum: ['auto', 'instagram', 'instagram-story', 'tiktok', 'youtube', 'youtube-thumbnail', 'twitter', 'linkedin', 'web', 'print-a4', 'print-letter'],
+                    description: "Target platform, which sets the output DIMENSIONS. 'auto' (the default) renders the canvas at its own size — use it when the canvas is already the size you want, otherwise a preset REPLACES your dimensions. Every other value forces that platform's frame regardless of the canvas.",
                 },
                 format: {
                     type: 'string',
@@ -7740,7 +7857,19 @@ EXAMPLES:
                 quality: {
                     type: 'string',
                     enum: ['draft', 'standard', 'high'],
-                    description: 'Export quality level (default: standard)',
+                    description: 'Compression level (default: standard). It ALSO carries a default frame rate — draft 15, standard 30, high 60 — so "high" doubles the frame count and the render time against "standard" unless you set fps yourself. Set fps and scale to control those halves directly and leave quality meaning compression.',
+                },
+                fps: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 120,
+                    description: 'Video only: frames per second, overriding whatever `quality` implies. File size is bitrate x duration and does not move with fps, but the picture gets fewer bits per frame at a higher one.',
+                },
+                scale: {
+                    type: 'number',
+                    minimum: 0.1,
+                    maximum: 1,
+                    description: 'Video only: render at this fraction of the platform preset dimensions (0.1-1). The engine derives its encode target from RESOLUTION, so this is the size control — there is no bitrate to set, and halving the frame roughly quarters the pixels and the file. It is also the preview knob: scale 0.5 with quality "draft" is the fast look-check before committing to a full render. Rounded to even dimensions, which H.264 requires.',
                 },
                 framing: {
                     type: 'string',
@@ -7749,7 +7878,7 @@ EXAMPLES:
                 },
                 estimateOnly: {
                     type: 'boolean',
-                    description: 'Preflight only — return the estimated file size for these exact settings and render nothing. Modeled for mp4/webm/gif; png/pdf/svg report confidence "none" (no dimension-based model exists for them); wav reports confidence "exact", because uncompressed PCM size is arithmetic.',
+                    description: 'Preflight only — return the estimated file size for these exact settings and render nothing. Modeled for mp4/webm/gif; png/pdf/svg report confidence "none" (no dimension-based model exists for them); wav reports confidence "exact", because uncompressed PCM size is arithmetic. Also answers what THIS scene would lose to this format — a png of an animated scene is one frame, a gif drops the soundtrack — under "fidelity", which is present only when there is something to lose.',
                 },
                 duration: {
                     type: 'number',
@@ -7758,7 +7887,10 @@ EXAMPLES:
                     description: 'Video duration in seconds for mp4/webm/gif (default 5). Max 60 for mp4/webm; GIF is capped at 15 because it has no bitrate target, so size scales with frames × dimensions — use mp4/webm for longer clips. Static formats ignore this. If you set play_timeline to N seconds, pass the same N here.',
                 },
             },
-            required: ['platform'],
+            // Nothing is required: platform defaults to 'auto', which is the canvas's
+            // own size. Requiring it forced every caller to pick a preset, and a
+            // preset silently replaces the dimensions they had already chosen.
+            required: [],
         },
     },
     {
@@ -7993,7 +8125,9 @@ EXAMPLES:
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: `Capture the live canvas as compact pp: ontology triples + a structured item summary.
+        description: `Capture the REGISTERED canvas as compact pp: ontology triples + a structured item summary.
+
+It reads the item registry, so it inherits the same blind spot as pinepaper_get_items: a generator may register some, all or none of what it paints — drawSunsetScene 6 of 27 objects, drawPattern none of 15 — so a scene built by a generator is described partially or not at all. That is deliberate (memory per path), not a gap to work around.
 
 USE THIS instead of pinepaper_get_items when you need to REASON about composition (what's on the canvas, how items relate, what's animated). Typical scenes shrink 3-10× compared to a raw item dump while preserving relations, animations, effects, masks, and collage styling.
 
@@ -8154,7 +8288,7 @@ QUERIES (14):
 Listing:
 - list_types: All item types (filter by category, includeAbstract)
 - list_edges: All relation/edge types (filter by category)
-- list_generators: All background generators (filter by category)
+- list_generators: every generator the engine can run — the built-ins AND the registry, merged and awaited, which on a current studio is about 74 rather than the 3 this once reported. A generator you registered at runtime DOES appear. A custom draw function passed to execute_generator does not, because it was never registered; that is the one gap. If the registry chunk has not finished loading the result says partial: true and names the retry rather than presenting the built-ins as the whole set, and an older studio that cannot merge the registry answers with the built-ins under that same flag.
 - list_effects: All visual effect types
 - list_patterns: All detected design patterns
 - list_math_functions: All math functions used in animations