@pinepaper.studio/mcp-server 1.6.18 → 1.6.19

package/dist/types/schemas.js

@@ -8,7 +8,7 @@
  * 3. TypeScript type inference
  */
 import { z } from 'zod';
-import { ENGINE_EASING_NAMES, DESIGN_MEDIA, DESIGN_MEDIA_APPLY } from '../tools/engine-lists.js';
+import { ENGINE_EASING_NAMES, DESIGN_MEDIA, DESIGN_MEDIA_APPLY, FILTER_TYPES, LINEAGE_KINDS, STYLED_SCENE_STYLES } from '../tools/engine-lists.js';
 // =============================================================================
 // COMMON SCHEMAS
 // =============================================================================
@@ -1105,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
 // =============================================================================
@@ -1441,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({
@@ -1521,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(),
@@ -1738,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'),
@@ -1752,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'),
@@ -1824,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)'),
 });
@@ -2039,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'),
@@ -2171,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
  */
@@ -2591,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');
@@ -2656,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'),
@@ -2671,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'),
@@ -3135,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(),
 });
@@ -3539,6 +3590,41 @@ export const ValidateSceneInputSchema = z.object({
  * 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.'),
@@ -3571,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(),
@@ -3684,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)."),
@@ -3708,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).
@@ -3737,9 +3848,9 @@ 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', 'apply'])
+    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(', ')}; the others are refused by the engine with the reason (encaustic is absent here; charcoal and ink are brushes, not fills).`),
+    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()
@@ -3756,9 +3867,9 @@ export const DesignMediumInputSchema = z.object({
     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
@@ -3791,12 +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 !== '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)"),
@@ -3985,7 +4162,7 @@ export const World3DInputSchema = z.object({
     }).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.'),
@@ -4098,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."),
@@ -4164,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'] })
@@ -4260,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.
@@ -4273,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()
@@ -4472,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'] })