@pinepaper.studio/mcp-server 1.6.11 → 1.6.12

package/README.md

@@ -217,6 +217,63 @@ If you do not want an agent executing anything, `code` mode is a first-class pat
 - Puppeteer mode launches Chrome with `--no-sandbox` and `--disable-setuid-sandbox`. That is routine for headless automation and it does weaken Chrome's own process sandbox. If that matters where you are running it, use `code` mode or put the server in a container.
 - Puppeteer itself is an **optional** peer dependency, kept out of the default tree precisely because a headless browser plus an install script is what scanners flag hardest. Install it only if you want the executing mode.
 
+## What's new in 1.6.12
+
+### Fixed: images could not be imported at all
+
+Two separate bugs meant no photo could be placed into a scene over MCP.
+
+`pinepaper_import_image` failed on **every** URL with a syntax error before it ran — an apostrophe in one of its own error messages closed a string early. And `pinepaper_import_svg` with an external `<image href>` reported success, created nothing, and then broke **every later export** in the session with "Tainted canvases may not be exported", including scenes that never touched the image; only a page reload recovered it.
+
+SVGs now have their remote images fetched and inlined before importing. One that can't be fetched has its element removed and the removal named in `imageWarnings` — a missing picture is visible and recoverable, a tainted canvas is neither.
+
+### Fixed: parameters that were accepted and then ignored
+
+A tool that takes a parameter, validates it, and drops it is worse than one that refuses it, because the caller has no way to tell. This release removes every instance found:
+
+- **Ellipses** took `radiusX`/`radiusY` — the pair documented in this package's own examples — and built the default size instead. They now map to the axes the engine reads.
+- **`pinepaper_stick`** accepted eight: `propSide: 'right'` put the prop in the *left* hand (the engine compares against `'L'`/`'R'`), `walk: true` walked nowhere, expression beats keyed `name` were dropped entirely, and `facing` did nothing on a figure — it is now refused by name rather than ignored.
+- **`pinepaper_load_map`** accepted seven the engine never reads. Style keys nest under `styles` and are spelled differently there; `enableHover`/`enableClick` are `interactive`/`selectable`.
+- **`hoverStroke`** was documented by the engine and implemented nowhere; it now reaches the renderer.
+
+`pinepaper_agent_end_job` also reported the canvas as **2233×1472** for a 1920×1080 artboard — it was reading the backing store, whose ratio to the artboard is not the device pixel ratio and so cannot be divided back out. It reports the artboard now.
+
+### New: `anchor` — say which corner your x/y meant
+
+Position has always been the bounding-box **centre**. Anything that computed a layout box authored the **top-left**, so passing those coordinates displaced every item by half its own size. `anchor: 'top-left'` (also `top-right`, `bottom-left`, `bottom-right`, `center`) states which corner you meant, applied after size and rotation so it uses the item's real box. A misspelled anchor is now refused rather than silently falling back to centre.
+
+### New: figures that act, and exports that tell you what they cost
+
+`pinepaper_stick` gained `gait` (9 named walks — `trudge` leans away from where it's going, `sneak` crouches), `poses` as a track over time, and named `sequence`s. Every valid name is read from the engine's own kit, so the list cannot drift.
+
+Exports now report what **this scene** loses to the format you chose — a PNG of an animated scene is one frame, a GIF drops the soundtrack — on both `estimateOnly` and a real export. It appears only when there is something to lose: its absence is a statement about your scene, not a claim that the format is lossless.
+
+### Fixed: discovery
+
+`pinepaper_list_generators` reported **3 generators when the engine has 74**, and dropped the parameters it promised to list. The batch tool advertised 15 of those 74, so 59 working generators were invisible to anyone reading it. All lists now come from one source.
+
+Loading a template that carries clipped character parts now warns when the studio dropped them, and says not to save over the template — the file is still intact until you do.
+
+### Documentation: shapes described a fraction of what they accept
+
+`triangle` was documented as taking `color` and nothing else, while the engine accepts width, height, and either `kind` (`'right'`, `'equilateral'`, `'obtuse'`…) or exact interior `angles` and builds the triangle by the law of sines. `polygon` accepts an explicit **vertex list** for irregular shapes. `ellipse` and `heart` were `color`-only. Six of the eight speech bubbles take `cornerRadius`. And **every** item type accepts a `label` — a string, or a full config with position, offset, font and colour — so captioning no longer needs a second call and hand-computed coordinates.
+
+Two silent fallbacks are now stated: an angle set the engine rejects gives you the default isosceles with no error, and the vertex-list polygon uses absolute coordinates and ignores `position`.
+
+### Fixed: exporting without naming a platform ignored your canvas
+
+`platform` defaults to `auto`, but `auto` wasn't a real preset — the lookup fell through to the `web` preset, so an export that named no platform silently rendered **800×600** over whatever size your canvas actually was. Measured: three exports of a 960×540 canvas all came back 800×600, which reads from outside as a dimension mismatch with nothing saying the canvas had been replaced.
+
+`auto` now means the canvas's own size, read at export time, with the preset kept only as a fallback for older studios. Naming a platform still uses its preset exactly as before — and `platform` is no longer required, so you can export at your canvas size without picking a preset that overrides it.
+
+### Fixed: `fps` and `scale` were accepted but undiscoverable
+
+Both parameters worked and were documented in the tool's own text, but were missing from the machine-readable schema — which is the only part a model actually reads. So callers were told to use them and had no way to find them. Published now, along with `quality`'s description admitting that it carries a **frame rate** (15/30/60) as well as compression.
+
+### Three design generators are now included
+
+`device-mockup`, `recursive-subdivision` and `textile-weave` existed upstream but had never been copied into the package.
+
 ## What's new in 1.6.11
 
 ### Fixed: modifying an item could edit a different one

package/dist/tools/compact-descriptions.js

@@ -106,7 +106,7 @@ SHAPE TYPES: ${DIAGRAM_SHAPES}.`,
     // -------------------------------------------------------------------------
     // agent_export
     // -------------------------------------------------------------------------
-    pinepaper_agent_export: `Export as MP4, GIF, PNG, SVG, or PDF. Formats: svg, png, gif, mp4, webm, pdf. Quality: draft, standard, high. Framing: canvas (default) or camera (camera_animates viewport — video formats only).`,
+    pinepaper_agent_export: `Export as MP4, GIF, PNG, SVG, or PDF. Formats: svg, png, gif, mp4, webm, pdf. Quality: draft, standard, high — compression, and a default frame rate (15/30/60) that fps overrides. Video size control is scale 0.1-1, not a bitrate; scale 0.5 + quality draft is the fast preview. Framing: canvas (default) or camera (camera_animates viewport — video formats only).`,
     // -------------------------------------------------------------------------
     // design_system
     // -------------------------------------------------------------------------

package/dist/tools/compact-descriptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"compact-descriptions.js","sourceRoot":"","sources":["../../src/tools/compact-descriptions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"compact-descriptions.js","sourceRoot":"","sources":["../../src/tools/compact-descriptions.ts"],"names":[],"mappings":"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"}

package/dist/tools/definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/tools/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAwB/C,eAAO,MAAM,cAAc,6kbAyK+G,CAAC;AAW3I,eAAO,MAAM,eAAe,EAAE,IAAI,EA8wQjC,CAAC;AAEF;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAE5D;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAEvC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,EAAE,CAO3D;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI,EAAE,CAQrE"}
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/tools/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA0B/C,eAAO,MAAM,cAAc,6kbAyK+G,CAAC;AAW3I,eAAO,MAAM,eAAe,EAAE,IAAI,EAw2QjC,CAAC;AAEF;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAE5D;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAEvC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,EAAE,CAO3D;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI,EAAE,CAQrE"}

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
@@ -380,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)
@@ -394,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.
@@ -2310,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.
 
@@ -2323,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'],
         },
@@ -6729,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: {
@@ -7581,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: {
@@ -7754,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',
@@ -7780,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',
@@ -7789,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',
@@ -7798,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: [],
         },
     },
     {
@@ -8196,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: the BUILT-IN background generators, from a fixed table in the engine. It is not a view of what is registered: a generator you registered at runtime will never appear here, and neither will a custom draw function. Use it to discover the built-ins and their parameters, not to check whether something exists.
+- 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