@pinepaper.studio/mcp-server 1.6.12 → 1.6.14

package/dist/tools/definitions.js

@@ -11,7 +11,7 @@ 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';
+import { EffectTypeSchema, SimpleAnimationTypeSchema, EasingSchema, GEOMETRY_OPERATIONS, THREAD_STITCHES, } from '../types/schemas.js';
 /**
  * Vocabulary lists derived from Zod schemas so tool descriptions stay in
  * sync automatically. The description-schema-parity test
@@ -21,6 +21,10 @@ import { EffectTypeSchema, SimpleAnimationTypeSchema, GEOMETRY_OPERATIONS, THREA
  */
 const EFFECT_TYPES_LIST = EffectTypeSchema.options.join(', ');
 const SIMPLE_ANIMATION_TYPES_LIST = SimpleAnimationTypeSchema.options.join(', ');
+// The easings a keyframe accepts. The batch description once listed
+// easeInCubic / easeOutCubic / easeOutBounce, which keyframe_animate rejects
+// (round 8 DD, 1.68) — derived now, so it cannot say what the schema refuses.
+const KEYFRAME_EASINGS_LIST = EasingSchema.options.join(', ');
 // =============================================================================
 // AI AGENT GUIDE (exported for pinepaper_tool_guide)
 // =============================================================================
@@ -257,12 +261,12 @@ COMMON PRESETS:
 - hd-landscape: 1920x1080
 - hd-portrait: 1080x1920
 
-Max canvas size: 4096x4096. For wedding invitations, event cards, or detailed designs, use at least 1080x1080 or larger.`,
+Max canvas size: 8192x8192 (a 5400x1350 carousel panorama fits). For wedding invitations, event cards, or detailed designs, use at least 1080x1080 or larger.`,
         inputSchema: {
             type: 'object',
             properties: {
-                width: { type: 'number', description: 'Canvas width in pixels (100-4096)' },
-                height: { type: 'number', description: 'Canvas height in pixels (100-4096)' },
+                width: { type: 'number', description: 'Canvas width in pixels (100-8192)' },
+                height: { type: 'number', description: 'Canvas height in pixels (100-8192)' },
                 preset: {
                     type: 'string',
                     description: 'Optional preset name',
@@ -338,10 +342,19 @@ USE WHEN:
 
 IMPORTANT NOTES:
 - This reloads the entire page, which resets everything
-- The welcome template will NOT appear after refresh (only shows for first-time visitors)
-- After refresh, the canvas will be completely empty
 - All unsaved work will be lost
-- You may need to wait a moment after refresh before executing other commands`,
+- You may need to wait a moment after refresh before executing other commands
+
+WHAT YOU ACTUALLY GET, which is not always an empty canvas:
+- The template picker and a "Restore your previous work?" dialog can both
+  appear after a reload — observed in agent mode. A screenshot taken straight
+  afterwards shows those, not your scene, so do not read one as evidence that
+  the canvas is broken or that your items failed to draw.
+- Dismiss or clear whatever appears before judging the result, and prefer
+  pinepaper_agent_reset when you want a clean canvas rather than a clean PAGE:
+  it skips the reload and the dialogs entirely.
+- This description used to promise the welcome template would not appear and
+  that the canvas would be empty. Neither is reliable, so neither is claimed.`,
         inputSchema: {
             type: 'object',
             properties: {},
@@ -391,6 +404,10 @@ 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.
+PIXEL-EXACT SLOTS (a spec'd 615x345 end-screen box, a UI frame): use anchor
+'top-left' with WHOLE-NUMBER x, y, width and height. A centred box with an odd
+width or height has its edges on half pixels, which renders 1 px short with a
+soft anti-aliased edge (measured: 615x345 centred came out 614x344).
 
 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
@@ -404,7 +421,12 @@ 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)
+- text: Text content with font styling (properties: content, fontSize, color, fontFamily, justification, fontWeight, fontStyle, leading, lineHeight)
+  fontWeight: 400 / 700 / 'bold'. fontStyle: 'italic'. leading: line spacing in px; lineHeight: a multiple of fontSize (<= 4) or px. Multi-line content splits on \n.
+  fit: {maxWidth, maxHeight?, minFontSize? (8), maxFontSize? (current), wrap? (true), hold? ('top' | 'center' | …)} — auto-size the text into a box, keeping its anchored edge. The box is remembered: changing content later refits (shrinks, or grows back to maxFontSize); modify_item {fit: {...}} sets a new box; {fit: null} stops fitting. The result's textFit says {fontSize, lines, fits}; fits:false means it overflows even at minFontSize. Studios without auto-fit say so in textFit. Every export's fidelity then lists text_overflow for any text past its box or off the frame — the check to run before a batch of variants.
+  direction: 'auto' (default: the first strong letter decides, so Arabic and Hebrew need nothing) | 'ltr' | 'rtl' — the paragraph's base direction, which places neutrals like the final period (aliases textDirection, dir). The result's direction says whether the studio applied it; a studio without RTL support lays text out left-to-right and says so. justification: 'right' is alignment, not direction.
+  tabularFigures: true (or fontVariantNumeric: 'tabular-nums', or fontFeatures containing 'tnum') — fixed-width digits, so a counter, price or timer does not jitter as it changes. The result's tabularFigures says whether the studio applied them.
+  strokePosition: 'outside' — the stroke sits entirely outside the letters (drawn under the fill at twice strokeWidth), so a thick caption / meme outline keeps the letterform; 'center' (default) is the ordinary stroke. The result's strokePosition says whether the studio applied it.
 - 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
@@ -441,6 +463,7 @@ the label to replace the content.
   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)
+  color on a path: a CLOSED path (closed:true, or pathData ending in Z) is FILLED with it; an OPEN path is STROKED with it. Pass fillColor / strokeColor to say exactly which.
 - line: Line between two points (properties: from, to, strokeColor, strokeWidth)
 - arc: Curved arc through three points (properties: from, through, to, strokeColor)
 - pentagon: Regular 5-sided polygon (properties: radius, color)
@@ -487,6 +510,7 @@ Use itemType: "path" with either:
 
 ADVANCED STYLING (NEW):
 All shapes support these additional properties:
+- No fill (stroke-only outlines, line art): fillColor: null, 'transparent' or 'none', with a strokeColor and strokeWidth.
 - Gradients: color can be an object: {type: "linear"|"radial", stops: [{color: "#fff", offset: 0}, {color: "#000", offset: 1}], origin: [x,y], destination: [x,y]}
 - Shadows: shadowColor, shadowBlur (pixels), shadowOffset: [x, y]
 - Blend modes: blendMode: "multiply"|"screen"|"overlay"|"darken"|"lighten"|etc.
@@ -565,6 +589,11 @@ LIFETIME — on ANY item, and the only way to build a piece that CUTS between sh
 - ttl: seconds it lives for. Omit for "until the end".
 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.
 
 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'
@@ -587,6 +616,11 @@ thousands of authored items.
 - Example — a rolling swell: xExpr "(i % 120) * 8", yExpr "400 + sin((i % 120) * 0.4 - t * 2) * 12", count 3600`,
                     additionalProperties: true,
                 },
+                anchor: {
+                    type: 'string',
+                    enum: ['center', 'top-left', 'top-right', 'bottom-left', 'bottom-right'],
+                    description: "Which point of the item `position` names (default center). Same as properties.anchor — for a pixel-exact slot use 'top-left' with whole numbers.",
+                },
                 data: {
                     type: 'object',
                     description: 'Item data flags for selection and behavior control',
@@ -659,6 +693,7 @@ MODIFIABLE PROPERTIES:
 - content: Text content
 - opacity: Transparency (0-1)
 - rotation: Rotation in degrees
+- skewX / skewY: shear in degrees about the item's centre; matrix: [a, b, c, d, tx, ty] affine. For mockups (a box face, a screen at an angle). APPLIED to the current shape, so calling again compounds — the result's affine says so.
 - scale: Size multiplier
 - shadowColor: Shadow color
 - shadowBlur: Shadow blur radius
@@ -957,6 +992,8 @@ USE WHEN:
 - Adding logos or vector graphics
 - User mentions SVG files or vector graphics
 
+CHECK LINE-ART IMPORTS: fill="none" and stroke-dasharray have been measured to be lost on import — outline icons come in filled, dashed strokes come in solid. For line art, check the result with a screenshot; to fix it, set fillColor: null (and dashArray) on the imported paths with pinepaper_modify_item.
+
 ⚠️ RECOMMENDED FOR COMPLEX CHARACTERS:
 Instead of drawing "a witch" or "a cat" with many path operations, use SVG import:
 1. Describe what you need and use a simple placeholder SVG
@@ -1120,6 +1157,11 @@ EXAMPLES:
                     enum: ['circle', 'rounded', 'hexagon', 'star'],
                     description: 'Optional mask shape to apply to the image',
                 },
+                smoothing: {
+                    type: 'string',
+                    enum: ['off', 'low', 'medium', 'high'],
+                    description: "Resampling when the image is scaled. 'off' = nearest-neighbour, hard pixel edges — use it for pixel art. Default 'low'. Change it later with pinepaper_modify_item {smoothing}.",
+                },
             },
             required: ['url'],
         },
@@ -1530,7 +1572,7 @@ warp (optional): chained parametric warp(s) — displace each sampled point by {
 
 RETURNS: { success, kind, itemId } — itemId is the created path. Bad expressions / empty ranges return { success:false, error }.
 
-To make an item TRAVEL along an equation curve (instead of drawing it), use pinepaper_add_relation relationType moves_along_path with params.equation instead.
+To make an item TRAVEL along an equation curve (instead of drawing it), use pinepaper_add_relation relationType moves_along_path with params.equation — but note that equation is read ONLY on the relation's signal path. An option that leaves that path takes the equation with it and the item simply does not move: easing 'bounce' is piecewise and falls back, so bounce + equation is a static item reporting success. Use a signal-friendly easing (linear, easeIn, easeOut, easeInOut, sine, pingpong) with an equation, or supply params.path instead.
 
 EXAMPLES:
 - Sine wave: { kind: "function", expr: "sin(x/40) * 60", min: -300, max: 300, style: { strokeColor: "#4f46e5" } }
@@ -1555,7 +1597,7 @@ EXAMPLES:
                 y: { type: 'number', description: 'Canvas origin y (default: canvas center)' },
                 flipY: { type: 'boolean', description: 'Math y-up → screen y-down (default true)' },
                 style: { type: 'object', description: 'Path style forwarded to create (strokeColor, strokeWidth, fillColor, …)' },
-                solveOde: { type: 'object', description: "Integrate an ODE instead of plotting a closed form, and return the SOLUTION rather than drawing it: { equations, initialState, tEnd?, dt?, method? ('rk4' default, or 'euler' — faster and visibly wrong on anything stiff) }. The trajectory comes back as data, to inspect, feed to a path, or drive keyframes with." },
+                solveOde: { type: 'object', description: "Integrate an ODE instead of plotting a closed form, and return the SOLUTION rather than drawing it: { equations, initialState, tEnd?, dt?, method? ('rk4' default, or 'euler' — faster and visibly wrong on anything stiff) }. STATE VARIABLES ARE POSITIONAL: each expression is written in terms of t, y0, y1, y2 ... where yN is the Nth entry of initialState. There is no x or y, so a Lorenz system is ['10*(y1-y0)', 'y0*(28-y2)-y1', 'y0*y1-(8/3)*y2'] with initialState [1,1,1] — writing it as '10*(y-x)' fails with \"Undefined symbol y\". The trajectory comes back as data, to inspect, feed to a path, or drive keyframes with." },
                 warp: {
                     anyOf: [{ type: 'object' }, { type: 'array', items: { type: 'object' } }],
                     description: 'Chained parametric warp(s): { dx, dy } expressions of x, y, t — one object or an array',
@@ -1687,6 +1729,75 @@ EXAMPLES:
             required: ['action'],
         },
     },
+    {
+        name: 'pinepaper_accessibility_check',
+        annotations: {
+            title: 'Accessibility Check',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Check the live scene for two accessibility failures that stop ads and broadcast spots: low text contrast and flashing.
+
+- contrast: WCAG 1.4.3 AA — 4.5:1, or 3:1 for large text (24 px, or 18.66 px bold). Each text's fill against the solid fill of the topmost item under it, or the page background. Text over a photo or gradient is skipped and listed.
+- flash: WCAG 2.3.1 general flash — samples the timeline (duration, fps) and fails any region of the frame with more than 3 flashes in a second. It seeks deterministically, so playback is not disturbed.
+
+Both are heuristic screens and say so: not a certified photosensitive-epilepsy (PSE) test, and red flashes are not checked. Needs a live studio for verdicts; in code-only mode it returns the measuring code.
+
+EXAMPLE: { checks: ["contrast", "flash"], duration: 6, fps: 20 }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                checks: { type: 'array', items: { type: 'string', enum: ['contrast', 'flash'] }, description: 'Which checks (default both).' },
+                duration: { type: 'number', exclusiveMinimum: 0, maximum: 120, description: 'flash: seconds of the timeline to sample (default 5).' },
+                fps: { type: 'integer', minimum: 10, maximum: 60, description: 'flash: samples per second (default 20).' },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_render_batch',
+        annotations: {
+            title: 'Render Batch',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Render one creative per row of data from the current scene: for each row, apply its changes (modify_item per item, and / or a template's params), then export with the shared export options. For variants, translations and dynamic creative (DCO).
+
+Each row runs through the same tools you would call yourself, so every check applies per row: unread properties, text fit, export fidelity. A row that fails is reported by index and the batch continues.
+
+ROWS DO NOT RESET: row 2 starts from the scene row 1 left. Give every row every field that varies (all headlines, all prices), not only what differs from the row before. Pair with text fit so longer copy still fits its box, and read each row's fidelity for text_overflow.
+
+Needs a live studio (it renders); in code-only mode it is refused. Max 100 rows; estimateOnly checks the rows first.
+
+EXAMPLE:
+{ rows: [
+    { id: "en", changes: { headline: { content: "Summer Sale" }, price: { content: "$19" } } },
+    { id: "de", changes: { headline: { content: "Sommerschlussverkauf" }, price: { content: "19 €" } } } ],
+  export: { format: "png", platform: "instagram" } }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                rows: {
+                    type: 'array', minItems: 1, maxItems: 100,
+                    description: 'One entry per creative.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string', description: 'A name for the row, echoed in its result.' },
+                            changes: { type: 'object', additionalProperties: { type: 'object' }, description: 'itemId → properties (as modify_item takes them).' },
+                            template: { type: 'object', properties: { templateId: { type: 'string' }, params: { type: 'object' } }, required: ['templateId', 'params'], description: 'template_params apply for this row.' },
+                        },
+                    },
+                },
+                export: { type: 'object', description: 'pinepaper_agent_export options for every row (format, platform, quality, duration, ad, …).' },
+                estimateOnly: { type: 'boolean', description: 'Validate and return the plan without rendering.' },
+            },
+            required: ['rows', 'export'],
+        },
+    },
     {
         name: 'pinepaper_camera_director',
         annotations: {
@@ -1933,7 +2044,7 @@ EXAMPLE: { times: [0, 0.5, 1, 1.5, 2], seed: 42 }`,
 
 ACTIONS:
 - upload_video: { url (required), position?, scale?, timeOffset? (timeline start, s), clipInPoint?, clipOutPoint? (trim, s) } → { id, duration, width, height, name }
-- upload_audio: { url (required), volume? (0–1, default 1), loop? (default true), muted?, timeOffset? } → { id, duration, name }
+- upload_audio: { url (required), volume? (0–1, default 1), loop?, muted?, timeOffset? } → { id, registryId, duration, name }. Pass loop EXPLICITLY — loop:true for a music bed, loop:false for a voice-over or sting; when omitted, the studio's own default applies and differs between builds.
 - list: → all media [{ id, kind, duration, … }]
 - remove: { id } → removed boolean
 - set_playback_rate: { id, rate (0.25–4) } → applies to video or audio
@@ -1971,7 +2082,7 @@ EXAMPLE: { action: 'upload_video', url: 'https://…/clip.mp4', scale: 0.5, time
                 strength: { type: 'number', description: 'apply_track_matte: 0–1.' },
                 hideMatte: { type: 'boolean', description: 'apply_track_matte: hide the matte item after applying.' },
                 live: { type: 'boolean', description: 'apply_track_matte: keep re-cutting as the matte moves/animates — the kinetic mask reveal. Omitted = bake once, destructively.' },
-                url: { type: 'string', description: 'Media URL — required for upload_video / upload_audio.' },
+                url: { type: 'string', description: "Required for upload_video / upload_audio: an http(s) URL, a data: URL, or a PATH TO A LOCAL FILE. Remote URLs and local files are fetched/read by the server (the page may not fetch third-party hosts), so stock music and SFX links work; the HTTP status or content-type is named if one does not. Up to 48 MB." },
                 id: { type: 'string', description: 'Media id — required for remove / set_playback_rate / set_clip.' },
                 rate: { type: 'number', description: 'Playback rate 0.25–4 — set_playback_rate.' },
                 inPoint: { type: 'number', description: 'Clip in-point (media-time s) — set_clip.' },
@@ -1982,7 +2093,7 @@ EXAMPLE: { action: 'upload_video', url: 'https://…/clip.mp4', scale: 0.5, time
                 clipInPoint: { type: 'number', description: 'Trim in-point (s) — upload_video.' },
                 clipOutPoint: { type: 'number', description: 'Trim out-point (s) — upload_video.' },
                 volume: { type: 'number', description: 'Volume 0–1 (default 1) — upload_audio.' },
-                loop: { type: 'boolean', description: 'Loop (default true) — upload_audio.' },
+                loop: { type: 'boolean', description: 'upload_audio: true = loop (music beds), false = play once (voice-over, stings). Pass it explicitly; the default when omitted is the studio\'s and differs between builds.' },
                 muted: { type: 'boolean', description: 'Start muted — upload_audio.' },
             },
             required: ['action'],
@@ -2004,11 +2115,24 @@ ACTIONS:
 - set_font_axes: { itemId, axes: { weight?, width?, slant? } } — STANDARD variable-font axes only (Canvas 2D has no font-variation-settings, so custom foundry axes are unreachable — platform limit, stated, not silent). Returns {applied, rejected}: CHECK rejected — an axis silently ignored is the failure this surface exists to prevent. All three are ordinary animatable properties: keyframe fontWeight and type breathes between weights.
 - list_styles: {} — styles + palettes + axes, for pickers. Call this first; styleKey strings come from here.
 
+OVER PHOTOGRAPHS, PASS A PALETTE — NEVER THE DEFAULT. Measured on a real
+render of captions over photographs: highlighter, sticker, caption and badge
+read correctly at the default palette. neon needs one on a dark photo. chrome,
+cutout and glitch are off-brief at the default palette over any photograph —
+they are designed against flat backgrounds and the default palette assumes one.
+A style that is hard to read still reports success, so this is a judgement the
+tool cannot make for you.
+
+MEASURE THE WIDTH BEFORE COMMITTING TO A SIZE. glitch at 80px in a monospace
+face overflows a 1920 canvas at 36 characters. Layered styles draw offset
+copies, so the group is WIDER than the text — use 'wrap' first, or shorten the
+line, rather than discovering it in an export.
+
 EXAMPLE: { action: 'apply_style', itemId: 'title_1', styleKey: 'arcade', fontFamily: 'suggested' }`,
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['apply_style', 'set_font_axes', 'list_styles', 'cursive', 'wrap', 'unwrap', 'to_collage'], description: "Text style operation. 'cursive' draws text as STROKED handwriting — a path, not a glyph, so draw-on animation and outline_stroke both apply. 'wrap'/'unwrap' break a text item to a width, reversibly. 'to_collage' converts an EXISTING text item into a letter collage in place." },
+                action: { type: 'string', enum: ['apply_style', 'set_font_axes', 'list_styles', 'list', 'cursive', 'wrap', 'unwrap', 'to_collage'], description: "Text style operation. 'list' is accepted as an alias for 'list_styles', because pinepaper_text_effect spells the same action 'list' and an agent moving between them guesses wrong. 'cursive' draws text as STROKED handwriting — a path, not a glyph, so draw-on animation and outline_stroke both apply. 'wrap'/'unwrap' break a text item to a width, reversibly. 'to_collage' converts an EXISTING text item into a letter collage in place." },
                 text: { type: 'string', description: 'cursive: the words to write. to_collage: the text to build from, if it differs from the item.' },
                 maxWidth: { type: 'number', description: 'wrap: the width to break at, in canvas units. unwrap restores the original, so this is not destructive.' },
                 cursiveOptions: { type: 'object', description: 'cursive: { x?, y?, scale?, strokeColor?, strokeWidth? }.' },
@@ -2278,9 +2402,9 @@ RECIPE — assemble-from-pieces: shatter with keepSource, keyframe each tile fro
 
 Input is the output of a single-image layer decomposer (See-through — one flat anime drawing in, ~20 occlusion-inpainted layers out — or any PSD-style layer dump with the same manifest shape). The decomposition model does NOT run here: it needs a GPU and minutes per image; run it where it fits and import the folder.
 
-Layer tags map onto the exact role tokens the expresses presets read (eye_left, pupil_right, mouth…), so pinepaper_animate/expresses blink-smile-talk work on the imported character immediately.
+Layer tags map onto the exact role tokens the expresses presets read (eye_left, pupil_right, mouth…), so blink / smile / talk work on the imported character immediately — through an 'expresses' RELATION (pinepaper_add_relation relationType expresses), which is the only thing that drives them. pinepaper_animate applies ambient motion (bounce, pulse, wobble) and cannot blink: asking it to is a silent no-op.
 
-Params: { info (the decomposer manifest: tags, xyxy rects, depth_median draw order, frame_size [h,w]), images ({tag: PNG data URL or CORS-reachable https URL} — data URLs are the reliable path; ~20 layers of base64 is a big call, use URLs when you can), position?, scale?, name? }
+Params: { info — the decomposer manifest, whose parts live under info.parts (or info.tag2pinfo) as an OBJECT KEYED BY TAG, not a layers[] array: { eye_left: { xyxy: [x0,y0,x1,y1], depth_median: <draw order> }, … } plus frame_size [h,w]. An array here imports nothing and reports no parts. images ({tag: PNG data URL or CORS-reachable https URL} — data URLs are the reliable path; ~20 layers of base64 is a big call, use URLs when you can), position?, scale?, name? }
 Returns: { groupId, parts, roles, rolesWired, warnings }
 
 CHECK rolesWired: a character importing with 0 roles renders perfectly and silently refuses to animate — that number is the difference between a picture and a puppet.`,
@@ -2464,7 +2588,7 @@ Three of these refuse quietly in the engine: exportGLB with no perspective objec
             type: 'object',
             properties: {
                 action: { type: 'string', enum: ['export_lottie', 'export_dotlottie', 'import_lottie', 'export_glb', 'export_bvh', 'export_png_sequence'], description: 'Which interchange operation.' },
-                options: { type: 'object', description: 'Format options passed through to the exporter: frame range, dimensions, fps, naming.' },
+                options: { type: 'object', description: "Format options passed through to the exporter. export_png_sequence: { duration (seconds), fps, width, height, transparent (keep alpha; default false fills the background) } — PASS duration and fps: the studio does not size the sequence to the scene, and without them it writes its own default length, which does not follow the scene (runs have measured 45 and 90 frames). The result's defaultsUsed says when that happened." },
                 data: { anyOf: [{ type: 'string' }, { type: 'object' }], description: 'import_lottie: the Lottie JSON — object, JSON string, or URL.' },
                 skeletonId: { type: 'string', description: "export_bvh: which skeleton to write. A BVH is one skeleton's motion." },
             },
@@ -2496,7 +2620,8 @@ render_soundtrack mixes every placed sound to a WAV and writes it to a file. It
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['list_instruments', 'list_percussion', 'list_sfx', 'play_tone', 'play_chord', 'chord_frequencies', 'play_percussion', 'play_sfx', 'play_spec', 'from_text', 'play_from_text', 'create', 'timbre_from_path', 'set_placement', 'remove', 'stop_all', 'define_instrument', 'define_percussion', 'define_sfx', 'render_soundtrack'], description: 'Which sound operation.' },
+                action: { type: 'string', enum: ['list_instruments', 'list_percussion', 'list_sfx', 'play_tone', 'play_chord', 'chord_frequencies', 'play_percussion', 'play_sfx', 'play_spec', 'from_text', 'play_from_text', 'create', 'sequence', 'timbre_from_path', 'set_placement', 'remove', 'stop_all', 'define_instrument', 'define_percussion', 'define_sfx', 'render_soundtrack'], description: 'Which sound operation.' },
+                cues: { type: 'array', description: "sequence: every cue in ONE call — [{t, spec|preset, note?, duration?, visual?}]. Each is created and placed at its own t, so a music bed is one call rather than one per cue. Failures come back by index in failed[], because a bed where three of a hundred cues did not sound is neither a success nor a failure.", items: { type: 'object' } },
                 partials: { type: 'array', items: { type: 'object' }, description: 'define_*: [{ h, amp }] — the harmonic table that IS the timbre. Required for define_instrument.' },
                 envelope: { type: 'object', description: 'define_*: { attack, decay, sustain, release } — seconds, except sustain which is a level 0-1.' },
                 gain: { type: 'number', description: 'define_*: output level 0-1 (0.8 instrument, 0.85 percussion, 0.65 sfx).' },
@@ -2628,7 +2753,7 @@ RECIPE — a character walking through a forest: create {spec:'forest'} → impo
                 camera: { type: 'object', description: "set_camera: { mode: follow|fixed|orbit, target?, radius?, speed?, eye?, lookAt? }." },
                 object: { type: 'object', description: 'add_object: { x, z, height?, color?, y? }. metalness/roughness are accepted and IGNORED here — a plain object is drawn by the prop shader, which declares no such uniform. They render on the mesh path only.' },
                 pathId: { type: 'string', description: 'extrude_path / lathe_path: the canvas path to turn into geometry. The path itself is unchanged.' },
-                mesh: { type: 'object', description: 'extrude_path / lathe_path options: { id?, depth?, unitsPerPixel?, caps?, segments?, arc?, flatness?, x?, y?, z?, rotY?, rotYDegrees?, scale?, doubleSided? }. arc is DEGREES; rotY is RADIANS (fed straight to cos/sin in the shader) — pass rotYDegrees to write degrees. These names are the ones the engine records as the mesh provenance, so a captured meshProvenance.opts spreads straight back in.' },
+                mesh: { type: 'object', description: 'extrude_path / lathe_path options: { id?, depth?, unitsPerPixel?, caps?, segments?, arc?, flatness?, x?, y?, z?, rotY?, rotYDegrees?, scale?, doubleSided?, color?, metalness?, roughness? }. color is hex or [r,g,b] (default light grey — without it the mesh rendered black); it becomes the shader\'s diffuse uniform. arc is DEGREES; rotY is RADIANS (fed straight to cos/sin in the shader) — pass rotYDegrees to write degrees. These names are the ones the engine records as the mesh provenance, so a captured meshProvenance.opts spreads straight back in.' },
                 meshId: { type: 'string', description: 'remove_mesh: the mesh id.' },
                 light: { type: 'object', description: 'add_light / set_light: { id?, x?, y?, z?, color?, intensity?, range? }. At most 8 point lights; the ninth is refused by name because the shader array is fixed-size.' },
                 lightId: { type: 'string', description: 'set_light / remove_light: the light id.' },
@@ -2929,6 +3054,11 @@ PARAMS: { eps? (bounds-match tolerance px, default 4), cap? (max suggestions, de
         },
         description: `Create a behavior relationship between two items. Relations are the PRIMARY way to add animation in PinePaper - they describe HOW items should behave relative to each other.
 
+MOVES_ALONG_PATH — ride a path (a hand tracing a stroke, a car on a road):
+- sourceId: the item that moves. The path comes from ONE of: targetId (or params.pathId) naming a PATH ITEM, sampled into points for you; params.path as points [[x, y], …]; or params.equation.
+- params.duration: seconds for one traversal (or pass speed directly, 1 ≈ 150 px/s). params.delay: seconds on the timeline before it starts; until then the item waits at the path start. params.offset: [dx, dy] added to the point on the path — set it to (centre - pen tip) so a hand image's TIP, not its centre, rides the stroke. closed (loop back to the start; default from the path item), phase (0–1 start point), easing (linear | easeIn | easeOut | easeInOut | sine | bounce | pingpong), signal (deterministic, frame-rate-invariant — prefer it for export).
+- With no path from any of those it is refused, not accepted as a still item.
+
 USE WHEN:
 - "moon orbits earth" → relationType: orbits
 - "label follows player" → relationType: follows
@@ -2994,7 +3124,7 @@ RELATION COMPATIBILITY:
   Text→Text: font blend
   Cross-type: particle denoising transition
 - group_morphs_to: pair-by-index morph between two paper.Groups (any two — graph vertices+edges, letter collages, dashboard clusters). Path.Line children deform via endpoints; other children translate; excess children fade. Params: duration, hold, loop, easing (linear|easeIn|easeOut|easeInOut), deformLines.
-- moves_along_path: self-relation (targetId=null); item is driven along a path. Source the path EITHER from params.path (array of {x,y} or [x,y]) OR from params.equation (S10 B5) — a math curve the item TRAVERSES, sampled deterministically on the Expression IR: params.equation = { kind: function|parametric|fourier|preset, expr | xExpr/yExpr | harmonics | preset, min, max, samples, scale, cx, cy, flipY, warp } (same equation contract as pinepaper_equation_path, but origin is cx/cy, default 0). Params: path OR equation, speed, closed, phase, easing (linear|easeIn|easeOut|easeInOut|sine|bounce|pingpong).
+- moves_along_path: self-relation (targetId=null); item is driven along a path. Source the path EITHER from params.path (array of {x,y} or [x,y]) OR from params.equation (S10 B5) — a math curve the item TRAVERSES, sampled deterministically on the Expression IR: params.equation = { kind: function|parametric|fourier|preset, expr | xExpr/yExpr | harmonics | preset, min, max, samples, scale, cx, cy, flipY, warp } (same equation contract as pinepaper_equation_path, but origin is cx/cy, default 0). READ ONLY ON THE SIGNAL PATH: easing 'bounce' is piecewise and leaves it, which silently discards the equation and leaves the item where it started. Params: path OR equation, speed, closed, phase, easing (linear|easeIn|easeOut|easeInOut|sine|bounce|pingpong).
 
 GEOMETRIC CONSTRUCTION CONSTRAINTS (Layer 2) — the source item is RE-DERIVED every frame from its anchor item(s), so dragging an anchor updates the dependent live (GeoGebra-style), and the construction persists as relation graph data (edit it by editing relations, not by re-running code). Anchor A is the relation target; extra anchors ride in params:
 - is_midpoint_of: source = midpoint(target, params.other). params.other = id of the second endpoint (B).
@@ -3372,9 +3502,13 @@ ANIMATABLE PROPERTIES:
 - opacity: 0-1
 - fillColor: Color string
 - strokeColor: Color string
+- strokeWidth, width, height, radius, shadowBlur, shadowColor: Numbers / colours
 - fontSize: Number
+- STROKE DRAW-ON (paths): trimStart, trimEnd (0-1 of the path's length), trimOffset (shifts the visible window along it), dashArray. A draw-on is trimEnd 0 -> 1.
+The authoritative list for a given item is pinepaper_get_animatable_properties — ask it rather than guessing.
 
-EASING OPTIONS:
+EASING — IT SHAPES THE SEGMENT ARRIVING AT THE KEYFRAME IT IS ON.
+The move from keyframe A to keyframe B is eased by B's easing, not A's. Easing on the FIRST keyframe does nothing (no segment arrives at it) — a Ken Burns with easing only on its first key plays linear. Put the easing on the key you are moving TO.
 - linear: Constant speed
 - easeIn: Slow start
 - easeOut: Slow end
@@ -3410,6 +3544,7 @@ EXAMPLE — Reveal at 2s, skip first second of keyframe data, end at 4s of keyfr
                             easing: {
                                 type: 'string',
                                 enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'bounce', 'elastic'],
+                                description: 'Shapes the segment ARRIVING at this keyframe (from the previous one). Ignored on the first keyframe.',
                             },
                         },
                         required: ['time', 'properties'],
@@ -3617,7 +3752,9 @@ USE WHEN:
 - Creating complex reveal sequences
 - Building custom transitions
 
-Requires maskType and keyframes array.`,
+Requires maskType and keyframes array.
+
+COORDINATES: a 'rectangle' mask's x / y are its TOP-LEFT corner (measured: {x:540, y:620, width:800, height:800} reads back as bounds [540, 620, 800, 800]) — unlike items, which are placed by their centre. Convert before masking an item you placed by centre.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -3754,7 +3891,6 @@ USE WHEN:
 - Building presentation zoom sequences
 - Making dramatic reveals with camera motion
 - Tour animations showing different parts of canvas
-- 3D perspective effects (pitch/yaw tilt via equirectangular projection)
 
 The camera follows a keyframe sequence. For an orbit-style camera (revolving
 around a subject), add 4-8 keyframes around the pivot using pathMode: "arc"
@@ -3769,8 +3905,7 @@ KEYFRAME PROPERTIES:
     'item-id'                      itemRegistry lookup → item bounds center (tracks the item as it moves)
     { item: 'id', offset: [dx, dy] } item center + offset
 - center: [x, y] — legacy alias, honored only when focus is absent
-- pitch: 3D tilt in degrees (0=flat, positive=tilt forward). Uses equirectangular projection
-- yaw: 3D rotation in degrees. Uses equirectangular projection
+- pitch / yaw: 3D tilt in degrees. Rendered by studio builds that support camera tilt; on others they are accepted with NO visible effect — the result's tiltRenders says which this studio is, and a note appears when a tilt would be invisible.
 - easing: Timing function (linear, easeIn, easeOut, easeInOut, bounce, elastic)
 
 CURVED INTER-KEYFRAME PATHS (optional; default is linear):
@@ -3822,8 +3957,8 @@ EXAMPLE (curved arc between waypoints):
                                 items: { type: 'number' },
                                 description: 'Legacy view center [x, y] — honored only when focus is absent',
                             },
-                            pitch: { type: 'number', description: '3D tilt in degrees (0=flat, positive=forward tilt)' },
-                            yaw: { type: 'number', description: '3D rotation in degrees' },
+                            pitch: { type: 'number', description: '3D tilt in degrees — rendered where the studio supports camera tilt (result.tiltRenders).' },
+                            yaw: { type: 'number', description: '3D rotation in degrees — rendered where the studio supports camera tilt (result.tiltRenders).' },
                             easing: {
                                 type: 'string',
                                 enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'bounce', 'elastic'],
@@ -3860,12 +3995,12 @@ EXAMPLE (curved arc between waypoints):
                         },
                     },
                 },
-                duration: { type: 'number', description: 'Total animation duration in seconds' },
+                duration: { type: 'number', description: 'Total animation duration in seconds. Optional: omitted, the camera runs to its last keyframe.' },
                 loop: { type: 'boolean', description: 'Loop the animation' },
                 delay: { type: 'number', description: 'Delay before animation starts' },
                 fov: { type: 'number', description: 'Field of view in degrees for 3D perspective (default: 60)' },
             },
-            required: ['keyframes', 'duration'],
+            required: ['keyframes'],
         },
     },
     {
@@ -4004,8 +4139,8 @@ SUPPORTED ANIMATIONS: bounce, breathe, fade, glow, jelly, path, pulse, rotate, s
                             },
                             itemType: {
                                 type: 'string',
-                                enum: ['text', 'circle', 'star', 'rectangle', 'triangle', 'polygon', 'ellipse', 'path', 'line', 'arc'],
-                                description: 'Type of item to create',
+                                enum: [...ItemTypeSchema.options],
+                                description: 'Type of item to create. Every type the engine has — this used to advertise ten while the tool hand-built four and turned the rest into a small circle.',
                             },
                             position: {
                                 type: 'object',
@@ -4293,7 +4428,7 @@ EXAMPLE:
         },
         description: `Shape a delay across many items. What makes a stagger read as designed rather than as a queue is where it STARTS and how it SPREADS — a grid lighting up outward from the centre, a row converging from both edges.
 
-Delays are written to the channel the engine and the SMIL exporter already read, so a staggered scene scrubs, exports and restores. Nothing here is playback-only.
+Delays go where each kind of animation reads them: loop presets take animationDelay, and an item that already has a KEYFRAME track has that track's start offset (timeOffset) shifted by its delay — so apply the stagger after the keyframes, and re-applying replaces the shift rather than adding to it. The result's shiftedKeyframeTracks says how many tracks moved.
 
 ACTIONS:
 - apply: write the delays onto real items, in the order you list them (row-major for a grid).
@@ -4760,7 +4895,7 @@ Both actions return a WCAG contrast audit, so you can see failing pairs before s
 ACTIONS:
 - define: Turn items into a component master. Params: itemIds[], name
 - list: All defined components
-- instantiate: Place an instance. Params: componentId, position, overrides
+- instantiate: Place an instance. Params: componentId, position, overrides → { instanceId, parts: [{key, type, content?}], orphaned }. overrides is { <componentKey>: { <prop>: value } }, e.g. { "ck_1": { "content": "50% OFF" }, "ck_2": { "fillColor": "#e11d48" } } — keys come from list (each component's parts) or from a previous instantiate.
 - set_override: Change ONE part of ONE instance without detaching it. Params: instanceId, componentKey, prop, value
 - sync: Push the master's current state to every instance (overrides are preserved). Params: componentId
 - update_from_instance: Promote an instance's edits back into the master. Params: instanceId
@@ -4788,7 +4923,7 @@ Overrides are the point: an instance can differ from its master and still receiv
                     anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }, { type: 'object' }, { type: 'array' }],
                     description: 'Override value',
                 },
-                overrides: { type: 'object', description: 'Overrides applied at instantiate time' },
+                overrides: { type: 'object', description: 'instantiate: { <componentKey>: { <prop>: value } } — keys are listed in parts by list and instantiate. A key the component does not have is reported in orphaned, not applied silently.' },
             },
             required: ['action'],
         },
@@ -4933,7 +5068,7 @@ node survives none of them.`,
             type: 'object',
             properties: {
                 action: { type: 'string', enum: ['analyze', 'animate_to_beat'] },
-                source: { type: 'string', description: 'Asset id, data URL, or URL' },
+                source: { type: 'string', description: 'Asset id, data URL, URL — or an uploaded clip\'s id / registryId from pinepaper_media upload_audio / upload_video.' },
                 itemId: { type: 'string' },
                 beats: { type: 'array', items: { type: 'number' }, description: 'Beat times (s) you already have' },
                 grid: { type: 'boolean', description: 'Even pulse from the tempo instead of raw onsets' },
@@ -5023,26 +5158,28 @@ ACTIONS:
 
 Available filters (GPU raster set):
 - Color: grayscale, sepia, brightness, contrast, saturation, invert, posterize (levels), hsl (hue/saturation/lightness), colorTint (color, intensity, blendMode), colorMatrix (matrix), duotone (shadow, highlight, mix), paletteMap (swatches[], amount, preserveShading — recolor to a fixed palette)
-- Stylize: vignette (intensity, radius), edgeDetect, halftoneDots (size, angle), halftoneCMYK (size), dither (levels), grain (amount, seed), scanlines (intensity, period), chromaticAberration (amount), blur
+- Stylize: vignette (intensity, radius), edgeDetect, halftoneDots (size, angle), halftoneCMYK (size), dither (levels), grain (amount, seed), scanlines (intensity, period), chromaticAberration (amount), blur (radius)
 - Light (additive): bloom (amount, threshold, radius), glow, halation (warm-fringed bloom; color), lightShafts (amount, threshold, decay, density, x, y, color — volumetric rays from a point)
 - Keying: lumaKey (threshold, softness, invert)
 - SECOND-INPUT (params.map = another item's id, resolved to its pixels): displace (amount, dispersion, map, mapChannel — the map's brightness pushes pixels), refract (displace with per-channel dispersion — glass), trackMatte (channel, invert, strength — prefer pinepaper_media apply_track_matte for the live version), datamosh (amount, block, map? — self-moshes without a map)
 
 RECIPE — grunge poster: chain [grain, scanlines, vignette]. Glass header: refract with map = a gradient item.
+HARD-EDGED LOOKS NEED SMOOTHING OFF: posterize, dither, halftone and pixel looks are exact at 1:1, but a raster that is then scaled, skewed or rotated is RESAMPLED with smoothing, which blends the flat levels back into a gradient (measured: posterize then skew → 256 tones again). Set smoothing 'off' on the image (pinepaper_import_image, or pinepaper_modify_item {smoothing: 'off'}) to keep the levels.
+CHAIN ORDER MATTERS: each filter runs on the previous one's output. duotone then halftoneDots comes out grey (the ink colour is lost); halftoneDots then duotone keeps it. If a chain loses its colour, move the colour-mapping filter (duotone, paletteMap, colorTint) to the end.
 (Scene-wide filters — sharpen/emboss/noise/vintage etc. — are a different surface: use pinepaper_add_filter.)`,
         inputSchema: {
             type: 'object',
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['apply', 'chain'],
+                    enum: ['apply', 'chain', 'analyze_palette', 'recolor_palette'],
                     description: 'Filter action',
                 },
                 itemId: { type: 'string', description: 'Target raster item ID' },
                 filterName: { type: 'string', description: 'Filter name (for apply)' },
                 params: {
                     type: 'object',
-                    description: 'Filter parameters (e.g. {amount: 5} for blur)',
+                    description: "Filter parameters, named per filter in the list above. Blur takes {radius: 5} — a misspelled parameter is ignored rather than refused, so check the name. For blur only, 'amount' is accepted as an alias for radius because this example used to say so; every other filter that lists amount reads amount.",
                 },
                 filters: {
                     type: 'array',
@@ -5054,8 +5191,18 @@ RECIPE — grunge poster: chain [grain, scanlines, vignette]. Glass header: refr
                         },
                         required: ['name'],
                     },
-                    description: 'Filter chain (for chain action)',
+                    description: 'Filter chain (for chain action). Order matters — see CHAIN ORDER above.',
+                },
+                maxSwatches: { type: 'integer', minimum: 1, maximum: 32, description: 'analyze_palette: swatch count cap (default 8).' },
+                mapping: {
+                    oneOf: [
+                        { type: 'array', items: { type: 'object', properties: { from: { type: 'string' }, to: { type: 'string' } }, required: ['from', 'to'] } },
+                        { type: 'object', additionalProperties: { type: 'string' } },
+                    ],
+                    description: "recolor_palette: {from,to}[] or {'#old':'#new'} — colours swap, shading survives.",
                 },
+                amount: { type: 'number', minimum: 0, maximum: 1, description: 'recolor_palette: blend 0–1. (A filter\'s own amount goes in params.)' },
+                preserveShading: { type: 'number', minimum: 0, maximum: 1, description: 'recolor_palette: how much of the original luminance detail survives (default 1).' },
             },
             required: ['action', 'itemId'],
         },
@@ -5069,20 +5216,28 @@ RECIPE — grunge poster: chain [grain, scanlines, vignette]. Glass header: refr
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Freeform lasso selection for image items.
+        description: `Cut a region out of an image along a polygon — the subject cutout behind 2.5D parallax, stickers and collage.
 
 ACTIONS:
-- activate: Start lasso mode on an image item. Params: itemId
-- apply: Confirm and apply the lasso selection`,
+- cut: { itemId, points: [[x, y], …] (canvas coordinates, at least 3 vertices, in order around the subject), keepOriginal? (default true) } → { cutoutId, originalId, originalKept }. The cutout is a NEW image item, placed exactly over the region it came from, transparent outside the polygon. keepOriginal:false consumes the source image (the studio's own lasso deletes it); the default keeps it, so you can layer the cutout over the photo.
+- activate / apply: the interactive, mouse-driven lasso. Refused over MCP — use cut.
+
+Vertices closer than 12 px to the FIRST vertex are skipped (the lasso reads a click there as "close the shape"), so trace with points at least that far from where you started.`,
         inputSchema: {
             type: 'object',
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['activate', 'apply'],
-                    description: 'Lasso action',
+                    enum: ['cut', 'activate', 'apply'],
+                    description: 'Lasso action — cut is the one that works over MCP',
+                },
+                itemId: { type: 'string', description: 'The image item to cut from' },
+                points: {
+                    type: 'array',
+                    description: 'cut: polygon vertices in canvas coordinates, [x, y] or {x, y}, at least 3',
+                    items: { anyOf: [{ type: 'array', items: { type: 'number' }, minItems: 2, maxItems: 2 }, { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, required: ['x', 'y'] }] },
                 },
-                itemId: { type: 'string', description: 'Target image item ID (for activate)' },
+                keepOriginal: { type: 'boolean', description: 'cut: keep the source image (default true). false = the source is consumed.' },
             },
             required: ['action'],
         },
@@ -5514,6 +5669,9 @@ Params: title (page title), download (bool)`,
             type: 'object',
             properties: {
                 title: { type: 'string', description: 'HTML page title (default: PinePaper Widget)' },
+                lang: { type: 'string', description: 'BCP 47 language tag for the page (default en), e.g. "ar", "hi", "zh-Hans".' },
+                dir: { type: 'string', enum: ['ltr', 'rtl', 'auto'], description: 'Text direction for the page — "rtl" for Arabic / Hebrew.' },
+                alt: { type: 'string', description: 'Text alternative for the animation: the canvas gets role="img" and this as its aria-label, and the page a meta description. Screen readers otherwise announce nothing.' },
                 download: { type: 'boolean', description: 'Trigger browser download (default: false)' },
             },
         },
@@ -6419,6 +6577,7 @@ ACTIONS:
 
 ACTIONS:
 - enable      — { rotation?: [lambda,phi,gamma], momentum?, showOcean? }     switch to globe mode
+- disable     — {}                                                           leave globe mode: stops spin, drag and rotation (reload the map for a flat projection)
 - rotate_to   — { lon, lat, duration? }                                       versor-slerp the globe to face a coordinate
 - spin        — { speed?, axis?: "longitude"|"latitude", duration? }          continuous auto-rotation
 - world_tour  — { regions?: string[] | coords?: [lon,lat][], dwell?, travel?, tilt?, loop?, easing?, highlightColors?: string[], showLabels?, labelColor? }   the headline: the globe swings to each stop, highlighting it (requires regions OR coords)
@@ -6428,7 +6587,7 @@ ACTIONS:
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['enable', 'rotate_to', 'spin', 'world_tour', 'stop_tour', 'pin_item', 'tour_item'], description: 'Globe action' },
+                action: { type: 'string', enum: ['enable', 'disable', 'rotate_to', 'spin', 'world_tour', 'stop_tour', 'pin_item', 'tour_item'], description: 'Globe action' },
                 rotation: { type: 'array', items: { type: 'number' }, description: 'Initial rotation [lambda, phi, gamma] (enable)' },
                 momentum: { type: 'boolean', description: 'Drag-spin inertia (enable)' },
                 showOcean: { type: 'boolean', description: 'Render ocean sphere (enable)' },
@@ -6472,7 +6631,8 @@ ACTIONS:
 Most of this tool is glyph authoring — drawing a typeface. If you just want to know what font families are available to set on a text item, that is ONE action:
 
 - list_available       — { category?, loadedOnly? }  every family the studio can render, with whether its file is loaded yet
-- check                — { name, text? }             is this family really there, and can it draw THIS string? Pass the text: a font with four glyphs is installed and will still render most characters in the fallback face, and that second answer is the one that decides the pixels. Do NOT rely on document.fonts.check() — it returns true for a family that does not exist.
+- load                 — { name }                    load a family NOW: the studio's catalogue first, then Google Fonts (e.g. Monoton). Returns available + via. Text tools also load on first use, so this is for checking up front.
+- check                — { name, text? }             is this family really there, and can it draw THIS string? "available: false" means NOT LOADED YET — the result says whether it is loadable; use load. Pass the text: a font with four glyphs is installed and will still render most characters in the fallback face, and that second answer is the one that decides the pixels. Do NOT rely on document.fonts.check() — it returns true for a family that does not exist.
 - fallbacks            — {}                          which text items on the canvas are silently drawing in something other than the family they asked for
 
 ACTIONS (authoring):
@@ -6498,7 +6658,7 @@ ACTIONS (authoring):
                 action: {
                     type: 'string',
                     enum: [
-                        'list_available', 'check', 'fallbacks',
+                        'list_available', 'check', 'load', 'fallbacks',
                         'show_studio', 'set_name', 'get_required_chars', 'get_status',
                         'create_glyph', 'create_space', 'remove_glyph', 'set_metrics',
                         'export', 'load_into_document', 'export_data', 'import_data',
@@ -6509,7 +6669,8 @@ ACTIONS (authoring):
                 text: { type: 'string', description: 'check: the string you intend to draw. Without it you learn only whether the family is installed, not whether it has glyphs for your characters.' },
                 category: { type: 'string', description: 'list_available: narrow to one category (e.g. display, serif, mono).' },
                 loadedOnly: { type: 'boolean', description: 'list_available: only families whose font file has already loaded. Unloaded ones still render once the studio fetches them.' },
-                name: { type: 'string', description: 'Font name (set_name)' },
+                name: { type: 'string', description: 'Font family (check, load) or the font being built (set_name). family / fontFamily are accepted for it.' },
+                family: { type: 'string', description: 'Alias of name, for check / load.' },
                 set: { type: 'string', description: 'Character set name (get_required_chars; default "minimum")' },
                 character: { type: 'string', description: 'Single-character glyph identifier (create_glyph, remove_glyph)' },
                 pathId: { type: 'string', description: 'Item id of the path source (create_glyph, remove_overlap, correct_direction, cleanup_path)' },
@@ -6772,7 +6933,7 @@ New — Geometric:
 - drawGeometricAbstract: Mixed translucent shapes (colors, shapeCount, blendMode, rotation)
 
 New — Particles:
-- drawWindField: Directional wind particles with noise turbulence (particleCount, colors, direction, turbulence, trailLength, speed)
+- drawWindField: Directional wind particles with noise turbulence (particleCount, colors, windDirection (degrees), windSpeed, turbulence, trailLength, trailWidth, opacity, bgColor; direction / speed are accepted for windDirection / windSpeed)
 
 New — Textures:
 - drawNoiseTexture: Perlin/grain/stipple noise (noiseType: perlin|grain|stipple, colors, scale, density, animated)
@@ -6795,7 +6956,7 @@ S6 Procedural (seeded, OKLCH palettes, curated presets, optional Motion). All ta
 GPU / GLSL math-art (transpiled to a fragment shader, 60fps; all take renderScale 0.25–1, transparentBg, speed):
 - drawFormulaArt: type a math expression in x,y,t → scalar mapped through a 3-stop palette (formula, domain, color1/color2/color3). Try sin(x*5+t)*cos(y*3).
 - drawParametricCollection: N circles or line segments indexed by k, expressions in k,N,t — Yeganeh-style (mode: circles|lines, count, xExpression/yExpression/radiusExpression or x1..y2Expression, scale, palette, bgColor).
-- drawShaderArt: paste your own GLSL fragment shader (fragmentSource; uniforms u_time, u_resolution, u_color1/2/3) or pick a preset.
+- drawShaderArt: a GLSL fragment shader. PASSING fragmentSource ALONE DOES NOTHING — preset defaults to 'wavefield' and wins, so your shader is ignored and a preset renders instead, reporting success. Pass preset: 'custom' to use fragmentSource verbatim. The shader is GLSL ES 3.00: inputs 'in vec2 v_uv', output 'out vec4 outColor' — NOT gl_FragColor, and there is no u_uv. Uniforms: u_time, u_resolution (vec2), u_color1/2/3 (vec3). Other presets: wavefield, gradient_glow, noise_clouds, voronoi, simplex_noise, perlin, pulsing_border. renderScale 0.25-1 (default 0.5) trades resolution for speed.
 - drawYeganehMountains: GLSL port of Hamid Naderi Yeganeh's "Mountains" (mountainCount, timeOffset, skyTop, skyBottom, ridgeColor, valleyColor).
 
 OKLCH seeded backgrounds (palette + seed → reproducible):
@@ -6825,14 +6986,19 @@ COMMON PARAMS (all generators):
                 },
                 region: {
                     type: 'object',
-                    description: 'Optional sub-region {x, y, width, height} (canvas coords) — generator draws into a clipped, translated sub-group instead of full-canvas. Region runs imply preserve (won\'t wipe the canvas) and re-running the same generator replaces its prior region; different generators\' regions coexist. Invalid/zero-size regions fall back to full-canvas.',
+                    description: 'Optional sub-region {x, y, width, height} (canvas coords) — generator draws into a clipped, translated sub-group instead of full-canvas. Region runs imply preserve (won\'t wipe the canvas). An instance is the generator plus its box, or an explicit region.id: re-running with the same box (or id) replaces it, and the same generator in a different box adds another — so one generator several times, or several generators side by side, is regions. Older studios keep one region per generator (a second box replaces the first). Invalid/zero-size regions fall back to full-canvas. shape clips the region to a rounded rect, ellipse, circle, polygon or star, or to an existing path ({itemId}: x/y/width/height may then be omitted and default to its bounds). A studio without region shapes says so in the result (regionShapeApplied: false). On older studios, some generators also paint a page-wide background when confined to a region.',
                     properties: {
                         x: { type: 'number', description: 'Region top-left X in canvas coords' },
                         y: { type: 'number', description: 'Region top-left Y in canvas coords' },
                         width: { type: 'number', minimum: 1, description: 'Region width in pixels' },
                         height: { type: 'number', minimum: 1, description: 'Region height in pixels' },
+                        shape: { anyOf: [{ type: 'string', enum: ['rect', 'roundedRect', 'ellipse', 'circle', 'polygon', 'star'] }, { type: 'object', properties: { itemId: { type: 'string' } }, required: ['itemId'] }], description: "Clip shape (default 'rect'), or {itemId} to clip to that path's geometry." },
+                        radius: { type: 'number', minimum: 0, description: 'roundedRect corner radius (default 20% of the shorter side).' },
+                        sides: { type: 'integer', minimum: 3, maximum: 64, description: 'polygon sides (default 6).' },
+                        points: { type: 'integer', minimum: 3, maximum: 64, description: 'star points (default 5).' },
+                        innerRatio: { type: 'number', minimum: 0.05, maximum: 0.95, description: 'star inner radius / outer (default 0.5).' },
+                        id: { type: 'string', minLength: 1, maxLength: 64, description: 'Names this region instance, so re-running under the same id replaces it even if its box moved.' },
                     },
-                    required: ['x', 'y', 'width', 'height'],
                 },
             },
             required: ['generatorName'],
@@ -6879,6 +7045,15 @@ USE WHEN:
 - Celebration effects (confetti)
 - Enhancing visual impact (ripple, glow, electric)
 
+SIZE IS A MULTIPLIER, NOT PIXELS — and this is the one that bites hardest.
+Every effect derives its scale from the ITEM'S OWN BOUNDS, and 'size' multiplies
+that. glow computes a radius from max(width, height) and pulses it to
+'1 + (size - 1)', so size: 30 on a modest item asks for a disc thousands of
+pixels across, gets one, and reports success. Typical values are 1.5 to 3 —
+glow's own default is 1.5. Pass a pixel count here and you will be wrong by
+about two orders of magnitude. A recent studio warns about it
+(kind: 'glow-size-unit'); an older one does not.
+
 EFFECTS (15 particle + 7 shader auras):
 - sparkle: Glitter/sparkle particles (color, speed, size)
 - blast: Explosion burst effect (color, radius, count)
@@ -6955,13 +7130,14 @@ AVAILABLE FILTERS:
 - blur: Gaussian blur effect (params: radius 0-20)
 - brightness: Adjust brightness (params: value -100 to 100)
 - contrast: Adjust contrast (params: value -100 to 100)
-- saturate: Adjust color saturation (params: value -100 to 100)
+- saturation: Adjust color saturation (params: value -100 to 100). 'saturate' is accepted as the same filter.
 - invert: Invert colors (params: intensity 0-1)
 - noise: Add film grain (params: intensity 0-100, monochrome: true/false)
 - vignette: Darken edges (params: intensity 0-1, radius 0-1)
 - vintage: Preset combining sepia, vignette, noise
 - colorOverlay: Add color tint (params: color, intensity, blendMode)
 - sharpen: Increase sharpness (params: intensity 0-100)
+- emboss: 3D emboss (params: intensity 0-1)
 - posterize: Reduce color levels (params: levels 2-32)
 
 EXAMPLES:
@@ -6976,7 +7152,7 @@ Filters can be stacked - call multiple times to combine effects.`,
             properties: {
                 filterType: {
                     type: 'string',
-                    enum: ['grayscale', 'sepia', 'blur', 'brightness', 'contrast', 'saturate', 'invert', 'noise', 'vignette', 'vintage', 'colorOverlay', 'sharpen', 'posterize'],
+                    enum: ['grayscale', 'sepia', 'blur', 'brightness', 'contrast', 'saturation', 'invert', 'noise', 'vignette', 'vintage', 'colorOverlay', 'sharpen', 'emboss', 'posterize', 'saturate'],
                     description: 'Type of filter to apply',
                 },
                 params: {
@@ -7408,7 +7584,7 @@ WORKFLOW: start_job → batch_execute (everything in ONE call) → end_job (scre
 
 RETURNS: canvasSize {width, height} — use this to position items within bounds. Also returns ontology: a pp: triples + item summary snapshot of the (typically empty) canvas. Reuse this baseline across the same agent turn instead of calling pinepaper_get_canvas_ontology unless you've mutated the canvas. When clearCanvas is false, the ontology captures whatever's already on the canvas.
 
-CANVAS PRESETS: instagram (1080x1080), instagram-story (1080x1920), tiktok (1080x1920), youtube (1920x1080), youtube-thumbnail (1280x720), twitter (1200x675), linkedin (1200x627), web, print-a4, print-letter`,
+CANVAS PRESETS: instagram (1080x1080), instagram-story (1080x1920), tiktok (1080x1920), youtube (1920x1080), youtube-thumbnail (1280x720), twitter (1200x675), linkedin (1200x627), web, print-a4, print-letter, print-a4-landscape, print-letter-landscape (print presets carry 300 dpi, so a PDF comes out at paper size)`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -7422,12 +7598,12 @@ CANVAS PRESETS: instagram (1080x1080), instagram-story (1080x1920), tiktok (1080
                 },
                 screenshotPolicy: {
                     type: 'string',
-                    enum: ['on_complete', 'on_error', 'never', 'on_request'],
-                    description: 'When to take screenshots (default: on_complete)',
+                    enum: ['on_complete', 'on_error', 'none', 'on_request', 'never'],
+                    description: "When to take screenshots (default: on_complete). 'never' is accepted as 'none'.",
                 },
                 canvasPreset: {
                     type: 'string',
-                    enum: ['instagram', 'instagram-story', 'tiktok', 'youtube', 'youtube-thumbnail', 'twitter', 'linkedin', 'web', 'print-a4', 'print-letter'],
+                    enum: ['instagram', 'instagram-story', 'tiktok', 'youtube', 'youtube-thumbnail', 'twitter', 'linkedin', 'web', 'print-a4', 'print-letter', 'print-a4-landscape', 'print-letter-landscape'],
                     description: 'Set canvas size to platform preset',
                 },
                 clearCanvas: {
@@ -7534,7 +7710,7 @@ EXAMPLES:
             properties: {
                 canvasPreset: {
                     type: 'string',
-                    enum: ['instagram', 'instagram-story', 'tiktok', 'youtube', 'youtube-thumbnail', 'twitter', 'linkedin', 'web', 'print-a4', 'print-letter'],
+                    enum: ['instagram', 'instagram-story', 'tiktok', 'youtube', 'youtube-thumbnail', 'twitter', 'linkedin', 'web', 'print-a4', 'print-letter', 'print-a4-landscape', 'print-letter-landscape'],
                     description: 'Set canvas size to platform preset after reset',
                 },
                 backgroundColor: {
@@ -7563,7 +7739,7 @@ NOTE: For diagrams (flowcharts, UML), use pinepaper_create_diagram_shape + pinep
 
 ⚠️ EVERY operation executes LIVE on the canvas. Calling this twice DOUBLES all items. Call ONCE per pipeline.
 
-⚠️ SIZING: All positions/sizes MUST fit within the canvas. start_job returns canvasSize. Keep items within 5%-95% of canvas width/height. Max canvas: 4096x4096.
+⚠️ SIZING: All positions/sizes MUST fit within the canvas. start_job returns canvasSize. Keep items within 5%-95% of canvas width/height. Max canvas: 8192x8192.
 
 ONTOLOGY PREFLIGHT: Before code generation, this tool validates itemType, relationType, effectType, and generatorName against the canonical PinePaper vocabulary. A typo (e.g. "circel") returns a structured VALIDATION_ERROR with the operation index, the offending field, the canonical valid list, and a suggested fix — fix and retry rather than guessing. Pass skipValidation: true to bypass when intentionally using experimental vocabulary.
 
@@ -7599,8 +7775,8 @@ ANIMATION:
   animate — Loop animation: {itemId, animationType, animationOptions}
     animationType: ${SIMPLE_ANIMATION_TYPES_LIST}
   keyframe_animate — Timed animation: {itemId, keyframes: [{time, properties, easing}], duration, loop}
-    Animatable properties: opacity, scale, scaleX, scaleY, x, y, rotation, fillColor, strokeColor, fontSize
-    Easing: easeInOut, easeIn, easeOut, easeInCubic, easeOutCubic, easeOutBounce, linear
+    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}
     relationType: orbits, follows, attached_to, points_at, mirrors, parallax, wave_through, morphs_to, group_morphs_to, moves_along_path (+ 9 more in schema)
 
@@ -7650,8 +7826,8 @@ EXAMPLE — Animated sky scene with timed reveals:
                                 description: 'Operation type',
                             },
                             // Canvas setup
-                            width: { type: 'number', description: 'Canvas width for set_canvas_size (100-4096)' },
-                            height: { type: 'number', description: 'Canvas height for set_canvas_size (100-4096)' },
+                            width: { type: 'number', description: 'Canvas width for set_canvas_size (100-8192)' },
+                            height: { type: 'number', description: 'Canvas height for set_canvas_size (100-8192)' },
                             preset: { type: 'string', description: 'Canvas preset for set_canvas_size' },
                             backgroundColor: { type: 'string', description: 'For set_background: hex color' },
                             generatorName: {
@@ -7803,7 +7979,10 @@ Held exports last until released, or until a LATER export needs the space — an
 
 WHAT quality ACTUALLY SETS, because it bundles three things and only one of them is "quality": draft = 15fps / 72dpi / compression 0.6, standard = 30fps / 150dpi / 0.85, high = 60fps / 300dpi / 0.95. So asking for high DOUBLES the frame count and the render time against standard. Override either half directly - fps for frame rate, scale for resolution - and leave quality to mean compression.
 
-DOES THIS SURVIVE EXPORT? It is a PATH fact, not a per-feature one, so the rule is short and does not go stale as capabilities land: IF IT TICKS INSIDE THE ENGINE'S UPDATE LOOP, IT EXPORTS. Loop animations, relations, keyframes, generators and camera moves all do - measured frame-by-frame, not assumed. What does NOT survive is anything driven by the wall clock outside that loop, or anything on the realtime recorder path.
+DOES THIS SURVIVE EXPORT? It is a PATH fact, not a per-feature one, so the rule is short and does not go stale as capabilities land: IF IT TICKS INSIDE THE ENGINE'S UPDATE LOOP, IT EXPORTS. Loop presets (pinepaper_animate), relations, keyframes, generators and camera moves all do - measured frame-by-frame, not assumed. What does NOT survive is anything driven by the wall clock outside that loop, or anything on the realtime recorder path.
+ONE MEASURED EXCEPTION TO CHECK: keyframe_animate's loop:true has been measured playing ONCE in an export and then holding the last keyframe. Before exporting past one cycle, sample a frame in the second cycle; if it holds, write the keyframes out for each cycle, or use a loop preset.
+
+SEAMLESS LOOPS: there is no loop switch on export. Key the animation to the SAME state at t = 0 and at t = duration, and export exactly that duration — the export renders t = 0 up to one frame before duration, so no frame is doubled at the wrap. A GIF's play count is the loop parameter.
 
 If exported frames look frozen, check the SAMPLING before believing it: a loop animation at animationSpeed 1 has a one-second period, so two frames a whole second apart are identical by design. Compare frames that are not a whole number of periods apart.
 
@@ -7817,6 +7996,8 @@ PLATFORMS & OPTIMAL FORMATS:
 | twitter         | 1200x675   | PNG    | GIF      |
 | web             | flexible   | SVG    | SVG      |
 
+A preset's dimensions assume the canvas has the same aspect. When it does not, the canvas aspect is KEPT (never stretched) and its short edge takes the preset's short edge — a 4:5 canvas on instagram exports 1080x1350 — and the result carries platformFit saying so.
+
 FORMATS: svg, png, gif, mp4, webm, pdf.
 QUALITY: draft, standard, high.
 FRAMING: canvas (default, full canvas) | camera (camera_animates first-keyframe viewport — video formats only, requires a keyframe-mode walkthrough on the canvas; camera animation still drives motion within the fixed output frame).
@@ -7831,19 +8012,21 @@ EXAMPLES:
 - {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, 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.`,
+Every export answers the second question too: the result carries "fidelity", which says whether the check could run at all (available), what this scene loses to the format you chose (warnings), and what that verdict was derived from (checked). An empty warnings list with a note means this SCENE loses nothing to this format — not that the format is lossless.
+
+VERIFY MOTION BEFORE YOU RENDER. An export takes seconds to minutes and shows you the result only at the end, by which time a frozen animation has cost you the whole render. pinepaper_capture_frames samples the timeline and reports allIdentical plus per-frame hashes, so a scene that is not moving is one cheap call away — it is the fastest way to catch a frozen chart, an animation whose tail never fires, or a curve that was never drawn. Run it before a long export, not after.`,
         inputSchema: {
             type: 'object',
             properties: {
                 platform: {
                     type: 'string',
-                    enum: ['auto', 'instagram', 'instagram-story', 'tiktok', 'youtube', 'youtube-thumbnail', 'twitter', 'linkedin', 'web', 'print-a4', 'print-letter'],
+                    enum: ['auto', 'instagram', 'instagram-story', 'tiktok', 'youtube', 'youtube-thumbnail', 'twitter', 'linkedin', 'web', 'print-a4', 'print-letter', 'print-a4-landscape', 'print-letter-landscape'],
                     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',
-                    enum: ['svg', 'png', 'gif', 'mp4', 'webm', 'pdf', 'wav'],
-                    description: "Override format (auto-detected if not specified). 'wav' exports the SOUNDTRACK ON ITS OWN, with no frames rendered — no platform preset resolves to it, so it must be asked for by name, and platform dimensions, framing and quality do not apply.",
+                    enum: ['svg', 'png', 'gif', 'apng', 'mp4', 'webm', 'pdf', 'jpg', 'webp', 'srt', 'vtt', 'wav', 'scc', 'html5-ad', 'playable'],
+                    description: "Override format (auto-detected if not specified). 'scc' is broadcast CEA-608 captions (CC1, pop-on, 29.97 drop-frame; two rows of 32 characters, Latin set) from the same timed text as srt / vtt — the result names captions cut, characters dropped and captions that had to go on late. 'html5-ad' is a display-network HTML5 ad (Google Ads, DV360 / CM360, most DSPs): a zip with index.html carrying the ad.size meta and a clickTag click target (the whole ad, or ad.ctaItemId's box), plus a backup PNG saved beside it; the result checks the zip against ad.maxBytes (default 150000) and lists any external requests. 'playable' is an MRAID playable: one HTML file loading mraid.js, whose CTA (ad.ctaItemId, required) opens ad.clickUrl (required) through mraid.open. Both are built from the standalone widget page at the canvas size. 'apng' is animation with FULL alpha (stepped PNG frames, saved as .png; transparent unless transparent: false) — the answer for an animated overlay or sticker, since webm here cannot carry alpha and gif's transparency is 1-bit. 'jpg' / 'webp' are stills for a byte budget (ad specs): the png render re-encoded at the quality tier's compression — draft 0.6, standard 0.85, high 0.95 — so lower quality means a smaller file; 'srt' / 'vtt' write a caption file from every text item that has a lifetime (bornAt / ttl) — one cue each, in start order; duration closes a caption with no ttl. jpg has no transparency: it is flattened onto the scene's background colour, or white when none is set. 'wav' exports the SOUNDTRACK ON ITS OWN, with no frames rendered — no platform preset resolves to it, so it must be asked for by name, and platform dimensions, framing and quality do not apply.",
                 },
                 sampleRate: {
                     type: 'number',
@@ -7854,22 +8037,62 @@ Every export answers the second question too: where this scene loses something t
                     enum: [16, 32],
                     description: 'wav only: 16 (default) or 32-bit float. Rejected for any other format.',
                 },
+                ad: {
+                    type: 'object',
+                    description: 'html5-ad / playable options.',
+                    properties: {
+                        clickUrl: { type: 'string', description: 'html5-ad: the clickTag value for testing (networks replace it at serve time). playable: the store / landing URL the CTA opens (required).' },
+                        ctaItemId: { type: 'string', description: 'The item whose bounds are the click target. Optional for html5-ad (default: whole ad); required for playable. Static: where the item is at export time.' },
+                        maxBytes: { type: 'integer', minimum: 1, description: 'Upload size budget (zip for html5-ad, HTML for playable). html5-ad default 150000 (Google Ads display); set your network figure.' },
+                    },
+                },
+                transparent: { type: 'boolean', description: 'apng only: keep the alpha channel (the default); false fills the background colour.' },
+                loop: { anyOf: [{ type: 'boolean' }, { type: 'integer', minimum: 0, maximum: 1000 }], description: 'gif / apng: true = loop forever, false / 0 / 1 = play once, n = play n times (email clients often want a few plays, not forever). Refused on video formats — see SEAMLESS LOOPS.' },
+                broadcast: { type: 'boolean', description: 'mp4 only: broadcast-safe — BT.709, limited range (16-235), tagged bt709, constant bitrate with an 8 Mbps floor at 720p+ (4 below). result.video reports what the encoder did.' },
+                broadcastHeadroom: { type: 'integer', minimum: 0, maximum: 40, description: 'mp4 with broadcast only, default 12: luma codes kept clear at both ends, so encoder ringing stays legal (12 measured clean on hard edges; 4 = ~100x fewer out-of-range samples, 12 = ~1000x; never zero). Fidelity raises luma_out_of_range with the legaliser command when any remain.' },
+                bitrate: { type: 'integer', minimum: 100000, maximum: 200000000, description: 'mp4 / webm: target bits/s, replacing the quality-derived one. The browser encoder treats it as a CEILING; result.video.achievedBitrate is what it produced.' },
+                minBitrate: { type: 'integer', minimum: 100000, maximum: 200000000, description: 'mp4 / webm: a floor; a miss is a fidelity warning naming the re-encode a delivery spec needs.' },
+                bitrateMode: { type: 'string', enum: ['constant', 'variable'], description: "mp4 / webm: 'constant' (the default with broadcast) or 'variable'." },
+                maxBytes: { type: 'integer', minimum: 1, description: 'gif only: size budget in bytes (email: 1000000). Over it, the GIF is re-encoded at a smaller frame size, at most twice; result.budget reports each attempt.' },
+                time: { type: 'number', minimum: 0, description: 'Stills only (png / jpg / webp / svg / pdf): render at this time in seconds; the playhead is put back afterwards. Without it a still is whatever frame the playhead is on, so repeated runs can differ.' },
+                pdf: {
+                    type: 'object',
+                    description: "pdf only: print options. paperFormat 'a4' | 'a3' | 'letter' | … | 'custom' (canvas size, default); orientation; bleed in mm (> 0 includes the bleed area); trimMarks adds crop marks; dpi 72–600. Bleed and trim marks take effect with paperFormat 'custom' (the page is the canvas plus bleed) — on a named size the page stays that size and they are dropped, which the result's warnings say. The canvas's physical size comes from its preset's DPI: start the job with canvasPreset 'print-a4' / 'print-letter' / 'print-a4-landscape' / 'print-letter-landscape' (300 dpi) for print; a hand-sized canvas is read at 96 dpi.",
+                    properties: {
+                        paperFormat: { type: 'string' },
+                        orientation: { type: 'string', enum: ['portrait', 'landscape'] },
+                        bleed: { type: 'number', minimum: 0, maximum: 20 },
+                        trimMarks: { type: 'boolean' },
+                        searchableText: { type: 'boolean', description: 'Default true where the studio supports it: an invisible text layer over the artwork, so the PDF is selectable, searchable and screen-readable. Lines no font in the PDF can carry (older studios have only a built-in Latin font) are drawn but left out, and fidelity says how many and which fonts could not be embedded. Multi-page (pages) exports get it per page on studios that support it. false omits it. result.pdf reports linesWritten / linesSkipped.' },
+                        dpi: { type: 'integer', minimum: 72, maximum: 600 },
+                        pages: { anyOf: [{ type: 'string', enum: ['scenes'] }, { type: 'array', items: { anyOf: [{ type: 'string' }, { type: 'object', properties: { sceneId: { type: 'string' }, width: { type: 'number' }, height: { type: 'number' } }, required: ['sceneId', 'width', 'height'] }] }, minItems: 1 }], description: "Multi-page PDF: 'scenes' = one page per saved scene (the scenes tool's save action) in timeline order, or an ordered list of scene ids. Saved scenes do NOT record their canvas size, so every page uses the current canvas size unless you give it: {sceneId, width, height} (pixels) per page. Pages are embedded as JPEG at the quality tier's compression." },
+                    },
+                },
+                region: {
+                    type: 'object',
+                    description: 'png / jpg / webp only: export just this part of the canvas (canvas coordinates, x/y = TOP-LEFT) — carousel slices, crops. Output is the region\'s own size unless outputWidth/outputHeight say otherwise; a different aspect is covered, not stretched. SMALL ASSETS (emotes, badges, favicons): design at 2-4x on a canvas of at least 100 px, then export the whole board as a region with the small outputWidth/outputHeight — e.g. a 112x112 canvas, region {x:0, y:0, width:112, height:112, outputWidth:28, outputHeight:28}.',
+                    properties: {
+                        x: { type: 'number' }, y: { type: 'number' },
+                        width: { type: 'number', exclusiveMinimum: 0 }, height: { type: 'number', exclusiveMinimum: 0 },
+                        outputWidth: { type: 'integer', minimum: 1, maximum: 8192 }, outputHeight: { type: 'integer', minimum: 1, maximum: 8192 },
+                        excludeForeign: { type: 'boolean', description: 'Default true: an item reaching into the region but centred outside it (a neighbouring card overflow) is left out of this image; result.excludedItems names them. false renders everything that touches the region.' },
+                    },
+                    required: ['x', 'y', 'width', 'height'],
+                },
                 quality: {
                     type: 'string',
                     enum: ['draft', 'standard', 'high'],
                     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.',
+                    anyOf: [{ type: 'number', minimum: 1, maximum: 120 }, { type: 'string', pattern: '^[0-9]+/[0-9]+$' }],
+                    description: 'Video only: frames per second, overriding whatever `quality` implies. Integers, NTSC rates (23.976, 29.97, 59.94 — snapped to the exact 24000/1001, 30000/1001, 60000/1001, which CTV / OTT specs require) or a rational string "30000/1001". At an NTSC rate a duration of N seconds is round(N x fps) frames, so 6 s at 29.97 is 180 frames = 6.006 s — the result says when that overruns the duration you asked for. File size is bitrate x duration and does not move with fps.',
                 },
                 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.',
+                    description: 'Video only: render at this fraction of the platform preset dimensions (0.1-1). The engine derives its encode target from RESOLUTION unless bitrate is given, so this is the size control; 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',
@@ -8441,6 +8664,7 @@ DATA FORMAT: Array of objects, e.g. [{category: "A", value: 10}, {category: "B",
 
 OPTIONS (vary by chart type):
 - Common: title, width, height, x, y, colors, animation, axisColor, labelColor, labelFontSize
+  x / y are the chart's CENTRE (measured: x 1000, y 300 at 800x600 reads back as bounds [600, -25, 800, 625]) — pass the centre of the rect you want it in, not its top-left.
 - Bar: barWidth, barGap, xLabel, yLabel
     orient: 'horizontal' flips bars to grow rightward from a left Y-axis — best for long category names
     labelArrangement: 'auto'|'horizontal'|'slanted'|'vertical'|'truncate'|'wrap'