@pinepaper.studio/mcp-server 1.6.16 → 1.6.18

package/dist/types/schemas.js

@@ -8,6 +8,7 @@
  * 3. TypeScript type inference
  */
 import { z } from 'zod';
+import { ENGINE_EASING_NAMES, DESIGN_MEDIA, DESIGN_MEDIA_APPLY } from '../tools/engine-lists.js';
 // =============================================================================
 // COMMON SCHEMAS
 // =============================================================================
@@ -70,14 +71,77 @@ export const BlendModeSchema = z.enum([
     'difference',
     'exclusion',
 ]).describe('Blend mode for compositing with background');
-export const EasingSchema = z.enum([
-    'linear',
-    'easeIn',
-    'easeOut',
-    'easeInOut',
-    'bounce',
-    'elastic',
-]).describe('Easing function for animation');
+/**
+ * Every easing name the engine's table accepts: GENERATED from FxTool's
+ * EASING_NAMES (scripts/sync-engine-lists.mjs, checked in prepublishOnly).
+ * Keyframes, masks, relations and the camera all resolve a name through that
+ * one table, so every easing enum here is this list.
+ */
+export const KEYFRAME_EASINGS = ENGINE_EASING_NAMES;
+/** One line per easing, for tool descriptions and pinepaper_get_available_easings. */
+export const EASING_DESCRIPTIONS = {
+    linear: 'Constant speed',
+    easeIn: 'Slow start, fast end',
+    easeOut: 'Fast start, slow end',
+    easeInOut: 'Slow start and end',
+    easeInCubic: 'Slow start, stronger than easeIn',
+    easeOutCubic: 'Slow end, stronger than easeOut',
+    easeInOutCubic: 'Slow start and end, stronger than easeInOut',
+    bounce: 'Bounces to rest at the end (same as easeOutBounce)',
+    easeOutBounce: 'Bounces to rest at the end',
+    easeInBounce: 'Bounces at the start, then moves',
+    elastic: 'Overshoots and oscillates at the end (same as easeOutElastic)',
+    easeOutElastic: 'Overshoots and oscillates at the end',
+    easeInElastic: 'Oscillates at the start, then moves',
+    easeOutBack: 'Overshoots the target slightly, then settles',
+    easeInBack: 'Pulls back first, then moves',
+    easeInOutBack: 'Pulls back first and overshoots at the end',
+    spring: 'Damped spring, ζ≈1: settles with no overshoot',
+    springSnappy: 'Damped spring, ζ≈0.69: quick, one ~5% overshoot',
+    springPlayful: 'Damped spring, ζ≈0.45: ~21% overshoot, visible wobbles',
+    easeInQuad: 'Quadratic slow start (same as easeIn)',
+    easeOutQuad: 'Quadratic slow end (same as easeOut)',
+    easeInOutQuad: 'Quadratic slow start and end (same as easeInOut)',
+    easeInSine: 'Gentle slow start (sine)',
+    easeOutSine: 'Gentle slow end (sine)',
+    easeInOutSine: 'Gentle slow start and end (sine)',
+    easeInQuart: 'Slow start, stronger than cubic (t⁴)',
+    easeOutQuart: 'Slow end, stronger than cubic',
+    easeInOutQuart: 'Slow start and end, stronger than cubic',
+    easeInQuint: 'Very slow start (t⁵)',
+    easeOutQuint: 'Very slow end',
+    easeInOutQuint: 'Very slow start and end',
+    easeInExpo: 'Near-still start, then fast (the standard expo curve)',
+    easeOutExpo: 'Fast, then a long near-still end (the standard expo curve)',
+    easeInOutExpo: 'Near-still at both ends, fast in the middle',
+    easeInCirc: 'Slow start, sharp finish (circular)',
+    easeOutCirc: 'Sharp start, slow finish (circular)',
+    easeInOutCirc: 'Circular slow start and end',
+};
+export const EasingSchema = z.enum(KEYFRAME_EASINGS).describe('Easing function for animation');
+/**
+ * A keyframe's easing: a name from the table, or a custom cubic Bézier
+ * [x1, y1, x2, y2]. The interpolator runs the array natively, the validator
+ * accepts it, and every export path handles it (SMIL clamps y into keySplines;
+ * CSS and Lottie take the raw curve). Keyframe tracks only — keyframe_animate,
+ * camera_animate and inline keyframes — not masks or relations (fxtool-d7).
+ */
+export const BezierEasingSchema = z.tuple([z.number(), z.number(), z.number(), z.number()])
+    .refine(([x1, , x2]) => x1 >= 0 && x1 <= 1 && x2 >= 0 && x2 <= 1, {
+    message: 'cubic-bezier x1 and x2 must be within 0..1 (y1 and y2 may exceed it for overshoot)',
+})
+    .describe('Custom cubic-bezier [x1, y1, x2, y2]');
+export const KeyframeEasingSchema = z.union([EasingSchema, BezierEasingSchema]);
+/** JSON-Schema form of KeyframeEasingSchema, for tool definitions. */
+export const KEYFRAME_EASING_JSON_SCHEMA = {
+    oneOf: [
+        { type: 'string', enum: [...KEYFRAME_EASINGS] },
+        {
+            type: 'array', items: { type: 'number' }, minItems: 4, maxItems: 4,
+            description: 'or a custom cubic-bezier [x1, y1, x2, y2] — x in 0..1, y may exceed 0..1 for overshoot',
+        },
+    ],
+};
 // =============================================================================
 // ITEM TYPES
 // =============================================================================
@@ -251,7 +315,7 @@ export const SimpleAnimationTypeSchema = z.enum([
 export const KeyframeSchema = z.object({
     time: z.number().describe('Time in seconds for this keyframe'),
     properties: z.record(z.unknown()).describe('Property values at this keyframe'),
-    easing: EasingSchema.optional().default('linear'),
+    easing: KeyframeEasingSchema.optional().default('linear'),
 });
 // =============================================================================
 // RELATION TYPES
@@ -1149,6 +1213,8 @@ export const ModifyItemInputSchema = z.object({
     itemId: z.string().describe('Registry ID of the item'),
     properties: z.record(z.unknown()).describe('Properties to update'),
     data: ItemDataFlagsSchema.optional(),
+    atTime: z.number().min(0).optional().describe('AUTO-KEY: write these properties as keyframes at this time (seconds) instead of a static edit — eased from the previous value, other keys kept.'),
+    easing: z.string().optional().describe('atTime: easing of the segment arriving at the new key (default linear).'),
 });
 // Delete Item
 export const DeleteItemInputSchema = z.object({
@@ -1367,13 +1433,16 @@ export const SetBackgroundColorInputSchema = z.object({
     color: SolidColorSchema.describe('Background color to set (solid colors only)'),
 });
 export const SetCanvasSizeInputSchema = z.object({
-    // 8192, not 4096: the artboard tool takes any size and a 5400x1350 carousel
-    // panorama exported exactly, while this refused it. 8192 stays well inside
-    // the browser's per-side canvas limit.
+    // 16384: the engine's own safe dimension for Chrome / Firefox
+    // (ExportEngine.CANVAS_LIMITS; its hard limit is 32767 per side and 2^28
+    // pixels), and what DOOH / projection canvases need (round 12: 8220 and
+    // 12000 px wide rendered fine while this refused them at 8192, which is
+    // Safari's safe size). Above 8192 the result warns that Safari / iOS may
+    // not manage it.
     // The refusal NAMES the route: a 728x90 banner refused with a bare "too
     // small" left a caller to export the preset instead (round 8 BB, 1.48).
-    width: z.number().min(100, "a canvas side under 100 px is not supported. For small assets (a 728x90 or 320x50 banner, a 28 px emote) design at 2-4x — e.g. 1456x180 — and export with agent_export region {x:0, y:0, width, height, outputWidth:728, outputHeight:90}. For VIDEO at a small size, design at 2x and export with agent_export scale: 0.5.").max(8192).describe('Canvas width (100-8192)'),
-    height: z.number().min(100, "a canvas side under 100 px is not supported. For small assets (a 728x90 or 320x50 banner, a 28 px emote) design at 2-4x — e.g. 1456x180 — and export with agent_export region {x:0, y:0, width, height, outputWidth:728, outputHeight:90}. For VIDEO at a small size, design at 2x and export with agent_export scale: 0.5.").max(8192).describe('Canvas height (100-8192)'),
+    width: z.number().min(100, "a canvas side under 100 px is not supported. For small assets (a 728x90 or 320x50 banner, a 28 px emote) design at 2-4x — e.g. 1456x180 — and export with agent_export region {x:0, y:0, width, height, outputWidth:728, outputHeight:90}. For VIDEO at a small size, design at 2x and export with agent_export scale: 0.5.").max(16384).describe('Canvas width (100-16384; above 8192 Safari / iOS may fail)'),
+    height: z.number().min(100, "a canvas side under 100 px is not supported. For small assets (a 728x90 or 320x50 banner, a 28 px emote) design at 2-4x — e.g. 1456x180 — and export with agent_export region {x:0, y:0, width, height, outputWidth:728, outputHeight:90}. For VIDEO at a small size, design at 2x and export with agent_export scale: 0.5.").max(16384).describe('Canvas height (100-16384; above 8192 Safari / iOS may fail)'),
     preset: z.string().optional().describe('Optional preset name'),
 });
 // Export
@@ -1816,9 +1885,7 @@ export const MaskPresetSchema = z.enum([
 export const MaskTypeSchema = z.enum([
     'rectangle', 'circle', 'ellipse', 'star', 'triangle', 'hexagon', 'heart', 'rounded',
 ]).describe('Mask shape type');
-export const MaskEasingSchema = z.enum([
-    'linear', 'easeIn', 'easeOut', 'easeInOut', 'bounce', 'elastic',
-]).describe('Mask animation easing function');
+export const MaskEasingSchema = z.enum(KEYFRAME_EASINGS).describe('Mask animation easing function');
 export const MaskKeyframePropertiesSchema = z.object({
     x: z.number().optional(),
     y: z.number().optional(),
@@ -1997,8 +2064,8 @@ export const AgentBatchOperationSchema = z.object({
     generatorParams: z.record(z.unknown()).optional().describe('Generator parameters'),
     generatorRegion: GeneratorRegionSchema.optional().describe('Optional sub-region {x, y, width, height} for execute_generator'),
     // Set canvas size fields
-    width: z.number().min(100).max(8192).optional().describe('Canvas width for set_canvas_size (100-8192)'),
-    height: z.number().min(100).max(8192).optional().describe('Canvas height for set_canvas_size (100-8192)'),
+    width: z.number().min(100).max(16384).optional().describe('Canvas width for set_canvas_size (100-16384)'),
+    height: z.number().min(100).max(16384).optional().describe('Canvas height for set_canvas_size (100-16384)'),
     preset: z.string().optional().describe('Canvas preset for set_canvas_size (e.g. instagram, youtube)'),
     // Keyframe animate fields
     keyframes: z.array(z.object({
@@ -2187,6 +2254,13 @@ export const AgentExportInputSchema = z.object({
     loop: z.union([z.boolean(), z.number().int().min(0).max(1000)]).optional().describe('gif / apng: true = loop forever, false / 0 / 1 = play once, n = play n times.'),
     maxBytes: z.number().int().positive().optional().describe('gif only: a size budget in bytes (email wants <= 1 MB). Over it, the GIF is re-encoded smaller — frame size scaled from the overshoot — at most twice; the result reports each attempt and whether the budget was met.'),
     broadcast: z.boolean().optional().describe('mp4 only: broadcast-safe — BT.709, limited range (samples 16-235), tagged bt709, constant bitrate with an 8 Mbps floor at 720p and up (4 below). result.video reports what the encoder did.'),
+    frames: z.number().int().min(1).max(36_000).optional().describe('Animated formats: export exactly this many frames; it takes the place of duration (duration x fps frames is rounded UP for mp4 / webm / gif). For frame-exact segments to assemble.'),
+    // FxTool #55 (motion-course G2): N sub-frames per frame, averaged across
+    // the shutter, so fast motion smears the way a camera's does.
+    motionBlur: z.object({
+        subframes: z.number().int().min(1).max(32).optional().describe('Renders per frame (default 8; 1 = no blur). Export time scales with it.'),
+        shutter: z.number().min(0).max(1).optional().describe('Fraction of the frame interval the shutter is open (default 0.5, a 180° shutter).'),
+    }).optional().describe('mp4 / webm: real motion blur. Each frame is rendered subframes times across the shutter and averaged, so fast movement smears instead of strobing. Costs subframes× the render time: run estimateOnly first, which reports renders and renderCost.'),
     deterministic: z.boolean().optional().describe('mp4 / webm: byte-identical files for the same scene, so an export can be checksummed or cached by hash. The container\'s creation / modification timestamps are pinned; nothing about the pixels changes.'),
     broadcastHeadroom: z.number().int().min(0).max(40).optional().describe('mp4 with broadcast only (default 12 with broadcast): luma codes kept clear at both ends of 16-235, so encoder ringing stays legal. 12 measured clean on hard edges; 4 cuts out-of-range samples ~100x, 12 ~1000x; never to zero, so a legaliser pass is still required (result fidelity names it).'),
     bitrate: z.number().int().min(100_000).max(200_000_000).optional().describe('mp4 / webm: target bits per second, replacing the quality-derived one. The browser encoder treats it as a CEILING: simple content comes out lower, and result.video.achievedBitrate says what it was.'),
@@ -2196,8 +2270,8 @@ export const AgentExportInputSchema = z.object({
     region: z.object({
         x: z.number(), y: z.number(),
         width: z.number().positive(), height: z.number().positive(),
-        outputWidth: z.number().int().positive().max(8192).optional(),
-        outputHeight: z.number().int().positive().max(8192).optional(),
+        outputWidth: z.number().int().positive().max(16384).optional(),
+        outputHeight: z.number().int().positive().max(16384).optional(),
         excludeForeign: z.boolean().optional().describe('Default true: an item that reaches into the region but is centred outside it (a neighbouring card\'s overflow) is left out of this image; result.excludedItems names them. false renders everything that touches the region.'),
     }).optional().describe('png / jpg / webp only: export just this canvas region (canvas coordinates, top-left x/y) — carousel slices, crops. Output is the region\'s size unless outputWidth/outputHeight say otherwise; a different aspect is covered, not stretched.'),
 }).describe('Smart export options')
@@ -2211,7 +2285,10 @@ export const AgentExportInputSchema = z.object({
     if (val.broadcastHeadroom !== undefined && !val.broadcast) {
         ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['broadcastHeadroom'], message: 'broadcastHeadroom applies only with broadcast: true (mp4).' });
     }
-    for (const k of ['bitrate', 'minBitrate', 'bitrateMode', 'deterministic']) {
+    if (val.frames !== undefined && !['mp4', 'webm', 'gif', 'apng'].includes(String(val.format))) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['frames'], message: 'frames applies to animated formats: mp4, webm, gif, apng.' });
+    }
+    for (const k of ['bitrate', 'minBitrate', 'bitrateMode', 'deterministic', 'motionBlur']) {
         if (val[k] !== undefined && val.format !== 'mp4' && val.format !== 'webm') {
             ctx.addIssue({ code: z.ZodIssueCode.custom, path: [k], message: `${k} is a video setting: mp4 or webm. A gif's size is set by maxBytes and scale.` });
         }
@@ -2256,14 +2333,14 @@ export const AgentExportInputSchema = z.object({
     // Same shape as the wav refusal below: a knob that cannot apply is said
     // once rather than accepted and dropped. png/svg/pdf carry no encode
     // target, so scaling them here would promise a resize that never happens.
-    if (val.fps !== undefined && !['mp4', 'webm', 'gif', 'auto'].includes(String(val.format))) {
+    if (val.fps !== undefined && !['mp4', 'webm', 'gif', 'apng', 'auto'].includes(String(val.format))) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
             path: ['fps'],
-            message: `fps applies to video formats (mp4/webm/gif), not "${val.format}" — a still has no frame rate.`,
+            message: `fps applies to animated formats (mp4/webm/gif/apng), not "${val.format}" — a still has no frame rate.`,
         });
     }
-    if (val.scale !== undefined && !['mp4', 'webm', 'gif', 'auto'].includes(String(val.format))) {
+    if (val.scale !== undefined && !['mp4', 'webm', 'gif', 'apng', 'auto'].includes(String(val.format))) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
             path: ['scale'],
@@ -2694,6 +2771,8 @@ export const ImportImageInputSchema = z.object({
     position: PositionSchema.optional().describe('Position on canvas (defaults to center)'),
     maxWidth: z.number().optional().describe('Maximum width constraint in pixels'),
     maxHeight: z.number().optional().describe('Maximum height constraint in pixels'),
+    maxEdge: z.union([z.number().int().positive(), z.literal('native')]).optional().describe("The longest edge the studio STORES the image at, in px; 'native' keeps every pixel. Default: the studio's cap (it follows the canvas on desktop)."),
+    nativeSize: z.boolean().optional().describe('Place the image at its source footprint even if it was stored smaller.'),
     mask: ImageMaskSchema.optional().describe('Optional mask shape to apply to the image'),
     smoothing: z.enum(['off', 'low', 'medium', 'high']).optional().describe("Resampling when the image is scaled. 'off' = nearest-neighbour, hard pixel edges (pixel art). Default 'low'."),
 }).describe('Import image input');
@@ -2989,8 +3068,10 @@ export const TransformInputSchema = z.object({
 // count is already the thing the consolidation backlog complains about, and
 // `pinepaper_media` / `pinepaper_transform` set the precedent.
 export const BrandKitInputSchema = z.object({
-    /** 'plan' reports what WOULD change without touching the scene. */
-    action: z.enum(['plan', 'apply']),
+    /** 'plan' reports what WOULD change without touching the scene. 'from_url' reads a site into a proposed kit. */
+    action: z.enum(['plan', 'apply', 'from_url']),
+    url: z.string().url().optional().describe("from_url: the product's site (http/https). Read in an isolated browser context: the studio is not navigated."),
+    screenshots: z.number().int().min(1).max(6).optional().describe('from_url: screenshots taken down the page (default 3).'),
     // Spelled out rather than a loose record. A first version typed this as
     // `z.record(...)` described as a "role → colour map", which is NOT the shape
     // the engine takes — every call was rejected with "name is required;
@@ -3011,9 +3092,11 @@ export const BrandKitInputSchema = z.object({
             heading: z.string().optional(),
             body: z.string().optional(),
         }).optional(),
-    }),
+    }).optional(),
     selectionOnly: z.boolean().optional(),
-});
+})
+    .refine((v) => v.action === 'from_url' || !!v.kit, { message: 'plan and apply require kit (from_url proposes one)', path: ['kit'] })
+    .refine((v) => v.action !== 'from_url' || (!!v.url && /^https?:\/\//i.test(v.url)), { message: 'from_url requires an http(s) url', path: ['url'] });
 export const ComponentInputSchema = z.object({
     action: z.enum(['define', 'list', 'instantiate', 'set_override', 'sync', 'update_from_instance', 'detach']),
     itemIds: z.array(z.string()).optional(),
@@ -3153,6 +3236,13 @@ export const AccessibilityCheckInputSchema = z.object({
     duration: z.number().positive().max(120).optional().describe('flash: seconds of the timeline to sample (default 5).'),
     fps: z.number().int().min(10).max(60).optional().describe('flash: samples per second (default 20; a flash rate is only seen below half of it).'),
 });
+// QUERY MUTATIONS (plan C5a): a property's keyframe series.
+export const QueryMutationsInputSchema = z.object({
+    itemId: z.string().min(1),
+    property: z.string().min(1).optional().describe('One property; all animated properties when omitted.'),
+    range: z.tuple([z.number().min(0), z.number().min(0)]).optional().describe('[from, to] seconds.'),
+    fps: z.number().positive().max(240).optional().describe('For the frame numbers (default 30).'),
+});
 // RENDER BATCH (data-driven creative): one scene, many rows, one export per
 // row. The handler runs each row through modify_item / template_params and
 // then agent_export, so every per-tool check applies to every row.
@@ -3443,11 +3533,34 @@ export const ValidateSceneInputSchema = z.object({
 });
 // Deterministic headless frame capture (S3) — evaluate the scene at each time via
 // sceneAt(t) with Math.random seeded once around the whole sequence, then snapshot.
+/**
+ * A contact sheet: many frames tiled into ONE small image, saved to a file,
+ * so an agent can look at its own film (G3 critique loop). Built on the same
+ * deterministic capture; the times come from `times`, or from one of the
+ * modes below.
+ */
+export const CaptureSheetSchema = z.object({
+    every: z.number().positive().optional().describe('One frame every N seconds from 0 to duration (needs duration).'),
+    duration: z.number().positive().optional().describe('Scene length in seconds, for every and loopSeam.'),
+    strip: z.object({
+        at: z.number().min(0).describe('Centre time in seconds.'),
+        count: z.number().int().min(2).max(24).default(8),
+        step: z.number().positive().default(1 / 30).describe('Seconds between frames (default one frame at 30 fps).'),
+    }).optional().describe('Consecutive frames around a moment: to check a transition or a stutter.'),
+    loopSeam: z.boolean().optional().describe('The last frame next to the first (needs duration): does the loop join without a jump?'),
+    tileWidth: z.number().int().min(120).max(1080).default(360).describe('Width of each tile in px. 360 is phone width: read every word at this size.'),
+    columns: z.number().int().min(1).max(12).optional().describe('Tiles per row (default: as square as the count allows, at most 6).'),
+    format: z.enum(['jpeg', 'png']).default('jpeg'),
+    labels: z.boolean().default(true).describe('Stamp each tile with its time.'),
+});
 export const CaptureFramesInputSchema = z.object({
-    times: z.array(z.number()).min(1).describe('Capture times in seconds, rendered in order.'),
+    times: z.array(z.number()).min(1).optional().describe('Capture times in seconds, rendered in order. Required unless sheet gives every, strip or loopSeam.'),
     seed: z.number().optional().describe('Seed Math.random once around the whole sequence so random generators/particles are reproducible (default 0).'),
     includeDataUrls: z.boolean().optional().describe('Include each frame as a PNG data URL (large — token-heavy). Default false → returns a cheap per-frame hash + byte size only.'),
-});
+    sheet: CaptureSheetSchema.optional().describe('Return ONE tiled image (saved to a file) instead of per-frame hashes, plus a critique rubric.'),
+})
+    .refine((v) => !!v.times || !!(v.sheet && (v.sheet.every || v.sheet.strip || v.sheet.loopSeam)), { message: 'give times, or sheet with every, strip or loopSeam', path: ['times'] })
+    .refine((v) => !v.sheet || !(v.sheet.every || v.sheet.loopSeam) || !!v.sheet.duration || !!v.times, { message: 'sheet.every and sheet.loopSeam need sheet.duration (the scene length in seconds)', path: ['sheet', 'duration'] });
 // Ontology→scene compiler (S12-E3). Compiles a pp:-namespaced JSON-LD design graph
 // (typed nodes + structural edges like pp:onTopOf) into a real scene. Compilation
 // runs server-side (deterministic, testable); only the resulting create/addRelation
@@ -3474,20 +3587,27 @@ export const LintSceneInputSchema = z.object({
 // Media (video/audio) via window.PinePaperAgent. Agent-facing surface is URL-based
 // (the agent can't hand over a File). Uploaded media are first-class canvas items.
 export const MediaInputSchema = z.object({
-    action: z.enum(['upload_video', 'upload_audio', 'list', 'remove', 'set_playback_rate', 'set_clip', 'split', 'add_transition', 'set_time_remap', 'speed_ramp', 'match_cut', 'apply_track_matte', 'stop_live_matte'])
+    action: z.enum(['upload_video', 'upload_audio', 'list', 'remove', 'set_playback_rate', 'set_clip', 'split', 'add_transition', 'set_time_remap', 'speed_ramp', 'match_cut', 'apply_track_matte', 'stop_live_matte', 'analyze_reference', 'remake_from_reference'])
         .describe("'upload_video' / 'upload_audio' (from a URL) · 'list' media · 'remove' by id · 'set_playback_rate' · 'set_clip' (re-trim; with timeOffset also moves the clip) · 'split' (cut a clip in two at canvas time `at`; the first half keeps its id) · 'add_transition' (crossfade or dip between fromItemId, which ends at the cut, and toItemId, which starts there) · 'set_time_remap' (canvas-time→source-time curve: ramps, freezes, reverse) · 'speed_ramp' ({duration, speed} segments — the human way to say a remap) · 'match_cut' (cut between two shots aligning the SUBJECT via on-device detection) · 'apply_track_matte' (an item's alpha driven by another item's luma/alpha — type-filled-with-footage; live:true keeps it tracking as the matte animates) · 'stop_live_matte'"),
     // Not .url(): a bare absolute path is not a URL, and 48f3a2a made the server
     // read local files — so `/Users/…/broll1.mp4` was advertised and then rejected
     // by the schema before anything could read it. resolveMediaSource validates
     // what it is given and names the problem.
     url: z.string().min(1).optional().describe('Required for upload_video / upload_audio: an http(s) URL, a data: URL, or a local file path (absolute, relative to the server, or file://).'),
-    id: z.string().optional().describe('Media id — required for remove / set_playback_rate / set_clip / split.'),
+    id: z.string().optional().describe('Media id — required for remove / set_playback_rate / set_clip / split / analyze_reference.'),
+    // G4 reference intake (FxTool #52): measure a reference video's FORMAT and
+    // build on it. Nothing of its footage, words or sound is copied.
+    texts: z.array(z.string()).optional().describe('remake_from_reference: your words, one per shot of the reference (a short list is reused across shots).'),
+    duration: z.number().positive().optional().describe('remake_from_reference: total length in seconds (default the reference\'s own).'),
+    clear: z.boolean().optional().describe('remake_from_reference: empty the canvas first (media survives).'),
+    thumbnails: z.boolean().optional().describe('analyze_reference: include a small image per shot (default false: they are inline images and token-heavy).'),
     rate: z.number().min(0.25).max(4).optional().describe('Playback rate 0.25–4 — required for set_playback_rate.'),
     inPoint: z.number().min(0).optional().describe('Clip in-point in media-time seconds — required for set_clip.'),
     outPoint: z.number().min(0).optional().describe('Clip out-point in media-time seconds — required for set_clip.'),
     // upload_video placement
     position: PositionSchema.optional().describe('Canvas position — upload_video.'),
-    scale: z.number().positive().optional().describe('Scale factor — upload_video.'),
+    scale: z.number().positive().optional().describe("upload_video: a multiplier on the FIT the studio applies (fit: 'contain' by default), not on the video's own pixels — 0.7 of a contain-fit 1920 clip on a 1080 canvas is not 0.7 x 1920. Pass fit: 'none' for scale to be of the source pixels."),
+    fit: z.enum(['contain', 'cover', 'none']).optional().describe("upload_video: how the clip is sized before scale — 'contain' (default; whole clip inside the canvas), 'cover' (fills it, cropped), 'none' (source pixels). The result gives the scale and bounds that landed."),
     timeOffset: z.number().optional().describe('Start offset on the timeline in seconds — upload_video / upload_audio; set_clip: move the clip to start here (canvas seconds).'),
     clipInPoint: z.number().optional().describe('Trim in-point in seconds — upload_video.'),
     clipOutPoint: z.number().optional().describe('Trim out-point in seconds — upload_video.'),
@@ -3530,6 +3650,8 @@ export const MediaInputSchema = z.object({
     atPlayhead: z.boolean().optional().describe('upload_video / upload_audio: start the clip at the current playback time (instead of timeOffset).'),
 })
     .refine((v) => !(v.action === 'upload_video' || v.action === 'upload_audio') || !!v.url, { message: 'upload requires url', path: ['url'] })
+    .refine((v) => v.action !== 'analyze_reference' || !!v.id, { message: 'analyze_reference requires id: the uploaded reference clip (upload_video it first)', path: ['id'] })
+    .refine((v) => v.action !== 'remake_from_reference' || (!!v.texts && v.texts.length > 0), { message: 'remake_from_reference requires texts: your own words, one per shot', path: ['texts'] })
     .refine((v) => !(v.action === 'remove' || v.action === 'set_playback_rate' || v.action === 'set_clip' || v.action === 'split') || !!v.id, { message: 'this action requires id', path: ['id'] })
     .refine((v) => v.action !== 'split' || (v.at !== undefined && v.at >= 0), { message: 'split requires at (canvas seconds) — where to cut', path: ['at'] })
     .refine((v) => v.action !== 'add_transition' || (!!v.fromItemId && !!v.toItemId), { message: 'add_transition requires fromItemId (the clip ending at the cut) and toItemId (the clip starting at it)', path: ['fromItemId'] })
@@ -3615,17 +3737,20 @@ export const TextStyleInputSchema = z.object({
  * `list_media` before promising a medium in prose.
  */
 export const DesignMediumInputSchema = z.object({
-    action: z.enum(['list_media', 'resolve', 'list_stitches', 'apply_thread', 'apply_hatch', 'list_flow_fields', 'list_hatch_options'])
-        .describe("'list_media' (7 media with fidelity + limitation) · 'resolve' (can this medium be made here, and how honestly) · 'list_stitches' · 'apply_thread' (render an item in thread) · 'apply_hatch' (rule an item with hatching — value through line density) · 'list_flow_fields' · 'list_hatch_options'"),
-    medium: z.string().optional().describe("resolve: medium key — vector, thread, hatch, watercolor, ink, cutPaper, charcoal, oil, encaustic. Call list_media for the live set with each one's fidelity; the catalogue grows."),
-    itemId: z.string().optional().describe('apply_thread / apply_hatch: a closed path, compound path, or a group of them. Its own silhouette is the region and its fill is the ink colour.'),
+    action: z.enum(['list_media', 'resolve', 'list_stitches', 'apply_thread', 'apply_hatch', 'list_flow_fields', 'list_hatch_options', 'apply'])
+        .describe("'apply' (render an item in ANY medium the engine can make: medium + options — watercolor, oil, cutPaper, thread, hatch) · 'list_media' (every medium with fidelity + limitation) · 'resolve' (can this medium be made here, and how honestly) · 'list_stitches' · 'apply_thread' (render an item in thread) · 'apply_hatch' (rule an item with hatching — value through line density) · 'list_flow_fields' · 'list_hatch_options'"),
+    medium: z.string().optional().describe(`resolve / apply: medium key — ${DESIGN_MEDIA.join(', ')}. apply works for ${Object.keys(DESIGN_MEDIA_APPLY).join(', ')}; the others are refused by the engine with the reason (encaustic is absent here; charcoal and ink are brushes, not fills).`),
+    options: z.record(z.string(), z.unknown()).optional().describe('apply: the medium\'s own options. watercolor: color, brush, water 0..1, opacity, edge 0..1 (the dark rim), angle, bleed, seed, keepSource. oil: color, brush, length, density, toneRange, relief, angle, seed, keepSource. cutPaper: color, facet, jitter, shadow, shadowColor, shadowOpacity, shadowOffset [dx, dy], seed, keepSource. thread / hatch: as apply_thread / apply_hatch.'),
+    itemId: z.string().optional().describe('apply / apply_thread / apply_hatch: a closed path, compound path (holes kept), or a group of them (applied per path). The result takes the source\'s place in the stacking order and the source is hidden; applying again replaces it. One undo step.'),
     stitch: z.enum(THREAD_STITCHES).optional()
         .describe("Which stitch, when the medium is thread. Default longAndShort. These six are THE_STITCH_OPS the engine publishes — call 'list_stitches' for each one's description and its own parameters. An unknown name is refused by the engine rather than quietly stitched as a default fill."),
     field: z.object({
         kind: z.enum(['radial', 'spine', 'constant']),
         cx: z.number().optional(), cy: z.number().optional(),
         angle: z.number().optional(),
-        spine: z.array(PositionSchema).optional(),
+        // [x, y] is converted to {x, y} here: the engine's own spine reader only
+        // takes {x, y} and crashed on an array pair when called directly.
+        spine: z.array(PositionSchema).optional().describe('Points along the midrib, each {x, y} or [x, y]'),
         across: z.boolean().optional(),
     }).optional().describe("apply_thread: the direction field — the thing that makes it needlepainting rather than hatching. Default radial from the shape centre. 'spine' runs stitches along a midrib or feather shaft; 'constant' is flat hatch."),
     stitchLen: z.number().positive().optional().describe('apply_thread: nominal stitch length px (default 18).'),
@@ -3669,7 +3794,9 @@ export const DesignMediumInputSchema = z.object({
 })
     .refine((v) => v.action !== 'apply_thread' || !!v.itemId, { message: 'apply_thread requires itemId', path: ['itemId'] })
     .refine((v) => v.action !== 'resolve' || !!v.medium, { message: 'resolve requires medium', path: ['medium'] })
-    .refine((v) => v.action !== 'apply_hatch' || !!v.itemId, { message: 'apply_hatch requires itemId', path: ['itemId'] });
+    .refine((v) => v.action !== 'apply_hatch' || !!v.itemId, { message: 'apply_hatch requires itemId', path: ['itemId'] })
+    .refine((v) => v.action !== 'apply' || (!!v.itemId && !!v.medium), { message: 'apply requires itemId and medium', path: ['medium'] })
+    .refine((v) => v.action !== 'apply' || !v.medium || DESIGN_MEDIA.includes(v.medium), { message: `unknown medium; the engine knows ${DESIGN_MEDIA.join(', ')}`, path: ['medium'] });
 export const TextEffectInputSchema = z.object({
     action: z.enum(['apply', 'list'])
         .describe("'apply' (explode a text item into animated characters) · 'list' (the 37 effects with key/label/definition, for a picker)"),
@@ -3791,7 +3918,7 @@ export const World3DInputSchema = z.object({
         .describe("'create' (a preset world) · 'describe' (every parameter with type/range — CALL THIS before configure) · 'configure' (live deep-merge patch, schema-validated) · actor ops · 'set_camera' (follow|fixed|orbit) · object ops · 'remove_world' · MESH AUTHORING: 'extrude_path' / 'lathe_path' turn a canvas path into real geometry, 'list_meshes', 'remove_mesh' · 'add_light' / 'set_light' / 'remove_light' / 'list_lights' (at most 8 point lights) · 'add_material' / 'set_material' / 'remove_material' / 'list_materials'"),
     spec: z.union([z.string(), z.record(z.string(), z.unknown())]).optional().describe("create: a preset id ('forest', 'snowMountain', …) or a full world spec object."),
     character: z.union([z.boolean(), z.record(z.string(), z.unknown())]).optional().describe('create: include the walkable character (true/config).'),
-    patch: z.record(z.string(), z.unknown()).optional().describe('configure: partial world spec, deep-merged and validated — a wrong key errors naming the right one.'),
+    patch: z.record(z.string(), z.unknown()).optional().describe('configure: partial world spec, deep-merged and validated — a wrong key errors naming the right one. Colours (env.zenith, env.horizon, env.fogColor, env.sunColor, env.ambient, env.lowColor … env.propColorB) take hex ("#03050c") or [r, g, b] in 0..1.'),
     actorId: z.string().optional().describe('Actor id — add_actor (optional, generated if omitted) / remove_actor / set_actor_pose / set_camera target.'),
     x: z.number().optional().describe('World-space x — add_actor / add_object.'),
     z: z.number().optional().describe('World-space z — add_actor / add_object.'),
@@ -3806,8 +3933,12 @@ export const World3DInputSchema = z.object({
     pathId: z.string().optional().describe("extrude_path / lathe_path: the canvas path to turn into geometry. Extrude sweeps it along depth; lathe revolves its profile around the Y axis. The path is unchanged — the mesh is new."),
     mesh: z.object({
         id: z.string().optional().describe('Mesh id (generated if omitted).'),
-        depth: z.number().optional().describe('extrude_path: how far to sweep, in world units.'),
-        unitsPerPixel: z.number().optional().describe('Canvas pixels → world units. The whole scale relationship between the drawing and the world.'),
+        depth: z.number().optional().describe('extrude_path: how far to sweep, in WORLD units (default 1). Not pixels: the outline is canvas px × unitsPerPixel.'),
+        unitsPerPixel: z.number().optional().describe('Canvas pixels → world units (default 0.01, so a 200 px outline is 2 world units). The whole scale relationship between the drawing and the world.'),
+        // FxTool #49 (7c50c838). Declared here, or z.object() strips them before
+        // the emitter's spread can pass them on (the 5.64 colour bug, again).
+        upright: z.boolean().optional().describe('extrude_path: stand the drawing up (canvas up = world up, extruded along Z) — a sign, a letter, a cut-out. Default false: flat, a floor plan in XZ extruded along Y.'),
+        placement: z.enum(['centered', 'canvas']).optional().describe("extrude_path: 'centered' (default) centres the mesh on x/z with its BASE at y, so it stands on the ground at the point you give. 'canvas' keeps the outline's canvas position (× unitsPerPixel), the older behaviour."),
         caps: z.boolean().optional().describe('extrude_path: close the two ends. A capped extrude is a solid; an uncapped one is a ribbon.'),
         segments: z.number().optional().describe('extrude_path: segments along the sweep · lathe_path: segments around the revolution.'),
         arc: z.number().optional().describe('lathe_path: how far round to revolve, in degrees. 360 is a full solid of revolution; less leaves it open.'),
@@ -3834,7 +3965,7 @@ export const World3DInputSchema = z.object({
         x: z.number().optional().describe('World-space x (default 0).'),
         y: z.number().optional().describe('World-space y (default 3 — above the ground, not on it).'),
         z: z.number().optional().describe('World-space z (default 0).'),
-        color: z.array(z.number()).length(3).optional().describe('Linear RGB, each component ≥ 0 (default [1, 0.86, 0.62], a warm lamp).'),
+        color: z.union([z.string(), z.array(z.number()).length(3)]).optional().describe('Hex ("#ffdca0") or linear RGB [r, g, b], each component ≥ 0 and may exceed 1 for a brighter light (default [1, 0.86, 0.62], a warm lamp).'),
         intensity: z.number().optional().describe('Brightness (default 6).'),
         range: z.number().optional().describe('How far the light reaches, in world units (default 20).'),
     }).optional().describe('add_light / set_light: the light spec. At most 8 point lights exist at once — the shader array is fixed-size, so a ninth is refused by name rather than ignored.'),
@@ -3842,14 +3973,14 @@ export const World3DInputSchema = z.object({
     // --- Materials ------------------------------------------------------------
     material: z.object({
         id: z.string().optional().describe('Material id (generated if omitted).'),
-        color: z.array(z.number()).length(3).optional().describe('Base colour, linear RGB (default [0.8, 0.8, 0.82]).'),
-        emissive: z.array(z.number()).length(3).optional().describe('Light the surface emits regardless of the scene (default [0, 0, 0]).'),
+        color: z.union([z.string(), z.array(z.number()).length(3)]).optional().describe('Base colour: hex ("#e9e4d8") or linear RGB [r, g, b] in 0..1 (default [0.8, 0.8, 0.82]).'),
+        emissive: z.union([z.string(), z.array(z.number()).length(3)]).optional().describe('Light the surface emits regardless of the scene: hex or [r, g, b] in 0..1 (default [0, 0, 0]).'),
         metalness: z.number().min(0).max(1).optional().describe('0 dielectric → 1 metal.'),
         roughness: z.number().min(0).max(1).optional().describe('0 mirror → 1 fully diffuse. Floored at 0.045: a true zero is a numerically unstable mirror.'),
         emissiveIntensity: z.number().min(0).optional().describe('Scales `emissive` before the frame is built, so it reaches every path that draws emissive.'),
         clearcoat: z.number().min(0).max(1).optional().describe('A lacquer layer over the base — car paint, varnished wood.'),
         clearcoatRoughness: z.number().min(0).max(1).optional().describe("The coat's own roughness. NOT floored like the base, so a mirror-smooth lacquer stays expressible."),
-        sheenColor: z.array(z.number()).length(3).optional().describe('Retroreflective sheen colour — cloth, velvet.'),
+        sheenColor: z.union([z.string(), z.array(z.number()).length(3)]).optional().describe('Retroreflective sheen colour — cloth, velvet: hex or [r, g, b] in 0..1.'),
         sheenRoughness: z.number().min(0).max(1).optional().describe('How broad the sheen lobe is.'),
     }).optional().describe("add_material / set_material: a NAMED, SHARED surface referenced by many objects, so one edit restyles all of them. metalness and roughness reach the shader on the MESH path only. There are no aoMapIntensity / normalScale / envMapIntensity knobs: each scales a map that does not exist, and a knob that scales nothing is worse than a missing one."),
     materialId: z.string().optional().describe('set_material / remove_material: the material id.'),
@@ -3860,8 +3991,8 @@ export const World3DInputSchema = z.object({
     crossfade: z.number().optional().describe('set_mesh_clip: seconds to blend out of the clip that was playing. The blend happens in LOCAL pose space — a palette cannot be blended after the fact.'),
     // --- Navigation, picking and the camera ----------------------------------
     navTarget: z.enum(['2d', '3d']).optional().describe("set_nav_target: which layer the pointer drives — '2d' the Paper canvas, '3d' the world."),
-    point: z.object({ x: z.number(), y: z.number(), z: z.number().optional() }).optional()
-        .describe('ground_height / canvas_to_ground / world_to_canvas: the point to convert. ground_height and canvas_to_ground read x and y (canvas) or x and z (world); world_to_canvas takes a world point.'),
+    point: z.object({ x: z.number(), y: z.number().optional(), z: z.number().optional() }).optional()
+        .describe('The point to convert. ground_height: {x, z} in WORLD coordinates (the terrain height there; y is read as z if z is absent). canvas_to_ground: {x, y} in CANVAS pixels. world_to_canvas: {x, y, z?} in world coordinates.'),
     origin: z.array(z.number()).length(3).optional().describe('raycast: ray origin in world space, [x, y, z].'),
     direction: z.array(z.number()).length(3).optional().describe('raycast: ray direction in world space, [x, y, z]. Need not be normalised.'),
     multiplier: z.number().optional().describe('dolly_camera: greater than 1 moves away, less than 1 moves closer.'),
@@ -3879,6 +4010,10 @@ export const World3DInputSchema = z.object({
         .describe('set_mesh_instances: one entry per copy, six numbers each — x, y, z, scale, rotY (RADIANS), and a free variant a shader may read for per-instance colour or phase.'),
 })
     .refine((v) => v.action !== 'configure' || !!v.patch, { message: 'configure requires patch', path: ['patch'] })
+    // ground_height reads a WORLD (x, z); y is accepted in z's place for older callers.
+    .refine((v) => v.action !== 'ground_height' || (!!v.point && (v.point.z !== undefined || v.point.y !== undefined)), { message: 'ground_height requires point {x, z} (world coordinates)', path: ['point'] })
+    .refine((v) => v.action !== 'canvas_to_ground' || (!!v.point && v.point.y !== undefined), { message: 'canvas_to_ground requires point {x, y} (canvas coordinates)', path: ['point'] })
+    .refine((v) => v.action !== 'world_to_canvas' || (!!v.point && v.point.y !== undefined), { message: 'world_to_canvas requires point {x, y, z?} (world coordinates)', path: ['point'] })
     .refine((v) => !['remove_actor', 'set_actor_pose'].includes(v.action) || !!v.actorId, { message: 'this action requires actorId', path: ['actorId'] })
     .refine((v) => v.action !== 'set_actor_pose' || !!v.pose, { message: 'set_actor_pose requires pose', path: ['pose'] })
     .refine((v) => v.action !== 'set_camera' || !!v.camera, { message: 'set_camera requires camera', path: ['camera'] })
@@ -4078,6 +4213,7 @@ export const SoundInputSchema = z.object({
         from: z.number().positive().describe('Starting frequency in Hz.'),
         tau: z.number().positive().max(5).describe('Glide time constant in seconds (max 5).'),
     }).optional().describe("define_percussion / define_sfx: the pitch glide, which is what makes a kick a kick — the engine's own note is that the glide IS the drum. Omit it and a defined kick comes out a beep."),
+    duration: z.number().positive().optional().describe('render_soundtrack: seconds to render (same as options.duration; this wins if both are given).'),
     sampleRate: z.number().int().positive().optional().describe('render_soundtrack: samples per second (default 48000).'),
     bitDepth: z.union([z.literal(16), z.literal(32)]).optional().describe('render_soundtrack: 16 (default) or 32-bit float.'),
     text: z.string().optional().describe("from_text / play_from_text: a plain-language description, e.g. 'a soft warm bell on A4'. 'from_text' resolves it to a spec WITHOUT playing, so a caller can inspect or edit before committing."),
@@ -4119,7 +4255,7 @@ export const SoundInputSchema = z.object({
     .refine((v) => !['define_percussion', 'define_sfx'].includes(v.action)
     || (v.partials?.length ?? 0) > 0 || (v.noise ?? 0) > 0, { message: 'this action needs a partial table or noise > 0 — with neither the sound is silent', path: ['noise'] })
     // Bound by the scene, like every other timed export.
-    .refine((v) => v.action !== 'render_soundtrack' || (v.options?.duration ?? 1) <= VIDEO_MAX_DURATION_S, { message: `render_soundtrack duration is capped at ${VIDEO_MAX_DURATION_S}s, the same ceiling as video`, path: ['options'] });
+    .refine((v) => v.action !== 'render_soundtrack' || (v.duration ?? v.options?.duration ?? 1) <= VIDEO_MAX_DURATION_S, { message: `render_soundtrack duration is capped at ${VIDEO_MAX_DURATION_S}s, the same ceiling as video`, path: ['options'] });
 /**
  * pinepaper_motion — the generators' Animation knob, pointed at anything.
  *