@pinepaper.studio/mcp-server 1.6.17 → 1.6.19

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, FILTER_TYPES, LINEAGE_KINDS, STYLED_SCENE_STYLES } 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
@@ -1041,22 +1105,10 @@ export const BlastParamsSchema = z.object({
 // 'saturate' is what the published JSON schema offered for releases, while
 // the engine registers 'saturation' and this enum rejected 'saturate' — a
 // caller who followed the docs got a validation error. Accepted and mapped.
-export const FilterTypeSchema = z.preprocess((v) => (v === 'saturate' ? 'saturation' : v), z.enum([
-    'grayscale',
-    'sepia',
-    'blur',
-    'brightness',
-    'contrast',
-    'saturation',
-    'invert',
-    'noise',
-    'vignette',
-    'vintage',
-    'colorOverlay',
-    'sharpen',
-    'emboss',
-    'posterize',
-])).describe('Type of visual filter to apply');
+// GENERATED list (FilterSystem.js registerFilter, scripts/sync-engine-lists.mjs).
+// The hand copy here hid six of twenty: dither, halftoneCMYK, halftoneDots,
+// edgeDetect, hsl and colorTint. 'saturate' stays accepted as 'saturation'.
+export const FilterTypeSchema = z.preprocess((v) => (v === 'saturate' ? 'saturation' : v), z.enum(FILTER_TYPES)).describe('Type of visual filter to apply');
 // =============================================================================
 // TOOL INPUT SCHEMAS
 // =============================================================================
@@ -1377,9 +1429,12 @@ export const SetCanvasSizeInputSchema = z.object({
     // 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(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'),
+    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).optional().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).optional().describe('Canvas height (100-16384; above 8192 Safari / iOS may fail)'),
+    preset: z.string().optional().describe('A named size instead of width/height; an unknown name is refused with the known ones listed.'),
+}).refine((v) => !!v.preset || (v.width !== undefined && v.height !== undefined), {
+    // {preset} alone was refused for a missing width (1.6.19 gate).
+    message: 'pass width and height, or a preset', path: ['width'],
 });
 // Export
 export const ExportSVGInputSchema = z.object({
@@ -1457,12 +1512,12 @@ export const SetToolkitInputSchema = z.object({
 // =============================================================================
 export const SearchAssetsInputSchema = z.object({
     query: z.string().describe('Search term (e.g., "rocket", "heart", "user icon")'),
-    repository: z.enum(['all', 'svgrepo', 'openclipart', 'iconify', 'fontawesome']).optional().describe('Which repository to search (default: all)'),
+    repository: z.enum(['all', 'iconify', 'fontawesome']).optional().describe('Which repository to search (default: all)'),
     limit: z.number().min(1).max(50).optional().describe('Max results to return (default: 10)'),
     includeSvgContent: z.boolean().optional().describe('Include actual SVG content for each result (default: false). When true, fetches and returns the SVG string for each asset, enabling AI to display or describe the icons.'),
 });
 export const ImportAssetInputSchema = z.object({
-    assetId: z.string().optional().describe('Asset ID from search results (e.g., "svgrepo_12345")'),
+    assetId: z.string().optional().describe('Asset ID from search results (e.g., "iconify_mdi_rocket")'),
     url: z.string().optional().describe('Direct URL to SVG (alternative to assetId)'),
     position: z.object({
         x: z.number(),
@@ -1674,8 +1729,23 @@ export const CreateDiagramShapeInputSchema = z.object({
 /**
  * Connect items input
  */
-export const ConnectInputSchema = z.object({
-    id: z.string().optional().describe('Stable connector ID. Assign your own and reuse it as `connectorId` in update/remove — the engine otherwise mints a Date.now()-based ID no caller can predict'),
+// strokeColor / strokeWidth are what a model guesses (Paper's names); they
+// were stripped and the connector drew in the default colour (gate run 3).
+export const ConnectInputSchema = z.preprocess((v) => {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return v;
+    const o = { ...v };
+    if (o.lineColor === undefined && o.strokeColor !== undefined) {
+        o.lineColor = o.strokeColor;
+        delete o.strokeColor;
+    }
+    if (o.lineWidth === undefined && o.strokeWidth !== undefined) {
+        o.lineWidth = o.strokeWidth;
+        delete o.strokeWidth;
+    }
+    return o;
+}, z.object({
+    id: z.string().optional().describe('Requested connector id. The studio may not honour it (the result says idHonoured): always use the connectorId the result returns for update/remove.'),
     sourceItemId: z.string().describe('Registry ID of source item'),
     targetItemId: z.string().describe('Registry ID of target item'),
     routing: ConnectorRoutingSchema.optional().default('orthogonal'),
@@ -1688,12 +1758,12 @@ export const ConnectInputSchema = z.object({
     curvature: z.number().min(0.1).max(1.0).optional().default(0.5).describe('Curve intensity for curved routing'),
     boltEnabled: z.boolean().optional().default(true).describe('Enable animated bolt effect'),
     boltColor: z.string().optional().default('#fbbf24').describe('Bolt animation color'),
-});
+}));
 /**
  * Connect specific ports input
  */
 export const ConnectPortsInputSchema = z.object({
-    id: z.string().optional().describe('Stable connector ID. Assign your own and reuse it as `connectorId` in update/remove — the engine otherwise mints a Date.now()-based ID no caller can predict'),
+    id: z.string().optional().describe('Requested connector id. The studio may not honour it (the result says idHonoured): always use the connectorId the result returns for update/remove.'),
     sourceItemId: z.string().describe('Registry ID of source item'),
     sourcePort: PortPositionSchema.describe('Port position on source'),
     targetItemId: z.string().describe('Registry ID of target item'),
@@ -1760,16 +1830,34 @@ export const GetDiagramShapesInputSchema = z.object({
 /**
  * Update connector input
  */
+// Paper.js's own names are what a model guesses for a connector's style, and
+// an unknown key was STRIPPED, so {strokeColor} changed nothing and reported
+// success (gate run 3). The Paper names are mapped; anything else is refused
+// with the keys that work.
+const CONNECTOR_STYLE_ALIASES = { strokeColor: 'lineColor', color: 'lineColor', strokeWidth: 'lineWidth', width: 'lineWidth' };
+const CONNECTOR_STYLE_KEYS = ['lineColor', 'lineWidth', 'headStyle', 'tailStyle', 'routing', 'lineStyle'];
 export const UpdateConnectorInputSchema = z.object({
     connectorId: z.string().describe('Connector ID to update'),
-    style: z.object({
+    style: z.preprocess((v) => {
+        if (!v || typeof v !== 'object' || Array.isArray(v))
+            return v;
+        const out = {};
+        for (const [k, val] of Object.entries(v)) {
+            if (k === 'dashArray') {
+                out.lineStyle = Array.isArray(val) && val.length ? 'dashed' : 'solid';
+                continue;
+            }
+            out[CONNECTOR_STYLE_ALIASES[k] ?? k] = val;
+        }
+        return out;
+    }, z.object({
         lineColor: z.string().optional(),
         lineWidth: z.number().optional(),
         headStyle: ArrowHeadStyleSchema.optional(),
         tailStyle: ArrowHeadStyleSchema.optional(),
         routing: ConnectorRoutingSchema.optional(),
         lineStyle: ConnectorLineStyleSchema.optional(),
-    }).optional(),
+    }).strict(`a connector's style takes ${CONNECTOR_STYLE_KEYS.join(', ')} (strokeColor, strokeWidth and dashArray are accepted for lineColor, lineWidth and lineStyle)`)).optional(),
     label: z.string().optional().describe('Update connector label'),
     labelPosition: z.number().min(0).max(1).optional().describe('Label position along path (0-1)'),
 });
@@ -1821,9 +1909,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(),
@@ -1977,10 +2063,8 @@ export const AgentBatchOperationSchema = z.object({
     type: AgentBatchOperationTypeSchema,
     // Create operation fields
     itemType: z.string().optional().describe('Item type for create operations'),
-    position: z.object({
-        x: z.number(),
-        y: z.number(),
-    }).optional().describe('Position for create operations'),
+    // PositionSchema, as create_item takes: [x, y] was refused here (1.6.19 gate).
+    position: PositionSchema.optional().describe('Position for create operations: {x, y} or [x, y]'),
     properties: z.record(z.unknown()).optional().describe('Properties for create/modify operations'),
     // Modify/Animate/Delete/Keyframe/Mask/Effect target
     itemId: z.string().optional().describe('Target item ID or $N reference'),
@@ -2109,6 +2193,19 @@ export const GIF_MAX_DURATION_S = 15;
  * out-of-memory — it turns into a message naming the ceiling and what to do.
  */
 export const VIDEO_MAX_DURATION_S = 600;
+/**
+ * pinepaper_styled_scene (FxTool K2): one declarative composition drawn in a
+ * built-in style, as ONE canvas item that redraws itself every exported frame.
+ * The styles are GENERATED (STYLED_SCENE_STYLES); the engine also resolves its
+ * own aliases ('watercolour', 'papercut'), so style is a string here and an
+ * unknown one is refused by the engine with the known list.
+ */
+export const StyledSceneInputSchema = z.object({
+    style: z.string().optional().describe(`The look: ${STYLED_SCENE_STYLES.join(' | ')} (default watercolor). The engine also takes its aliases (watercolour, papercut, 1bit…).`),
+    duration: z.number().positive().max(VIDEO_MAX_DURATION_S).optional().describe('Seconds the scene runs (default the composition\'s, 8). Export for this long.'),
+    id: z.string().optional().describe('Scene id (default "styled-scene"). Calling again with the same id REPLACES that scene, e.g. to change style.'),
+    spec: z.record(z.string(), z.unknown()).optional().describe("The composition, every key optional (omitted keys take the 'valley' preset): preset, size [W, H], duration, transition {name, start, length}, camera {zoom: [from, to], pan}, palette, sun, clouds, ridges, foreground, river, settlements, structure, pylons, vegetation, effects {steam, ripples, scars}, hud {label}."),
+});
 /**
  * Smart export input schema
  */
@@ -2193,6 +2290,12 @@ export const AgentExportInputSchema = z.object({
     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.'),
@@ -2220,7 +2323,7 @@ export const AgentExportInputSchema = z.object({
     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']) {
+    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.` });
         }
@@ -2523,6 +2626,7 @@ export const HighlightRegionsInputSchema = z.object({
         strokeColor: z.string().optional().describe('Highlight stroke color'),
         stroke: z.string().optional().describe("The engine's own name for the stroke."),
         strokeWidth: z.number().optional().describe('Highlight stroke width'),
+        opacity: z.number().min(0).max(1).optional().describe('0..1: a TINT over the land. The colour is pre-blended over the region\'s land fill and drawn opaque, so the export shows exactly the fill reported. Hex colours only.'),
         animate: z.boolean().optional().describe('Animate the highlight'),
     }).optional().describe('Highlight options'),
 }).describe('Highlight regions input');
@@ -2588,12 +2692,24 @@ export const GetRegionAtPointInputSchema = z.object({
     y: z.number().describe('Canvas Y coordinate'),
 }).describe('Get region at point input');
 // Map Animation Schemas
-export const MapRegionKeyframeSchema = z.object({
+// The engine reads fillColor OR color, plus easing (MapSystem.animateRegions);
+// requiring fillColor refused keyframes written with color (gate D17, 1.6.19).
+// A keyframe may nest its values under `properties`, the shape every other
+// keyframe tool takes; it is flattened rather than refused (gate run 2).
+export const MapRegionKeyframeSchema = z.preprocess((k) => {
+    if (!k || typeof k !== 'object' || Array.isArray(k))
+        return k;
+    const { properties, ...rest } = k;
+    return properties && typeof properties === 'object' && !Array.isArray(properties) ? { ...properties, ...rest } : k;
+}, z.object({
     time: z.number().describe('Time in seconds'),
-    fillColor: z.string().describe('Fill color at this keyframe'),
+    fillColor: z.string().optional().describe('Fill color at this keyframe (or color)'),
+    color: z.string().optional().describe('Same as fillColor'),
     strokeColor: z.string().optional().describe('Stroke color (optional)'),
     opacity: z.number().optional().describe('Opacity 0-1 (optional)'),
-}).describe('Map region keyframe');
+    easing: z.string().optional().describe('Easing into this keyframe'),
+}).refine((k) => !!(k.fillColor || k.color), { message: 'each keyframe needs fillColor (or color)', path: ['fillColor'] }))
+    .describe('Map region keyframe');
 export const WaveDirectionSchema = z.enum(['horizontal', 'vertical', 'radial']).describe('Wave animation direction');
 export const AnimateMapRegionsInputSchema = z.object({
     duration: z.number().optional().default(5).describe('Total animation duration in seconds'),
@@ -2603,9 +2719,10 @@ export const AnimateMapRegionsInputSchema = z.object({
 export const AnimateMapWaveInputSchema = z.object({
     duration: z.number().optional().default(10).describe('Total wave duration in seconds'),
     loop: z.boolean().optional().default(true).describe('Loop the animation'),
-    colors: z.array(z.string()).optional().describe('Array of colors for the wave'),
+    colors: z.array(z.string()).optional().describe('Colors the wave cycles through (at least 2)'),
     waveDirection: WaveDirectionSchema.optional().default('horizontal').describe('Direction of wave effect'),
-}).describe('Animate map wave input');
+    waveSpeed: z.number().positive().optional().describe('Speed of the wave (default 1)'),
+}).describe('Animate map wave input: the wave runs across ALL regions of the map');
 export const StopMapAnimationsInputSchema = z.object({
     regions: z.array(z.string()).optional().describe('Specific region IDs to stop (omit for all)'),
     resetColors: z.boolean().optional().default(true).describe('Reset regions to default colors'),
@@ -3000,8 +3117,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;
@@ -3022,9 +3141,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(),
@@ -3063,7 +3184,9 @@ export const CommentInputSchema = z.object({
 export const ProvenanceInputSchema = z.object({
     action: z.enum(['get', 'lineage', 'dependents', 'record']),
     itemId: z.string(),
-    kind: z.string().optional(),
+    // GENERATED (LINEAGE_KINDS): the default was 'derived', which the engine
+    // refuses, and the docs named three kinds that do not exist (1.6.19 gate).
+    kind: z.enum(LINEAGE_KINDS).optional().describe('record: how the item came from sourceRef (default derivedFrom).'),
     sourceRef: z.string().optional(),
     meta: z.record(z.string(), z.unknown()).optional(),
 });
@@ -3461,11 +3584,69 @@ 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.
+ */
+/**
+ * pinepaper_export_scene / pinepaper_import_scene (D28): a restorable save.
+ * The default export is a summary for inspection; `full` writes the engine's
+ * project document (captureProjectDocument) to a file.
+ */
+/**
+ * pinepaper_place_on_surface (D22, FxTool #56): a UI onto a screen in a photo,
+ * corner-pinned, matted and lit, baked into the photo's pixels.
+ */
+const PointPair = z.tuple([z.number(), z.number()]);
+export const PlaceOnSurfaceInputSchema = z.object({
+    photoId: z.string().describe('The photo: an image item (or a group holding one).'),
+    sourceId: z.string().describe('The UI to place: any canvas item or group, or an image item.'),
+    quad: z.tuple([PointPair, PointPair, PointPair, PointPair]).optional().describe('The screen\'s four corners TL, TR, BR, BL. Omit to detect it (the largest bright, neutral region).'),
+    quadSpace: z.enum(['image', 'canvas']).optional().describe("quad's coordinates: 'image' (default) photo pixels, or 'canvas'."),
+    occlusion: z.enum(['luma', 'none']).optional().describe("'luma' (default) keeps a thumb or hand in front of the screen; 'none' covers it."),
+    key: z.number().optional().describe('Brightness above which the photo counts as screen (default: found from the photo).'),
+    erode: z.number().min(0).optional().describe('Pull the matte in from the bezel, px (default 2).'),
+    matteBlur: z.number().min(0).optional().describe('Soften the matte edge (default 0.8).'),
+    soften: z.number().min(0).optional().describe('Soften the UI to the photo\'s focus (default 0.5).'),
+    glare: z.number().min(0).max(1).optional().describe('Glass glare kept over the UI (default 0.10).'),
+    spill: z.number().min(0).max(1).optional().describe('Screen light spilling onto the surroundings (default 0.35).'),
+    spillRadius: z.number().min(0).optional().describe('Spill reach, px (default 40).'),
+    tint: z.tuple([z.number(), z.number(), z.number()]).optional().describe('Multiply the UI by [r, g, b], 0..1, to match the photo\'s white balance.'),
+    slot: z.string().optional().describe("Name for this screen (default 'screen'). Placing again in the same slot REPLACES it; several screens in one photo use different slots."),
+    hideSource: z.boolean().optional().describe('Hide the UI item after placing it (default true).'),
+});
+export const ExportSceneInputSchema = z.object({
+    full: z.boolean().optional().describe('Save a RESTORABLE project document to a file (keyframes, relations, rigging, scene chains), not the summary. Restore it with pinepaper_import_scene.'),
+    name: z.string().optional().describe('full: a name recorded in the document.'),
+});
+export const ImportSceneInputSchema = z.object({
+    path: z.string().min(1).describe('The project document a full pinepaper_export_scene saved (absolute path, or relative to the server working directory).'),
+    strict: z.boolean().optional().describe('Refuse a document with validation problems (default true). false loads anyway and returns the problems as warnings.'),
+});
+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
@@ -3476,7 +3657,7 @@ export const InstantiateOntologyInputSchema = z.object({
     canvas: z.object({
         width: z.number().positive(),
         height: z.number().positive(),
-    }).optional().describe('Canvas size used to tile component roots (default 1080×1080).'),
+    }).optional().describe('Canvas size to lay out for (default: the live canvas).'),
     defaultGeometry: z.record(z.string(), z.object({
         width: z.number(),
         height: z.number(),
@@ -3492,14 +3673,20 @@ 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.'),
@@ -3549,6 +3736,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'] })
@@ -3581,7 +3770,26 @@ export const TextStyleInputSchema = z.object({
         scale: z.number().optional().describe('Size multiplier (default 1).'),
         strokeColor: z.string().optional().describe("Ink colour (default '#ffffff')."),
         strokeWidth: z.number().optional().describe('Pen width (default 2).'),
-    }).optional().describe('cursive: where and how it is written. The result is a STROKED PATH, so pinepaper_animate\'s draw-on and pinepaper_path\'s outline_stroke both apply to it — which is the reason to prefer it over a script font.'),
+        nib: z.union([
+            z.boolean(),
+            z.enum(['monoline', 'broad']),
+            z.object({
+                angle: z.number().optional().describe('Nib angle in degrees.'),
+                width: z.number().positive().optional().describe('Widest stroke, in px.'),
+                contrast: z.number().min(0).max(1).optional().describe('0..1; the hairline is width × (1 − contrast).'),
+                taper: z.number().min(0).max(0.5).optional().describe('0..0.5; thin entry and exit.'),
+            }).strict(),
+        ]).optional().describe("The pen. 'monoline' (or false): one even line. 'broad' (or true): a broad nib, thick across it and hairline along it; an object tunes the broad nib. Omitted: the studio's default pen."),
+        // Draw-on (gate D41): the engine keyframes trimEnd 0→1 itself; these were
+        // stripped, so a handwritten title arrived fully drawn.
+        animate: z.boolean().optional().describe('true writes the words on, stroke by stroke, over `duration` seconds — no keyframe_animate needed (default false: drawn at once).'),
+        duration: z.number().positive().optional().describe('animate: seconds to write the whole line (default 2).'),
+        easing: z.enum(ENGINE_EASING_NAMES).optional().describe("animate: the write-on easing (default 'easeOut')."),
+        timeOffset: z.number().min(0).optional().describe('animate: seconds into the timeline before writing starts (default 0).'),
+        singleStroke: z.boolean().optional().describe('Primary strokes only — drop the secondary strokes (default false).'),
+        showGhost: z.boolean().optional().describe('Show a faint outline of the whole line under the write-on (default false).'),
+        tension: z.number().optional().describe("Curve tension of the pen path (the studio's default when omitted)."),
+    }).strict().optional().describe('cursive: where and how it is written. The result is a STROKED PATH, so pinepaper_animate\'s draw-on and pinepaper_path\'s outline_stroke both apply to it — which is the reason to prefer it over a script font.'),
     collageOptions: z.record(z.string(), z.unknown()).optional().describe('to_collage: style, palette and the rest, same vocabulary as pinepaper_create_letter_collage.'),
     itemId: z.string().optional().describe('Text item id — apply_style / set_font_axes.'),
     styleKey: z.string().optional().describe("apply_style: style name from list_styles (e.g. 'stacked', 'arcade' — the pixel/arcade styles suggest their own face)."),
@@ -3605,7 +3813,13 @@ export const TextStyleInputSchema = z.object({
     }).passthrough().optional().describe('set_font_axes: weight/width/slant, or OpenType tags (wght/wdth/slnt). Unknown axes are passed to the engine and come back in `rejected` rather than being dropped here. All three named axes are animatable (addKeyframe with fontWeight interpolates).'),
 })
     .refine((v) => v.action !== 'apply_style' || (!!v.itemId && !!v.styleKey), { message: 'apply_style requires itemId and styleKey', path: ['styleKey'] })
-    .refine((v) => v.action !== 'set_font_axes' || (!!v.itemId && !!v.axes && Object.keys(v.axes).length > 0), { message: 'set_font_axes requires itemId and at least one axis', path: ['axes'] });
+    .refine((v) => v.action !== 'set_font_axes' || (!!v.itemId && !!v.axes && Object.keys(v.axes).length > 0), { message: 'set_font_axes requires itemId and at least one axis', path: ['axes'] })
+    // cursive WRITES new words; with no text it reached the engine and failed as
+    // "Cannot read properties of undefined (reading 'length')" (gate, P2).
+    .refine((v) => v.action !== 'cursive' || (typeof v.text === 'string' && v.text.trim() !== ''), {
+    message: "cursive writes new text from `text`; it does not restyle an existing item. Pass text (the words to write); for a style on an existing text item use apply_style with its itemId.",
+    path: ['text']
+});
 /**
  * pinepaper_text_effect — the 37 character-level text effects
  * (terminaltexteffects' vocabulary, reimplemented in FxTool from source).
@@ -3634,25 +3848,28 @@ 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', 'sdf_stroke'])
+        .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(', ')}; a medium the studio cannot apply is refused by the engine with the reason. ink and charcoal, where the studio applies them, restyle the item IN PLACE (same id).`),
+    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).'),
     rowGap: z.number().positive().optional().describe('apply_thread: row spacing px. Defaults from the thread width so the rows abut; setting it wider is what makes a fill read as hatching.'),
     variance: z.number().min(0).max(1).optional().describe('apply_thread: length jitter 0..1 (default 0.35) — the variance IS the long-and-short shading.'),
-    width: z.number().positive().optional().describe('apply_thread: thread width px (default 2).'),
+    width: z.number().positive().optional().describe('apply_thread: thread width px (default 2). sdf_stroke: stroke width px (default 8).'),
     sheen: z.boolean().optional().describe('apply_thread: draw the highlight along each stitch (default true) — thread is not matte.'),
-    color: z.string().optional().describe("apply_thread: thread colour, defaulting to the item's own fill."),
+    color: z.string().optional().describe("apply_thread: thread colour, defaulting to the item's own fill. sdf_stroke: stroke colour."),
     seed: z.number().int().optional().describe('apply_thread: PRNG seed (default 1). Same seed stitches the same way.'),
     count: z.number().int().positive().optional().describe('apply_thread: stitch count for seed/satin.'),
     // THE OPTIONS THE ENGINE READS AND NOTHING NAMED. ThreadPainting.paint reads
@@ -3685,10 +3902,78 @@ export const DesignMediumInputSchema = z.object({
     flowField: z.enum(['hand', 'curved', 'zigzag', 'waves', 'seabed', 'spiral', 'columns']).optional()
         .describe('apply_hatch: bend each line along a flow field. The straight scanline is the ruling; the field is what makes it read as drawn rather than printed. See list_flow_fields.'),
     t: z.number().optional().describe('apply_hatch: flow-field time offset — advances the field without changing the seed.'),
+    // --- SDF brush stroke (FxTool D5) ---
+    points: z.array(z.union([
+        z.object({ x: z.number(), y: z.number(), pressure: z.number().min(0).max(1).optional() }),
+        z.tuple([z.number(), z.number()]),
+        z.tuple([z.number(), z.number(), z.number()]),
+    ])).min(1).optional().describe('sdf_stroke: the stroke path in canvas px, each {x, y, pressure?} or [x, y, pressure?]. Pressure 0..1 scales the width at that point.'),
+    softness: z.number().min(0).max(1).optional().describe('sdf_stroke: edge softness 0..1 (default 0.2).'),
+    opacity: z.number().min(0).max(1).optional().describe('sdf_stroke: 0..1 (default 1).'),
+    resolution: z.number().positive().optional().describe('sdf_stroke: bitmap pixels per canvas px (default 2).'),
+    name: z.string().optional().describe('sdf_stroke: item name.'),
 })
     .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 !== 'sdf_stroke' || (Array.isArray(v.points) && v.points.length > 0), { message: 'sdf_stroke requires points', path: ['points'] })
+    .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'] });
+/**
+ * pinepaper_relight — a lighting pass over the 3D world layer (FxTool D5).
+ * CPU-backed; normals from the world's luminance (no depth). Applied in the
+ * preview and in PNG / PDF / MP4 / WebM; not GIF / APNG; not saved with the
+ * project. Lights are validated by the engine, which names every error.
+ */
+const RelightColorSchema = z.union([z.string(), z.tuple([z.number(), z.number(), z.number()])]);
+export const RelightInputSchema = z.object({
+    action: z.enum(['set', 'get', 'clear', 'list_lights'])
+        .describe("'set' (install or replace the rig) · 'get' (the current rig) · 'clear' (remove it) · 'list_lights' (the light types)"),
+    lights: z.array(z.discriminatedUnion('type', [
+        z.object({
+            type: z.literal('point'),
+            x: z.number(), y: z.number(),
+            z: z.number().optional().describe('Height above the picture, px (default 120).'),
+            radius: z.number().positive().optional().describe('Falloff radius, px (default 400).'),
+            color: RelightColorSchema.optional(),
+            intensity: z.number().min(0).optional().describe('Default 1.'),
+            specular: z.number().min(0).optional().describe('Shininess exponent (default 32).'),
+        }),
+        z.object({
+            type: z.literal('directional'),
+            dir: z.tuple([z.number(), z.number(), z.number()]).describe('[dx, dy, dz]; [0, 0, -1] faces the viewer.'),
+            color: RelightColorSchema.optional(),
+            intensity: z.number().min(0).optional(),
+        }),
+    ])).max(8).optional().describe('set: up to 8 lights. Coordinates are export-frame px. Colours are #rrggbb or [r, g, b].'),
+    ambient: z.number().min(0).optional().describe('set: ambient light (default 0.2).'),
+    strength: z.number().positive().optional().describe('set: normal-map strength (default 2).'),
+    enabled: z.boolean().optional().describe('set: false keeps the rig but turns it off.'),
+    preview: z.union([z.boolean(), z.object({ maxSide: z.number().min(64).max(4096) })]).optional()
+        .describe('set: show it in the live preview (capped-resolution overlay); {maxSide} sets the cap.'),
+}).refine((v) => v.action !== 'set' || (Array.isArray(v.lights) && v.lights.length > 0) || v.enabled === false, { message: 'set requires at least one light (or enabled: false)', path: ['lights'] });
+/**
+ * pinepaper_shader_graph — validated JSON pixel graphs (FxTool D5), CPU-backed.
+ * Linear chains only; the engine names every error (unknown type, duplicate,
+ * dangling edge, cycle, branching).
+ */
+const ShaderGraphJsonSchema = z.object({
+    id: z.string().optional(),
+    nodes: z.array(z.object({ id: z.string(), type: z.string(), params: z.record(z.string(), z.unknown()).optional() })).min(1),
+    edges: z.array(z.object({ from: z.string(), to: z.string() })).optional(),
+});
+export const ShaderGraphInputSchema = z.object({
+    action: z.enum(['node_types', 'validate', 'create', 'get', 'list', 'remove', 'apply'])
+        .describe("'node_types' (the node vocabulary + params) · 'validate' (check a graph, store nothing) · 'create' (validate + store) · 'get' / 'remove' (by graphId) · 'list' · 'apply' (run a graph over an item or the scene)"),
+    graph: ShaderGraphJsonSchema.optional().describe('validate / create / apply: {id?, nodes: [{id, type, params?}], edges: [{from, to}]} — a linear chain.'),
+    graphId: z.string().optional().describe('get / remove / apply: a stored graph id.'),
+    target: z.string().optional().describe("apply: an itemId, or 'scene'."),
+    keepSource: z.boolean().optional().describe('apply to an item: keep the source visible (default: hidden).'),
+    asItem: z.boolean().optional().describe("apply to 'scene': add the result as an image item instead of returning it."),
+})
+    .refine((v) => !['validate', 'create'].includes(v.action) || !!v.graph, { message: 'validate / create require graph', path: ['graph'] })
+    .refine((v) => !['get', 'remove'].includes(v.action) || !!v.graphId, { message: 'get / remove require graphId', path: ['graphId'] })
+    .refine((v) => v.action !== 'apply' || (!!v.target && (!!v.graph || !!v.graphId)), { message: "apply requires target (an itemId or 'scene') and graph or graphId", path: ['target'] });
 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)"),
@@ -3810,7 +4095,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.'),
@@ -3825,8 +4110,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.'),
@@ -3853,7 +4142,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.'),
@@ -3861,26 +4150,26 @@ 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.'),
     // --- Import ---------------------------------------------------------------
-    source: z.string().optional().describe('import_obj: the OBJ file TEXT. import_gltf: a URL, or a data: URI of the .glb bytes.'),
+    source: z.string().optional().describe('import_obj: the OBJ file TEXT. import_gltf: the .gltf JSON TEXT with its buffers embedded. A URL, data: URI or file path is NOT fetched (the string is parsed as JSON), so a .glb cannot be imported here.'),
     importOptions: z.record(z.string(), z.unknown()).optional().describe('import_obj / import_gltf: placement and scale options, passed through to the engine.'),
     clip: z.string().optional().describe('set_mesh_clip: which imported animation clip a skinned mesh plays.'),
     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.'),
@@ -3898,6 +4187,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'] })
@@ -3982,7 +4275,7 @@ export const DesignSystemInputSchema = z.object({
 export const StickInputSchema = z.object({
     action: z.enum(['figure', 'set']).describe("'figure' a posed, walking or travelling stick figure · 'set' the floor, wall and objects it stands on and among."),
     id: z.string().optional().describe('Prefix for the created items.'),
-    kind: z.string().optional().describe("figure: which figure. set: which piece of the scene kit ('floor', 'wall', a named object) — list-free, because the kit is vendored and grows there."),
+    kind: z.string().optional().describe("figure: which figure. set: which piece — room (floor + wall; options groundY, wall, floor), tabletop (object + surfaceY), chair (facing), table, counter, door, shelf (items), window. An unknown kind or tabletop object is refused with the engine's current list."),
     at: z.object({ x: z.number().optional(), y: z.number().optional() }).optional().describe('Where it goes.'),
     scale: z.number().optional().describe('Size multiplier.'),
     facing: z.enum(['left', 'right']).optional().describe("set: which way a CHAIR faces. The figure has no facing — it is ignored on action 'figure', which refuses it by name rather than dropping it."),
@@ -4048,7 +4341,7 @@ export const InterchangeInputSchema = z.object({
         .describe("'export_lottie' (JSON) · 'export_dotlottie' (the zipped .lottie) · 'import_lottie' (a Lottie or .lottie back onto the canvas) · 'export_glb' (the perspective 3D objects — needs some to exist) · 'export_bvh' (a skeleton's motion — needs a rig) · 'export_png_sequence' (one file per frame)."),
     options: z.record(z.string(), z.unknown()).optional().describe('Format options, passed through to the exporter: frame range, dimensions, fps, naming.'),
     data: z.union([z.string(), z.record(z.string(), z.unknown())]).optional()
-        .describe('import_lottie: the Lottie JSON — an object, a JSON string, or a URL.'),
+        .describe('import_lottie: the Lottie JSON — an object or a JSON string. A URL or a file path is NOT fetched: read the file and pass its contents.'),
     skeletonId: z.string().optional().describe('export_bvh: which skeleton to write. A BVH is one skeleton\'s motion, so this is not optional in practice.'),
 })
     .refine((v) => v.action !== 'import_lottie' || v.data !== undefined, { message: 'import_lottie requires data', path: ['data'] })
@@ -4144,7 +4437,7 @@ export const SoundInputSchema = z.object({
  * pinepaper_motion — the generators' Animation knob, pointed at anything.
  *
  * The same engine every generator's own animation runs on, reachable for any
- * group or list of items. Two kinds: a GROUP motion (drift, sway, rotate,
+ * group or list of items. Two kinds: a GROUP motion (driftX/Y, swayX/Y, rotate,
  * pulse, wave, bounce) moves the target as one; a FIELD motion (ripple,
  * breathe, undulate) sweeps a crest through the children from an origin, with
  * a chosen waveform. The field kind is the one nothing else here can do.
@@ -4157,7 +4450,7 @@ export const MotionInputSchema = z.object({
     action: z.enum(['list', 'apply']).describe("'list' every motion, waveform and origin the engine offers · 'apply' one to a target."),
     itemId: z.string().optional().describe('apply: a group or single item to move.'),
     itemIds: z.array(z.string()).optional().describe('apply: several items, wrapped in a new group that becomes the motion host. The members keep their own identity and ids.'),
-    motion: z.string().optional().describe("apply: the motion name — a GROUP motion (drift, sway, rotate, pulse, wave, bounce) moves the target as one; a FIELD motion (ripple, breathe, undulate) sweeps a crest through its children. Call 'list' for the engine's own set rather than guessing."),
+    motion: z.string().optional().describe("apply: the motion name — a GROUP motion (driftX, driftY, swayX, swayY, rotate, pulse, wave, bounce) moves the target as one; a FIELD motion (ripple, breathe, undulate) sweeps a crest through its children. Call 'list' for the engine's own set rather than guessing."),
     speed: z.number().optional().describe('apply: cycles per second, roughly. Higher is faster.'),
     intensity: z.number().optional().describe('apply: amplitude. 0.15 is the usual default elsewhere in this surface.'),
     waveform: z.enum(['sine', 'triangle', 'square', 'sawtooth', 'spike']).optional()
@@ -4356,7 +4649,8 @@ export const RiggingInputSchema = z.object({
     duration: z.number().positive().optional().describe('Seconds to traverse the path (default 1) — set_target_path.'),
     loop: z.boolean().optional().describe('Cycle the path — set_target_path.'),
 })
-    .refine((v) => ['create_skeleton', 'import_bvh', 'import_spine'].includes(v.action) || !!v.skeletonId, { message: 'this action requires skeletonId', path: ['skeletonId'] })
+    // Listing ALL skeletons or pose libraries needs no skeleton (gate D6, 1.6.19).
+    .refine((v) => ['create_skeleton', 'import_bvh', 'import_spine', 'list_skeletons', 'list_pose_libraries'].includes(v.action) || !!v.skeletonId, { message: 'this action requires skeletonId', path: ['skeletonId'] })
     .refine((v) => v.action !== 'add_bone' || v.skeletonId != null, { message: 'add_bone requires skeletonId', path: ['skeletonId'] })
     .refine((v) => v.action !== 'attach_item' || (!!v.boneId && !!v.itemId), { message: 'attach_item requires boneId and itemId', path: ['boneId'] })
     .refine((v) => v.action !== 'create_ik_chain' || (!!v.boneIds && v.boneIds.length >= 2), { message: 'create_ik_chain requires boneIds (≥2)', path: ['boneIds'] })