@pinepaper.studio/mcp-server 1.6.18 → 1.6.20

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
 // =============================================================================
@@ -78,8 +78,18 @@ export const BlendModeSchema = z.enum([
  * one table, so every easing enum here is this list.
  */
 export const KEYFRAME_EASINGS = ENGINE_EASING_NAMES;
+/**
+ * Lines for easings an engine branch adds before the list is resynced
+ * (FxTool D11: hold / step). Spread in, so they satisfy the record the moment
+ * the sync brings the names, and are unused until then.
+ */
+const UPCOMING_EASING_DESCRIPTIONS = {
+    hold: 'Holds the previous value, then jumps at the next key (a cut, no in-between)',
+    step: 'Same as hold: jumps at the next key',
+};
 /** One line per easing, for tool descriptions and pinepaper_get_available_easings. */
 export const EASING_DESCRIPTIONS = {
+    ...UPCOMING_EASING_DESCRIPTIONS,
     linear: 'Constant speed',
     easeIn: 'Slow start, fast end',
     easeOut: 'Fast start, slow end',
@@ -316,6 +326,8 @@ 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: KeyframeEasingSchema.optional().default('linear'),
+    interpolation: z.literal('hold').optional().describe("'hold': this key holds ITS OWN value until the next key, then jumps (FxTool D11). Refused on a studio without hold keys."),
+    hold: z.boolean().optional().describe("Same as interpolation: 'hold'."),
 });
 // =============================================================================
 // RELATION TYPES
@@ -396,6 +408,10 @@ export const RelationTypeSchema = z.enum([
     'on_event_toggle',
     'on_event_store_set',
     'on_event_store_increment',
+    'on_event_play_sound',
+    'looks_at',
+    'reacts_to',
+    'drag_to_turn',
     // --- Proximity — the pointer entering or leaving an item ---
     'on_enter_set_color',
     'on_enter_set_property',
@@ -724,6 +740,7 @@ export const EventInputSchema = z.object({
     payloadType: z.string().optional().describe("Payload type label (default 'Pulse') — action 'create'"),
     x: z.number().optional().describe('Canvas x for the event marker — action create'),
     y: z.number().optional().describe('Canvas y for the event marker — action create'),
+    at: z.union([z.number().min(0), z.array(z.number().min(0)).min(1)]).optional().describe('create: fire the event ITSELF at these scene times (seconds) — a timed trigger, so on_event_play_sound and every other reaction runs on the timeline and in video exports.'),
     eventId: z.string().optional().describe("Event id to fire — required for action 'pulse'"),
     payload: z.unknown().optional().describe("Optional value forwarded to listeners — action 'pulse'"),
 }).refine((v) => v.action !== 'create' || !!v.name, { message: "action 'create' requires name", path: ['name'] })
@@ -1105,22 +1122,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
 // =============================================================================
@@ -1162,6 +1167,40 @@ export const ItemDataFlagsSchema = z.object({
     isDraggable: z.boolean().optional(),
     isDecorative: z.boolean().optional(),
 });
+/**
+ * Per-item engine setters applied after create / modify (FxTool D20, D11).
+ * Sent through their own engine calls, never as create params: an engine
+ * without them would ignore an unknown param in silence, and the call says so
+ * instead.
+ */
+export const ScreenSpaceSchema = z.boolean()
+    .describe('HUD layer: true keeps the item fixed in the FRAME under camera moves (its x/y, keyframes and relations are then frame coordinates). Exports honour it; the live preview still tilts it; SVG and Lottie ignore it.');
+export const StepTimingSchema = z.union([
+    z.number().int().min(1),
+    z.object({ every: z.number().int().min(1), baseFps: z.number().positive().optional() }).strict(),
+    z.object({ fps: z.number().positive() }).strict(),
+    z.null(),
+]).describe("Animate this item 'on twos' (or threes…): N or {every: N, baseFps?} steps every N frames of a 30 fps base unless baseFps is given; {fps} steps at that rate; null turns it off. A stepped group steps its children. Not stepped: follows, spring_follow, auras, rigging and GPU generators.");
+/** A text item's counter (FxTool D70): a number that counts on the scene clock. */
+export const CounterSchema = z.union([
+    z.object({
+        from: z.number(), to: z.number(),
+        start: z.number().min(0).optional().describe('Seconds into the timeline (default 0).'),
+        duration: z.number().positive().optional().describe('Seconds to count (default 1).'),
+        easing: z.union([z.string(), z.tuple([z.number(), z.number(), z.number(), z.number()])]).optional().describe("Any engine easing (including 'hold' / 'step') or a cubic Bézier [x1, y1, x2, y2]; default linear."),
+        decimals: z.number().int().min(0).max(10).optional().describe('Default: the precision from / to were written with.'),
+        prefix: z.string().optional(), suffix: z.string().optional(),
+        locale: z.string().optional().describe("Number format locale (default 'en-US')."),
+        grouping: z.boolean().optional().describe('Thousands separators (default true).'),
+        padStart: z.number().int().min(1).max(21).optional().describe('Zero-pad to this many digits.'),
+        steps: z.number().int().positive().optional().describe('Count in N jumps instead of smoothly.'),
+        tabular: z.boolean().optional().describe('Fixed-width digits so the width stays steady (default true).'),
+        era: z.boolean().optional().describe("Years with an era: a negative prints as its magnitude + eraNegative ('30,000 BCE'), a positive + eraPositive ('2026 CE'). No year 0: the count crosses 1 BCE → 1 CE. Years group from five digits only ('1274 BCE'); grouping: false turns that off; prefix / suffix still wrap it."),
+        eraNegative: z.string().optional().describe("Era label for negative years (default 'BCE')."),
+        eraPositive: z.string().optional().describe("Era label for positive years (default 'CE'; '' for a bare year; 'AD' works)."),
+    }).strict(),
+    z.null(),
+]).describe("A text that COUNTS on the scene clock: {from, to, start?, duration?, easing?, decimals?, prefix?, suffix?, locale?, grouping?, padStart?, steps?, tabular?}; null removes it. Exact on every exported frame. To shape the count by hand, keyframe the numeric property counterValue instead.");
 export const CreateItemInputSchema = z.object({
     itemType: ItemTypeSchema,
     position: PositionSchema.optional().default({ x: 400, y: 300 }),
@@ -1176,6 +1215,9 @@ export const CreateItemInputSchema = z.object({
     // is read beside position as often as inside properties — and at the top
     // level it was stripped without a word (round 7 retest, 1.63).
     anchor: z.string().optional().describe("Which point position names: 'center' (default), 'top-left', 'top-right', 'bottom-left', 'bottom-right'. Same as properties.anchor."),
+    screenSpace: ScreenSpaceSchema.optional(),
+    stepTiming: StepTimingSchema.optional(),
+    counter: CounterSchema.optional(),
 });
 // Light direction for 3D effects
 export const LightDirectionSchema = z.enum([
@@ -1215,6 +1257,9 @@ export const ModifyItemInputSchema = z.object({
     data: ItemDataFlagsSchema.optional(),
     atTime: z.number().min(0).optional().describe('AUTO-KEY: write these properties as keyframes at this time (seconds) instead of a static edit — eased from the previous value, other keys kept.'),
     easing: z.string().optional().describe('atTime: easing of the segment arriving at the new key (default linear).'),
+    screenSpace: ScreenSpaceSchema.optional(),
+    stepTiming: StepTimingSchema.optional(),
+    counter: CounterSchema.optional(),
 });
 // Delete Item
 export const DeleteItemInputSchema = z.object({
@@ -1441,9 +1486,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 +1569,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 +1786,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 +1815,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 +1887,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,11 +2120,12 @@ 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'),
+    screenSpace: ScreenSpaceSchema.optional().describe('create: keep the item fixed in the frame under camera moves (HUD).'),
+    stepTiming: StepTimingSchema.optional().describe("create: step this item's animation (N, {every, baseFps?} or {fps})."),
+    counter: CounterSchema.optional().describe('create (text): count on the scene clock.'),
     // Modify/Animate/Delete/Keyframe/Mask/Effect target
     itemId: z.string().optional().describe('Target item ID or $N reference'),
     // Group operation fields
@@ -2171,6 +2253,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 +2686,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 +2752,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 +2779,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'),
@@ -2865,6 +2974,8 @@ export const ScenePlaybackInputSchema = z.object({
     defaultDuration: z.number().optional(),
     defaultTransition: z.enum(['none', 'fade', 'zoom-in', 'zoom-out']).optional(),
     transitionDuration: z.number().optional(),
+    cutSound: z.union([z.string().min(1), z.object({ sound: z.string().min(1), gain: z.number().min(0).optional(), offset: z.number().optional() }).strict()]).optional()
+        .describe("create_chain: a sound at every cut — a catalogue name, or {sound, gain?, offset? (seconds, + later / − earlier)}. The scene_cut event also fires at each cut ({from, to, time, index})."),
     enabled: z.boolean().optional(),
     index: z.number().optional(),
 });
@@ -3069,7 +3180,7 @@ export const TransformInputSchema = z.object({
 // `pinepaper_media` / `pinepaper_transform` set the precedent.
 export const BrandKitInputSchema = z.object({
     /** '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']),
+    action: z.enum(['plan', 'apply', 'from_url', 'set', 'get', 'clear']),
     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
@@ -3095,7 +3206,7 @@ export const BrandKitInputSchema = z.object({
     }).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) => !['plan', 'apply', 'set'].includes(v.action) || !!v.kit, { message: 'plan, apply and set 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']),
@@ -3135,7 +3246,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 +3652,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 +3719,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 +3832,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 +3875,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 +3910,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 +3929,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 +3964,177 @@ 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_emitter — the data-driven particle item (FxTool D29). The engine validates the spec and refuses by name. */
+export const EmitterInputSchema = z.object({
+    action: z.enum(['create', 'set']),
+    itemId: z.string().optional().describe('set: the emitter to change.'),
+    spec: z.record(z.string(), z.unknown()).describe('create: the whole spec. set: the keys to change (merged).'),
+}).refine((v) => v.action !== 'set' || !!v.itemId, { message: 'set requires itemId', path: ['itemId'] });
+/** pinepaper_look (D64): restyle an item, a subtree or the whole scene as a named look. */
+export const LookInputSchema = z.object({
+    action: z.enum(['list', 'describe', 'apply', 'remove', 'get', 'grid']),
+    look: z.union([z.string().min(1), z.record(z.string(), z.unknown())]).optional().describe('describe / apply: a look id from list, or a look spec.'),
+    target: z.string().optional().describe("apply / remove / get: an itemId, or 'scene' (default)."),
+    scope: z.enum(['item', 'subtree', 'scene']).optional().describe('apply: how far the look reaches (default: the item for an id, the scene for scene).'),
+    looks: z.array(z.string()).optional().describe('grid: which looks (default every one).'),
+    cols: z.number().int().positive().optional(), cellWidth: z.number().positive().optional(), t: z.number().min(0).optional(),
+})
+    .refine((v) => !['describe', 'apply'].includes(v.action) || v.look !== undefined, { message: 'describe and apply require look', path: ['look'] });
+/** pinepaper_original_character (D66): an ORIGINAL character from a base rig and a declarative variant. */
+export const OriginalCharacterInputSchema = z.object({
+    action: z.enum(['bases', 'describe', 'random', 'create']),
+    base: z.string().optional().describe('person | robot | cat | bird | blob (bases lists them).'),
+    variant: z.record(z.string(), z.unknown()).optional().describe('create: {palette, features, look, seed, name} — legal values from describe.'),
+    seed: z.number().int().optional().describe('random: same (base, seed) → the same variant.'),
+    fixed: z.record(z.string(), z.unknown()).optional().describe('random: traits every member shares (a look, proportions), merged over the random choice.'),
+    at: z.object({ x: z.number(), y: z.number() }).optional().describe('create: x, and y = the FEET.'),
+    height: z.number().positive().optional().describe('create: drawn height px (default 320).'),
+    scale: z.number().positive().optional().describe('create: multiplier of the default height.'),
+    rig: z.boolean().optional().describe('create: build the skeleton (default true).'),
+})
+    .refine((v) => !['random', 'create'].includes(v.action) || !!v.base, { message: 'random and create require base', path: ['base'] })
+    .refine((v) => v.action !== 'random' || v.seed !== undefined, { message: 'random requires seed', path: ['seed'] });
+/** pinepaper_morph_sequence (D73): one element through N states as a morphs_to chain. */
+export const MorphSequenceInputSchema = z.object({
+    itemId: z.string().describe('The element that morphs (it keeps its id through every state).'),
+    states: z.array(z.object({
+        at: z.number().min(0).describe('Seconds: when the morph INTO this state starts.'),
+        duration: z.number().positive().optional().describe('Seconds the morph takes (default 0.8).'),
+        to: z.string().optional().describe('An existing item whose shape this state takes (it is hidden; it is only the shape reference).'),
+        shape: z.object({
+            itemType: z.string(),
+            position: z.object({ x: z.number(), y: z.number() }),
+            properties: z.record(z.string(), z.unknown()).optional(),
+        }).optional().describe('Or describe the state: it is created hidden as the reference.'),
+    }).refine((s) => !!s.to !== !!s.shape, { message: 'each state takes exactly one of to or shape' })).min(1).max(40),
+    easing: z.enum(['linear', 'easeIn', 'easeOut', 'easeInOut']).optional().describe('Morph easing (default easeInOut) — the morph supports these four.'),
+    camera: z.union([z.boolean(), z.object({ fill: z.number().min(0.05).max(1).optional(), easing: z.string().optional() })]).optional()
+        .describe('true: the camera rides every morph on the same timing, framing each state (fill = share of the frame the state fills, default 0.45).'),
+    sound: z.union([z.boolean(), z.string().min(1)]).optional().describe("true: a whoosh at each morph start; or a catalogue sound name."),
+}).superRefine((v, ctx) => {
+    let end = -Infinity;
+    [...v.states].sort((a, b) => a.at - b.at).forEach((s, i) => {
+        if (s.at < end - 1e-6)
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `state at ${s.at} s starts before the previous morph ends at ${end} s`, path: ['states', i, 'at'] });
+        end = s.at + (s.duration ?? 0.8);
+    });
+});
+/** pinepaper_render_hook — per-frame drawing saved as SOURCE (FxTool D29). */
+export const RenderHookInputSchema = z.object({
+    action: z.enum(['register', 'unregister', 'list']),
+    id: z.string().min(1).optional(),
+    source: z.string().min(1).optional().describe('register: JS that evaluates to (ctx, t, info) => {}.'),
+    layer: z.enum(['above', 'below']).optional(),
+    deterministic: z.boolean().optional(),
+    seed: z.number().int().optional(),
+}).refine((v) => v.action === 'list' || !!v.id, { message: 'register / unregister require id', path: ['id'] })
+    .refine((v) => v.action !== 'register' || !!v.source, { message: 'register requires source', path: ['source'] });
+/** pinepaper_choreograph — beat verbs compiled to one squash-and-stretch track (D67). */
+const ChoreoPointSchema = z.union([z.tuple([z.number(), z.number()]), z.object({ x: z.number(), y: z.number() })]);
+const ChoreoEdgeSchema = z.enum(['left', 'right', 'top', 'bottom']);
+export const CHOREO_VERBS = ['pop', 'drop', 'hop', 'bounce', 'roll', 'fly', 'peek', 'shake', 'squash', 'enter', 'exit'];
+export const ChoreographBeatSchema = z.object({
+    at: z.number().min(0).describe('Seconds. Beats run one after another; one that starts before the previous ends is refused.'),
+    verb: z.enum(CHOREO_VERBS),
+    to: ChoreoPointSchema.optional().describe('Where the actor ends up (its centre, canvas px): hop / bounce / roll / fly / drop / enter. roll and fly require it.'),
+    duration: z.number().positive().optional().describe('Seconds for this beat (each verb has a sensible default).'),
+    height: z.number().positive().optional().describe('hop / bounce: jump height px (default 1.2× / 1.5× the actor).'),
+    times: z.number().int().min(1).max(12).optional().describe('bounce: number of bounces (default 3).'),
+    decay: z.number().min(0.1).max(0.95).optional().describe('bounce: each bounce is this fraction of the last (default 0.6).'),
+    arc: z.number().optional().describe('fly: how far above the higher end the path rises, px (default 2× the actor).'),
+    edge: ChoreoEdgeSchema.optional().describe('peek: the frame edge it peeks from (default left). exit: the edge it leaves by (default right).'),
+    from: ChoreoEdgeSchema.optional().describe('enter: the frame edge it comes in from (default left).'),
+    amount: z.number().min(0).max(1).optional().describe('peek: how much of it shows, 0..1 (default 0.5). squash: depth (default 0.25).'),
+    hold: z.number().min(0).optional().describe('peek: seconds it stays out (default 1).'),
+    intensity: z.number().positive().optional().describe('shake: px each way (default 8% of its width).'),
+}).strict().superRefine((b, ctx) => {
+    if ((b.verb === 'roll' || b.verb === 'fly') && !b.to)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: `${b.verb} needs to: [x, y]`, path: ['to'] });
+    if (b.verb === 'exit' && b.to !== undefined)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'exit leaves by an edge: pass edge (left | right | top | bottom), not to', path: ['to'] });
+});
+const ChoreoSoundName = z.union([z.string().min(1), z.literal(false)]);
+export const ChoreographInputSchema = z.object({
+    itemId: z.string().describe('The actor: any item — a shape, a group, an imported SVG character, a photo cut-out.'),
+    beats: z.array(ChoreographBeatSchema).min(1).max(60),
+    sound: z.union([z.boolean(), z.object({
+            pop: ChoreoSoundName.optional(), whoosh: ChoreoSoundName.optional(),
+            contact: ChoreoSoundName.optional(), shake: ChoreoSoundName.optional(),
+            gain: z.number().min(0).max(1).optional(),
+        }).strict()]).optional().describe("true: a sound on every pop, launch, landing and shake, its loudness following the motion (a bounce's contacts get quieter as it decays). An object picks the sound per moment by catalogue name (an SFX — beep, pop, wind, whoosh, zap — or a drum — kick, snare, tom, hat, clap — or one you defined), false to leave one silent, and gain 0..1. Placed on the timeline, baked into video and render_soundtrack."),
+});
+/**
+ * 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 +4323,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 +4436,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."),
@@ -4145,6 +4483,7 @@ export const StoryInputSchema = z.object({
     spec: z.record(z.string(), z.unknown()).optional().describe('apply_spec: the story spec — usually one from `distill`, edited.'),
     images: z.array(z.union([z.string(), z.record(z.string(), z.unknown())])).optional().describe('plan_book: the images to lay out, as ids or specs.'),
     options: z.record(z.string(), z.unknown()).optional().describe('Assembly or layout options, passed through.'),
+    nav: z.enum(['panels', 'scenes']).optional().describe("from_text / apply_spec: 'scenes' is the VIDEO form — one scene per part on a scene chain, cut in time (export it as MP4); 'panels' (default) the WIDGET form — tabs a viewer clicks through (export_widget_html)."),
 })
     .refine((v) => !['distill', 'from_text'].includes(v.action) || !!v.text, { message: 'this action requires text', path: ['text'] })
     .refine((v) => v.action !== 'apply_spec' || !!v.spec, { message: 'apply_spec requires spec', path: ['spec'] })
@@ -4164,7 +4503,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 +4599,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 +4612,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 +4811,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'] })