@pinepaper.studio/mcp-server 1.6.26 → 1.6.28

package/dist/types/code-generator.js

@@ -7,11 +7,18 @@
 import { compileChoreography } from '../tools/choreograph.js';
 import { compileBatchTimelines, emitTimelineOpBody } from '../tools/timeline.js';
 import { normalizeSvgSize } from '../utils/svg-size.js';
-import { WORLD3D_COLOR_PATHS, PATTERN_KINDS } from '../tools/engine-lists.js';
+import { WORLD3D_COLOR_PATHS, PATTERN_KINDS, EXPRESSION_FUNCTION_ARITY, EXPRESSION_CONSTANTS, EXPRESSION_REJECTED, RELATION_PARAM_KEYS } from '../tools/engine-lists.js';
+import { expressionGrammarText } from '../tools/expression-grammar.js';
 import { REQUIRED_ENGINE_METHODS, OPTIONAL_ENGINE_METHODS } from '../tools/engine-methods.js';
 import { NORMALIZE_PARAM_READS, MODIFY_CHANGE_READS } from '../tools/shape-params.js';
 import { CREATE_KNOWN_KEYS } from '../tools/create-known-keys.js';
 import { jsLiteral } from '../utils/js-literal.js';
+/** A value spliced into a generated `//` comment, on one line: a line break in caller text would end the comment and run the rest as code. */
+/** How many relations pinepaper_lint_scene lists back; past it the result says how many there are. */
+const RELATIONS_READBACK_CAP = 200;
+function oneLine(v) {
+    return String(v).replace(/[\r\n\u2028\u2029]+/g, ' ');
+}
 import { generateP5DrawCode } from '../tools/p5-compat/p5-helpers.js';
 import { expandBatchMacros } from '../tools/batch-macros.js';
 import { CreateItemInputSchema, ScreenSpaceSchema, StepTimingSchema, CounterSchema, ImportMotionCaptureInputSchema, ModifyItemInputSchema, AddRelationInputSchema, AnimateItemInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, CreateSceneInputSchema, 
@@ -78,7 +85,7 @@ function normalizeGradientSpec(v, key) {
  */
 function generateGradientCode(gradient, itemVarName, position, propertyName = 'fillColor') {
     const { type, stops, origin, destination } = gradient;
-    const stopsCode = stops.map(s => `['${s.color}', ${s.offset}]`).join(', ');
+    const stopsCode = stops.map(s => `[${jsLiteral(s.color)}, ${s.offset}]`).join(', ');
     if (type === 'radial') {
         // A RADIAL CORE BELONGS ON THE ITEM, NOT ON THE NUMBER ASKED FOR (17
         // RADIALOFFSET). The origin was the REQUESTED position and the radius a
@@ -126,7 +133,7 @@ ${itemVarName}.${propertyName} = {
 function generateShadowCode(itemVarName, shadowColor, shadowBlur, shadowOffset) {
     const lines = [];
     if (shadowColor) {
-        lines.push(`${itemVarName}.shadowColor = '${shadowColor}';`);
+        lines.push(`${itemVarName}.shadowColor = ${jsLiteral(shadowColor)};`);
     }
     if (shadowBlur !== undefined) {
         lines.push(`${itemVarName}.shadowBlur = ${shadowBlur};`);
@@ -140,7 +147,7 @@ function generateShadowCode(itemVarName, shadowColor, shadowBlur, shadowOffset)
  * Generate blend mode code for an item
  */
 function generateBlendModeCode(itemVarName, blendMode) {
-    return `${itemVarName}.blendMode = '${blendMode}';`;
+    return `${itemVarName}.blendMode = ${jsLiteral(blendMode)};`;
 }
 // =============================================================================
 // CODE TEMPLATES
@@ -155,7 +162,7 @@ function generateCreateItemCode(itemType, position, properties, dataFlags, posit
     // break those later calls: refused here, by name, before anything is made.
     if (typeof properties.id === 'string' && UNSAFE_ID_CHARS.test(properties.id)) {
         return `
-// Create ${itemType} — refused: an id later calls could not address
+// Create ${oneLine(itemType)} — refused: an id later calls could not address
 ({ success: false, error: ${jsLiteral(`properties.id ${JSON.stringify(properties.id)} has a quote, backslash or line break, so later calls could not address the item. Nothing was made. Use letters, digits, spaces, - and _ (e.g. "bobs-hat").`)} });`.trim();
     }
     // Colour objects are gradient specs: normalised, or refused by name.
@@ -165,7 +172,7 @@ function generateCreateItemCode(itemType, position, properties, dataFlags, posit
             const g = normalizeGradientSpec(v, key);
             if ('error' in g) {
                 return `
-// Create ${itemType} — refused: an unreadable gradient would draw nothing
+// Create ${oneLine(itemType)} — refused: an unreadable gradient would draw nothing
 ({ success: false, error: ${JSON.stringify(g.error)} });`.trim();
             }
             properties = { ...properties, [key]: g.gradient };
@@ -274,7 +281,7 @@ function generateCreateItemCode(itemType, position, properties, dataFlags, posit
         if (params.opacity != null)
             plate.opacity = params.opacity;
         return `
-// ${itemType} — a render-time surface: a plate tagged with what to draw over it.
+// ${oneLine(itemType)} — a render-time surface: a plate tagged with what to draw over it.
 const item = app.create('rectangle', ${JSON.stringify(plate, null, 2)});
 if (item && item.data) { item.data.renderAs = ${JSON.stringify(itemType)}; item.data.renderParams = ${JSON.stringify(params)}; }
 // The snippet's value is its last statement's, which was the assignment above:
@@ -284,7 +291,7 @@ if (item && item.data) { item.data.renderAs = ${JSON.stringify(itemType)}; item.
 // and its value is lost.
 ((item && item.data)
   ? { itemId: item.data.registryId, type: ${JSON.stringify(itemType)}, position: { x: ${position.x}, y: ${position.y} } }
-  : { success: false, error: 'the plate for this ${itemType} was not created.' });`;
+  : { success: false, error: 'the plate for this ' + ${jsLiteral(itemType)} + ' was not created.' });`;
     }
     // AN UNKNOWN ANCHOR IS INVISIBLE OVER MCP.
     //
@@ -299,7 +306,7 @@ if (item && item.data) { item.data.renderAs = ${JSON.stringify(itemType)}; item.
         const normalized = String(anchorGiven).toLowerCase().replace(/[\s_]+/g, '-');
         if (!ANCHORS.includes(normalized)) {
             return `
-// Create ${itemType} — refused, rather than silently centred
+// Create ${oneLine(itemType)} — refused, rather than silently centred
 ({ success: false, error: ${JSON.stringify(`anchor ${JSON.stringify(String(anchorGiven))} is not one of ${ANCHORS.slice(0, 5).join(', ')}. `
                 + 'The engine would leave x/y as the CENTRE and say so only in a console this tool cannot read, '
                 + 'so the item would land half its own size away with nothing to explain it.')} });`.trim();
@@ -331,8 +338,8 @@ if (item && item.data) { item.data.renderAs = ${JSON.stringify(itemType)}; item.
         : !CREATE_KNOWN_KEYS.has(k) || textOnly(k));
     // Build the code
     let code = `
-// Create ${itemType} item
-const item = app.create('${itemType}', ${JSON.stringify(params, null, 2)});`;
+// Create ${oneLine(itemType)} item
+const item = app.create(${jsLiteral(itemType)}, ${JSON.stringify(params, null, 2)});`;
     // Add gradient support for colors
     if (color && isGradient(color)) {
         code += generateGradientCode(color, 'item', position, 'fillColor');
@@ -413,7 +420,7 @@ const item = app.create('${itemType}', ${JSON.stringify(params, null, 2)});`;
             opts.countdownTarget = countdownTarget;
         if (countdownEndText)
             opts.countdownEndText = countdownEndText;
-        code += `\nif (app.setDynamicContent) app.setDynamicContent(item, '${contentType}', ${JSON.stringify(opts)});`;
+        code += `\nif (app.setDynamicContent) app.setDynamicContent(item, ${jsLiteral(contentType)}, ${JSON.stringify(opts)});`;
     }
     const loadsFont = itemType === 'text' && typeof properties.fontFamily === 'string' && properties.fontFamily.trim() !== '';
     // A LINE WITH `from` IS DRAWN WHERE from AND to SAY (issue #29 O8). They are
@@ -435,7 +442,7 @@ const itemId = item.data.registryId;
 app.historyManager.saveState();
 
 // Return item info
-({ itemId, type: '${itemType}'${outlineOnly ? `, fill: ${JSON.stringify(OUTLINE_NOTE)}` : ''}${textFit ? ', textFit: __textFit' : ''}${textDirection ? ', direction: __direction' : ''}${textTabular ? ', tabularFigures: __tabular' : ''}${createFillOpacity ? ', fillOpacity: __fillOpacity' : ''}${textStrokePos ? ', strokePosition: __strokePos' : ''}, position: ${reportActualPosition ? `(item.position ? { x: item.position.x, y: item.position.y } : null)` : `{ x: ${position.x}, y: ${position.y} }`}${hasLifetime ? ', lifetime: __lifetime' : ''}${loadsFont ? ', ...(__font ? { font: __font } : {})' : ''}${ignored.length > 0
+({ itemId, type: ${jsLiteral(itemType)}${outlineOnly ? `, fill: ${JSON.stringify(OUTLINE_NOTE)}` : ''}${textFit ? ', textFit: __textFit' : ''}${textDirection ? ', direction: __direction' : ''}${textTabular ? ', tabularFigures: __tabular' : ''}${createFillOpacity ? ', fillOpacity: __fillOpacity' : ''}${textStrokePos ? ', strokePosition: __strokePos' : ''}, position: ${reportActualPosition ? `(item.position ? { x: item.position.x, y: item.position.y } : null)` : `{ x: ${position.x}, y: ${position.y} }`}${hasLifetime ? ', lifetime: __lifetime' : ''}${loadsFont ? ', ...(__font ? { font: __font } : {})' : ''}${ignored.length > 0
         ? `, ignoredProperties: ${JSON.stringify(ignored)}` : ''}${warnings.length > 0 ? `, warning: ${JSON.stringify(warnings.join(' '))}` : ''} });`;
     // Loading a font is async, and it has to happen BEFORE create() measures the
     // text — so only this case becomes an async IIFE; every other create stays a
@@ -1003,7 +1010,7 @@ if (entry && entry.item && app.removeDynamicContent) app.removeDynamicContent(en
                 opts.countdownEndText = countdownEndText;
             code += `
 const entry = app.itemRegistry.get(${ID});
-if (entry && entry.item && app.setDynamicContent) app.setDynamicContent(entry.item, '${contentType}', ${jsLiteral(opts)});`;
+if (entry && entry.item && app.setDynamicContent) app.setDynamicContent(entry.item, ${jsLiteral(contentType)}, ${jsLiteral(opts)});`;
         }
     }
     // AN AUDIO ITEM'S LEVEL IS NOT AN ITEM PROPERTY. modifyItem applies changes
@@ -1221,6 +1228,8 @@ export function relationSpecProblem(relationType, params) {
     const p = (params && typeof params === 'object' ? params : {});
     if (relationType === 'on_event_fire_if')
         return fireIfProblem(p);
+    if (relationType === 'time_expression' && typeof p.expression === 'string')
+        return expressionProblem(p.expression);
     if (typeof relationType === 'string' && VISIBILITY_REACTION.test(relationType))
         return visibilityProblem(relationType, p);
     if (relationType === 'on_event_add_relation' && (p.type === 'on_event_fire_if' || (typeof p.type === 'string' && VISIBILITY_REACTION.test(p.type)))) {
@@ -1230,6 +1239,129 @@ export function relationSpecProblem(relationType, params) {
     }
     return null;
 }
+/**
+ * A time_expression formula outside the engine's grammar parses to nothing, and the relation then does nothing with
+ * success reported (#39: Math.sin(...) from JavaScript habit, no motion). Names are checked against the grammar the
+ * engine publishes (engine-lists, generated from expr-to-ir.js); syntax is the engine's to judge.
+ */
+function expressionProblem(expr) {
+    const allowed = new Set([...Object.keys(EXPRESSION_FUNCTION_ARITY), ...EXPRESSION_CONSTANTS, 't', 'v']);
+    const grammar = expressionGrammarText();
+    for (let i = 0; i < expr.length;) {
+        const c = expr[i];
+        if (/[0-9]/.test(c) || (c === '.' && /[0-9]/.test(expr[i + 1] ?? ''))) {
+            i++;
+            while (i < expr.length && /[0-9.]/.test(expr[i]))
+                i++;
+            if (/[eE]/.test(expr[i] ?? '') && /[0-9+-]/.test(expr[i + 1] ?? '')) {
+                i += 2;
+                while (i < expr.length && /[0-9]/.test(expr[i]))
+                    i++;
+            }
+            continue;
+        }
+        if (/[A-Za-z_]/.test(c)) {
+            let j = i + 1;
+            while (j < expr.length && /[A-Za-z0-9_]/.test(expr[j]))
+                j++;
+            const name = expr.slice(i, j);
+            if (expr[j] === '.') {
+                const member = /^[A-Za-z_][A-Za-z0-9_]*/.exec(expr.slice(j + 1))?.[0] ?? '';
+                return `expression ${JSON.stringify(expr)} uses ${name}.${member}, and the formula is not JavaScript: it would parse to nothing and the item would not move. Write ${member || 'the function'}(…) without ${name}. The grammar: ${grammar}.`;
+            }
+            if (EXPRESSION_REJECTED.includes(name)) {
+                return `expression ${JSON.stringify(expr)} uses ${name}(), which the engine refuses: a formula must give the same value at the same time in every export. Use noise(t) for a varying value that repeats.`;
+            }
+            const arity = EXPRESSION_FUNCTION_ARITY[name];
+            if (arity !== undefined) {
+                // Count the call's top-level arguments: a wrong count parses to nothing as well (min(1, 2, 3)).
+                let k = j;
+                while (expr[k] === ' ')
+                    k++;
+                if (expr[k] === '(') {
+                    let depth = 0, args = 0, any = false;
+                    for (let q = k; q < expr.length; q++) {
+                        const ch = expr[q];
+                        if (ch === '(') {
+                            depth++;
+                            continue;
+                        }
+                        if (ch === ')') {
+                            depth--;
+                            if (depth === 0)
+                                break;
+                            continue;
+                        }
+                        if (depth === 1 && ch === ',')
+                            args++;
+                        if (depth >= 1 && ch.trim())
+                            any = true;
+                    }
+                    const given = any ? args + 1 : 0;
+                    if (given !== arity)
+                        return `expression ${JSON.stringify(expr)} calls ${name} with ${given} argument${given === 1 ? '' : 's'}; it takes ${arity}, and any other count parses to nothing, so the item would not move.`;
+                }
+            }
+            if (!allowed.has(name)) {
+                const near = [...allowed].find((a) => a.toLowerCase() === name.toLowerCase());
+                return `expression ${JSON.stringify(expr)} names ${name}, which the formula grammar does not have, so it would parse to nothing and the item would not move.${near ? ` Did you mean ${near}?` : ''} The grammar: ${grammar}.`;
+            }
+            i = j;
+            continue;
+        }
+        i++;
+    }
+    return null;
+}
+/**
+ * A relationOptions key the rule never reads, said instead of accepted in silence. The list is the engine's own
+ * (RELATION_PARAM_KEYS: what each rule declares or reads); a rule without one (custom, event reactions) gets no
+ * warning. `injected` are keys the tool added itself (a name pattern's index and count).
+ */
+/** Levenshtein distance, for a "did you mean" on a misspelt key. */
+function editDistance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        let prev = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const t = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = t;
+        }
+    }
+    return row[b.length];
+}
+export function relationOptionWarning(relationType, params, injected = []) {
+    const flip = equationFlipNote(relationType, params);
+    const unread = unreadOptionWarning(relationType, params, injected);
+    return unread && flip ? `${unread} ${flip}` : unread ?? flip;
+}
+/**
+ * An equation route is in math coordinates, y up, unless flipY: false. Authored
+ * as screen coordinates it rode the curve mirrored about cy, every centroid
+ * within a pixel of the mirror and up to 300 px off the curve as written, with
+ * nothing said (ORBDUR26, ASYMORB27). Said when the caller left flipY to the default.
+ */
+function equationFlipNote(relationType, params) {
+    if (relationType !== 'moves_along_path' || !params || typeof params !== 'object')
+        return null;
+    const eq = params.equation;
+    if (!eq || typeof eq !== 'object' || eq.flipY !== undefined)
+        return null;
+    return 'params.equation is read with y UP (flipY defaults to true), so on screen the curve is mirrored about cy. If you wrote it in screen coordinates (y down), add flipY: false to the equation.';
+}
+function unreadOptionWarning(relationType, params, injected) {
+    const keys = typeof relationType === 'string' ? RELATION_PARAM_KEYS[relationType] : undefined;
+    if (!keys || !params || typeof params !== 'object')
+        return null;
+    const unknown = Object.keys(params).filter((k) => !keys.includes(k) && !injected.includes(k));
+    if (!unknown.length)
+        return null;
+    const norm = (x) => x.replace(/_/g, '').toLowerCase();
+    const hint = unknown.map((k) => keys.find((x) => norm(x) === norm(k)) ?? keys.find((x) => editDistance(norm(x), norm(k)) <= (k.length > 5 ? 2 : 1))).map((x, i) => (x ? `${unknown[i]} → ${x}?` : '')).filter(Boolean);
+    return `${relationType} does not read ${unknown.join(', ')}, so ${unknown.length > 1 ? 'they were' : 'it was'} ignored${hint.length ? ` (${hint.join('; ')})` : ''}. ${relationType} reads: ${keys.join(', ')}.`;
+}
 const VISIBILITY_REACTION = /^on_(event|enter|exit)_set_visibility$/;
 /**
  * A visibility reaction reads params.visible and nothing else: absent means show. `value`, which the other set_*
@@ -1249,23 +1381,23 @@ function generateAddRelationCode(sourceId, targetId, relationType, params) {
     // an item, the camera, a cursor target — is asked first here, after the same
     // '#id' forgiveness the engine applies.
     return `
-// Add ${relationType} relation: ${sourceId} -> ${targetId}
+// Add ${oneLine(relationType)} relation: ${oneLine(sourceId)} -> ${oneLine(targetId)}
 (function() {
   const norm = function(id) { return typeof app._resolveRelationEndpoint === 'function' ? app._resolveRelationEndpoint(id) : id; };
   if (typeof app._isKnownRelationEndpoint === 'function') {
     const bad = [${JSON.stringify(sourceId)}, ${JSON.stringify(targetId)}].filter(function(id) { return !app._isKnownRelationEndpoint(norm(id)); });
     if (bad.length) {
-      return { success: false, relationType: '${relationType}', error: bad.map(function(id) { return JSON.stringify(id); }).join(' and ')
+      return { success: false, relationType: ${jsLiteral(relationType)}, error: bad.map(function(id) { return JSON.stringify(id); }).join(' and ')
         + ' ' + (bad.length > 1 ? 'are not items' : 'is not an item') + ' on the canvas, so the relation would be stored and skipped every frame. Check the id (pinepaper_get_items lists them).' };
     }
   }
-  const success = app.addRelation('${sourceId}', '${targetId}', '${relationType}', ${JSON.stringify(params, null, 2)});
+  const success = app.addRelation(${jsLiteral(sourceId)}, ${jsLiteral(targetId)}, ${jsLiteral(relationType)}, ${JSON.stringify(params, null, 2)});
   if (!success) {
     const __why = ${relationRefusalReasonJs(jsLiteral(relationType))};
-    return { success: false, relationType: '${relationType}', error: 'the studio refused the ${relationType} relation between ${sourceId} and ${targetId}' + (__why ? ': ' + __why : '.') };
+    return { success: false, relationType: ${jsLiteral(relationType)}, error: 'the studio refused the ' + ${jsLiteral(relationType)} + ' relation between ' + ${jsLiteral(sourceId)} + ' and ' + ${jsLiteral(targetId)} + (__why ? ': ' + __why : '.') };
   }
   app.historyManager.saveState();
-  return { success: true, sourceId: '${sourceId}', targetId: '${targetId}', relationType: '${relationType}' };
+  return { success: true, sourceId: ${jsLiteral(sourceId)}, targetId: ${jsLiteral(targetId)}, relationType: ${jsLiteral(relationType)}${(() => { const w = relationOptionWarning(relationType, params); return w ? `, warning: ${jsLiteral(w)}` : ''; })()} };
 })();
 `.trim();
 }
@@ -1423,7 +1555,7 @@ function generateMovesAlongPathCode(sourceId, targetId, raw) {
     const hasDuration = typeof duration === 'number' && duration > 0;
     const hasDelay = typeof delay === 'number' && delay > 0;
     return `
-// moves_along_path: ${sourceId}${ref ? ` along ${ref}` : ''}
+// moves_along_path: ${oneLine(sourceId)}${ref ? ` along ${oneLine(ref)}` : ''}
 (function() {
   const params = ${JSON.stringify(params)};
   const hasPoints = Array.isArray(params.path) && params.path.length >= 2;
@@ -1537,14 +1669,14 @@ function aliasGeneratorParams(name, params) {
  * Template for removing relations
  */
 function generateRemoveRelationCode(sourceId, targetId, relationType) {
-    const relationArg = relationType ? `'${relationType}'` : 'undefined';
+    const relationArg = relationType ? jsLiteral(relationType) : 'undefined';
     return `
-// Remove relation: ${sourceId} -> ${targetId}${relationType ? ` (${relationType})` : ''}
-app.removeRelation('${sourceId}', '${targetId}', ${relationArg});
+// Remove relation: ${oneLine(sourceId)} -> ${oneLine(targetId)}${relationType ? ` (${oneLine(relationType)})` : ''}
+app.removeRelation(${jsLiteral(sourceId)}, ${jsLiteral(targetId)}, ${relationArg});
 app.historyManager.saveState();
 
 // Return success
-({ success: true, sourceId: '${sourceId}', targetId: '${targetId}' });
+({ success: true, sourceId: ${jsLiteral(sourceId)}, targetId: ${jsLiteral(targetId)} });
 `.trim();
 }
 /**
@@ -1553,7 +1685,7 @@ app.historyManager.saveState();
 function generateQueryRelationsCode(itemId, relationType, direction = 'outgoing') {
     const ID = jsLiteral(itemId); // caller text: a quoted literal, never spliced raw
     if (direction === 'outgoing') {
-        const typeArg = relationType ? `'${relationType}'` : 'undefined';
+        const typeArg = relationType ? jsLiteral(relationType) : 'undefined';
         return `
 // Query outgoing relations for ${ID}
 const relations = app.getRelations(${ID}, ${typeArg});
@@ -1574,7 +1706,7 @@ const formatted = relations.map(r => ({
 `.trim();
     }
     else {
-        const typeArg = relationType ? `'${relationType}'` : 'undefined';
+        const typeArg = relationType ? jsLiteral(relationType) : 'undefined';
         return `
 // Query incoming relations for ${ID}
 const results = app.queryByRelationTarget(${ID}, ${typeArg});
@@ -1586,7 +1718,7 @@ const relations = results.map(r => ({
   // queryByTarget returns the real relation name on each result. Hardcoding
   // the filter string labelled every edge 'unknown' on an unfiltered query —
   // which is exactly the query you make when exploring an unfamiliar graph.
-  relationType: r.relation || ${relationType ? `'${relationType}'` : "'unknown'"},
+  relationType: r.relation || ${relationType ? jsLiteral(relationType) : "'unknown'"},
   params: r.params || {}
 }));
 
@@ -1597,18 +1729,26 @@ const relations = results.map(r => ({
 /**
  * Template for simple animation
  */
-function generateAnimateCode(itemId, animationType, speed, intensity, delay) {
+function generateAnimateCode(itemId, animationType, speed, intensity, delay, waveform, origin) {
     const ID = jsLiteral(itemId); // caller text: a quoted literal, never spliced raw
     const extra = (intensity !== undefined ? `,\n  animationIntensity: ${intensity}` : '') +
-        (delay !== undefined ? `,\n  animationDelay: ${delay}` : '');
+        (delay !== undefined ? `,\n  animationDelay: ${delay}` : '') +
+        (waveform !== undefined ? `,\n  animationWaveform: ${jsLiteral(waveform)}` : '') +
+        (origin !== undefined ? `,\n  animationOrigin: ${jsLiteral(origin)}` : '');
+    // A studio from before field motions (FxTool #255) drops waveform and origin
+    // without a word, and the wave runs as sine from the centre. Read them back.
+    const optionCheck = waveform === undefined && origin === undefined ? '' : `
+  const __unset = [${waveform !== undefined ? `['waveform', 'animationWaveform', ${jsLiteral(waveform)}]` : ''}${waveform !== undefined && origin !== undefined ? ', ' : ''}${origin !== undefined ? `['origin', 'animationOrigin', ${jsLiteral(origin)}]` : ''}]
+    .filter(function (o) { return !item.data || item.data[o[1]] !== o[2]; }).map(function (o) { return o[0]; });
+  if (__unset.length) out.warning = __unset.join(' and ') + ' did not take: this studio predates field-motion options (or refused the value), so the wave runs as sine from the centre. Update the studio.';`;
     return `
-// Apply ${animationType} animation to ${ID}
+// Apply ${oneLine(animationType)} animation to ${ID}
 const item = app.getItemById(${ID});
 if (!item) {
   throw new Error('Item not found: ' + ${ID});
 }
 app.animate(item, {
-  animationType: '${animationType}',
+  animationType: ${jsLiteral(animationType)},
   animationSpeed: ${speed}${extra}
 });
 
@@ -1627,7 +1767,8 @@ app.animate(item, {
       known: r.known,
     };
   }
-  return { success: true, itemId: ${ID}, animationType: '${animationType}' };
+  const out = { success: true, itemId: ${ID}, animationType: ${jsLiteral(animationType)} };${optionCheck}
+  return out;
 })();
 `.trim();
 }
@@ -1703,6 +1844,12 @@ const TEXT_KEY_ENGINE_NAMES = {
     textAlign: ['textAlign', 'justification'],
     lineHeight: ['lineHeight', 'leading'],
     letterSpacing: ['letterSpacing'],
+    // Text style keys no studio has animated so far. Keyed, they were stored and
+    // drew nothing, with success:true (WORDSPC26). Checked against the same list,
+    // so a studio that learns one is believed and the warning stops.
+    wordSpacing: ['wordSpacing'],
+    textDecoration: ['textDecoration'],
+    textTransform: ['textTransform'],
 };
 /** A JS expression (run in the page) → the keys of `keys` this studio does not animate. '' when none are text keys. */
 function unanimatedTextKeysJs(keys) {
@@ -1717,7 +1864,7 @@ function unanimatedTextKeysJs(keys) {
   })()`;
 }
 /** The sentence for the keys unanimatedTextKeysJs found, built in the page. */
-const UNANIMATED_TEXT_KEYS_SENTENCE = `' is not an animatable property in this studio (app.listAnimatableProperties does not list it), so it had no effect. The current studio animates fontStyle, textAlign, lineHeight and letterSpacing; here, set a fixed value with pinepaper_modify_item, or animate fontSize or scaleX.'`;
+const UNANIMATED_TEXT_KEYS_SENTENCE = `' is not an animatable property in this studio (app.listAnimatableProperties does not list it), so it had no effect: a text key animates only where that list names it. Here, set a fixed value with pinepaper_modify_item, or animate fontSize or scaleX.'`;
 function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false, timeOffset, clipInPoint, clipOutPoint, timeUnits, append = false, easingAt) {
     const ID = jsLiteral(itemId); // caller text: a quoted literal, never spliced raw
     const keyframesJson = JSON.stringify(normalizeKeyframePositions(keyframes), null, 2);
@@ -1868,7 +2015,7 @@ function generateExecuteGeneratorCode(generatorName, params, region) {
         ? ` in region ${region.width}×${region.height} @ (${region.x},${region.y})`
         : ` in the shape of ${region.shape.itemId}`;
     return `
-// Execute ${generatorName} generator${where}
+// Execute ${oneLine(generatorName)} generator${oneLine(where)}
 (async function() {${emitGeneratorRun(generatorName, JSON.stringify(params, null, 2), region)}
 })();
 `.trim();
@@ -1895,9 +2042,9 @@ function emitGeneratorRun(generatorName, paramsJson, region) {
     if (!__si) return { success: false, error: ${JSON.stringify(`region.shape names no item "${itemId}" — nothing was drawn. List items with pinepaper_get_items.`)} };
     if (__si.className !== 'Path' && __si.className !== 'CompoundPath') return { success: false, error: ${JSON.stringify(`region.shape item "${itemId}" is a `)} + __si.className + ', and a clip needs a path (a shape, not text, a group or an image) — nothing was drawn.' };
   }` : ''}
-  await app.executeGenerator('${generatorName}', ${paramsJson}, ${options});${shaped ? `
+  await app.executeGenerator(${jsLiteral(generatorName)}, ${paramsJson}, ${options});${shaped ? `
   const __shapes = !!(app.generatorRegistry && typeof app.generatorRegistry._regionClipPath === 'function');` : ''}
-  return { success: true, generator: '${generatorName}'${region ? `, region: ${JSON.stringify(region)}` : ''}${shaped ? `, ...(__shapes ? {} : { regionShapeApplied: false, warning: ${JSON.stringify(`this studio does not clip generator regions to a shape, so ${typeof region.shape === 'object' ? 'the region had no box and the generator drew across the whole canvas' : `the ${region.shape} was drawn as a rectangle`}. It needs an engine with region shapes.`)} })` : ''} };`;
+  return { success: true, generator: ${jsLiteral(generatorName)}${region ? `, region: ${JSON.stringify(region)}` : ''}${shaped ? `, ...(__shapes ? {} : { regionShapeApplied: false, warning: ${JSON.stringify(`this studio does not clip generator regions to a shape, so ${typeof region.shape === 'object' ? 'the region had no box and the generator drew across the whole canvas' : `the ${region.shape} was drawn as a rectangle`}. It needs an engine with region shapes.`)} })` : ''} };`;
 }
 /**
  * Template for applying effects
@@ -1905,14 +2052,14 @@ function emitGeneratorRun(generatorName, paramsJson, region) {
 function generateApplyEffectCode(itemId, effectType, params) {
     const ID = jsLiteral(itemId); // caller text: a quoted literal, never spliced raw
     return `
-// Apply ${effectType} effect to ${ID}
+// Apply ${oneLine(effectType)} effect to ${ID}
 const item = app.getItemById(${ID});
 if (!item) {
   throw new Error('Item not found: ' + ${ID});
 }
-app.applyEffect(item, '${effectType}', ${JSON.stringify(params, null, 2)});
+app.applyEffect(item, ${jsLiteral(effectType)}, ${JSON.stringify(params, null, 2)});
 
-({ success: true, itemId: ${ID}, effectType: '${effectType}' });
+({ success: true, itemId: ${ID}, effectType: ${jsLiteral(effectType)} });
 `.trim();
 }
 /**
@@ -1964,9 +2111,9 @@ function generateGetItemsCode(filter) {
     // conditions, not on the keys.
     const conditions = [];
     if (filter?.type)
-        conditions.push(`entry.type === '${filter.type}'`);
+        conditions.push(`entry.type === ${jsLiteral(filter.type)}`);
     if (filter?.source)
-        conditions.push(`entry.source === '${filter.source}'`);
+        conditions.push(`entry.source === ${jsLiteral(filter.source)}`);
     if (filter?.hasAnimation !== undefined) {
         // 'none' is what the engine stores on a still item, and !!'none' is true
         // (gate H5): animated means a real loop animation OR keyframes.
@@ -2163,8 +2310,8 @@ app.setPlaybackTime(${time || 0});
 function generateSetBackgroundColorCode(color) {
     return `
 // Set background color
-app.setBackgroundColor('${color}');
-({ success: true, color: '${color}' });
+app.setBackgroundColor(${jsLiteral(color)});
+({ success: true, color: ${jsLiteral(color)} });
 `.trim();
 }
 /**
@@ -2671,7 +2818,7 @@ ${body}
   } catch (e) { errors.push({ index: ${i}, error: (e && e.message) || String(e) }); }`;
     });
     return `
-// Batch create ${items.length} items — create_item for each, one history save
+// Batch create ${oneLine(items.length)} items — create_item for each, one history save
 (async function() {
   const results = [];
   const errors = [];
@@ -2704,7 +2851,7 @@ function generateBatchModifyCode(modifications) {
   } catch (e) { skipped.push({ itemId: ${JSON.stringify(m.itemId)}, reason: (e && e.message) || String(e) }); }`;
     });
     return `
-// Batch modify ${modifications.length} items — modify_item for each, one history save
+// Batch modify ${oneLine(modifications.length)} items — modify_item for each, one history save
 (async function() {
   let count = 0;
   const skipped = [];
@@ -2726,11 +2873,11 @@ ${blocks.join('\n')}
  */
 function generateCreateGridCode(cols, rows, strokeColor, strokeWidth, animated, waveSpeed, waveAmplitude) {
     return `
-// Create grid with ${cols} columns and ${rows} rows
+// Create grid with ${oneLine(cols)} columns and ${oneLine(rows)} rows
 const grid = app.createGrid({
   cols: ${cols},
   rows: ${rows},
-  strokeColor: '${strokeColor}',
+  strokeColor: ${jsLiteral(strokeColor)},
   strokeWidth: ${strokeWidth},
   animated: ${animated},
   waveSpeed: ${waveSpeed},
@@ -3119,7 +3266,7 @@ export class PinePaperCodeGenerator {
         // than read as a single string, which would render "[object Object]".
         if (validated.presetId) {
             return `
-// Adopt relation preset "${validated.presetId}" on ${validated.sourceId}
+// Adopt relation preset ${jsLiteral(validated.presetId)} on ${jsLiteral(validated.sourceId)}
 (async function() {
   if (typeof app.applyRelationPreset !== 'function') { return { success: false, error: 'app.applyRelationPreset unavailable — update FxTool' }; }
   const r = await app.applyRelationPreset(${JSON.stringify(validated.sourceId)}, ${JSON.stringify(validated.presetId)}, ${JSON.stringify(validated.presetValues ?? {})});
@@ -3149,7 +3296,7 @@ export class PinePaperCodeGenerator {
         if (validated.targetId)
             return code;
         return code
-            .replace(`return { success: true, sourceId: '${validated.sourceId}', targetId: '${validated.sourceId}',`, `return { success: true, sourceId: '${validated.sourceId}', targetId: null,`)
+            .replace(`return { success: true, sourceId: ${jsLiteral(validated.sourceId)}, targetId: ${jsLiteral(validated.sourceId)},`, `return { success: true, sourceId: ${jsLiteral(validated.sourceId)}, targetId: null,`)
             .replace(`relation between ${validated.sourceId} and ${validated.sourceId}.`, `relation on ${validated.sourceId} (no target).`);
     }
     /**
@@ -3169,7 +3316,7 @@ export class PinePaperCodeGenerator {
      */
     generateAnimate(input) {
         const validated = AnimateItemInputSchema.parse(input);
-        return generateAnimateCode(validated.itemId, validated.animationType, validated.speed, validated.intensity, validated.delay);
+        return generateAnimateCode(validated.itemId, validated.animationType, validated.speed, validated.intensity, validated.delay, validated.waveform, validated.origin);
     }
     /**
      * Generate code for keyframe animation
@@ -3313,7 +3460,7 @@ ${asReturningBody(code)}
             : `{ item: app.importSVG(${varName}), changes: [] }`;
         if (url) {
             return `
-// Import SVG from URL${source === 'figma' ? ' (Figma-normalised)' : ''}
+// Import SVG from URL${oneLine(source === 'figma' ? ' (Figma-normalised)' : '')}
 // WRAPPED, because these were bare top-level statements with an await. That
 // parses under the governor, which builds an AsyncFunction, and is a SYNTAX
 // ERROR on the eval fallback — so importing an SVG by URL never ran at all on
@@ -3322,12 +3469,12 @@ ${asReturningBody(code)}
 (async function() {
   let response;
   try {
-    response = await fetch('${url}');
+    response = await fetch(${jsLiteral(url)});
   } catch (netErr) {
-    return { success: false, error: 'could not reach ${url} — ' + ((netErr && netErr.message) || 'network request failed') };
+    return { success: false, error: 'could not reach ' + ${jsLiteral(url)} + ' — ' + ((netErr && netErr.message) || 'network request failed') };
   }
   if (!response.ok) {
-    return { success: false, error: 'the server refused ${url} — HTTP ' + response.status + ' ' + (response.statusText || ''), status: response.status };
+    return { success: false, error: 'the server refused ' + ${jsLiteral(url)} + ' — HTTP ' + response.status + ' ' + (response.statusText || ''), status: response.status };
   }
   let svgText = await response.text();
 ${INLINE_REMOTE_IMAGES}
@@ -3336,7 +3483,7 @@ ${INLINE_REMOTE_IMAGES}
   const _r = ${importExpr('svgText')};
   const imported = _r.item;
   if (!imported) {
-    return { success: false, error: 'the response from ${url} did not parse as SVG. Check the URL serves the file itself rather than a page around it.' };
+    return { success: false, error: 'the response from ' + ${jsLiteral(url)} + ' did not parse as SVG. Check the URL serves the file itself rather than a page around it.' };
   }
   imported.position = new paper.Point(${position.x}, ${position.y});
   imported.scale(${scale});
@@ -3360,7 +3507,7 @@ ${INLINE_REMOTE_IMAGES}
             // Escape the SVG string for embedding in code
             const escapedSvg = svgString.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$/g, '\\$');
             return `
-// Import SVG string${source === 'figma' ? ' (Figma-normalised)' : ''}
+// Import SVG string${oneLine(source === 'figma' ? ' (Figma-normalised)' : '')}
 (async function() {
 let svgString = \`${escapedSvg}\`;
 ${INLINE_REMOTE_IMAGES}
@@ -3542,9 +3689,9 @@ throw new Error('Either svgString or url must be provided');
      */
     generateAddFilter(filterType, params = {}) {
         return `
-// Add ${filterType} filter
-const filterId = app.filterSystem.addFilter('${filterType}', ${JSON.stringify(params, null, 2)});
-({ success: true, filterId, filterType: '${filterType}' });
+// Add ${oneLine(filterType)} filter
+const filterId = app.filterSystem.addFilter(${jsLiteral(filterType)}, ${JSON.stringify(params, null, 2)});
+({ success: true, filterId, filterType: ${jsLiteral(filterType)} });
 `.trim();
     }
     /**
@@ -3573,7 +3720,7 @@ const filterId = app.filterSystem.addFilter('${filterType}', ${JSON.stringify(pa
         return `
 // Create glossy 3D sphere effect
 const sphereGroup = new paper.Group({ parent: app.textItemGroup });
-const baseColor = new paper.Color('${baseColor}');
+const baseColor = new paper.Color(${jsLiteral(baseColor)});
 
 ${castShadow ? `// Shadow underneath
 const shadow = new paper.Path.Ellipse({
@@ -3753,7 +3900,7 @@ paper.project.activeLayer.children.forEach(c => {
 const bg = new paper.Path.Rectangle({
   point: [0, 0],
   size: [paper.view.size.width, paper.view.size.height],
-  fillColor: '${backgroundColor}',
+  fillColor: ${jsLiteral(backgroundColor)},
   name: 'background'
 });
 bg.sendToBack();
@@ -3763,7 +3910,7 @@ bg.sendToBack();
         if (backgroundGenerator) {
             codeParts.push(`
 // Execute background generator
-const _gen = app.generatorRegistry?.get('${backgroundGenerator}');
+const _gen = app.generatorRegistry?.get(${jsLiteral(backgroundGenerator)});
 if (typeof _gen === 'function') {
   _gen();
 } else if (_gen && typeof _gen.generate === 'function') {
@@ -3795,20 +3942,20 @@ if (typeof _gen === 'function') {
                 ...properties,
             };
             codeParts.push(`
-// Create item: ${name}
+// Create item: ${oneLine(name)}
 (function() {
-  const item = app.create('${itemType}', ${JSON.stringify(sceneParams)});
+  const item = app.create(${jsLiteral(itemType)}, ${JSON.stringify(sceneParams)});
   if (!item) {
-    results.items.push({ name: '${name}', error: 'app.create returned nothing for type ${itemType} — check the type and its properties.' });
+    results.items.push({ name: ${jsLiteral(name)}, error: 'app.create returned nothing for type ' + ${jsLiteral(itemType)} + ' — check the type and its properties.' });
     return;
   }
   // create() registers and mints the id; only fall back for an older studio.
   const itemId = (item.data && item.data.id)
     ? item.data.id
-    : app.registerItem(item, '${itemType}', { source: 'mcp-scene' });
+    : app.registerItem(item, ${jsLiteral(itemType)}, { source: 'mcp-scene' });
   if (item.bringToFront) item.bringToFront();
-  nameToId['${name}'] = itemId;
-  results.items.push({ name: '${name}', itemId, type: '${itemType}' });
+  nameToId[${jsLiteral(name)}] = itemId;
+  results.items.push({ name: ${jsLiteral(name)}, itemId, type: ${jsLiteral(itemType)} });
 })();`);
         }
         // Establish relations
@@ -3818,25 +3965,25 @@ if (typeof _gen === 'function') {
             const specProblem = relationSpecProblem(type, params);
             if (specProblem) {
                 codeParts.push(`
-// Refused relation: ${source} ${type} ${target}
+// Refused relation: ${oneLine(source)} ${oneLine(type)} ${oneLine(target)}
 (results.relationsRefused = results.relationsRefused || []).push(${JSON.stringify({ source, target, type, reason: specProblem })});
 results.success = false;
 results.error = 'refused ' + results.relationsRefused.length + ' relation(s): ' + results.relationsRefused.map(function(r) { return r.type + ' ' + r.source + ' -> ' + r.target + ' (' + r.reason + ')'; }).join('; ') + '. The items were created.';`);
                 continue;
             }
             codeParts.push(`
-// Add relation: ${source} ${type} ${target}
+// Add relation: ${oneLine(source)} ${oneLine(type)} ${oneLine(target)}
 (function() {
-  const sourceId = nameToId['${source}'];
-  const targetId = nameToId['${target}'];
+  const sourceId = nameToId[${jsLiteral(source)}];
+  const targetId = nameToId[${jsLiteral(target)}];
   if (sourceId && targetId) {
     const params = ${paramsStr};
     // A refused relation is not listed as made (owner rule 1).
-    if (app.addRelation(sourceId, targetId, '${type}', params)) {
-      results.relations.push({ source: '${source}', target: '${target}', type: '${type}' });
+    if (app.addRelation(sourceId, targetId, ${jsLiteral(type)}, params)) {
+      results.relations.push({ source: ${jsLiteral(source)}, target: ${jsLiteral(target)}, type: ${jsLiteral(type)} });
     } else {
       const __why = ${relationRefusalReasonJs(jsLiteral(type))};
-      (results.relationsRefused = results.relationsRefused || []).push({ source: '${source}', target: '${target}', type: '${type}', reason: __why || 'the studio refused it' });
+      (results.relationsRefused = results.relationsRefused || []).push({ source: ${jsLiteral(source)}, target: ${jsLiteral(target)}, type: ${jsLiteral(type)}, reason: __why || 'the studio refused it' });
       results.success = false;
       results.error = 'the studio refused ' + results.relationsRefused.length + ' relation(s): ' + results.relationsRefused.map(function(r) { return r.type + ' ' + r.source + ' -> ' + r.target + ' (' + r.reason + ')'; }).join('; ') + '. The items were created.';
     }
@@ -3853,9 +4000,9 @@ results.error = 'refused ' + results.relationsRefused.length + ' relation(s): '
                 ...(startTime !== undefined ? { animationDelay: startTime } : {}),
             });
             codeParts.push(`
-// Apply animation: ${type} to ${target}
+// Apply animation: ${oneLine(type)} to ${oneLine(target)}
 (function() {
-  const targetId = nameToId['${target}'];
+  const targetId = nameToId[${jsLiteral(target)}];
   if (targetId) {
     const targetItem = app.itemRegistry.get(targetId);
     if (targetItem) {
@@ -3865,8 +4012,8 @@ results.error = 'refused ' + results.relationsRefused.length + ' relation(s): '
       // loops with no end, so there is no duration to map and none is invented
       // — staggering the STARTS is what makes a scene read as choreographed
       // rather than everything moving at once from frame zero.
-      app.animate(targetItem, { animationType: '${type}', ...params });
-      results.animations.push({ target: '${target}', type: '${type}'${startTime !== undefined ? `, startTime: ${startTime}` : ''} });
+      app.animate(targetItem, { animationType: ${jsLiteral(type)}, ...params });
+      results.animations.push({ target: ${jsLiteral(target)}, type: ${jsLiteral(type)}${startTime !== undefined ? `, startTime: ${startTime}` : ''} });
     }
   }
 })();
@@ -3900,7 +4047,7 @@ return results;
         // ending in \ escapes the closing quote; 'x\\'; evil()' breaks out).
         const labelStr = label ? JSON.stringify(label) : 'null';
         return `
-// Create diagram shape: ${shapeType}
+// Create diagram shape: ${oneLine(shapeType)}
 // POSITIONAL: createShape(shapeType, config). The type was being passed
 // INSIDE the config object, where nothing reads it.
 const shapeConfig = {
@@ -3911,12 +4058,12 @@ const shapeConfig = {
   style: ${styleStr}
 };
 
-const shape = app.diagramSystem.createShape('${shapeType}', shapeConfig);
-if (!shape) throw new Error('createShape returned nothing for shapeType "${shapeType}" — call pinepaper_get_diagram_shapes for the registered types.');
+const shape = app.diagramSystem.createShape(${jsLiteral(shapeType)}, shapeConfig);
+if (!shape) throw new Error('createShape returned nothing for shapeType ' + ${jsLiteral(shapeType)} + ' — call pinepaper_get_diagram_shapes for the registered types.');
 const itemId = shape.data?.registryId || shape.id;
 app.historyManager.saveState();
 
-({ itemId, shapeType: '${shapeType}', position: { x: ${position.x}, y: ${position.y} } });
+({ itemId, shapeType: ${jsLiteral(shapeType)}, position: { x: ${position.x}, y: ${position.y} } });
 `.trim();
     }
     /**
@@ -3948,12 +4095,12 @@ app.historyManager.saveState();
         if (label)
             config.label = label;
         return `
-// Connect items: ${sourceItemId} -> ${targetItemId}
-const sourceItem = app.getItemById('${sourceItemId}');
-const targetItem = app.getItemById('${targetItemId}');
+// Connect items: ${oneLine(sourceItemId)} -> ${oneLine(targetItemId)}
+const sourceItem = app.getItemById(${jsLiteral(sourceItemId)});
+const targetItem = app.getItemById(${jsLiteral(targetItemId)});
 
-if (!sourceItem) throw new Error('Source item not found: ${sourceItemId}');
-if (!targetItem) throw new Error('Target item not found: ${targetItemId}');
+if (!sourceItem) throw new Error('Source item not found: ' + ${jsLiteral(sourceItemId)});
+if (!targetItem) throw new Error('Target item not found: ' + ${jsLiteral(targetItemId)});
 
 const config = ${JSON.stringify(config, null, 2)};
 const connector = app.diagramSystem.connect(sourceItem, targetItem, config);
@@ -3971,8 +4118,8 @@ app.historyManager.saveState();
 // mismatch is REPORTED rather than left for a later call to trip over.
 ({
   connectorId,
-  sourceItemId: '${sourceItemId}',
-  targetItemId: '${targetItemId}',
+  sourceItemId: ${jsLiteral(sourceItemId)},
+  targetItemId: ${jsLiteral(targetItemId)},
   ...(${JSON.stringify(id ?? null)} && connectorId !== ${JSON.stringify(id ?? null)}
     ? { requestedId: ${JSON.stringify(id ?? null)},
         idHonoured: false,
@@ -3994,12 +4141,12 @@ app.historyManager.saveState();
         const merged = id ? { ...(config ?? {}), id } : config;
         const configStr = merged ? JSON.stringify(merged, null, 2) : '{}';
         return `
-// Connect ports: ${sourceItemId}:${sourcePort} -> ${targetItemId}:${targetPort}
-const sourceItem = app.getItemById('${sourceItemId}');
-const targetItem = app.getItemById('${targetItemId}');
+// Connect ports: ${oneLine(sourceItemId)}:${oneLine(sourcePort)} -> ${oneLine(targetItemId)}:${oneLine(targetPort)}
+const sourceItem = app.getItemById(${jsLiteral(sourceItemId)});
+const targetItem = app.getItemById(${jsLiteral(targetItemId)});
 
-if (!sourceItem) throw new Error('Source item not found: ${sourceItemId}');
-if (!targetItem) throw new Error('Target item not found: ${targetItemId}');
+if (!sourceItem) throw new Error('Source item not found: ' + ${jsLiteral(sourceItemId)});
+if (!targetItem) throw new Error('Target item not found: ' + ${jsLiteral(targetItemId)});
 
 const config = ${configStr};
 // connectPorts(sourcePort, targetPort, config) takes PORT OBJECTS (gate C8,
@@ -4024,7 +4171,7 @@ if (!connector) { return { success: false, error: 'the diagram system did not cr
 const connectorId = connector.id || connector.data?.registryId;
 app.historyManager.saveState();
 
-({ connectorId, sourceItemId: '${sourceItemId}', sourcePort: '${sourcePort}', targetItemId: '${targetItemId}', targetPort: '${targetPort}' });
+({ connectorId, sourceItemId: ${jsLiteral(sourceItemId)}, sourcePort: ${jsLiteral(sourcePort)}, targetItemId: ${jsLiteral(targetItemId)}, targetPort: ${jsLiteral(targetPort)} });
 `.trim();
     }
     /**
@@ -4042,22 +4189,22 @@ app.historyManager.saveState();
         if (ports !== undefined || count !== undefined) {
             const named = [ports !== undefined && 'ports', count !== undefined && 'count'].filter(Boolean).join(' and ');
             throw new Error(`add_ports cannot honour ${named}: this engine lays out a whole port SET by type `
-                + `(portType '${portType}'), with no per-port placement or count. Drop ${named}, or place `
+                + `(portType ${jsLiteral(portType)}), with no per-port placement or count. Drop ${named}, or place `
                 + 'individual connection points as items and join them with pinepaper_connect.');
         }
         return `
-// Add ports to item: ${itemId}
-const item = app.getItemById('${itemId}');
-if (!item) throw new Error('Item not found: ${itemId}');
+// Add ports to item: ${oneLine(itemId)}
+const item = app.getItemById(${jsLiteral(itemId)});
+if (!item) throw new Error('Item not found: ' + ${jsLiteral(itemId)});
 
 // The second argument is a TYPE STRING, not a config object. Passing an
 // object made the engine iterate it as a list — "t.forEach is not a function".
-const result = app.diagramSystem.addPorts(item, '${portType}');
+const result = app.diagramSystem.addPorts(item, ${jsLiteral(portType)});
 app.historyManager.saveState();
 
 // addPorts returns the ports it made; older builds returned a count object.
 const _added = Array.isArray(result) ? result.length : (result?.portsAdded ?? 0);
-({ itemId: '${itemId}', portsAdded: _added, portType: '${portType}' });
+({ itemId: ${jsLiteral(itemId)}, portsAdded: _added, portType: ${jsLiteral(portType)} });
 `.trim();
     }
     /**
@@ -4069,7 +4216,7 @@ const _added = Array.isArray(result) ? result.length : (result?.portsAdded ?? 0)
         const itemIdsStr = itemIds ? JSON.stringify(itemIds) : 'null';
         const optionsStr = options ? JSON.stringify(options, null, 2) : '{}';
         return `
-// Apply auto-layout: ${layoutType}
+// Apply auto-layout: ${oneLine(layoutType)}
 // Wrapped: applyLayout is async, and a bare top-level await only works on the
 // governed path. A paren-led IIFE also keeps the trailing-expression capture.
 (async function() {
@@ -4085,10 +4232,10 @@ const items = itemIds
   : (app.itemRegistry?.getAll?.() ?? []);
 if (!items.length) throw new Error('auto_layout found no items to lay out' + (itemIds ? ' for the given itemIds' : ' on the canvas'));
 
-await app.diagramSystem.applyLayout(items, '${layoutType}', options);
+await app.diagramSystem.applyLayout(items, ${jsLiteral(layoutType)}, options);
 app.historyManager.saveState();
 
-return { layoutType: '${layoutType}', itemsAffected: items.length, success: true };
+return { layoutType: ${jsLiteral(layoutType)}, itemsAffected: items.length, success: true };
 })();
 `.trim();
     }
@@ -4098,7 +4245,7 @@ return { layoutType: '${layoutType}', itemsAffected: items.length, success: true
     generateGetDiagramShapes(input) {
         const validated = GetDiagramShapesInputSchema.parse(input);
         const { category } = validated;
-        const categoryFilter = category ? `'${category}'` : 'null';
+        const categoryFilter = category ? jsLiteral(category) : 'null';
         return `
 // Get available diagram shapes
 const category = ${categoryFilter};
@@ -4117,7 +4264,7 @@ const shapes = category ? _lib.getByCategory(category) : _lib.getAll();
         const validated = UpdateConnectorInputSchema.parse(input);
         const { connectorId, style, label, labelPosition } = validated;
         return `
-// Update connector: ${connectorId}
+// Update connector: ${oneLine(connectorId)}
 (function() {
   // CONNECTORS LIVE IN THE DIAGRAM SYSTEM, NOT THE ITEM REGISTRY (gate D1,
   // 1.6.19): getItemById never resolves the id connect returned.
@@ -4169,7 +4316,7 @@ const shapes = category ? _lib.getByCategory(category) : _lib.getAll();
         const validated = RemoveConnectorInputSchema.parse(input);
         const { connectorId } = validated;
         return `
-// Remove connector: ${connectorId}
+// Remove connector: ${oneLine(connectorId)}
 // Resolved through the diagram system (gate D1, 1.6.19), as update_connector is.
 const __cid = ${JSON.stringify(connectorId)};
 const connector = (app.diagramSystem && app.diagramSystem.getConnector(__cid)) || app.getItemById(__cid);
@@ -4178,7 +4325,7 @@ if (!connector) throw new Error('Connector not found: ' + __cid);
 app.diagramSystem.connectorManager.removeConnector(connector);
 app.historyManager.saveState();
 
-({ connectorId: '${connectorId}', removed: true });
+({ connectorId: ${jsLiteral(connectorId)}, removed: true });
 `.trim();
     }
     /**
@@ -4207,17 +4354,17 @@ const isActive = app.diagramSystem.toggle();
 ({ action: 'toggle', active: isActive });
 `.trim();
             case 'setMode':
-                const modeStr = mode ? `'${mode}'` : "'select'";
-                const shapeStr = shapeType ? `, '${shapeType}'` : '';
+                const modeStr = mode ? jsLiteral(mode) : "'select'";
+                const shapeStr = shapeType ? `, ${jsLiteral(shapeType)}` : '';
                 return `
 // Set diagram tool mode
 app.diagramSystem.setMode(${modeStr}${shapeStr});
-({ action: 'setMode', mode: ${modeStr}${shapeType ? `, shapeType: '${shapeType}'` : ''} });
+({ action: 'setMode', mode: ${modeStr}${shapeType ? `, shapeType: ${jsLiteral(shapeType)}` : ''} });
 `.trim();
             default:
                 return `
 // Unknown diagram mode action
-throw new Error('Unknown diagram mode action: ${action}');
+throw new Error('Unknown diagram mode action: ' + ${jsLiteral(action)});
 `.trim();
         }
     }
@@ -4239,7 +4386,7 @@ throw new Error('Unknown diagram mode action: ${action}');
 (async function() {
   const jobOptions = {
     name: ${nameStr},
-    screenshotPolicy: '${policyStr}',
+    screenshotPolicy: ${jsLiteral(policyStr)},
     agentMode: true
   };
 `;
@@ -4259,7 +4406,7 @@ throw new Error('Unknown diagram mode action: ${action}');
         if (canvasPreset) {
             code += `
   // Set canvas size to preset (platform name → engine preset key)
-  app.setCanvasSize('${canvasPresetFor(canvasPreset)}');
+  app.setCanvasSize(${jsLiteral(canvasPresetFor(canvasPreset))});
   // Allow canvas resize to take effect
   await new Promise(r => setTimeout(r, 50));
 `;
@@ -4303,14 +4450,14 @@ throw new Error('Unknown diagram mode action: ${action}');
 `;
         }
         code += `
-  // Return job context with canvas size${wantOntology ? ' + initial ontology' : ''}
+  // Return job context with canvas size${oneLine(wantOntology ? ' + initial ontology' : '')}
   const _cs = app.getCanvasSize ? app.getCanvasSize() : { width: 800, height: 600 };
   return {
     success: true,
     jobStarted: true,
     name: ${nameStr},
-    screenshotPolicy: '${policyStr}',
-    canvasPreset: ${canvasPreset ? `'${canvasPreset}'` : 'null'},
+    screenshotPolicy: ${jsLiteral(policyStr)},
+    canvasPreset: ${canvasPreset ? jsLiteral(canvasPreset) : 'null'},
     canvasCleared: ${shouldClear},
     canvasSize: { width: _cs.width || 800, height: _cs.height || 600 }${canvasPreset ? '' : `,
     ...(_boundedFrom ? { note: 'the canvas was unbounded (it exported the artwork, not the board); it is now fixed at ' + (_cs.width || 800) + 'x' + (_cs.height || 600) + ', so stills and video both export that size.' } : {})`}${wantOntology ? `,
@@ -4510,7 +4657,7 @@ throw new Error('Unknown diagram mode action: ${action}');
         if (canvasPreset) {
             code += `
   // Set canvas to preset (platform name → engine preset key)
-  app.setCanvasSize('${canvasPresetFor(canvasPreset)}');
+  app.setCanvasSize(${jsLiteral(canvasPresetFor(canvasPreset))});
   // Allow canvas resize to take effect
   await new Promise(r => setTimeout(r, 50));
 `;
@@ -4518,14 +4665,14 @@ throw new Error('Unknown diagram mode action: ${action}');
         if (backgroundColor && !preserveBackground) {
             code += `
   // Set background color
-  app.setBackgroundColor('${backgroundColor}');
+  app.setBackgroundColor(${jsLiteral(backgroundColor)});
 `;
         }
         code += `
   // Save state
   if (app.historyManager) app.historyManager.saveState();
   const _cs = app.getCanvasSize ? app.getCanvasSize() : { width: 800, height: 600 };
-  return { success: true, reset: true, canvasPreset: ${canvasPreset ? `'${canvasPreset}'` : 'null'}, canvasSize: { width: _cs.width || 800, height: _cs.height || 600 } };
+  return { success: true, reset: true, canvasPreset: ${canvasPreset ? jsLiteral(canvasPreset) : 'null'}, canvasSize: { width: _cs.width || 800, height: _cs.height || 600 } };
 })();
 `;
         return code.trim();
@@ -4546,7 +4693,7 @@ throw new Error('Unknown diagram mode action: ${action}');
         // anything runs; a direct caller gets the op's own failure instead.
         const timelines = compileBatchTimelines(operations);
         let code = `
-// Batch execute ${operations.length} operations
+// Batch execute ${oneLine(operations.length)} operations
 (async function() {
   // An op's own verdict. Deliberately narrow, matching the server-side rule:
   // only an explicit success:false or ok:false is a failure, because most ops
@@ -4619,7 +4766,7 @@ throw new Error('Unknown diagram mode action: ${action}');
             const opItemJs = typeof opItem === 'string' && /^\$\d+$/.test(opItem) ? `__refName(${opItem.slice(1)})` : JSON.stringify(opItem);
             const opStep = typeof o._step === 'string' ? `op ${index}: ${o._step}` : `op ${index} (${op.type})`;
             code += `
-    // Operation ${index}: ${op.type}
+    // Operation ${oneLine(index)}: ${oneLine(op.type)}
     try {
       const result${index} = await (async () => {
         ${opCode}
@@ -4765,7 +4912,24 @@ return __created;
                 // The emitter embeds the id as a literal; a batch ref ($N) is only known
                 // at run time, so it is generated with a placeholder and the runtime
                 // variable put in its place.
-                const single = generateModifyItemCode('__MID__', (op.properties || {})).trim()
+                // A TOP-LEVEL position moves the item, as it places one on create (#42: it reported modified:true and the
+                // item stayed put; only properties were read). properties.x / y / position, when given, win.
+                const modProps = { ...(op.properties || {}) };
+                const pos = op.position;
+                const hasOwn = modProps.x !== undefined || modProps.y !== undefined || modProps.position !== undefined;
+                if (pos !== undefined && !hasOwn) {
+                    const [px, py] = Array.isArray(pos) ? pos : [pos.x, pos.y];
+                    if (typeof px === 'number')
+                        modProps.x = px;
+                    if (typeof py === 'number')
+                        modProps.y = py;
+                }
+                if (!Object.keys(modProps).length) {
+                    return `
+return { success: false, itemId: ${itemRef}, error: 'modify changes nothing: pass properties ({"x": 700}, {"fillColor": "#f00"}) or a top-level position.' };
+`;
+                }
+                const single = generateModifyItemCode('__MID__', modProps).trim()
                     .replace(/"__MID__"/g, '__mid')
                     .replace(/__MID__/g, "' + __mid + '")
                     .replace(/;\s*$/, '');
@@ -4803,14 +4967,55 @@ return { itemId: targetId, animationType: ${JSON.stringify(String(op.animationTy
                     return `
 throw new Error(${JSON.stringify(String(op.relationType) + ': ' + fireIf)});
 `;
+                // No targetId is a relation on the item alone (the engine takes a null target, as staggered_with does); a
+                // custom relation whose compute ignores the target needed a stand-in before.
+                const noTarget = op.targetId === undefined || op.targetId === null || op.targetId === '';
+                // A NAME PATTERN AND AN UPDATE (mcp-server#37). sourceId "dot-*" binds every item named like it, in name
+                // order (dot-2 before dot-10), each with index and count added to its params, so "12 → 20 dots" is
+                // adding members. update: true changes the params of the relation already bound instead of adding one.
+                const glob = typeof op.sourceId === 'string' && op.sourceId.includes('*') && !op.sourceId.startsWith('$');
+                if (glob || op.update === true) {
+                    const type = jsLiteral(String(op.relationType));
+                    const members = glob
+                        ? `const __re = new RegExp(${jsLiteral('^' + String(op.sourceId).split('*').map((p) => p.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$')});
+const __members = app.itemRegistry.getAll()
+  .map((e) => ({ id: e.id || e.itemId, name: (e.item && ((e.item.data && e.item.data.name) || e.item.name)) || '' }))
+  .filter((m) => __re.test(m.name))
+  .sort((a, b) => a.name.localeCompare(b.name, undefined, { numeric: true }));
+if (!__members.length) throw new Error('no item is named like ' + ${jsLiteral(op.sourceId)} + ': name items with properties.name');`
+                        : `const __members = [{ id: ${srcRef} }];
+if (!app.getItemById(__members[0].id)) throw new Error('Source not found: ' + __members[0].id);`;
+                    return `
+${members}
+const targetId = ${noTarget ? 'null' : tgtRef};
+const target = ${noTarget ? 'null' : 'app.getItemById(targetId)'};
+${noTarget ? '' : "if (!target) throw new Error('Target not found: ' + targetId);\n"}${op.update === true ? "if (typeof app.modifyRelationParams !== 'function') throw new Error('this studio cannot change a bound relation (app.modifyRelationParams): update PinePaper Studio');\n" : ''}const __done = [], __failed = [];
+__members.forEach((m, i) => {
+  const __p = Object.assign({}, ${relOpts}${glob ? `, { index: i, count: __members.length, pattern: ${jsLiteral(op.sourceId)} }` : ''});
+  const ok = ${op.update === true
+                        ? `app.modifyRelationParams(m.id, targetId, ${type}, __p) || (targetId === null && app.modifyRelationParams(m.id, undefined, ${type}, __p))`
+                        : glob
+                            // Already bound (a re-run after adding members): its params change, so index and count follow the new set.
+                            ? `((app.relationRegistry && app.relationRegistry.getAssociations(m.id, ${type}).some((a) => a.target === targetId || (targetId === null && a.target == null)) && typeof app.modifyRelationParams === 'function')
+      ? (app.modifyRelationParams(m.id, targetId, ${type}, __p) || (targetId === null && app.modifyRelationParams(m.id, undefined, ${type}, __p)))
+      : app.addRelation(app.getItemById(m.id), target, ${type}, __p))`
+                            : `app.addRelation(app.getItemById(m.id), target, ${type}, __p)`};
+  (ok ? __done : __failed).push(m.id);
+});
+if (!__done.length) {
+  const __why = ${op.update === true ? `'no ' + ${type} + ' relation is bound from ' + __failed.join(', ') + (targetId === null ? '' : ' to ' + targetId) + ' to change: bind it first (a relation op without update)'` : relationRefusalReasonJs(type)};
+  return { success: false, relationType: ${type}, sourceIds: __failed, error: ${op.update === true ? '__why' : `'the studio refused the ' + ${type} + ' relation for ' + __failed.join(', ') + ' — nothing was bound' + (__why ? ': ' + __why : '.')`} };
+}
+return { success: true, relationType: ${type}, ${op.update === true ? 'updated' : 'bound'}: __done, targetId${glob ? ', count: __members.length' : ''}${(() => { const w = relationOptionWarning(op.relationType, op.relationOptions, ['index', 'count', 'pattern']); return w ? `, optionWarning: ${jsLiteral(w)}` : ''; })()}, ...(__failed.length ? { failed: __failed, warning: __failed.length + ' of ' + __members.length + ' were not ${op.update === true ? 'changed' : 'bound'}: ' + __failed.join(', ') } : {}) };
+`;
+                }
                 return `
 const sourceId = ${srcRef};
-const targetId = ${tgtRef};
+const targetId = ${noTarget ? 'null' : tgtRef};
 const source = app.getItemById(sourceId);
-const target = app.getItemById(targetId);
+const target = ${noTarget ? 'null' : 'app.getItemById(targetId)'};
 if (!source) throw new Error('Source not found: ' + sourceId);
-if (!target) throw new Error('Target not found: ' + targetId);
-const relationId = app.addRelation(source, target, ${JSON.stringify(String(op.relationType))}, ${relOpts});
+${noTarget ? '' : "if (!target) throw new Error('Target not found: ' + targetId);\n"}const relationId = app.addRelation(source, target, ${JSON.stringify(String(op.relationType))}, ${relOpts});
 // NOT BOUND IS NOT A SUCCESS (owner rule 1, B119). addRelation answers false
 // when it refuses — spring_follow "not loaded yet" — and this op returned
 // { relationId: false } with nothing marking it failed, so the batch said
@@ -4820,7 +5025,7 @@ if (!relationId) {
   return { success: false, relationId: false, sourceId, targetId, relationType: ${JSON.stringify(op.relationType)},
     error: 'the studio refused the ' + ${JSON.stringify(op.relationType)} + ' relation between ' + sourceId + ' and ' + targetId + ' — nothing was bound' + (__why ? ': ' + __why : '.') };
 }
-return { relationId, sourceId, targetId, relationType: ${JSON.stringify(String(op.relationType))} };
+return { relationId, sourceId, targetId, relationType: ${JSON.stringify(String(op.relationType))}${(() => { const w = relationOptionWarning(op.relationType, op.relationOptions); return w ? `, warning: ${jsLiteral(w)}` : ''; })()} };
 `;
             case 'delete':
                 const delRef = batchRef(op.itemId);
@@ -4876,7 +5081,7 @@ return { success: true, width: (_cs && _cs.width) || ${w}, height: (_cs && _cs.h
                 const foldTarget = mergePlan?.foldedInto.get(index);
                 if (foldTarget !== undefined) {
                     return `
-// Keyframes merged into operation ${foldTarget} (same target). A keyframe track
+// Keyframes merged into operation ${oneLine(foldTarget)} (same target). A keyframe track
 // is replaced wholesale, so emitting both here would silently drop one.
 return { itemId: ${batchRef(op.itemId)}, merged: true, mergedInto: ${foldTarget} };
 `;
@@ -4906,7 +5111,7 @@ return { itemId: ${batchRef(op.itemId)}, merged: true, mergedInto: ${foldTarget}
                 }
                 const kfUnits = op.timeUnits;
                 if (kfUnits === 'seconds' || kfUnits === 'ms')
-                    kfExtra.push(`timeUnits: '${kfUnits}'`);
+                    kfExtra.push(`timeUnits: ${jsLiteral(kfUnits)}`);
                 const kfExtraStr = kfExtra.length > 0 ? `, ${kfExtra.join(', ')}` : '';
                 const kfTextKeysJs = unanimatedTextKeysJs((kfSource || []).flatMap((k) => Object.keys(k.properties ?? {})));
                 const kfTextCheck = kfTextKeysJs ? `\nconst _kfIgnored = ${kfTextKeysJs};` : '';
@@ -4933,12 +5138,12 @@ const targetId = ${maskItemRef};
 const item = app.getItemById(targetId);
 if (!item) throw new Error('Item not found: ' + targetId);
 if (!app.applyAnimatedMask) throw new Error('Mask system not available');
-const maskedGroup = app.applyAnimatedMask(item, '${preset}', ${maskOpts});
+const maskedGroup = app.applyAnimatedMask(item, ${jsLiteral(preset)}, ${maskOpts});
 const maskRej = maskedGroup && maskedGroup.data && maskedGroup.data.maskAnimationRejected;
 if (maskRej) {
   return { success: false, itemId: targetId, error: 'Masked, but animation preset "' + maskRej.requested + '" is unknown — it will NOT animate.', requested: maskRej.requested, known: maskRej.known };
 }
-return { success: !!maskedGroup, itemId: targetId, preset: '${preset}' };
+return { success: !!maskedGroup, itemId: targetId, preset: ${jsLiteral(preset)} };
 `;
             }
             case 'apply_effect': {
@@ -4952,12 +5157,12 @@ if (!item) throw new Error('Item not found: ' + targetId);
 // shape, so an effect the engine refused — an unknown preset, a facade that
 // is not loaded — was recorded as applied. The batch cannot report what the
 // op never tells it.
-const _eff = app.applyEffect(item, '${op.effectType || 'sparkle'}', ${effParams});
+const _eff = app.applyEffect(item, ${jsLiteral(op.effectType || 'sparkle')}, ${effParams});
 if (_eff && (_eff.success === false || _eff.ok === false)) {
-  return { success: false, itemId: targetId, effectType: '${op.effectType || 'sparkle'}',
+  return { success: false, itemId: targetId, effectType: ${jsLiteral(op.effectType || 'sparkle')},
     error: _eff.error || _eff.reason || 'the effect was refused without a reason' };
 }
-return { itemId: targetId, effectType: '${op.effectType || 'sparkle'}' };
+return { itemId: targetId, effectType: ${jsLiteral(op.effectType || 'sparkle')} };
 `;
             }
             case 'play_timeline': {
@@ -5005,7 +5210,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
         if (typeof length === 'number')
             range.length = length;
         return `
-// Read export chunk at ${offset}
+// Read export chunk at ${oneLine(offset)}
 (async function() {
   if (!app.exportEngine || typeof app.exportEngine.readExport !== 'function') {
     return { ok: false, reason: 'app.exportEngine.readExport unavailable — update FxTool' };
@@ -5050,9 +5255,13 @@ 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, motionBlur, 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, startTime } = validated;
         // Encoder options (FxTool 16719759); the schema keeps them to mp4 / webm.
         const videoEncodeOpts = {};
+        // A RANGE of the timeline (FxTool #250): frames for t in [startTime, startTime + duration), each exactly the frame
+        // a full export has at that time (the engine renders the frames before startTime without encoding them).
+        if (startTime !== undefined)
+            videoEncodeOpts.startTime = startTime;
         if (broadcast)
             videoEncodeOpts.broadcast = true;
         // Headroom defaults to 12 with broadcast (retest of caa9560): on a
@@ -5172,10 +5381,10 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
         if (exportFormat === 'srt' || exportFormat === 'vtt' || exportFormat === 'scc') {
             const fmt = exportFormat;
             return `
-// Export: captions (${fmt}) from text items with a lifetime
+// Export: captions (${oneLine(fmt)}) from text items with a lifetime
 (function() {
   if (!app.itemRegistry || typeof app.itemRegistry.getAll !== 'function') {
-    return { success: false, format: '${fmt}', error: 'this studio cannot list items (app.itemRegistry.getAll) — update PinePaper Studio.' };
+    return { success: false, format: ${jsLiteral(fmt)}, error: 'this studio cannot list items (app.itemRegistry.getAll) — update PinePaper Studio.' };
   }
   const texts = app.itemRegistry.getAll().filter(function(e) {
     const it = e && e.item;
@@ -5183,7 +5392,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   });
   const timed = texts.filter(function(e) { return e.item.data && typeof e.item.data.bornAt === 'number'; });
   if (!timed.length) {
-    return { success: false, format: '${fmt}', error: 'no captions to export: no text item has a lifetime. Stage each caption with properties.bornAt / ttl (seconds) on create_item or modify_item, then export ${fmt}.', untimedText: texts.length };
+    return { success: false, format: ${jsLiteral(fmt)}, error: 'no captions to export: no text item has a lifetime. Stage each caption with properties.bornAt / ttl (seconds) on create_item or modify_item, then export ${fmt}.', untimedText: texts.length };
   }
   const end = ${videoDuration};
   const ts = function(t, sep) {
@@ -5203,7 +5412,7 @@ ${fmt === 'scc' ? `  return { success: true, format: 'scc', sccCues: cues, cues:
     return ${fmt === 'srt' ? `(i + 1) + '\\n' + ts(c.start, ',') + ' --> ' + ts(c.stop, ',')` : `ts(c.start, '.') + ' --> ' + ts(c.stop, '.')`} + '\\n' + c.text;
   }).join('\\n\\n') + '\\n';
   const text = ${fmt === 'vtt' ? `'WEBVTT\\n\\n' + body` : 'body'};
-  return { success: true, format: '${fmt}', data: text, mimeType: '${fmt === 'srt' ? 'application/x-subrip' : 'text/vtt'}', size: text.length, cues: cues.length, untimedText: texts.length - timed.length };
+  return { success: true, format: ${jsLiteral(fmt)}, data: text, mimeType: ${jsLiteral(fmt === 'srt' ? 'application/x-subrip' : 'text/vtt')}, size: text.length, cues: cues.length, untimedText: texts.length - timed.length };
 })();`.trim();
         }
         if (exportFormat === 'wav') {
@@ -5253,7 +5462,7 @@ ${fmt === 'scc' ? `  return { success: true, format: 'scc', sccCues: cues, cues:
     bin += String.fromCharCode.apply(null, bytes.subarray(i, i + 8192));
   }
   return {
-    success: true, format: 'wav', platform: '${platform}',
+    success: true, format: 'wav', platform: ${jsLiteral(platform)},
     data: 'data:audio/wav;base64,' + btoa(bin),
     size: bytes.length,
     duration: r.duration, sampleRate: r.sampleRate, sounds: r.sounds, placed: r.placed,
@@ -5264,12 +5473,14 @@ ${fmt === 'scc' ? `  return { success: true, format: 'scc', sccCues: cues, cues:
 })();`.trim();
         }
         return `
-// Smart export for ${platform}
+// Smart export for ${oneLine(platform)}
 (async function() {${ENSURE_EXPORT_ENGINE}
-  const platform = '${platform}';
-  const format = '${exportFormat}';
-  const quality = '${qualityLevel}';
-  const framing = '${framing}';
+  const platform = ${jsLiteral(platform)};
+  const format = ${jsLiteral(exportFormat)};${startTime !== undefined ? `
+  if (format !== 'mp4' && format !== 'webm') return { success: false, format, error: 'startTime exports a range of the timeline, which only mp4 and webm can: ' + format + ' would start from 0.' };
+  if (!(app.exportEngine && app.exportEngine.supportsTimeRange === true)) return { success: false, format, error: 'this studio cannot export a range of the timeline (startTime): update PinePaper Studio, or export from 0.' };` : ''}
+  const quality = ${jsLiteral(qualityLevel)};
+  const framing = ${jsLiteral(framing)};
   // An explicit fps wins over the tier's. The tiers bundle frame rate with
   // compression (draft 15 / standard 30 / high 60), so "higher quality" also
   // doubled the frame count and the render time — a surprise the schema used
@@ -6438,7 +6649,7 @@ ${(() => {
       if (__bs.stale) {
         result.stale = true;
         result.fidelity = result.fidelity || { warnings: [] };
-        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'stale_build', message: 'this studio is running an old build (' + __bs.buildId + '; the live build is ' + __bs.liveBuildId + '): this file was made by the old code. Start a new job (pinepaper_agent_start_job, which reloads it) and export again.' }]);
+        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'stale_build', message: 'this studio is running an old build (' + __bs.buildId + '; the live build is ' + __bs.liveBuildId + '): this file was made by the old code, so it may differ from what the live build makes. pinepaper_clear_canvas (or pinepaper_agent_start_job) loads the live build; it empties the canvas, so rebuild the scene and export again if the difference matters.' }]);
       }
     }
   } catch (_) { /* older studio */ }
@@ -6450,7 +6661,7 @@ ${(() => {
       if (__rl && __rl.enabled) {
         result.fidelity = result.fidelity || { warnings: [] };
         if (['png', 'jpg', 'webp', 'pdf', 'mp4', 'webm'].indexOf(${JSON.stringify(format)}) === -1) {
-          result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'relight_not_applied', message: 'a relight rig is set, but ${format} is not relit. Export png, pdf, mp4 or webm to keep the lighting.' }]);
+          result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'relight_not_applied', message: 'a relight rig is set, but ' + ${jsLiteral(format)} + ' is not relit. Export png, pdf, mp4 or webm to keep the lighting.' }]);
         } else {
           result.relight = { applied: true, lights: (__rl.lights || []).length };
         }
@@ -6681,7 +6892,7 @@ ${(() => {
         const validated = AnimateLetterCollageInputSchema.parse(input);
         const { collageId, animationType, staggerDelay = 0.1, animationSpeed = 1, } = validated;
         return `
-// Animate letter collage: ${collageId}
+// Animate letter collage: ${oneLine(collageId)}
 (function() {
   const collageId = ${JSON.stringify(collageId)};
   const animationType = ${JSON.stringify(animationType)};
@@ -6778,10 +6989,10 @@ ${(() => {
   }
 
   try {
-    const result = await app.mapSystem.loadMap('${mapId}', ${optionsStr});
+    const result = await app.mapSystem.loadMap(${jsLiteral(mapId)}, ${optionsStr});
     return {
       success: true,
-      mapId: result.mapId || '${mapId}',
+      mapId: result.mapId || ${jsLiteral(mapId)},
       // regionPaths is a Map: .length was undefined, so every load reported
       // regions: 0 (gate D3). size, with the feature count as a fallback.
       regions: (result.regions && (result.regions.size ?? result.regions.length)) || (result.geoData && result.geoData.features ? result.geoData.features.length : 0),
@@ -7198,7 +7409,7 @@ ${(() => {
   }
 
   try {
-    const result = await app.mapSystem.importCustomMap('${validated.url}', ${optionsStr});
+    const result = await app.mapSystem.importCustomMap(${jsLiteral(validated.url)}, ${optionsStr});
     // A summary, not the engine's return: that carries the Paper group and
     // the region Map, which serialised into a raw Paper.js dump (gate N1).
     const __r = result && result.regions;
@@ -7316,7 +7527,7 @@ ${(() => {
       loop: ${validated.loop !== false},
       colors: ${colorsStr},${validated.waveSpeed !== undefined ? `
       waveSpeed: ${validated.waveSpeed},` : ''}
-      waveDirection: '${validated.waveDirection || 'horizontal'}'
+      waveDirection: ${jsLiteral(validated.waveDirection || 'horizontal')}
     });
     return { success: true, animatedRegions: result?.animatedRegions || [], totalRegions: result?.totalRegions || 0 };
   } catch (error) {
@@ -7388,7 +7599,7 @@ ${(() => {
       includeSelected: ${validated.includeSelected !== false},
       includeColors: ${validated.includeColors !== false},
       download: ${validated.download === true},
-      filename: '${validated.filename || 'map-regions.csv'}'
+      filename: ${jsLiteral(validated.filename || 'map-regions.csv')}
     });
     return { success: true, csv: result?.csv || '', regionCount: result?.regionCount || 0 };
   } catch (error) {
@@ -7645,7 +7856,7 @@ ${(() => {
 
   const item = (app.getItemById && app.getItemById(${JSON.stringify(itemId)})) || (app.itemRegistry && app.itemRegistry.get && app.itemRegistry.get(${JSON.stringify(itemId)}) && (app.itemRegistry.get(${JSON.stringify(itemId)}).item || app.itemRegistry.get(${JSON.stringify(itemId)})));
   if (!item) {
-    return { success: false, error: 'Item ${itemId} not found' };
+    return { success: false, error: 'Item ' + ${jsLiteral(itemId)} + ' not found' };
   }
 
   try {
@@ -7674,7 +7885,7 @@ ${(() => {
 
   const item = (app.getItemById && app.getItemById(${JSON.stringify(itemId)})) || (app.itemRegistry && app.itemRegistry.get && app.itemRegistry.get(${JSON.stringify(itemId)}) && (app.itemRegistry.get(${JSON.stringify(itemId)}).item || app.itemRegistry.get(${JSON.stringify(itemId)})));
   if (!item) {
-    return { success: false, error: 'Item ${itemId} not found' };
+    return { success: false, error: 'Item ' + ${jsLiteral(itemId)} + ' not found' };
   }
 
   try {
@@ -8047,10 +8258,10 @@ ${(() => {
         const paramsStr = validated.params ? JSON.stringify(validated.params) : '{}';
         const templatesStr = validated.templates ? JSON.stringify(validated.templates) : '[]';
         return `
-// Register custom relation: ${validated.name}
+// Register custom relation: ${oneLine(validated.name)}
 (function() {
   try {
-    app.registerRelationRule('${validated.name}', {
+    app.registerRelationRule(${jsLiteral(validated.name)}, {
       description: ${JSON.stringify(validated.description || '')},
       params: ${paramsStr},
       compute: (ctx) => {
@@ -8064,7 +8275,11 @@ ${(() => {
       continuous: ${validated.continuous !== false},
       priority: ${validated.priority || 0}
     });
-    return { success: true, relationName: '${validated.name}', message: 'Custom relation registered successfully' };
+    // The definition as given, kept on the page so a later call can read it back (pinepaper_lint_scene
+    // customRelations): the engine keeps the compiled rule, not the text an agent would edit.
+    window.__ppCustomRelations = window.__ppCustomRelations || {};
+    window.__ppCustomRelations[${jsLiteral(validated.name)}] = ${jsLiteral({ name: validated.name, ...(validated.description ? { description: validated.description } : {}), params: validated.params ?? {}, computeFunction: validated.computeFunction, applyFunction: validated.applyFunction })};
+    return { success: true, relationName: ${jsLiteral(validated.name)}, message: 'Custom relation registered successfully' };
   } catch (error) {
     return { success: false, error: error.message };
   }
@@ -8095,7 +8310,7 @@ ${(() => {
         // __ppValue with the scene lint beside it, and a throw comes back as { step, itemId, reason }, never a bare
         // message (and never "undefined" for a thrown non-Error).
         return `
-// ${description}
+// ${oneLine(description)}
 (async function() {
   // THE SCENE LINT AFTER THE CODE (FxTool lintScene().warnings): what the scene will show wrong without anything
   // failing (a centred title that runs out of the frame). Carried out under __ppLint; the server moves it beside the
@@ -8151,21 +8366,21 @@ ${(() => {
         // Per-preset options. Custom keyframes are an animated-mask extension —
         // when supplied, fall through to maskingSystem.applyCustomMask instead.
         return `
-// Apply animated mask to ${validated.itemId}
+// Apply animated mask to ${oneLine(validated.itemId)}
 (function() {
   if (!app.applyAnimatedMask) {
     return { success: false, error: 'Mask system not available' };
   }
-  const item = app.getItemById('${validated.itemId}');
-  if (!item) return { success: false, error: 'Item not found: ${validated.itemId}' };
+  const item = app.getItemById(${jsLiteral(validated.itemId)});
+  if (!item) return { success: false, error: 'Item not found: ' + ${jsLiteral(validated.itemId)} };
 
   try {
     const mergedOpts = Object.assign({}, ${optionsStr}, ${maskOptionsStr});
     let maskedGroup;
     if (${keyframesStr} && app.maskingSystem && app.maskingSystem.applyCustomMask) {
-      maskedGroup = app.maskingSystem.applyCustomMask(item, '${customShape}', ${keyframesStr}, mergedOpts);
+      maskedGroup = app.maskingSystem.applyCustomMask(item, ${jsLiteral(customShape)}, ${keyframesStr}, mergedOpts);
     } else {
-      maskedGroup = app.applyAnimatedMask(item, '${preset}', mergedOpts);
+      maskedGroup = app.applyAnimatedMask(item, ${jsLiteral(preset)}, mergedOpts);
     }
     // A mask with an unknown ANIMATION preset still masks — the item just never
     // animates — so !!maskedGroup is true either way. The engine records which.
@@ -8173,13 +8388,13 @@ ${(() => {
     if (rej) {
       return {
         success: false,
-        itemId: '${validated.itemId}',
+        itemId: ${jsLiteral(validated.itemId)},
         error: 'Masked, but the animation preset "' + rej.requested + '" is unknown — it will NOT animate.',
         requested: rej.requested,
         known: rej.known,
       };
     }
-    return { success: !!maskedGroup, itemId: '${validated.itemId}', preset: '${preset}' };
+    return { success: !!maskedGroup, itemId: ${jsLiteral(validated.itemId)}, preset: ${jsLiteral(preset)} };
   } catch (error) {
     return { success: false, error: error.message };
   }
@@ -8191,17 +8406,17 @@ ${(() => {
         const keyframesStr = JSON.stringify(validated.keyframes);
         const maskOptionsStr = validated.maskOptions ? JSON.stringify(validated.maskOptions) : '{}';
         return `
-// Apply custom mask to ${validated.itemId}
+// Apply custom mask to ${oneLine(validated.itemId)}
 (function() {
   if (!app.maskingSystem || !app.maskingSystem.applyCustomMask) {
     return { success: false, error: 'Mask system not available' };
   }
-  const item = app.getItemById('${validated.itemId}');
-  if (!item) return { success: false, error: 'Item not found: ${validated.itemId}' };
+  const item = app.getItemById(${jsLiteral(validated.itemId)});
+  if (!item) return { success: false, error: 'Item not found: ' + ${jsLiteral(validated.itemId)} };
 
   try {
-    const maskedGroup = app.maskingSystem.applyCustomMask(item, '${validated.maskType}', ${keyframesStr}, ${maskOptionsStr});
-    return { success: !!maskedGroup, itemId: '${validated.itemId}', maskType: '${validated.maskType}' };
+    const maskedGroup = app.maskingSystem.applyCustomMask(item, ${jsLiteral(validated.maskType)}, ${keyframesStr}, ${maskOptionsStr});
+    return { success: !!maskedGroup, itemId: ${jsLiteral(validated.itemId)}, maskType: ${jsLiteral(validated.maskType)} };
   } catch (error) {
     return { success: false, error: error.message };
   }
@@ -8211,20 +8426,20 @@ ${(() => {
     generateRemoveMask(input) {
         const validated = RemoveMaskInputSchema.parse(input);
         return `
-// Remove mask from ${validated.itemId}
+// Remove mask from ${oneLine(validated.itemId)}
 (function() {
   if (!app.removeMask) {
     return { success: false, error: 'Mask system not available' };
   }
   // The item id may point at either the masked group OR the original item;
   // app.removeMask expects the masked group, so resolve and walk up if needed.
-  const item = app.getItemById('${validated.itemId}');
-  if (!item) return { success: false, error: 'Item not found: ${validated.itemId}' };
+  const item = app.getItemById(${jsLiteral(validated.itemId)});
+  if (!item) return { success: false, error: 'Item not found: ' + ${jsLiteral(validated.itemId)} };
   const maskedGroup = (item.data && item.data.isMaskedGroup) ? item : (item.parent && item.parent.data && item.parent.data.isMaskedGroup ? item.parent : item);
 
   try {
     app.removeMask(maskedGroup);
-    return { success: true, itemId: '${validated.itemId}', message: 'Mask removed' };
+    return { success: true, itemId: ${jsLiteral(validated.itemId)}, message: 'Mask removed' };
   } catch (error) {
     return { success: false, error: error.message };
   }
@@ -8253,7 +8468,7 @@ ${(() => {
     return { success: false, error: 'app.listAnimatableProperties unavailable — update the studio. The keyframe tool lists the properties it accepts in its own description meanwhile.' };
   }
   const item = app.getItemById(${JSON.stringify(itemId)});
-  if (!item) { return { success: false, error: 'no item ${itemId}' }; }
+  if (!item) { return { success: false, error: 'no item ' + ${jsLiteral(itemId)} }; }
   const r = app.listAnimatableProperties(item);
   return { success: true, ...r };
 })();`.trim();
@@ -8351,7 +8566,7 @@ ${(() => {
     generateApplyTemplate(input) {
         const { templateId, category, listOnly } = input;
         if (listOnly || !templateId) {
-            const categoryFilter = category ? `'${category}'` : 'null';
+            const categoryFilter = category ? jsLiteral(category) : 'null';
             return `
 // List available templates
 (async function() {
@@ -8379,7 +8594,7 @@ ${(() => {
 `.trim();
         }
         return `
-// Apply template: ${templateId}
+// Apply template: ${oneLine(templateId)}
 (async function() {
   if (!app.templateManager) {
     return { error: 'Template manager not available. Make sure PinePaper Studio is loaded.' };
@@ -8426,7 +8641,7 @@ ${(() => {
     let fidelity = {};
     try {
       const tpl = (app.templateManager.getAllTemplates() || [])
-        .find(function(t) { return t && (t.id === '${templateId}' || t.templateId === '${templateId}'); });
+        .find(function(t) { return t && (t.id === ${jsLiteral(templateId)} || t.templateId === ${jsLiteral(templateId)}); });
       const items = tpl && tpl.data && Array.isArray(tpl.data.items) ? tpl.data.items : null;
       const declared = items ? items.filter(function(i) { return i && i.type === 'group' && i.paperJSON; }).length : 0;
       if (declared > 0 && app.itemRegistry && typeof app.itemRegistry.getAll === 'function') {
@@ -8447,7 +8662,7 @@ ${(() => {
       }
     } catch (e) { /* a check that cannot run must not fail the load */ }
 
-    return { success: true, templateId: '${templateId}', message: 'Template applied successfully. Canvas has been replaced with template content.', ...fidelity };
+    return { success: true, templateId: ${jsLiteral(templateId)}, message: 'Template applied successfully. Canvas has been replaced with template content.', ...fidelity };
   } catch (e) {
     return { error: 'Failed to apply template: ' + e.message };
   }
@@ -8497,7 +8712,7 @@ ${(() => {
     // The bytes then go in as a DATA URL, which img.src loads without touching
     // the network again — so a host that allows fetch but blocks the image
     // load (CORS on <img>, a tainted-canvas refusal) now works too.
-    let src = '${url}';
+    let src = ${jsLiteral(url)};
     // A STAGED KEY, not the bytes. The handler writes anything over ~64KB to
     // window.__ppStage and passes the key instead, because the governor's
     // loop-guard transform bails on a code string that large and takes the
@@ -8559,7 +8774,7 @@ ${mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask builds
     // refused instead of answered with the raster's bounds.
     const masked = app.imageTools.applyMask(raster, ${JSON.stringify(mask)});
     if (!masked) {
-      return { success: false, itemId: itemId, error: 'the ${mask} mask was not applied — the image may not be a raster yet. The unmasked image is on the canvas as ' + itemId + '.' };
+      return { success: false, itemId: itemId, error: 'the ' + ${jsLiteral(mask)} + ' mask was not applied — the image may not be a raster yet. The unmasked image is on the canvas as ' + itemId + '.' };
     }
     if (app.itemRegistry && typeof app.itemRegistry.rebind === 'function') app.itemRegistry.rebind(itemId, masked);
     placed = masked;
@@ -8586,7 +8801,7 @@ ${mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask builds
       success: true,
       itemId: itemId,
       message: 'Image imported and placed on canvas.',${name ? `\n      name: ${JSON.stringify(name)},` : ''}
-      bounds: { x: b.x, y: b.y, width: b.width, height: b.height }${mask ? `,\n      mask: '${mask}'` : ''}${hasShadow ? ',\n      shadow: __shadow' : ''},
+      bounds: { x: b.x, y: b.y, width: b.width, height: b.height }${mask ? `,\n      mask: ${jsLiteral(mask)}` : ''}${hasShadow ? ',\n      shadow: __shadow' : ''},
       // Stored smaller than its source (the studio's cap): said, with the
       // way to keep every pixel. The studio reports native size where it can.
       ...((entry && entry.nativeWidth && entry.width && entry.nativeWidth > entry.width)
@@ -8680,7 +8895,7 @@ ${mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask builds
 (function() {
   ${guard}
   const scene = app.sceneManager.getScene(${JSON.stringify(input.sceneId)});
-  if (!scene) return { error: 'Scene not found: ${input.sceneId}' };
+  if (!scene) return { error: 'Scene not found: ' + ${jsLiteral(input.sceneId)} };
   return { success: true, action: 'info', scene: scene };
 })();
 `.trim();
@@ -8960,8 +9175,17 @@ ${input.cutSound !== undefined ? `  const __cuts = (__cr && __cr.cuts) || (app.s
             }
             case 'modify': {
                 const ch = { ...(v.params ? { params: v.params } : {}), ...(v.members ? { members: v.members } : {}), ...(v.window !== undefined ? { window: v.window } : {}) };
+                // A pattern made with members as a plain array is stored as { refs }, a
+                // shape the engine's own re-check does not accept, so a params-only
+                // modify of it failed with "members is …" (PATIMG24). The stored refs
+                // are handed back as the array they came from.
+                const keep = v.members ? '' : `
+  const __cur = typeof app.getPattern === 'function' ? app.getPattern(${S(v.id)}) : null;
+  const __m = __cur && __cur.spec && __cur.spec.members;
+  if (__m && Array.isArray(__m.refs)) __ch.members = __m.refs.slice();`;
                 body = `${need('modifyPattern')}
-  const r = app.modifyPattern(${S(v.id)}, ${S(ch)});
+  const __ch = ${S(ch)};${keep}
+  const r = app.modifyPattern(${S(v.id)}, __ch);
   return Object.assign({ success: !!(r && r.ok) }, r || {}, app.lastReceipt ? { receipt: app.lastReceipt } : {});`;
                 break;
             }
@@ -9144,7 +9368,7 @@ ${input.cutSound !== undefined ? `  const __cuts = (__cr && __cr.cuts) || (app.s
       selected.push(id);
     }
   }
-  return { success: true, action: 'select', mode: '${mode}', selected };
+  return { success: true, action: 'select', mode: ${jsLiteral(mode)}, selected };
 })();`.trim();
             }
             case 'select_all':
@@ -9201,7 +9425,7 @@ ${input.cutSound !== undefined ? `  const __cuts = (__cr && __cr.cuts) || (app.s
      */
     _facadeCall(method, args, label) {
         return `
-// ${label}
+// ${oneLine(label)}
 (async function() {
   if (typeof app.${method} !== 'function') {
     return { success: false, error: 'app.${method}() unavailable — update PinePaper Studio to a build that has it.' };
@@ -9223,7 +9447,7 @@ ${input.cutSound !== undefined ? `  const __cuts = (__cr && __cr.cuts) || (app.s
         // studios, and a brand must not cross between them.
         if (input.action === 'get' || input.action === 'clear') {
             return `
-// Brand kit: ${input.action} the active brand
+// Brand kit: ${oneLine(input.action)} the active brand
 (function() {
   const b = (typeof window !== 'undefined' && window.__ppActiveBrand) || null;
   ${input.action === 'clear' ? 'if (typeof window !== "undefined") window.__ppActiveBrand = null;' : ''}
@@ -9480,7 +9704,7 @@ ${loads}
     __src = raster.url;
   }`;
         const call = (method, args, label) => `
-// ${label}
+// ${oneLine(label)}
 (async function() {
   if (typeof app.${method} !== 'function') {
     return { success: false, error: 'app.${method}() unavailable — update PinePaper Studio to a build that has it.' };
@@ -9624,7 +9848,7 @@ ${resolveSource}
             case 'fit': {
                 const mode = input.mode || 'contain';
                 return `
-// Fit item to the export frame (${mode})
+// Fit item to the export frame (${oneLine(mode)})
 (function() {
   // Route through the agent facade, not app.fitToFrame directly: an agent that
   // just called upload_video holds a MEDIA id (vraster_…), which is a different
@@ -9667,7 +9891,7 @@ ${resolveSource}
             case 'flip': {
                 const dir = input.direction || 'horizontal';
                 return `
-// Flip item ${dir}ly
+// Flip item ${oneLine(dir)}ly
 (function() {
   const entry = app.itemRegistry.get(${ID});
   if (!entry || !entry.item) return { error: 'Item not found: ' + ${ID} };
@@ -9688,7 +9912,7 @@ ${resolveSource}
                 if (needsSibling) {
                     const siblingExpr = order === 'moveUp' ? 'entry.item.nextSibling' : 'entry.item.previousSibling';
                     return `
-// Reorder item: ${order}
+// Reorder item: ${oneLine(order)}
 (function() {
   const entry = app.itemRegistry.get(${ID});
   if (!entry || !entry.item) return { error: 'Item not found: ' + ${ID} };
@@ -9698,7 +9922,7 @@ ${resolveSource}
 })();`.trim();
                 }
                 return `
-// Reorder item: ${order}
+// Reorder item: ${oneLine(order)}
 (function() {
   const entry = app.itemRegistry.get(${ID});
   if (!entry || !entry.item) return { error: 'Item not found: ' + ${ID} };
@@ -9788,7 +10012,7 @@ ${resolve}
     // otherwise; a falsy answer is a refusal it did not raise.
     if (r === false || r === null) {
       return { success: false, action: 'apply', itemId: ${JSON.stringify(input.itemId)},
-        error: 'the filter did not apply — ${input.filterName || ''} may not be available on this studio.' };
+        error: 'the filter did not apply — ' + ${jsLiteral(input.filterName || '')} + ' may not be available on this studio.' };
     }
     return { success: true, action: 'apply', itemId: ${JSON.stringify(input.itemId)}, filter: ${JSON.stringify(input.filterName || '')} };
   } catch (e) {
@@ -10143,7 +10367,7 @@ ${resolve}
 // Get item details by ID
 (function() {
   const entry = app.itemRegistry.get(${JSON.stringify(input.itemId || '')});
-  if (!entry || !entry.item) return { error: 'Item not found: ${input.itemId}' };
+  if (!entry || !entry.item) return { error: 'Item not found: ' + ${jsLiteral(input.itemId)} };
   const item = entry.item;
   return {
     success: true, action: 'get_by_id',
@@ -10443,8 +10667,8 @@ ${resolve}
   ${guard}
   const entry = app.itemRegistry.get(${itemIdStr});
   if (!entry || !entry.item) return { error: 'Item not found: ' + ${itemIdStr} };
-  app.deformPresets.apply(entry.item, '${input.preset}', ${JSON.stringify(params)});
-  return { success: true, action: 'apply', itemId: ${itemIdStr}, preset: '${input.preset}' };
+  app.deformPresets.apply(entry.item, ${jsLiteral(input.preset)}, ${JSON.stringify(params)});
+  return { success: true, action: 'apply', itemId: ${itemIdStr}, preset: ${jsLiteral(input.preset)} };
 })();`.trim();
             }
             case 'trigger': {
@@ -10464,8 +10688,8 @@ ${resolve}
   ${guard}
   const entry = app.itemRegistry.get(${itemIdStr});
   if (!entry || !entry.item) return { error: 'Item not found: ' + ${itemIdStr} };
-  app.deformPresets.trigger(entry.item, '${input.preset}', ${JSON.stringify(params)});
-  return { success: true, action: 'trigger', itemId: ${itemIdStr}, preset: '${input.preset}' };
+  app.deformPresets.trigger(entry.item, ${jsLiteral(input.preset)}, ${JSON.stringify(params)});
+  return { success: true, action: 'trigger', itemId: ${itemIdStr}, preset: ${jsLiteral(input.preset)} };
 })();`.trim();
             }
             case 'remove': {
@@ -10718,8 +10942,8 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
 // Export sprite sheet
 (async function() {
   ${guard}
-  const result = await app.exportSpriteSheet(${JSON.stringify(input.spriteSheetId || '')}, { format: '${input.format || 'png'}', download: true, includeMetadata: true });
-  return { success: true, action: 'export', format: '${input.format || 'png'}' };
+  const result = await app.exportSpriteSheet(${JSON.stringify(input.spriteSheetId || '')}, { format: ${jsLiteral(input.format || 'png')}, download: true, includeMetadata: true });
+  return { success: true, action: 'export', format: ${jsLiteral(input.format || 'png')} };
 })();`.trim();
             default:
                 return `(function() { return { error: 'Unknown sprite sheet action: ${input.action}' }; })();`;
@@ -10740,8 +10964,8 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
   ${guard}
   const entry = app.itemRegistry.get(${itemIdStr});
   if (!entry || !entry.item) return { error: 'Item not found: ' + ${itemIdStr} };
-  const behaviorId = app.interactionSystem.addContinuousBehavior(entry.item, '${input.behaviorType}', ${params});
-  return { success: true, action: 'add_behavior', itemId: ${itemIdStr}, behaviorType: '${input.behaviorType}', behaviorId };
+  const behaviorId = app.interactionSystem.addContinuousBehavior(entry.item, ${jsLiteral(input.behaviorType)}, ${params});
+  return { success: true, action: 'add_behavior', itemId: ${itemIdStr}, behaviorType: ${jsLiteral(input.behaviorType)}, behaviorId };
 })();`.trim();
             }
             case 'remove_behavior': {
@@ -10798,8 +11022,8 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
 // Trigger interaction action
 (function() {
   ${guard}
-  app.interactionSystem.executeAction('${input.actionType}', ${params});
-  return { success: true, action: 'trigger_action', actionType: '${input.actionType}' };
+  app.interactionSystem.executeAction(${jsLiteral(input.actionType)}, ${params});
+  return { success: true, action: 'trigger_action', actionType: ${jsLiteral(input.actionType)} };
 })();`.trim();
             }
             case 'get_state':
@@ -11226,14 +11450,14 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
         }[input.action];
         const id = JSON.stringify(input.itemId);
         return `
-// Arrange ${input.itemId} → ${input.action}
+// Arrange ${oneLine(input.itemId)} → ${oneLine(input.action)}
 (function() {
   const item = app.getItemById(${id});
   if (!item) return { success: false, error: 'Item not found: ' + ${id} };
   if (typeof app.${method} !== 'function') return { success: false, error: 'app.${method} unavailable — update FxTool' };
   app.select(${id});
   app.${method}();
-  return { success: true, itemId: ${id}, action: '${input.action}' };
+  return { success: true, itemId: ${id}, action: ${jsLiteral(input.action)} };
 })();`.trim();
     }
     /**
@@ -11266,7 +11490,7 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
             ...(input.queries !== undefined ? { queries: input.queries } : {}),
         });
         return `
-// Detect objects${input.queries !== undefined ? ' (open-vocabulary / OWL-ViT)' : ''}${input.asNodes ? ' (asNodes — relational compositing)' : ''}
+// Detect objects${oneLine(input.queries !== undefined ? ' (open-vocabulary / OWL-ViT)' : '')}${oneLine(input.asNodes ? ' (asNodes — relational compositing)' : '')}
 (async function() {
   if (typeof app.detectObjects !== 'function') {
     return { success: false, error: 'app.detectObjects unavailable — update FxTool to a build that exposes on-device object detection on app' };
@@ -11296,7 +11520,7 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
             ...(input.id !== undefined ? { id: input.id } : {}),
         };
         return `
-// Styled scene${input.style ? ` (${input.style.replace(/[\r\n]/g, ' ')})` : ''}
+// Styled scene${input.style ? ` (${oneLine(input.style.replace(/[\r\n]/g, ' '))})` : ''}
 (async function() {
   if (typeof app.styledScene !== 'function') { return { success: false, error: 'app.styledScene unavailable — update FxTool' }; }
   const r = await app.styledScene(${JSON.stringify(input.spec ?? {})}, ${JSON.stringify(opts)});
@@ -11316,7 +11540,7 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
             ...(input.threshold !== undefined ? { threshold: input.threshold } : {}),
         });
         return `
-// Extract object${input.label ? ` "${input.label}"` : ''} from the image
+// Extract object${input.label ? ` ${jsLiteral(input.label)}` : ''} from the image
 (async function() {
   if (typeof app.extractObject !== 'function') {
     return { success: false, error: 'app.extractObject unavailable — update FxTool to a build that exposes on-device object detection on app' };
@@ -11406,7 +11630,7 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
         if (input.action === 'break_apart') {
             const idExpr = JSON.stringify(input.itemId || '');
             return `
-// Break apart ${input.itemId || ''} into movable parts
+// Break apart ${oneLine(input.itemId || '')} into movable parts
 (function() {
   if (typeof app.breakApart !== 'function') return { success: false, error: 'app.breakApart unavailable — update FxTool to a build with SVG/group segmentation' };
   const target = app.getItemById(${idExpr});
@@ -11421,7 +11645,7 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
         if (input.action === 'ungroup') {
             const idExpr = JSON.stringify(input.groupId || '');
             return `
-// Ungroup ${input.groupId || ''}
+// Ungroup ${oneLine(input.groupId || '')}
 (function() {
   if (!app.groupManager) return { success: false, error: 'GroupManager not available — update FxTool' };
   const gid = ${idExpr};
@@ -11435,7 +11659,7 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
         const idsArrayExpr = JSON.stringify(input.itemIds ?? []);
         const nameExpr = input.groupName !== undefined ? JSON.stringify(input.groupName) : 'undefined';
         return `
-// Group ${(input.itemIds || []).length} items${input.groupName ? ` as "${input.groupName}"` : ''}
+// Group ${oneLine((input.itemIds || []).length)} items${input.groupName ? ` as ${jsLiteral(input.groupName)}` : ''}
 (function() {${this.groupCodeBody(idsArrayExpr, nameExpr)}
 })();`.trim();
     }
@@ -11485,7 +11709,7 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
         const duration = input.duration ?? 5;
         const n = Math.min(1200, Math.max(3, Math.round(duration * fps)));
         return `
-// Accessibility measurements (${checks.join(', ')})
+// Accessibility measurements (${oneLine(checks.join(', '))})
 (async function() {
   const out = { success: true, fps: ${fps}, duration: ${duration} };
   const rgba = function(c) {
@@ -11642,7 +11866,7 @@ ${checks.includes('contrast') ? `  // SAMPLED OVER TIME (round 12, 12.9): text i
         const mime = sheet.format === 'png' ? 'image/png' : 'image/jpeg';
         const S = (v) => JSON.stringify(v);
         return `
-// Contact sheet of ${n} frame(s)
+// Contact sheet of ${oneLine(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' };
@@ -11718,7 +11942,7 @@ ${checks.includes('contrast') ? `  // SAMPLED OVER TIME (round 12, 12.9): text i
         // tool call that screenshots next wants that to have happened.
         const engineOptsJson = JSON.stringify({ canvas: input.canvas, defaultGeometry: input.defaultGeometry, awaitImages: true });
         return `
-// Instantiate ontology → scene (${ops.filter((o) => o.op === 'create').length} items, ${ops.filter((o) => o.op === 'addRelation').length} relations)
+// Instantiate ontology → scene (${oneLine(ops.filter((o) => o.op === 'create').length)} items, ${oneLine(ops.filter((o) => o.op === 'addRelation').length)} relations)
 (async function() {
   // Engine door first: the studio's own OntologyCompiler reads every node facet
   // (geometry, paint, text, the keyframe track, masks) and builds through the
@@ -11803,10 +12027,60 @@ ${checks.includes('contrast') ? `  // SAMPLED OVER TIME (round 12, 12.9): text i
     return { success: false, error: 'app.lintScene unavailable — update FxTool to a build with the relational linter (S12-E2)' };
   }
   const result = app.lintScene(${optsJson});
+  // THE RELATIONS AS BOUND, so a later agent can find the one to edit without exporting the scene to read it:
+  // from, to, type and params, capped. And the custom relation definitions registered on this page, as given.
+  const __rels = [];
+  let __relCount = 0;
+  try {
+    const __rr = app.relationRegistry;
+    const __active = __rr && typeof __rr.queryActive === 'function' ? __rr.queryActive() : [];
+    __active.forEach((e) => (e.associations || []).forEach((a) => {
+      __relCount++;
+      if (__rels.length >= ${RELATIONS_READBACK_CAP}) return;
+      const __name = e.item && e.item.data && e.item.data.name;
+      __rels.push({ from: e.itemId, ...(__name ? { fromName: __name } : {}), to: a.target === undefined ? null : a.target, type: a.relation, params: a.params || {} });
+    }));
+  } catch (e) { /* the relations are an addition; the lint stands without them */ }
+  const __custom = (typeof window !== 'undefined' && window.__ppCustomRelations) ? Object.values(window.__ppCustomRelations) : [];
+  // HOW TO CHANGE IT (#43): an editing agent needs the op, not the schemas. Each relation comes with the batch op that
+  // changes it; a group bound by a name pattern ("dot-*", recorded in each member's params) comes once, with the ops
+  // that add and remove a member; a custom motion with the call that redefines it.
+  const __edit = { hint: 'To change this scene, send the ops below (your values in relationOptions) in ONE pinepaper_agent_batch_execute call; a custom motion changes by sending its pinepaper_register_custom_relation call again.', groups: [], relations: [], customRelations: [] };
+  try {
+    const __byPat = new Map();
+    __rels.forEach((r) => {
+      const pat = r.params && r.params.pattern;
+      if (typeof pat === 'string') {
+        const k = pat + '|' + r.type + '|' + r.to;
+        if (!__byPat.has(k)) __byPat.set(k, { pattern: pat, type: r.type, to: r.to, members: [] });
+        __byPat.get(k).members.push(r);
+        return;
+      }
+      __edit.relations.push({ from: r.from, ...(r.fromName ? { fromName: r.fromName } : {}), to: r.to, relationType: r.type,
+        change: { type: 'relation', sourceId: r.fromName || r.from, ...(r.to != null ? { targetId: r.to } : {}), relationType: r.type, update: true, relationOptions: r.params } });
+    });
+    __byPat.forEach((g) => {
+      const base = Object.assign({}, g.members[0].params); delete base.index; delete base.count; delete base.pattern;
+      const names = g.members.map((m) => m.fromName).filter(Boolean).sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+      const prefix = g.pattern.split('*')[0];
+      const nums = names.map((n) => Number(n.slice(prefix.length))).filter((n) => Number.isFinite(n));
+      const next = prefix + (nums.length ? Math.max.apply(null, nums) + 1 : g.members.length + 1);
+      const firstEntry = app.itemRegistry.get(g.members[0].from);
+      const bind = { type: 'relation', sourceId: g.pattern, ...(g.to != null ? { targetId: g.to } : {}), relationType: g.type, relationOptions: base };
+      __edit.groups.push({ pattern: g.pattern, relationType: g.type, members: g.members.length, ...(names.length ? { first: names[0], last: names[names.length - 1] } : {}), relationOptions: base,
+        change: Object.assign({}, bind, { update: true }),
+        addMember: [{ type: 'create', itemType: (firstEntry && firstEntry.type) || 'circle', position: [0, 0], properties: { name: next } }, bind],
+        ...(names.length ? { removeMember: [{ type: 'delete', itemId: names[names.length - 1] }, bind] } : {}) });
+    });
+    __custom.forEach((d) => __edit.customRelations.push({ name: d.name, change: { tool: 'pinepaper_register_custom_relation', args: d } }));
+  } catch (e) { /* the read-back stands without the edit ops */ }
   // warnings: what the engine's own rules found (TEXT_CLIPS_FRAME: a centre-anchored text running past the
   // frame edge). Passed through when the studio reports them; an older studio has none to pass.
   return { success: true, density: result.density, suggestions: result.suggestions,
-    ...(Array.isArray(result.warnings) && result.warnings.length ? { warnings: result.warnings } : {}) };
+    ...(Array.isArray(result.warnings) && result.warnings.length ? { warnings: result.warnings } : {}),
+    relations: __rels, ...(__relCount > __rels.length ? { relationsShown: __rels.length, relationCount: __relCount } : {}),
+    ...(__custom.length ? { customRelations: __custom } : {}),
+    ...(__edit.groups.length || __edit.relations.length || __edit.customRelations.length ? { edit: __edit } : {}) };
 })();`.trim();
     }
     /**
@@ -11837,11 +12111,11 @@ ${checks.includes('contrast') ? `  // SAMPLED OVER TIME (round 12, 12.9): text i
     if (u.indexOf('data:') !== 0) return u;
     const comma = u.indexOf(',');
     const meta = u.slice(5, comma);
-    const mime = meta.split(';')[0] || '${kind === 'audio' ? 'audio/mpeg' : 'video/mp4'}';
+    const mime = meta.split(';')[0] || ${jsLiteral(kind === 'audio' ? 'audio/mpeg' : 'video/mp4')};
     const body = u.slice(comma + 1);
     const bin = /;base64/i.test(meta) ? atob(body) : decodeURIComponent(body);
     const bytes = Uint8Array.from(bin, function(c) { return c.charCodeAt(0); });
-    const ext = (mime.split('/')[1] || '${kind === 'audio' ? 'mp3' : 'mp4'}').replace(/[^a-z0-9]/gi, '');
+    const ext = (mime.split('/')[1] || ${jsLiteral(kind === 'audio' ? 'mp3' : 'mp4')}).replace(/[^a-z0-9]/gi, '');
     return new File([bytes], '${kind}.' + ext, { type: mime });
   })(${JSON.stringify(url ?? '')})`;
         // TWO ID SPACES, AND THE CALLER HOLDS THE WRONG ONE.
@@ -11950,7 +12224,7 @@ ${input.timeOffset !== undefined ? `  // Moving the clip is the 4th argument, wh
             // refusals come back as {ok:false, reason} and are errors here.
             case 'split':
                 return `
-// Split a media clip at canvas time ${input.at}
+// Split a media clip at canvas time ${oneLine(input.at)}
 (async function() {
 ${guard}
   if (typeof A.splitMedia !== 'function') { return { success: false, action: 'split', error: 'this studio is too old to split a clip (no splitMedia) — nothing was changed.' }; }
@@ -11960,7 +12234,7 @@ ${guard}
 })();`.trim();
             case 'add_transition':
                 return `
-// ${input.transition?.type ?? 'crossfade'} between ${input.fromItemId} and ${input.toItemId}
+// ${oneLine(input.transition?.type ?? 'crossfade')} between ${oneLine(input.fromItemId)} and ${oneLine(input.toItemId)}
 (function() {
 ${guard}
   if (typeof A.addTransition !== 'function') { return { success: false, action: 'add_transition', error: 'this studio is too old for clip transitions (no addTransition) — nothing was changed.' }; }
@@ -12082,7 +12356,7 @@ ${guard}
                     ...(input.live !== undefined ? { live: input.live } : {}),
                 });
                 return `
-// Track matte: the matte item's ${input.channel || 'luma'} drives the target's alpha${input.live ? ' (LIVE — re-cuts as the matte animates)' : ''}
+// Track matte: the matte item's ${oneLine(input.channel || 'luma')} drives the target's alpha${oneLine(input.live ? ' (LIVE — re-cuts as the matte animates)' : '')}
 (async function() {
   // A media id (vraster_ / araster_, what upload returns) is resolved to the
   // registry id these app facades take (round 10, 10.12).
@@ -12167,7 +12441,7 @@ ${guard}
                     ...(input.fontSize !== undefined ? { fontSize: input.fontSize } : {}),
                 });
                 return `
-// Display text style: ${input.styleKey} — stacked-layer title, id adopted from the text
+// Display text style: ${oneLine(input.styleKey)} — stacked-layer title, id adopted from the text
 (async function() {
   if (typeof app.applyTextStyle !== 'function') { return { success: false, error: 'app.applyTextStyle unavailable — update FxTool to a text-styles build' }; }
   // LOAD THE FACES FIRST. The decorative stylesheet is fetched on pointerenter
@@ -12318,7 +12592,7 @@ ${guard}
         const S = (v) => JSON.stringify(v);
         const id = S(input.itemId);
         return `
-// Choreograph ${input.beats.length} beat(s) for ${input.itemId}
+// Choreograph ${oneLine(input.beats.length)} beat(s) for ${oneLine(input.itemId)}
 (function() {
   const __it = (app.getItemById && app.getItemById(${id}))
     || (app.itemRegistry && app.itemRegistry.get && (app.itemRegistry.get(${id}) || {}).item);
@@ -12426,7 +12700,7 @@ ${input.sound ? `  // SOUND ON THE ACTION (D68): one placed sound per moment the
         const cam = input.camera === true ? { fill: 0.45 } : (input.camera || null);
         const sound = input.sound === true ? 'whoosh' : (input.sound || null);
         return `
-// Morph sequence: ${states.length} state(s)
+// Morph sequence: ${oneLine(states.length)} state(s)
 (function() {
   const src = app.getItemById && app.getItemById(${S(input.itemId)});
   if (!src) { return { success: false, error: ${S(input.itemId)} + ' is not on the canvas.' }; }
@@ -12903,7 +13177,7 @@ ${cam ? `  // The camera rides the SAME timing: framing each state as its morph
             }
         })();
         return `
-// Shader graph: ${input.action}
+// Shader graph: ${oneLine(input.action)}
 (async function() {
 ${head}
 ${body}
@@ -12924,7 +13198,7 @@ ${body}
                 // 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}
+// Medium: apply ${oneLine(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 ?? {})});
@@ -13118,7 +13392,7 @@ ${body}
                     ...(input.keepSource !== undefined ? { keepSource: input.keepSource } : {}),
                 });
                 return `
-// Text effect: ${input.effect} — the text becomes one animated item PER CHARACTER
+// Text effect: ${oneLine(input.effect)} — the text becomes one animated item PER CHARACTER
 (async function() {
   if (typeof app.applyTextEffect !== 'function') { return { success: false, error: 'app.applyTextEffect unavailable — update FxTool to a text-effects build' }; }
   const r = await app.applyTextEffect(${S(input.itemId)}, ${S(input.effect)}, ${opts});
@@ -13190,7 +13464,7 @@ ${body}
             ...(input.keepSource !== undefined ? { keepSource: input.keepSource } : {}),
         });
         return `
-// Shatter ${input.itemId} into tiles (inert until animated — that is the point)
+// Shatter ${oneLine(input.itemId)} into tiles (inert until animated — that is the point)
 (function() {
   if (typeof app.shatterImage !== 'function') { return { success: false, error: 'app.shatterImage unavailable — update FxTool to a shatter-capable build' }; }
   const r = app.shatterImage(${S(input.itemId)}, ${opts});
@@ -13325,7 +13599,10 @@ ${body}
         const needWorld = `  if (!app._world3d) { return { success: false, error: "no 3D world — call pinepaper_world3d create first" }; }`;
         switch (input.action) {
             case 'create': {
-                const opts = S({ ...(input.character !== undefined ? { character: input.character } : {}) });
+                if (input.control === true && input.character === false) {
+                    return `({ success: false, error: ${jsLiteral('control: true walks the character, and character: false leaves it out. Nothing was made. Drop one of the two.')} });`;
+                }
+                const opts = S({ ...(input.character !== undefined ? { character: input.character } : {}), ...(input.control === true ? { control: true } : {}) });
                 return `
 // World3D: create — terrain, sky, shadows, walkable character, under the Paper canvas
 (async function() {
@@ -13338,7 +13615,11 @@ ${body}
   // 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 };
+  // What the world reports, not what was asked: an engine without the option takes the world and ignores control.
+  const result = { success: true, action: 'create', spec: ${S(input.spec ?? 'forest')}, configurableKeys: keys };${input.control === true ? `
+  result.control = !!(app._world3d && app._world3d.controlEnabled);
+  if (!result.control) result.warning = 'control was asked for and this studio did not turn it on: the character cannot be walked with the keyboard. Update PinePaper Studio.';` : ''}
+  return result;
 })();`.trim();
             }
             case 'describe':
@@ -13368,7 +13649,7 @@ ${needWorld}
                     ...(input.live !== undefined ? { live: input.live } : {}),
                 });
                 return `
-// World3D: put an actor on the stage${input.live ? ' (live sprite — a rigged character PERFORMS, not a photograph of itself)' : ''}
+// World3D: put an actor on the stage${oneLine(input.live ? ' (live sprite — a rigged character PERFORMS, not a photograph of itself)' : '')}
 (function() {
   if (typeof app.addWorldActor !== 'function') { return { success: false, error: 'app.addWorldActor unavailable — update FxTool' }; }
 ${needWorld}
@@ -13471,7 +13752,7 @@ ${needWorld}
                     mesh.uniforms = uniforms;
                 }
                 return `
-// World3D: ${input.action} — a canvas path becomes real geometry
+// World3D: ${oneLine(input.action)} — a canvas path becomes real geometry
 (async function() {
   // @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' }; }
@@ -13578,7 +13859,7 @@ ${needWorld}
             case 'import_gltf': {
                 const fn = input.action === 'import_obj' ? 'importOBJToWorld' : 'importGLTFToWorld';
                 return `
-// World3D: ${input.action}
+// World3D: ${oneLine(input.action)}
 (async function() {
   // @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' }; }
@@ -13780,7 +14061,7 @@ ${needWorld}
     generateDesignCompose(scene, ops, style, sizeWarning, report = {}) {
         const S = (v) => JSON.stringify(v);
         return `
-// Design: compose a ${style} scene — ${ops.length} items, laid out server-side
+// Design: compose a ${oneLine(style)} scene — ${oneLine(ops.length)} items, laid out server-side
 (function() {
   if (typeof app.create !== 'function') { return { success: false, error: 'app.create unavailable — update FxTool' }; }
   const size = ${S({ width: scene.width, height: scene.height })};
@@ -13860,7 +14141,7 @@ ${needWorld}
         }
         const fn = action === 'figure' ? 'stickFigure' : 'stickSet';
         return `
-// Stick: ${action}
+// Stick: ${oneLine(action)}
 (async function() {
   // @engine-methods stickFigure stickSet
   if (typeof app.${fn} !== 'function') { return { success: false, error: 'app.${fn} unavailable — update FxTool (the stick kit is vendored from mcp-cloud)' }; }
@@ -13954,7 +14235,7 @@ ${needWorld}
             case 'export_dotlottie': {
                 const fn = input.action === 'export_lottie' ? 'exportLottie' : 'exportDotLottie';
                 return `
-// Interchange: ${fn}
+// Interchange: ${oneLine(fn)}
 (async function() {
 ${guard(fn)}
   ${TO_DATA_URL_JS}
@@ -14071,7 +14352,7 @@ ${guard('exportPNGSequence')}
         const S = (v) => JSON.stringify(v);
         const guard = (fn) => `  if (typeof app.${fn} !== 'function') { return { success: false, error: 'app.${fn} unavailable — update FxTool' }; }`;
         const simple = (fn, args, key, label) => key === 'played' ? `
-// Sound: ${label}
+// Sound: ${oneLine(label)}
 (function() {
 ${guard(fn)}
   // A play that returns no voice played nothing, and reported success (gate
@@ -14080,7 +14361,7 @@ ${guard(fn)}
   if (__v == null) { return { success: false, error: 'nothing played: the studio returned no voice (it may have no audio output). Placed sounds (create, sequence) and render_soundtrack work without one.' }; }
   return { success: true, played: __v };
 })();`.trim() : `
-// Sound: ${label}
+// Sound: ${oneLine(label)}
 (function() {
 ${guard(fn)}
   return { success: true, ${key}: app.${fn}(${args}) };
@@ -14102,7 +14383,7 @@ ${guard(fn)}
                 : simple('playSoundFromText', S(input.text), 'played', 'a described sound');
             case 'from_text':
                 return `
-// Sound: resolve "${input.text}" to a spec WITHOUT playing it
+// Sound: resolve ${jsLiteral(input.text)} to a spec WITHOUT playing it
 (function() {
 ${guard('buildSoundFromText')}
   const spec = app.buildSoundFromText(${S(input.text)});
@@ -14145,7 +14426,7 @@ ${guard('buildSoundFromText')}
                 // checking the method a caller needs. It extracted only
                 // renderSoundtrackWav until this line existed.
                 return `
-// Sound: define ${input.name} at runtime
+// Sound: define ${oneLine(input.name)} at runtime
 (function() {
 ${guard(fn)}
   var name;
@@ -14329,7 +14610,7 @@ ${guard('timbreFromPath')}
                 opts[k] = input[k];
         }
         return `
-// Motion: ${input.motion} on ${input.itemIds?.length ? `${input.itemIds.length} items` : input.itemId}
+// Motion: ${oneLine(input.motion)} on ${input.itemIds?.length ? `${oneLine(input.itemIds.length)} items` : input.itemId}
 (async function() {
   if (typeof app.animateItems !== 'function') { return { success: false, error: 'app.animateItems unavailable — update FxTool' }; }
   const r = await app.animateItems(${target}, ${S(opts)});
@@ -14367,7 +14648,7 @@ ${guard('timbreFromPath')}
         switch (input.action) {
             case 'boolean':
                 return `
-// Path boolean: ${input.op} — CONSUMES its operands and leaves one result
+// Path boolean: ${oneLine(input.op)} — CONSUMES its operands and leaves one result
 (function() {
 ${guard('booleanOp')}${pass(`app.booleanOp(${S(input.itemIds)}, ${S(input.op)})`)}
 })();`.trim();
@@ -14391,7 +14672,7 @@ ${guard('togglePathClosed')}${pass(`app.togglePathClosed(${S(input.itemId)})`)}
 })();`.trim();
             case 'pattern':
                 return `
-// Pattern: repeat the item — ${input.kind}
+// Pattern: repeat the item — ${oneLine(input.kind)}
 (function() {
 ${guard('patternFrom')}${pass(`app.patternFrom(${S(input.itemId)}, ${S(input.kind)}, ${S(input.pattern ?? {})})`)}
 })();`.trim();
@@ -14427,7 +14708,7 @@ ${guard('unlockAllItems')}${pass('app.unlockAllItems()')}
     generateCropImage(input) {
         const opts = input.aspectRatio ? JSON.stringify({ aspectRatio: input.aspectRatio }) : '{}';
         return `
-// Crop image ${input.itemId}
+// Crop image ${oneLine(input.itemId)}
 (async function() {
   if (typeof app.cropImage !== 'function') { return { success: false, error: 'app.cropImage unavailable — update FxTool to a build with one-shot image ops' }; }
   const result = await app.cropImage(${JSON.stringify(input.itemId)}, ${JSON.stringify(input.rect)}, ${opts});
@@ -14446,7 +14727,7 @@ ${guard('unlockAllItems')}${pass('app.unlockAllItems()')}
             ...(input.smoothing !== undefined ? { smoothing: input.smoothing } : {}),
         });
         return `
-// Chroma-key image ${input.itemId}
+// Chroma-key image ${oneLine(input.itemId)}
 (async function() {
   if (typeof app.applyChromaKey !== 'function') { return { success: false, error: 'app.applyChromaKey unavailable — update FxTool to a build with one-shot image ops' }; }
   const result = await app.applyChromaKey(${JSON.stringify(input.itemId)}, ${opts});
@@ -14862,7 +15143,7 @@ ${guard('unlockAllItems')}${pass('app.unlockAllItems()')}
         const argsJson = JSON.stringify(input.args ?? []);
         const createAsJson = input.createAs ? JSON.stringify(input.createAs) : 'null';
         return `
-// Geometry construction: ${input.operation}
+// Geometry construction: ${oneLine(input.operation)}
 (function() {
   const g = app.geometry;
   if (!g || typeof g[${op}] !== 'function') {
@@ -14924,7 +15205,7 @@ ${guard('unlockAllItems')}${pass('app.unlockAllItems()')}
         const optsJson = JSON.stringify(input);
         const kindJson = JSON.stringify(input.kind);
         return `
-// Equation-driven path: ${input.kind}${input.preset ? ' ' + input.preset : ''}
+// Equation-driven path: ${oneLine(input.kind)}${oneLine(input.preset ? ' ' + input.preset : '')}
 (function() {
   if (typeof app.createEquationPath !== 'function') {
     return { success: false, error: 'app.createEquationPath unavailable — update FxTool to a build with the Expression IR equation-path API (S10 B5)' };
@@ -14948,7 +15229,7 @@ ${guard('unlockAllItems')}${pass('app.unlockAllItems()')}
             const nameJson = JSON.stringify(input.name);
             const optsJson = JSON.stringify({ payloadType: input.payloadType, x: input.x, y: input.y, ...(input.at !== undefined ? { at: input.at } : {}) });
             return `
-// Create event: ${input.name}
+// Create event: ${oneLine(input.name)}
 (function() {
   if (typeof app.createEvent !== 'function') {
     return { success: false, error: 'app.createEvent unavailable — update FxTool to a build with the event system (S11)' };
@@ -14963,7 +15244,7 @@ ${guard('unlockAllItems')}${pass('app.unlockAllItems()')}
         const eventIdJson = JSON.stringify(input.eventId);
         const payloadJson = JSON.stringify(input.payload ?? null);
         return `
-// Pulse event: ${input.eventId}
+// Pulse event: ${oneLine(input.eventId)}
 (function() {
   if (typeof app.pulseEvent !== 'function') {
     return { success: false, error: 'app.pulseEvent unavailable — update FxTool to a build with the event system (S11)' };
@@ -15108,7 +15389,7 @@ return {
  */
 export function generateAutoKeyCode(itemId, props, atTime, easing) {
     return `
-// Auto-key ${itemId} at ${atTime}s
+// Auto-key ${oneLine(itemId)} at ${oneLine(atTime)}s
 (function() {
   const item = app.getItemById(${JSON.stringify(itemId)});
   if (!item) return { success: false, error: ${JSON.stringify(`no item "${itemId}" on the canvas — check the id with pinepaper_get_items.`)} };
@@ -15166,7 +15447,7 @@ export function generateAutoKeyCode(itemId, props, atTime, easing) {
  */
 export function generateQueryMutationsCode(itemId, property, range, fps = 30) {
     return `
-// Keyframe series for ${itemId}${property ? '.' + property : ''}
+// Keyframe series for ${oneLine(itemId)}${oneLine(property ? '.' + property : '')}
 (function() {
   const item = app.getItemById(${JSON.stringify(itemId)});
   if (!item) return { success: false, error: ${JSON.stringify(`no item "${itemId}" on the canvas.`)} };