@pinepaper.studio/mcp-server 1.6.17 → 1.6.18

package/dist/types/code-generator.js

@@ -5,6 +5,7 @@
  * This code is designed to run in the browser context where window.PinePaper is available.
  */
 import { normalizeSvgSize } from '../utils/svg-size.js';
+import { WORLD3D_COLOR_PATHS } from '../tools/engine-lists.js';
 import { REQUIRED_ENGINE_METHODS, OPTIONAL_ENGINE_METHODS } from '../tools/engine-methods.js';
 import { ACCEPTED_CREATE_PARAMS, NORMALIZE_PARAM_READS, MODIFY_CHANGE_READS } from '../tools/shape-params.js';
 import { generateP5DrawCode } from '../tools/p5-compat/p5-helpers.js';
@@ -24,7 +25,7 @@ GlobeEnableInputSchema, GlobeRotateToInputSchema, GlobeSpinInputSchema, WorldTou
 // Custom relation/code types
 RegisterCustomRelationInputSchema, ExecuteCustomCodeInputSchema, 
 // Mask types
-ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, FlipInputSchema, QueryCapabilitiesInputSchema, } from './schemas.js';
+ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, FlipInputSchema, QueryCapabilitiesInputSchema, KEYFRAME_EASINGS, EASING_DESCRIPTIONS, } from './schemas.js';
 import { OntologyCompiler } from '../ontology/ontology-compiler.js';
 // =============================================================================
 // HELPER FUNCTIONS
@@ -2213,6 +2214,39 @@ function world3dColor(value) {
         return value;
     return [0, 2, 4].map((i) => parseInt(full.slice(i, i + 2), 16) / 255);
 }
+/**
+ * The world spec's colour fields: GENERATED from FxTool WORLD_SCHEMA's kind
+ * 'color' entries (scripts/sync-engine-lists.mjs). None of them is named
+ * `color`, so world3dColors never touched them and a hex `env.zenith` reached
+ * the engine as a string, where the validator refused it.
+ */
+export { WORLD3D_COLOR_PATHS };
+/** A hex colour to [r, g, b] 0..1; anything else unchanged (arrays too: light colours may exceed 1). */
+export function world3dHex(value) {
+    return typeof value === 'string' ? world3dColor(value) : value;
+}
+/** Convert hex strings at the world spec's colour paths (configure / create). */
+export function world3dSpecColors(spec) {
+    if (!spec || typeof spec !== 'object' || Array.isArray(spec))
+        return spec;
+    const out = JSON.parse(JSON.stringify(spec));
+    for (const path of WORLD3D_COLOR_PATHS) {
+        const [group, key] = path.split('.');
+        const g = out[group];
+        if (g && typeof g === 'object' && key in g)
+            g[key] = world3dHex(g[key]);
+    }
+    return out;
+}
+/** A light or material spec with hex colours (color, emissive, sheenColor) converted; an array is left exactly as given. */
+function world3dHexColor(spec) {
+    const out = { ...(spec ?? {}) };
+    for (const key of ['color', 'emissive', 'sheenColor']) {
+        if (typeof out[key] === 'string')
+            out[key] = world3dColor(out[key]);
+    }
+    return out;
+}
 /** Recursively convert every `color` field in a world3d payload. */
 function world3dColors(value) {
     if (Array.isArray(value))
@@ -2225,6 +2259,60 @@ function world3dColors(value) {
     }
     return out;
 }
+/** At most this many tiles in one contact sheet: past it, the tiles are too small to judge. */
+export const SHEET_MAX_TILES = 48;
+/**
+ * The times a contact sheet captures, and a label for each. Pure, so the
+ * modes are testable without a browser. Explicit `times` win; otherwise
+ * every / strip / loopSeam. Rounded to the millisecond, clamped at 0.
+ */
+export function sheetTimes(times, sheet) {
+    const r = (t) => Math.max(0, Math.round(t * 1000) / 1000);
+    const fmt = (t) => `${t.toFixed(2)}s`;
+    let out = [];
+    let labels = null;
+    if (times && times.length) {
+        out = times.map(r);
+    }
+    else if (sheet.strip) {
+        const { at, count, step } = sheet.strip;
+        const first = at - Math.floor(count / 2) * step;
+        out = Array.from({ length: count }, (_, i) => r(first + i * step));
+    }
+    else if (sheet.loopSeam && sheet.duration) {
+        // The frame BEFORE the loop wraps, then the first: a jump between them is the stutter.
+        out = [r(sheet.duration - 1 / 30), 0];
+        labels = [`end ${fmt(out[0])}`, 'start 0.00s'];
+    }
+    else if (sheet.every && sheet.duration) {
+        for (let t = 0; t < sheet.duration - 1e-9 && out.length < SHEET_MAX_TILES; t += sheet.every)
+            out.push(r(t));
+    }
+    out = out.slice(0, SHEET_MAX_TILES);
+    return { times: out, labels: labels ?? out.map(fmt) };
+}
+/**
+ * The critique an agent applies to a contact sheet. One scale, the same every
+ * time, so two passes over one film can be compared.
+ */
+export const SHEET_RUBRIC = {
+    scale: 'Score each 1-10. Under 7 on any line is a fix before export.',
+    criteria: [
+        'hook: does something worth watching happen in the first 2 s?',
+        'phone readability: at 360 px wide, can every word be read?',
+        'motion quality: do moves ease in and out, with nothing jumping or sliding at constant speed?',
+        'variety: does something change every 2-4 s, with no stretch that looks the same?',
+        'composition: is there a clear subject, with nothing crammed against an edge?',
+        'brand accuracy: are the colours, fonts and logo the brand\'s own?',
+        'sound sync: do cuts and hits land on the beat (check against pinepaper_beat_cuts)?',
+    ],
+    checklist: [
+        'text overlapping text or a subject',
+        'dead beats: adjacent tiles that are the same picture',
+        'labels or logos cut off in a corner',
+        'a jump between the last and first frame of a loop (loopSeam)',
+    ],
+};
 export class PinePaperCodeGenerator {
     /**
      * Generate code for creating an item
@@ -3997,7 +4085,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     }
     generateAgentExport(input) {
         const validated = AgentExportInputSchema.parse(input);
-        const { platform, format, quality, framing, duration, estimateOnly, scale, fps, pdf: pdfOpts, region, time: stillTime, maxBytes, loop: gifLoop, broadcast, broadcastHeadroom, bitrate, minBitrate, bitrateMode, transparent, alphaQuantizer, deterministic, ad: adOpts, frames } = validated;
+        const { platform, format, quality, framing, duration, estimateOnly, scale, fps, pdf: pdfOpts, region, time: stillTime, maxBytes, loop: gifLoop, broadcast, broadcastHeadroom, bitrate, minBitrate, bitrateMode, transparent, alphaQuantizer, deterministic, motionBlur, ad: adOpts, frames } = validated;
         // Encoder options (FxTool 16719759); the schema keeps them to mp4 / webm.
         const videoEncodeOpts = {};
         if (broadcast)
@@ -4019,6 +4107,10 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
         // the only bytes that varied, and this pins them.
         if (deterministic)
             videoEncodeOpts.deterministic = true;
+        // Motion blur (FxTool #55): the engine forwards it on every mp4/webm path
+        // (quickExport, the agent paths, the export store, videoExporter.export).
+        if (motionBlur)
+            videoEncodeOpts.motionBlur = motionBlur;
         // A transparent WebM (FxTool 1833b397) rides the store route too.
         const webmAlpha = format === 'webm' && transparent === true;
         if (webmAlpha) {
@@ -4308,7 +4400,10 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
       const bg = app.canvasEl && app.canvasEl.style && app.canvasEl.style.backgroundColor;
       const hasColor = !!bg && !/^(transparent|rgba\\([^)]*,\\s*0\\))$/i.test(bg);
       const hasBgItems = !!(app.patternGroup && app.patternGroup.children && app.patternGroup.children.length);
-      if (hasColor || hasBgItems) return [];
+      // A 3D world under the canvas IS the background: since FxTool #50
+      // (747315e3) jpg/webp stills composite it, so nothing turns white/black.
+      const hasWorld = !!app._world3d;
+      if (hasColor || hasBgItems || hasWorld) return [];
       return [{ code: 'alpha_dropped', message: fmt === 'apng'
         ? 'apng with transparent: false and no background colour: the frames are filled BLACK. Set a background colour, or drop transparent: false to keep the alpha.'
         : fmt === 'jpg'
@@ -4365,7 +4460,9 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
       fps: settings.fps,
       quality,
       width: dimensions.width,
-      height: dimensions.height,
+      height: dimensions.height,${motionBlur ? `
+      // The estimate reports renders (frames x subframes) and renderCost.
+      motionBlur: ${JSON.stringify(motionBlur)},` : ''}
     });
     return {
       success: true,
@@ -5230,6 +5327,17 @@ ${Object.keys(videoEncodeOpts).length ? `  if (result && result.success) {
       if (result.fidelity.note) delete result.fidelity.note;
     }
   }
+` : ''}${motionBlur ? `  // What the exporter actually did with motionBlur (FxTool #55 records it as
+  // lastMotionBlur, with renders = frames x subframes). A studio that predates
+  // it ignores the option silently, so that is said by name.
+  if (result && result.success) {
+    const __mb = __vx && __vx.lastMotionBlur;
+    if (__mb) result.motionBlur = __mb;
+    else {
+      result.fidelity = result.fidelity || { warnings: [] };
+      result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'motion_blur_not_applied', message: 'motionBlur was asked for, but this studio did not report applying it: it predates motion blur (FxTool #55), so the video has none.' }]);
+    }
+  }
 ` : ''}  const __ar = __vx && __vx.lastAudioReport;
   if (result && result.success && __ar && typeof __ar === 'object') {
     result.audio = __ar;
@@ -6861,19 +6969,25 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
 `.trim();
     }
     generateGetAvailableEasings() {
+        // The engine's own list wins: listAnimatableProperties().easings is its
+        // EASING_NAMES, read from the easing table itself. The static list is the
+        // fallback for studios that predate it (fixture-pinned, easing-parity test).
         return `
 // Get available easing functions
 (function() {
+  const fallback = ${JSON.stringify(KEYFRAME_EASINGS)};
+  const descriptions = ${JSON.stringify(EASING_DESCRIPTIONS)};
+  let live = null;
+  try {
+    const r = typeof app !== 'undefined' && app && typeof app.listAnimatableProperties === 'function'
+      ? app.listAnimatableProperties() : null;
+    if (r && Array.isArray(r.easings) && r.easings.length) live = r.easings;
+  } catch (e) { live = null; }
   return {
-    easings: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'bounce', 'elastic'],
-    descriptions: {
-      linear: 'Constant speed',
-      easeIn: 'Slow start, fast end',
-      easeOut: 'Fast start, slow end',
-      easeInOut: 'Slow start and end',
-      bounce: 'Bouncing effect at end',
-      elastic: 'Spring-like overshoot'
-    }
+    easings: live || fallback,
+    source: live ? 'engine' : 'mcp-server fallback list',
+    descriptions,
+    exportNote: 'Every easing renders exactly in video, GIF and APNG. Lottie and CSS get the closest single Bezier: springPlayful loses its wobble, and the in-out quart/quint/expo/circ curves are within 2-4%. SMIL is exact for springs and those four.'
   };
 })();
 `.trim();
@@ -9704,7 +9818,7 @@ ${checks.includes('contrast') ? `  // SAMPLED OVER TIME (round 12, 12.9): text i
 })();`.trim();
     }
     generateCaptureFrames(input) {
-        const timesJson = JSON.stringify(input.times);
+        const timesJson = JSON.stringify(input.times ?? []);
         const seed = input.seed !== undefined ? input.seed : 0;
         const includeDataUrls = !!input.includeDataUrls;
         return `
@@ -9763,6 +9877,69 @@ ${checks.includes('contrast') ? `  // SAMPLED OVER TIME (round 12, 12.9): text i
     ...(__firstSeek ? { firstSeek: __firstSeek } : {}),
     ...(__firstSeek && __firstSeek.timedOut > 0 ? { videoWarning: 'the video seek for the first frame timed out: its video may show an earlier picture. Retry after the clip has loaded.' } : {}),
     frames: frames };
+})();`.trim();
+    }
+    /**
+     * A contact sheet (G3): capture at the planned times and tile them into one
+     * image in the page. On a studio with sized capture (FxTool #42:
+     * captureFramesAt(times, { width, format })) the engine renders each frame
+     * small; on an older one the full frame is scaled while tiling.
+     */
+    generateCaptureSheet(input) {
+        const sheet = input.sheet;
+        const { times, labels } = sheetTimes(input.times, sheet);
+        const n = times.length;
+        const columns = sheet.columns ?? Math.min(6, Math.max(1, Math.ceil(Math.sqrt(n))));
+        const mime = sheet.format === 'png' ? 'image/png' : 'image/jpeg';
+        const S = (v) => JSON.stringify(v);
+        return `
+// Contact sheet of ${n} frame(s)
+(async function() {
+  if (typeof app.captureFramesAt !== 'function') {
+    return { success: false, error: 'app.captureFramesAt unavailable — update FxTool to a build with the deterministic capture entrypoint' };
+  }
+  const times = ${S(times)};
+  const labels = ${S(labels)};
+  const tileW = ${sheet.tileWidth};
+  const columns = ${columns};
+  const sized = typeof app._frameCapture === 'function';
+  const cap = typeof app.captureFramesAtAsync === 'function' ? app.captureFramesAtAsync.bind(app) : app.captureFramesAt.bind(app);
+  const urls = sized
+    ? await cap(times, { seed: ${input.seed ?? 0}, width: tileW, format: 'png' })
+    : await cap(times, { seed: ${input.seed ?? 0}, capture: function(c) {
+        return typeof app.captureFrameDataURL === 'function' ? app.captureFrameDataURL() : (c && c.toDataURL ? c.toDataURL() : '');
+      } });
+  const imgs = await Promise.all(urls.map(function(u) {
+    return new Promise(function(res) { const im = new Image(); im.onload = function() { res(im); }; im.onerror = function() { res(null); }; im.src = u; });
+  }));
+  const first = imgs.find(function(im) { return im && im.naturalWidth; });
+  if (!first) return { success: false, error: 'no frame could be captured' };
+  const tileH = Math.max(1, Math.round(tileW * first.naturalHeight / first.naturalWidth));
+  const rows = Math.ceil(imgs.length / columns);
+  const gap = 4;
+  const cv = document.createElement('canvas');
+  cv.width = columns * tileW + (columns + 1) * gap;
+  cv.height = rows * tileH + (rows + 1) * gap;
+  const g = cv.getContext('2d');
+  g.fillStyle = '#202020'; g.fillRect(0, 0, cv.width, cv.height);
+  imgs.forEach(function(im, i) {
+    const x = gap + (i % columns) * (tileW + gap);
+    const y = gap + Math.floor(i / columns) * (tileH + gap);
+    if (im) g.drawImage(im, x, y, tileW, tileH);
+    else { g.fillStyle = '#802020'; g.fillRect(x, y, tileW, tileH); }
+    if (${sheet.labels ? 'true' : 'false'}) {
+      const text = labels[i];
+      g.font = '600 13px system-ui, sans-serif';
+      const w = g.measureText(text).width + 10;
+      g.fillStyle = 'rgba(0,0,0,0.65)'; g.fillRect(x + 4, y + 4, w, 20);
+      g.fillStyle = '#fff'; g.fillText(text, x + 9, y + 19);
+    }
+  });
+  const dataUrl = cv.toDataURL(${S(mime)}${sheet.format === 'png' ? '' : ', 0.82'});
+  return { success: true, dataUrl: dataUrl, tiles: imgs.length, columns: columns, rows: rows,
+    width: cv.width, height: cv.height, tileWidth: tileW, times: times,
+    missing: imgs.filter(function(im) { return !im; }).length,
+    sizedCapture: sized };
 })();`.trim();
     }
     /**
@@ -10142,6 +10319,45 @@ ${guard}
     // The facade throws on a missing raster/matte rather than returning {ok:false}.
     return { success: false, error: e && e.message ? e.message : String(e) };
   }
+})();`.trim();
+            }
+            case 'analyze_reference': {
+                const S = (v) => JSON.stringify(v);
+                return `
+// Measure a reference video's FORMAT: cuts, shot lengths, colours, pacing, beat
+(async function() {
+  if (typeof app.analyzeReferenceVideo !== 'function') { return { success: false, error: 'app.analyzeReferenceVideo unavailable — update FxTool' }; }
+  const r = await app.analyzeReferenceVideo(${S(input.id)}, { thumbnails: ${input.thumbnails ? 'true' : 'false'} });
+  if (!r || !r.ok) { return { success: false, error: (r && r.error) || 'the reference could not be analysed' }; }
+  // Kept in the page for remake_from_reference, so the analysis does not have
+  // to travel back through the agent.
+  window.__ppLastReference = { analysis: r, id: ${S(input.id)} };
+  const shots = Array.isArray(r.shots) ? r.shots : [];
+  return { success: true, referenceId: ${S(input.id)}, duration: r.duration, aspect: r.aspect, width: r.width, height: r.height,
+    cuts: r.cuts, shots: shots, pacing: r.pacing, audio: r.audio, card: r.card,
+    ...(r.truncated ? { truncated: true } : {}),
+    next: 'remake_from_reference with texts: your own words, ' + shots.length + ' (one per shot). Nothing of the footage, its words or its sound is copied.' };
+})();`.trim();
+            }
+            case 'remake_from_reference': {
+                const S = (v) => JSON.stringify(v);
+                const opts = {
+                    texts: input.texts ?? [],
+                    ...(input.duration !== undefined ? { duration: input.duration } : {}),
+                    ...(input.clear !== undefined ? { clear: input.clear } : {}),
+                };
+                return `
+// Build a new piece on the analysed reference's structure, in your own words
+(async function() {
+  if (typeof app.remakeFromReference !== 'function') { return { success: false, error: 'app.remakeFromReference unavailable — update FxTool' }; }
+  const last = window.__ppLastReference;
+  if (!last || !last.analysis) { return { success: false, error: 'no analysed reference in this session: call pinepaper_media analyze_reference first' }; }
+  // reference: the analysed clip stays in the project MUTED; without it the
+  // reference's own sound is exported under the new cards.
+  const r = await app.remakeFromReference(last.analysis, Object.assign(${S(opts)}, { reference: last.id }));
+  return r && r.ok
+    ? { success: true, action: 'remake_from_reference', duration: r.duration, shots: r.shots, items: r.items, referenceMuted: last.id }
+    : { success: false, error: (r && r.error) || 'the remake could not be built' };
 })();`.trim();
             }
             case 'stop_live_matte': {
@@ -10313,6 +10529,21 @@ ${guard}
         const S = (v) => JSON.stringify(v);
         const wrap = (comment, body) => `\n// ${comment}\n(function() {\n${body}\n})();`.trim();
         switch (input.action) {
+            case 'apply':
+                // One engine entry point (FxTool #54): app.applyMedium dispatches to the
+                // medium's own method (DesignMedia MEDIA[key].apply) and refuses an absent
+                // or brush-only medium with the reason. The Paper item it returns is not
+                // passed back (it cannot cross the bridge); its id is.
+                return `
+// Medium: apply ${input.medium}
+(async function() {
+  if (typeof app.applyMedium !== 'function') { return { success: false, error: 'app.applyMedium unavailable — update FxTool' }; }
+  const r = await app.applyMedium(${S(input.itemId)}, ${S(input.medium)}, ${S(input.options ?? {})});
+  if (!r || r.ok === false) {
+    return { success: false, error: (r && (r.error || r.reason)) || 'the medium could not be applied', medium: ${S(input.medium)}, ...(r && r.fidelity ? { fidelity: r.fidelity } : {}) };
+  }
+  return { success: true, action: 'apply', medium: r.medium || ${S(input.medium)}, fidelity: r.fidelity, itemId: r.id, ...(r.note ? { note: r.note } : {}) };
+})();`.trim();
             case 'list_media':
                 return wrap('Medium: list', `  if (typeof app.listDesignMedia !== 'function') { return { success: false, error: 'medium axis unavailable — update FxTool' }; }
   const media = app.listDesignMedia();
@@ -10629,12 +10860,15 @@ ${guard}
 // World3D: create — terrain, sky, shadows, walkable character, under the Paper canvas
 (async function() {
   if (typeof app.createWorld3D !== 'function') { return { success: false, error: 'app.createWorld3D unavailable — update FxTool to a world3d-capable build' }; }
-  await app.createWorld3D(${S(world3dColors(input.spec ?? 'forest'))}, ${opts});
+  await app.createWorld3D(${S(world3dSpecColors(world3dColors(input.spec ?? 'forest')))}, ${opts});
   // describe() is the world's own parameter schema — return the preset list +
   // top-level keys so the agent knows what configure can touch, without the
   // full multi-KB schema on every create.
   const d = typeof app.describeWorld3D === 'function' ? await app.describeWorld3D() : null;
-  return { success: true, action: 'create', spec: ${S(input.spec ?? 'forest')}, configurableKeys: d ? Object.keys(d.params || d) : [] };
+  // params is WORLD_SCHEMA: an ARRAY of {path, kind, doc}. Object.keys on it
+  // returned "0", "1", "2"… — the indexes, not a single usable key.
+  const keys = !d ? [] : Array.isArray(d.params) ? d.params.map(function (e) { return e && e.path; }).filter(Boolean) : Object.keys(d.params || d);
+  return { success: true, action: 'create', spec: ${S(input.spec ?? 'forest')}, configurableKeys: keys };
 })();`.trim();
             }
             case 'describe':
@@ -10650,9 +10884,9 @@ ${guard}
 (function() {
   if (typeof app.configureWorld3D !== 'function') { return { success: false, error: 'app.configureWorld3D unavailable — update FxTool' }; }
 ${needWorld}
-  const r = app.configureWorld3D(${S(world3dColors(input.patch))});
+  const r = app.configureWorld3D(${S(world3dSpecColors(world3dColors(input.patch)))});
   // The validator names the right key on a wrong one — forward it verbatim.
-  return r && r.ok ? { success: true, action: 'configure' } : { success: false, error: (r && r.error) || 'configure failed' };
+  return r && r.ok ? { success: true, action: 'configure' } : { success: false, error: (r && (r.error || (Array.isArray(r.errors) && r.errors.length ? r.errors.join('; ') : '') || r.reason)) || 'configure failed' };
 })();`.trim();
             case 'add_actor': {
                 const actor = S({
@@ -10765,7 +10999,7 @@ ${needWorld}
   // @engine-methods extrudeToMesh latheToMesh importOBJToWorld importGLTFToWorld
   if (typeof app.${fn} !== 'function') { return { success: false, error: 'app.${fn} unavailable — update FxTool to a world3d-capable build' }; }
   const r = await app.${fn}(${S(input.pathId)}, ${S(mesh)});
-  if (!r || r.ok === false) { return { success: false, error: (r && r.reason) || 'the world refused the mesh' }; }
+  if (!r || r.ok === false) { return { success: false, error: (r && (r.error || (Array.isArray(r.errors) && r.errors.length ? r.errors.join('; ') : '') || r.reason)) || 'the world refused the mesh' }; }
   return { success: true, meshId: r.id, op: ${S(input.action === 'extrude_path' ? 'extrude' : 'lathe')}, sourceId: ${S(input.pathId)} };
 })();`.trim();
             }
@@ -10792,8 +11026,8 @@ ${needWorld}
 (function() {
   if (typeof app.addWorldLight !== 'function') { return { success: false, error: 'app.addWorldLight unavailable — update FxTool' }; }
 ${needWorld}
-  const r = app.addWorldLight(${S(input.light ?? {})});
-  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'the world refused the light' }; }
+  const r = app.addWorldLight(${S(world3dHexColor(input.light))});
+  if (!r || r.ok === false) { return { success: false, error: (r && (r.error || (Array.isArray(r.errors) && r.errors.length ? r.errors.join('; ') : '') || r.reason)) || 'the world refused the light' }; }
   return { success: true, lightId: r.id, light: r.light };
 })();`.trim();
             case 'set_light':
@@ -10801,7 +11035,7 @@ ${needWorld}
 // World3D: edit a light in place
 (function() {
   if (typeof app.setWorldLight !== 'function') { return { success: false, error: 'app.setWorldLight unavailable — update FxTool' }; }
-  return { success: !!app.setWorldLight(${S(input.lightId)}, ${S(input.light ?? {})}) };
+  return { success: !!app.setWorldLight(${S(input.lightId)}, ${S(world3dHexColor(input.light))}) };
 })();`.trim();
             case 'remove_light':
                 return `
@@ -10824,8 +11058,8 @@ ${needWorld}
 (function() {
   if (typeof app.addWorldMaterial !== 'function') { return { success: false, error: 'app.addWorldMaterial unavailable — update FxTool' }; }
 ${needWorld}
-  const r = app.addWorldMaterial(${S(input.material ?? {})});
-  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'the world refused the material' }; }
+  const r = app.addWorldMaterial(${S(world3dHexColor(input.material))});
+  if (!r || r.ok === false) { return { success: false, error: (r && (r.error || (Array.isArray(r.errors) && r.errors.length ? r.errors.join('; ') : '') || r.reason)) || 'the world refused the material' }; }
   return { success: true, materialId: r.id, material: r.material };
 })();`.trim();
             case 'set_material':
@@ -10833,7 +11067,7 @@ ${needWorld}
 // World3D: patch a material — every object referencing it changes next frame
 (function() {
   if (typeof app.setWorldMaterial !== 'function') { return { success: false, error: 'app.setWorldMaterial unavailable — update FxTool' }; }
-  return { success: !!app.setWorldMaterial(${S(input.materialId)}, ${S(input.material ?? {})}) };
+  return { success: !!app.setWorldMaterial(${S(input.materialId)}, ${S(world3dHexColor(input.material))}) };
 })();`.trim();
             case 'remove_material':
                 return `
@@ -10892,7 +11126,7 @@ ${needWorld}
 (function() {
   if (typeof app.setWorldNavTarget !== 'function') { return { success: false, error: 'app.setWorldNavTarget unavailable — update FxTool' }; }
   const r = app.setWorldNavTarget(${S(input.navTarget)});
-  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'the nav target was refused' }; }
+  if (!r || r.ok === false) { return { success: false, error: (r && (r.error || (Array.isArray(r.errors) && r.errors.length ? r.errors.join('; ') : '') || r.reason)) || 'the nav target was refused' }; }
   return { success: true, navTarget: ${S(input.navTarget)} };
 })();`.trim();
             case 'get_nav_target':