@pinepaper.studio/mcp-server 1.6.35 → 1.6.37

package/dist/tools/handlers.js

@@ -5,6 +5,7 @@
  * Supports i18n for localized error and success messages.
  * Supports browser execution via Puppeteer.
  */
+import { SCENE_MOTION_PROBE_JS, frozenOutputCheck } from './frozen-output.js';
 import { dropPrivateRelationParams, normalizeBatchOperationNames, renamedArgumentsNote, RENAMED_ARGUMENTS_META_KEY } from './batch-op-names.js';
 import { nestedIgnoredPaths } from './nested-ignored.js';
 import { CRAFT_FRAME_JS, generateDrawWeave, generateDrawKnots, generateDrawSashiko, generateDrawSubdivision, generateUiKit, uiKitCallProblems, } from './craft-tools.js';
@@ -12,7 +13,7 @@ import { exportPerScene } from './scene-cache-export.js';
 import { boundedStructured, reportedIgnoredPaths } from './reply-fields.js';
 import { codeGenerator, generateQueryMutationsCode, SHEET_RUBRIC } from '../types/code-generator.js';
 import { expandBatchMacros, BatchMacroError, batchPreflightView, withKeyColumns } from './batch-macros.js';
-import { CreateItemInputSchema, ModifyItemInputSchema, DeleteItemInputSchema, AddRelationInputSchema, RemoveRelationInputSchema, QueryRelationsInputSchema, AnimateItemInputSchema, ImportMotionCaptureInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, GetItemsInputSchema, PlayTimelineInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, ImportSVGInputSchema, ImportMermaidInputSchema, AddFilterInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, GeometryInputSchema, EquationPathInputSchema, EventInputSchema, ConstructionSequenceInputSchema, ValidateSceneInputSchema, CaptureFramesInputSchema, InstantiateOntologyInputSchema, LintSceneInputSchema, MediaInputSchema, TextStyleInputSchema, TextEffectInputSchema, DesignMediumInputSchema, RelightInputSchema, ChoreographInputSchema, EmitterInputSchema, MorphSequenceInputSchema, OriginalCharacterInputSchema, LookInputSchema, RenderHookInputSchema, ShaderGraphInputSchema, ShatterImageInputSchema, ImportLayeredCharacterInputSchema, CharacterInputSchema, GameInputSchema, World3DInputSchema, BrandKitInputSchema, ComponentInputSchema, ArtboardInputSchema, CommentInputSchema, ProvenanceInputSchema, SceneDiffInputSchema, AudioBeatsInputSchema, TemplateParamsInputSchema, RenderBatchInputSchema, AccessibilityCheckInputSchema, QueryMutationsInputSchema, ComposeInputSchema, CropImageInputSchema, PathOpInputSchema, MotionInputSchema, SoundInputSchema, InterchangeInputSchema, StickInputSchema, DesignSystemInputSchema, StoryInputSchema, ChromaKeyInputSchema, RiggingInputSchema, GroupInputSchema, CameraDirectorInputSchema, DetectObjectsInputSchema, ExtractObjectInputSchema, ArrangeInputSchema, CreateSceneInputSchema, GetPerformanceMetricsInputSchema, DiagnosticReportInputSchema, SearchAssetsInputSchema, ImportAssetInputSchema, P5DrawInputSchema, 
+import { CreateItemInputSchema, ModifyItemInputSchema, DeleteItemInputSchema, AddRelationInputSchema, RemoveRelationInputSchema, QueryRelationsInputSchema, AnimateItemInputSchema, ImportMotionCaptureInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, GetItemsInputSchema, PlayTimelineInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, ImportSVGInputSchema, ImportMermaidInputSchema, AddFilterInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, GeometryInputSchema, EquationPathInputSchema, EventInputSchema, ConstructionSequenceInputSchema, ValidateSceneInputSchema, CaptureFramesInputSchema, InstantiateOntologyInputSchema, LintSceneInputSchema, MediaInputSchema, TextStyleInputSchema, TextEffectInputSchema, DesignMediumInputSchema, RelightInputSchema, ChoreographInputSchema, EmitterInputSchema, MorphSequenceInputSchema, OriginalCharacterInputSchema, LookInputSchema, RenderHookInputSchema, ShaderGraphInputSchema, ShatterImageInputSchema, ImportLayeredCharacterInputSchema, CharacterInputSchema, GameInputSchema, World3DInputSchema, BrandKitInputSchema, ComponentInputSchema, ArtboardInputSchema, CommentInputSchema, ProvenanceInputSchema, SceneDiffInputSchema, AudioBeatsInputSchema, TemplateParamsInputSchema, RenderBatchInputSchema, AccessibilityCheckInputSchema, QueryMutationsInputSchema, ComposeInputSchema, CropImageInputSchema, PathOpInputSchema, MotionInputSchema, SoundInputSchema, InterchangeInputSchema, StickInputSchema, InstancesInputSchema, DesignSystemInputSchema, StoryInputSchema, ChromaKeyInputSchema, RiggingInputSchema, GroupInputSchema, CameraDirectorInputSchema, DetectObjectsInputSchema, ExtractObjectInputSchema, ArrangeInputSchema, CreateSceneInputSchema, GetPerformanceMetricsInputSchema, DiagnosticReportInputSchema, SearchAssetsInputSchema, ImportAssetInputSchema, P5DrawInputSchema, 
 // Diagram schemas
 CreateDiagramShapeInputSchema, ConnectInputSchema, ConnectPortsInputSchema, AddPortsInputSchema, AutoLayoutInputSchema, GetDiagramShapesInputSchema, UpdateConnectorInputSchema, RemoveConnectorInputSchema, DiagramModeInputSchema, 
 // Agent flow mode schemas
@@ -38,7 +39,7 @@ import { ZodError, z } from 'zod';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { effectClass } from './effect-class.js';
 import { capabilityAllowed, capabilityRefusal, CAPABILITY_SWITCH } from '../utils/capabilities.js';
-import { exportFileReceiptOrReason, receiptErrorLine } from './export-file-receipt.js';
+import { exportFileReceiptOrReason, receiptErrorLine, deliverAacIfOpus } from './export-file-receipt.js';
 import { ExportStepError, errorText, verifySavedFile, writeStep, bytesForSave } from './export-file-check.js';
 import { EFFECT_BEFORE_JS, effectAfterJs, namedItemIds, idMayBeGone, NO_CHANGE_NOTE } from './effect-check.js';
 import { writeFile, mkdir, appendFile, unlink, readFile, stat } from 'node:fs/promises';
@@ -746,6 +747,21 @@ export function withEngineReport(result, report) {
         _meta: { ...(result._meta ?? {}), [RECEIPTS_META_KEY]: body },
     };
 }
+/** B45 option D: the delivered file's audio, in the result and its words. */
+function audioDeliveryFields(d) {
+    if (d.action === 'transcoded')
+        return { audioDelivered: { ...d.audio, preRemux: d.preRemux, note: 'file.sha256 is the delivered file. The studio file hash, bitExact and provenance describe the bytes before the audio was re-encoded; its frameHashes still describe the video, which was copied unchanged.' } };
+    if (d.action === 'kept-opus')
+        return { audioNote: d.note };
+    return {};
+}
+function audioDeliveryLine(d) {
+    if (d.action === 'transcoded')
+        return `Audio: re-encoded from Opus to AAC (${d.audio.bitrate}); the video is copied unchanged, and the file has a new sha256.\n`;
+    if (d.action === 'kept-opus')
+        return `Audio: ${d.note}\n`;
+    return '';
+}
 function executedResult(code, result, screenshot, description, report) {
     const resultObj = { success: true, result };
     if (description)
@@ -851,6 +867,43 @@ function redactGeneratedCode(details) {
  * The studio's scene-lint warnings on an export (FxTool lintScene), one line each, so a centred title that runs
  * out of the frame ("IGNAL" for "SIGNAL") is read on the success path rather than left in the JSON. Empty when none.
  */
+/** Put a frozen-output finding on the result: in `warnings`, in the `warning` line the reply prints, and as `frozenOutput`. */
+export function noteFrozenOutput(exportResult, sceneMotion) {
+    if (!exportResult || typeof exportResult !== 'object')
+        return;
+    const f = frozenOutputCheck(exportResult, sceneMotion);
+    if (!f)
+        return;
+    const r = exportResult;
+    r.frozenOutput = { frozenAt: f.frozenAt, exportEnd: f.exportEnd, itemId: f.track.id, trackUntil: f.track.until >= 1e8 ? 'loops' : f.track.until };
+    if (Array.isArray(r.warnings))
+        r.warnings.push(f.warning);
+    else
+        r.warnings = [f.warning];
+    r.warning = typeof r.warning === 'string' && r.warning ? r.warning + ' ' + f.warning : f.warning;
+}
+/**
+ * A CLAIM THE NUMBERS NEXT TO IT CONTRADICT (tester, 1.6.36). The studio sets video.bitrateCeilingHeld: true
+ * whenever the file is within 10% OVER the target, and warns only past that, so a file 7% over its ceiling was
+ * reported as having held it. The flag is set from the file's own achievedBitrate and the target beside it.
+ */
+export function correctBitrateClaim(exportResult) {
+    const r = exportResult;
+    const v = r && typeof r === 'object' ? r.video : null;
+    if (!v || typeof v !== 'object' || v.bitrateCeilingHeld !== true)
+        return;
+    const target = Number(v.bitrate), achieved = Number(v.achievedBitrate);
+    if (!(target > 0) || !(achieved > target))
+        return;
+    const over = Math.round((achieved / target - 1) * 1000) / 10;
+    v.bitrateCeilingHeld = false;
+    v.bitrateOverPercent = over;
+    const msg = `bitrate_exceeded: the ${(target / 1e6).toFixed(2)} Mbps target was not held: the file is ${(achieved / 1e6).toFixed(2)} Mbps (${over}% over). The browser encoder treats the target loosely on content it cannot compress; pass a lower bitrate, or bitrateMode 'constant', which held closer in measurement.`;
+    if (Array.isArray(r.warnings))
+        r.warnings.push(msg);
+    else
+        r.warnings = [msg];
+}
 export function lintLines(exportResult) {
     const w = exportResult?.lintWarnings;
     if (!Array.isArray(w) || !w.length)
@@ -1262,6 +1315,34 @@ async function craftFrame(options) {
         return undefined;
     }
 }
+/**
+ * B136: Chromium draws a raster's smoothing 'low', 'medium' and 'high' the same, so a call asking for 'medium' or
+ * 'high' is applied and looks like 'low'. Said in the reply's JSON, since the docs alone left it silent. Any
+ * `smoothing` set to one of those words, at any depth (import, modify, create, batch ops); numeric smoothing
+ * (relations, chroma key) is another parameter and is left alone.
+ */
+export function smoothingLevelField(args) {
+    const seen = new Set();
+    const walk = (v, depth) => {
+        if (depth > 6 || !v || typeof v !== 'object')
+            return;
+        if (Array.isArray(v)) {
+            v.forEach((x) => walk(x, depth + 1));
+            return;
+        }
+        for (const [k, x] of Object.entries(v)) {
+            if (k === 'smoothing' && (x === 'medium' || x === 'high'))
+                seen.add(x);
+            else
+                walk(x, depth + 1);
+        }
+    };
+    walk(args, 0);
+    if (!seen.size)
+        return {};
+    const asked = [...seen].map((x) => `'${x}'`).join(' and ');
+    return { smoothingNote: `smoothing ${asked} was applied, but Chromium draws 'low', 'medium' and 'high' the same, so it looks like 'low'. The visible choice is 'off' (nearest-neighbour, hard pixel edges) or not.` };
+}
 export async function executeOrGenerate(code, description, options, toolName, 
 /**
  * Values too large to live inside the generated code. Written to
@@ -2010,6 +2091,7 @@ export async function handleToolCall(toolName, args, options = {}) {
         ...(dropped.length ? { droppedArguments: dropped } : {}),
         ...(ignoredPaths.length ? { ignoredArguments: ignoredPaths } : {}),
         ...await renderingBuildField(toolName, args, result, options),
+        ...smoothingLevelField(args),
     });
     if (!folded) {
         const lines = [...(renamed.length ? [renamedArgumentsNote(renamed)] : []), ...(dropped.length ? [`Not sent to the studio, as its private state: ${dropped.join(', ')}.`] : [])];
@@ -2552,6 +2634,10 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 const input = MorphSequenceInputSchema.parse(args);
                 return executeOrGenerate(codeGenerator.generateMorphSequence(input), `Morph sequence: ${input.states.length} states`, options, 'pinepaper_morph_sequence');
             }
+            case 'pinepaper_instances': {
+                const input = InstancesInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateInstances(input), `Instances: ${input.action}`, options, 'pinepaper_instances');
+            }
             case 'pinepaper_emitter': {
                 const input = EmitterInputSchema.parse(args);
                 return executeOrGenerate(codeGenerator.generateEmitter(input), `Emitter: ${input.action}`, options, 'pinepaper_emitter');
@@ -4222,6 +4308,11 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                 if (!exportSessionManager.hasActiveJob()) {
                     exportSessionManager.startJob({ name: 'auto_session', screenshotPolicy: 'on_complete' });
                 }
+                // The scene's motion, read before a video export so the delivered frames can be checked against it
+                // (frozen-output.ts). A probe that cannot run gives no verdict, never a false one.
+                const sceneMotion = /^(mp4|webm|auto|)$/.test(String(input.format ?? ''))
+                    ? await controller.executeCode(SCENE_MOTION_PROBE_JS, false).then((r) => (r.success ? r.result : null)).catch(() => null)
+                    : null;
                 const exportBrowserResult = await controller.executeCode(code, false, {
                     governorTimeoutMs: exportGovernorTimeoutMs(),
                 });
@@ -4230,6 +4321,8 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                     return errorResult(ErrorCodes.EXECUTION_ERROR, exportBrowserResult.error || 'Export failed', { code }, { toolName: 'pinepaper_agent_export', canvasState: canvasState || undefined });
                 }
                 const exportResult = exportBrowserResult.result;
+                correctBitrateClaim(exportResult);
+                noteFrozenOutput(exportResult, sceneMotion);
                 // TWO VERDICTS, and only one of them was being read.
                 //
                 // `exportBrowserResult.success` says the CODE RAN. The export's own
@@ -4283,14 +4376,20 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                             format,
                             chunkBytes: Number(exportResult.chunkBytes) || undefined,
                         }, input.platform || 'auto');
+                        const delivery = await deliverAacIfOpus(filePath, format, exportResult, input.platform);
+                        if (delivery.action === 'refuse') {
+                            await (await import('node:fs/promises')).unlink(filePath).catch(() => undefined);
+                            return errorResult(ErrorCodes.EXECUTION_ERROR, delivery.message, { code: 'audio_codec_unavailable', format, platform: input.platform }, { toolName: 'pinepaper_agent_export' });
+                        }
                         const receipt = await exportFileReceiptOrReason(filePath, exportResult);
-                        const cleanResult = { ...exportResult, data: undefined, filePath, fileSize, chunks, file: receipt };
+                        const deliveredSize = 'bytes' in receipt ? receipt.bytes : fileSize;
+                        const cleanResult = { ...exportResult, data: undefined, filePath, fileSize: deliveredSize, chunks, file: receipt, ...audioDeliveryFields(delivery) };
                         return withEngineReport({
                             structuredContent: boundedStructured(cleanResult),
                             content: [{
                                     type: 'text',
-                                    text: `Export saved to file:\n\nFile: ${filePath}\nFormat: ${format}\nSize: ${(fileSize / 1024).toFixed(1)} KB\nPlatform: ${input.platform}\nPaged out of the studio's export store in ${chunks} chunk${chunks === 1 ? '' : 's'}\n${receiptErrorLine(receipt)}${'receiptError' in receipt ? '' : probeLines(receipt)}${lintLines(exportResult)}\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
-                                }, exportFileLink(filePath, fileSize)],
+                                    text: `Export saved to file:\n\nFile: ${filePath}\nFormat: ${format}\nSize: ${(deliveredSize / 1024).toFixed(1)} KB\nPlatform: ${input.platform}\nPaged out of the studio's export store in ${chunks} chunk${chunks === 1 ? '' : 's'}\n${typeof exportResult.warning === 'string' ? `WARNING: ${exportResult.warning}\n` : ''}${audioDeliveryLine(delivery)}${receiptErrorLine(receipt)}${'receiptError' in receipt ? '' : probeLines(receipt)}${lintLines(exportResult)}\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
+                                }, exportFileLink(filePath, deliveredSize)],
                         }, exportBrowserResult.report);
                     }
                     catch (streamError) {
@@ -4345,9 +4444,15 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                     data.length > SAVE_THRESHOLD_BYTES);
                 if (shouldSaveToFile) {
                     try {
-                        const { filePath, fileSize } = await saveExportToFile(data, format, input.platform || 'auto');
+                        const { filePath, fileSize: savedSize } = await saveExportToFile(data, format, input.platform || 'auto');
+                        const delivery = await deliverAacIfOpus(filePath, format, exportResult, input.platform);
+                        if (delivery.action === 'refuse') {
+                            await (await import('node:fs/promises')).unlink(filePath).catch(() => undefined);
+                            return errorResult(ErrorCodes.EXECUTION_ERROR, delivery.message, { code: 'audio_codec_unavailable', format, platform: input.platform }, { toolName: 'pinepaper_agent_export' });
+                        }
                         const receipt = await exportFileReceiptOrReason(filePath, exportResult);
-                        const cleanResult = { ...exportResult, data: undefined, filePath, fileSize, file: receipt };
+                        const fileSize = 'bytes' in receipt ? receipt.bytes : savedSize;
+                        const cleanResult = { ...exportResult, data: undefined, filePath, fileSize, file: receipt, ...audioDeliveryFields(delivery) };
                         // A mix that dropped sounds wrote a perfectly good file that is
                         // missing tracks. It rides the SUCCESS path, which is exactly why
                         // it has to be said out loud here rather than left in the JSON.
@@ -4357,7 +4462,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                             content: [{
                                     type: 'text',
                                     text: `Export saved to file:\n\nFile: ${filePath}\nFormat: ${format}\nSize: ${(fileSize / 1024).toFixed(1)} KB\nPlatform: ${input.platform}\n`
-                                        + (dropNote ? `DROPPED: ${dropNote}\n` : '')
+                                        + (dropNote ? `DROPPED: ${dropNote}\n` : '') + audioDeliveryLine(delivery)
                                         // The studio's own warning on a saved file (a GIF over its maxBytes budget, GIFMAX34) was only
                                         // inside the Result JSON below; a reader of the words missed it.
                                         + (typeof exportResult.warning === 'string' ? `WARNING: ${exportResult.warning}\n` : '')
@@ -4425,11 +4530,28 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                     case 'list_styles':
                         return dataResult({ styles: designSystems.listStyles() });
                     case 'compose': {
+                        // NO SIZE GIVEN MEANS YOUR CANVAS, not the style's own (RISO-RESIZE, owner 2026-11-14). A style laid out
+                        // at its default size (1280x720 for most) and resized the canvas to it, so a 1080x1920 project became
+                        // 1280x720. Where the studio is reachable, an unsized compose uses the current canvas size.
+                        let width = input.width, height = input.height;
+                        let sizeFrom = width !== undefined || height !== undefined ? 'asked' : 'style';
+                        if (sizeFrom === 'style' && input.draw !== false && options.executeInBrowser) {
+                            const ctl = options.browserController || getBrowserController();
+                            if (ctl.connected) {
+                                const cs = await ctl.executeCode('(function () { const s = app.getCanvasSize ? app.getCanvasSize() : null; return s && s.width > 0 && s.height > 0 ? { width: s.width, height: s.height } : null; })()', false)
+                                    .then((r) => (r.success ? r.result : null)).catch(() => null);
+                                if (cs) {
+                                    width = cs.width;
+                                    height = cs.height;
+                                    sizeFrom = 'canvas';
+                                }
+                            }
+                        }
                         let scene;
                         try {
                             scene = designSystems.compose(input.style, {
                                 title: input.title, subtitle: input.subtitle, body: input.body,
-                                width: input.width, height: input.height, variant: input.variant,
+                                width, height, variant: input.variant,
                             });
                         }
                         catch (composeError) {
@@ -4443,10 +4565,12 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                         // Some vendored styles lay out at their OWN fixed size and ignore
                         // width/height (swiss_typographic is always 1280x720), so a caller
                         // asking for 1080x1080 got a resized canvas (gate run 3). Say so.
-                        const sizeIgnored = (input.width !== undefined && input.width !== scene.width)
-                            || (input.height !== undefined && input.height !== scene.height);
+                        const sizeIgnored = (width !== undefined && width !== scene.width)
+                            || (height !== undefined && height !== scene.height);
                         const sizeWarning = sizeIgnored
-                            ? `"${scene.style}" lays out at its own size, ${scene.width}x${scene.height}; the requested ${input.width ?? '?'}x${input.height ?? '?'} was not used`
+                            ? (sizeFrom === 'canvas'
+                                ? `"${scene.style}" lays out at its own size, ${scene.width}x${scene.height}, not your canvas's ${width}x${height}, so the canvas is resized to it`
+                                : `"${scene.style}" lays out at its own size, ${scene.width}x${scene.height}; the requested ${input.width ?? '?'}x${input.height ?? '?'} was not used`)
                             : undefined;
                         // BAUHAUS-SUBTITLE: at a size the style was not laid out for, its
                         // proportions can put text across a shape (bauhaus at 1920x1080
@@ -4454,18 +4578,20 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                         // the result names each collision rather than drawing it as intended.
                         const collisions = designSystems.scalingCollisions(input.style, {
                             title: input.title, subtitle: input.subtitle, body: input.body,
-                            width: input.width, height: input.height, variant: input.variant,
+                            width, height, variant: input.variant,
                         }, scene);
                         const layoutWarning = collisions.length
                             ? `at ${scene.width}x${scene.height} the "${scene.style}" layout runs text onto a shape it does not touch at its own default size: `
                                 + collisions.map((c) => `${c.text} over ${c.shape}`).join(', ')
-                                + '. Compose without width/height (its default size) for the layout as designed, or move the text afterwards with pinepaper_modify_item.'
+                                + '. For the layout as designed, compose at the style\'s own size (draw: false without width/height returns it), or move the text afterwards with pinepaper_modify_item.'
                             : undefined;
                         const collisionReport = collisions.length ? { layoutCollisions: collisions, layoutWarning } : {};
                         if (input.draw === false) {
                             return dataResult({ scene, ops, drawn: false, ...(sizeWarning ? { warning: sizeWarning } : {}), ...collisionReport });
                         }
-                        const code = codeGenerator.generateDesignCompose(scene, ops, scene.style, sizeWarning, collisionReport);
+                        // A style that cannot lay out at your canvas size is fitted into it rather than resizing it.
+                        const fitTo = sizeFrom === 'canvas' && sizeIgnored && width && height ? { width, height } : undefined;
+                        const code = codeGenerator.generateDesignCompose(scene, ops, scene.style, sizeWarning, collisionReport, fitTo);
                         return executeOrGenerate(code, `Composed a ${scene.style} scene (${ops.length} items)`, options, 'pinepaper_design_system');
                     }
                 }