@pinepaper.studio/mcp-server 1.6.12 → 1.6.14

package/dist/tools/handlers.js

@@ -6,7 +6,7 @@
  * Supports browser execution via Puppeteer.
  */
 import { codeGenerator } from '../types/code-generator.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, ShatterImageInputSchema, ImportLayeredCharacterInputSchema, CharacterInputSchema, GameInputSchema, World3DInputSchema, BrandKitInputSchema, ComponentInputSchema, ArtboardInputSchema, CommentInputSchema, ProvenanceInputSchema, SceneDiffInputSchema, AudioBeatsInputSchema, TemplateParamsInputSchema, 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, ShatterImageInputSchema, ImportLayeredCharacterInputSchema, CharacterInputSchema, GameInputSchema, World3DInputSchema, BrandKitInputSchema, ComponentInputSchema, ArtboardInputSchema, CommentInputSchema, ProvenanceInputSchema, SceneDiffInputSchema, AudioBeatsInputSchema, TemplateParamsInputSchema, RenderBatchInputSchema, AccessibilityCheckInputSchema, ComposeInputSchema, CropImageInputSchema, PathOpInputSchema, MotionInputSchema, SoundInputSchema, InterchangeInputSchema, StickInputSchema, 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
@@ -28,7 +28,7 @@ ImportImageInputSchema,
 ManageScenesInputSchema, ScenePlaybackInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, FlipInputSchema, 
 // New consolidated tool schemas
 SelectionInputSchema, TransformInputSchema, HistoryInputSchema, ImageFilterInputSchema, LassoInputSchema, CutoutStyleInputSchema, PrecompInputSchema, BackgroundInputSchema, QueryInputSchema, QueryCapabilitiesInputSchema, DeformInputSchema, SpriteSheetInputSchema, InteractionInputSchema, ExportWidgetInputSchema, ExportWidgetHtmlInputSchema, CreateChartInputSchema, MagicInputSchema, PhysicsInputSchema, MeasurementInputSchema, ErrorCodes, } from '../types/schemas.js';
-import { ZodError } from 'zod';
+import { ZodError, z } from 'zod';
 import { writeFile, mkdir, appendFile, unlink, readFile, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, extname } from 'node:path';
@@ -47,6 +47,10 @@ import { ontologyHandlers } from './handlers/ontology.js';
 import * as designSystems from '../design/design-systems.js';
 import { exportHandlers } from './handlers/export.js';
 import { planCharacter, generateCharacterCode } from './handlers/character.js';
+import { buildZip } from '../utils/zip.js';
+import { buildScc } from '../utils/scc.js';
+import { checkContrast, checkFlashes, parseCssColor } from '../utils/a11y.js';
+import { buildHtml5Ad, buildPlayable, externalRequests, pinSceneBackground } from '../utils/ad-package.js';
 /**
  * Registry of per-domain handler maps. Tools listed here short-circuit the
  * main switch at dispatch time (see handleToolCallInner). New domains are
@@ -83,8 +87,14 @@ function getExportDir() {
 // wav joins them: a minute of 48kHz 16-bit is ~5.8 MB of base64 and the ten
 // minutes the schema allows is ~77 MB. Deliverable across the bridge, useless
 // pasted into a response.
-export const ALWAYS_SAVE_FORMATS = new Set(['mp4', 'webm', 'gif', 'pdf', 'wav']);
-const SAVE_THRESHOLD_BYTES = 500_000; // ~500KB base64 ≈ 375KB decoded
+export const ALWAYS_SAVE_FORMATS = new Set(['mp4', 'webm', 'gif', 'apng', 'pdf', 'wav', 'srt', 'vtt', 'scc', 'html5-ad', 'playable']);
+// 500_000 was chosen against the bridge's limits, not the CALLER's. A pilot
+// session hit a 263K-character end_job result — comfortably under this, so it
+// was returned inline, and over the tool-result limit of the client reading
+// it, so the agent could not read its own verification step. A value that
+// lets a result through to be rejected downstream is the wrong value; saving
+// to a file and naming the path costs one line of text and always works.
+const SAVE_THRESHOLD_BYTES = 180_000; // ~180KB base64 ≈ 135KB decoded
 /**
  * Governor budget for the export run itself.
  *
@@ -131,10 +141,82 @@ const IMAGE_MIME = {
     '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
     '.webp': 'image/webp', '.svg': 'image/svg+xml', '.bmp': 'image/bmp', '.avif': 'image/avif',
 };
+/**
+ * THE PAGE CANNOT FETCH A THIRD-PARTY IMAGE. THIS PROCESS CAN.
+ *
+ * pinepaper.studio serves `connect-src 'self' https://cloud.pinepaper.studio`,
+ * so an in-page fetch() of ANY other host fails outright. `img-src` still
+ * allows https:, which is why the old path could LOAD a remote image — and
+ * tainted the canvas doing it, killing every later export. The taint fix
+ * replaced that load with a fetch, which is safe and, under this CSP, can
+ * never succeed: import by URL stopped being broken-and-dangerous and became
+ * simply impossible.
+ *
+ * Node has no CSP. Fetching here and handing the page a data: URL is the only
+ * shape that both works and cannot taint, so a URL is resolved BEFORE it
+ * reaches the browser. Verified end to end by the session that found it: a
+ * 157KB data: URL imports and exports cleanly.
+ */
+const MAX_REMOTE_IMAGE_BYTES = 32 * 1024 * 1024;
+export async function fetchImageAsDataUrl(url) {
+    let res;
+    try {
+        res = await fetch(url, { redirect: 'follow' });
+    }
+    catch (e) {
+        const why = e instanceof Error ? e.message : 'network request failed';
+        return { error: `could not reach ${url} — ${why}. This fetch runs in the MCP server, not the page, so it is not a CSP problem: check the host resolves and any proxy is reachable.` };
+    }
+    if (!res.ok) {
+        return { error: `the server refused ${url} — HTTP ${res.status} ${res.statusText || ''}`.trim() };
+    }
+    const type = (res.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase();
+    if (!type.startsWith('image/')) {
+        return { error: `${url} served "${type || 'no content-type'}", not an image. A URL that returns an HTML page around the image will do this — link the file itself.` };
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (buf.length > MAX_REMOTE_IMAGE_BYTES) {
+        return { error: `${url} is ${(buf.length / 1024 / 1024).toFixed(1)} MB, above the ${MAX_REMOTE_IMAGE_BYTES / 1024 / 1024} MB import cap.` };
+    }
+    return { src: `data:${type};base64,${buf.toString('base64')}` };
+}
+/**
+ * Resolve an SVG to a string with every remote <image> already inlined.
+ *
+ * The emitted code does this in the page as a backstop, and under
+ * pinepaper.studio's CSP that backstop can only ever DROP images — the page
+ * may not fetch a third-party host. Doing it here means the page receives a
+ * document with no remote references at all: nothing to fetch, nothing to
+ * taint, and the pictures actually arrive.
+ *
+ * An href that cannot be fetched is still removed rather than left in, on the
+ * same reasoning as the in-page pass: a missing picture is visible and
+ * recoverable, a tainted canvas is neither.
+ */
+async function inlineSvgImages(svg) {
+    const warnings = [];
+    const hrefs = [...new Set([...svg.matchAll(/(?:xlink:)?href\s*=\s*("|')(https?:\/\/[^"']+)\1/gi)].map((m) => m[2]))];
+    let out = svg;
+    for (const href of hrefs) {
+        const got = await fetchImageAsDataUrl(href);
+        if ('src' in got) {
+            out = out.split(href).join(got.src);
+            continue;
+        }
+        const esc = href.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        out = out
+            .replace(new RegExp(`<image\\b[^>]*${esc}[^>]*\\/?>`, 'gi'), '')
+            .replace(new RegExp(`<image\\b[^>]*${esc}[\\s\\S]*?<\\/image>`, 'gi'), '');
+        warnings.push({ url: href, action: 'removed', reason: 'unfetchable', message: got.error });
+    }
+    return { svg: out, warnings };
+}
 export async function resolveImageSource(input) {
     const raw = input.trim();
-    if (/^(https?:|data:)/i.test(raw))
+    if (/^data:/i.test(raw))
         return { src: raw };
+    if (/^https?:/i.test(raw))
+        return fetchImageAsDataUrl(raw);
     const path = raw.startsWith('file://') ? fileURLToPath(raw) : raw;
     const ext = extname(path).toLowerCase();
     if (!IMAGE_EXTENSIONS.has(ext)) {
@@ -159,10 +241,150 @@ export async function resolveImageSource(input) {
     }
     return { src: `data:${IMAGE_MIME[ext] ?? 'application/octet-stream'};base64,${bytes.toString('base64')}` };
 }
+/**
+ * Audio / video for pinepaper_media upload, fetched or read BY THE SERVER.
+ *
+ * The page cannot do it on production: its CSP refuses fetch() of a third-party
+ * host, so upload_audio of a working https URL (Wikimedia's Example.ogg, 200
+ * from anywhere else) failed "Failed to fetch (upload.wikimedia.org)" — every
+ * stock music and SFX URL was unusable. Same answer as remote images: the
+ * server fetches, and the page receives bytes (decoded to a File in the page,
+ * never fetch()ed there — see generateMedia).
+ *
+ * A User-Agent is sent because some media hosts (Wikimedia among them) refuse
+ * anonymous clients. The content-type check accepts audio/*, video/*,
+ * application/ogg, and a generic binary type when the extension says media;
+ * an HTML page around the file is refused by name.
+ */
+const MEDIA_MIME = {
+    '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.ogg': 'audio/ogg', '.oga': 'audio/ogg', '.m4a': 'audio/mp4',
+    '.aac': 'audio/aac', '.flac': 'audio/flac', '.opus': 'audio/ogg',
+    '.mp4': 'video/mp4', '.m4v': 'video/mp4', '.webm': 'video/webm', '.mov': 'video/quicktime', '.ogv': 'video/ogg',
+};
+const MAX_MEDIA_BYTES = 48 * 1024 * 1024;
+export async function resolveMediaSource(input) {
+    const raw = input.trim();
+    if (/^data:/i.test(raw))
+        return { src: raw };
+    const tooBig = (what, n) => ({
+        error: `${what} is ${(n / 1024 / 1024).toFixed(1)} MB, above the ${MAX_MEDIA_BYTES / 1024 / 1024} MB upload cap for this tool. Trim or re-encode it, or upload it in the studio itself.`,
+    });
+    if (/^https?:/i.test(raw)) {
+        let res;
+        try {
+            res = await fetch(raw, { redirect: 'follow', headers: { 'User-Agent': 'PinePaper-MCP (+https://pinepaper.studio)' } });
+        }
+        catch (e) {
+            const why = e instanceof Error ? e.message : 'network request failed';
+            return { error: `could not reach ${raw} — ${why}. This fetch runs in the MCP server, not the page, so it is not a CSP problem: check the host resolves and any proxy is reachable.` };
+        }
+        if (!res.ok)
+            return { error: `the server refused ${raw} — HTTP ${res.status} ${res.statusText || ''}`.trim() };
+        let type = (res.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase();
+        const extType = MEDIA_MIME[extname(new URL(raw).pathname).toLowerCase()];
+        if (!type || type === 'application/octet-stream' || type === 'binary/octet-stream')
+            type = extType ?? type;
+        if (type === 'application/ogg')
+            type = 'audio/ogg';
+        if (!/^(audio|video)\//.test(type)) {
+            return { error: `${raw} served "${type || 'no content-type'}", not audio or video. A URL that returns an HTML page around the file will do this — link the file itself.` };
+        }
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.length > MAX_MEDIA_BYTES)
+            return tooBig(raw, buf.length);
+        return { src: `data:${type};base64,${buf.toString('base64')}` };
+    }
+    const path = raw.startsWith('file://') ? fileURLToPath(raw) : raw;
+    const type = MEDIA_MIME[extname(path).toLowerCase()];
+    if (!type) {
+        return { error: `"${input}" is neither an http(s) URL, a data: URL, nor a path to an audio/video file. Recognised extensions: ${Object.keys(MEDIA_MIME).join(', ')}.` };
+    }
+    try {
+        const info = await stat(path);
+        if (!info.isFile())
+            return { error: `"${path}" is not a file.` };
+        if (info.size > MAX_MEDIA_BYTES)
+            return tooBig(`"${path}"`, info.size);
+        const bytes = await readFile(path);
+        return { src: `data:${type};base64,${bytes.toString('base64')}` };
+    }
+    catch (e) {
+        const why = e instanceof Error ? e.message : 'unknown error';
+        return { error: `could not read "${path}": ${why}. Paths are resolved from the server's working directory, so pass an absolute path if in doubt.` };
+    }
+}
 export function getFileExtension(format) {
-    const extMap = { mp4: 'mp4', webm: 'webm', gif: 'gif', pdf: 'pdf', png: 'png', svg: 'svg', wav: 'wav' };
+    const extMap = { mp4: 'mp4', webm: 'webm', gif: 'gif', apng: 'png', 'html5-ad': 'zip', playable: 'html', pdf: 'pdf', png: 'png', svg: 'svg', wav: 'wav', jpg: 'jpg', webp: 'webp', srt: 'srt', vtt: 'vtt', scc: 'scc' };
     return extMap[format] || format;
 }
+/** The text of a tool result, joined. */
+function toolText(r) {
+    return (r.content ?? []).map((c) => (c.type === 'text' ? c.text : '')).join('\n');
+}
+/**
+ * Wrap the widget page for its network, write it, and say what a trafficker
+ * checks: the upload's size against the budget, and anything the page fetches
+ * from outside (networks block or must allow-list external requests).
+ */
+async function saveAdExport(r, input, platform) {
+    const exportDir = getExportDir();
+    await mkdir(exportDir, { recursive: true });
+    const stamp = `pinepaper_${platform}_${Date.now()}`;
+    const opts = { width: r.adSize.width, height: r.adSize.height, clickUrl: input.ad?.clickUrl, cta: r.cta, background: r.background };
+    const warnings = [...(r.fidelity?.warnings ?? [])];
+    // The renderer paints SCENE.background over the page CSS, so the scene's own
+    // fill must be pinned too; a page without the hook is named, not assumed.
+    if (r.background && !pinSceneBackground(r.adPage, r.background).applied) {
+        warnings.push({ code: 'background_not_pinned', message: `the page's own scene background could not be replaced with ${r.background}; the ad may show the widget's stored colour instead. Check the backup image against the served ad.` });
+    }
+    const files = {};
+    let uploadBytes;
+    if (r.format === 'html5-ad') {
+        const html = buildHtml5Ad(r.adPage, opts);
+        const zip = buildZip([{ name: 'index.html', data: html }]);
+        files.zip = join(exportDir, `${stamp}.zip`);
+        await writeFile(files.zip, zip);
+        uploadBytes = zip.length;
+        // The backup image is uploaded BESIDE the zip, not inside it.
+        if (r.backupImage && r.backupImage.startsWith('data:')) {
+            files.backupImage = join(exportDir, `${stamp}_backup.png`);
+            await writeFile(files.backupImage, Buffer.from(r.backupImage.split(',')[1], 'base64'));
+        }
+        else {
+            warnings.push({ code: 'no_backup_image', message: 'no backup image was made (the studio could not capture a frame); display networks require one — export format "png" at the same size.' });
+        }
+    }
+    else {
+        const html = buildPlayable(r.adPage, opts);
+        files.html = join(exportDir, `${stamp}.html`);
+        await writeFile(files.html, html, 'utf-8');
+        uploadBytes = Buffer.byteLength(html, 'utf-8');
+    }
+    // 150 KB is Google Ads' display HTML5 figure; some uploads allow 600 KB, and
+    // playable networks set their own — so it is a default, not a rule.
+    const budget = input.ad?.maxBytes ?? (r.format === 'html5-ad' ? 150_000 : undefined);
+    if (budget !== undefined && uploadBytes > budget) {
+        warnings.push({ code: 'over_size_budget', message: `the ${r.format === 'html5-ad' ? 'zip' : 'HTML'} is ${uploadBytes} bytes, over the ${budget}-byte budget. Simplify the scene (fewer items, no embedded images), or set ad.maxBytes to your network's figure if it allows more.` });
+    }
+    const external = externalRequests(r.adPage);
+    if (external.length) {
+        warnings.push({ code: 'external_requests', message: `the page fetches ${external.length} external URL(s): ${external.slice(0, 5).join(', ')}${external.length > 5 ? ', …' : ''}. Display and playable networks often block external requests or require them allow-listed; a scene using only system fonts avoids web-font requests.` });
+    }
+    const { adPage: _page, backupImage: _img, ...rest } = r;
+    void _page;
+    void _img;
+    const cleanResult = { ...rest, files, uploadBytes,
+        ...(files.backupImage ? { backupNote: 'the backup image is a separate file beside the zip, not inside it: display ad servers take it as its own upload.' } : {}), ...(budget !== undefined ? { sizeBudget: budget } : {}), externalRequests: external,
+        fidelity: { ...(r.fidelity ?? {}), warnings } };
+    if (warnings.length && cleanResult.fidelity.note)
+        delete cleanResult.fidelity.note;
+    return {
+        content: [{
+                type: 'text',
+                text: `Ad saved:\n\n${Object.entries(files).map(([k, v]) => `${k}: ${v}`).join('\n')}\nFormat: ${r.format}\nSize: ${r.adSize.width}x${r.adSize.height}, upload ${(uploadBytes / 1024).toFixed(1)} KB\n\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
+            }],
+    };
+}
 async function saveExportToFile(data, format, platform) {
     const exportDir = getExportDir();
     await mkdir(exportDir, { recursive: true });
@@ -416,7 +638,44 @@ function screenshotResult(screenshot) {
         ],
     };
 }
-export function errorResult(code, message, details, context) {
+/**
+ * Swap a `code` field carrying the emitted script for a description of it.
+ *
+ * Only a long string is touched: a short `code` is usually a status or an
+ * error code, not a program, and stripping those would take information away.
+ */
+function redactGeneratedCode(details) {
+    if (process.env.PINEPAPER_ECHO_CODE === '1')
+        return details;
+    if (!details || typeof details !== 'object' || Array.isArray(details))
+        return details;
+    const d = details;
+    const script = d.code;
+    if (typeof script !== 'string' || script.length < 400)
+        return details;
+    const { code: _dropped, ...rest } = d;
+    return {
+        ...rest,
+        generatedCode: {
+            bytes: script.length,
+            lines: script.split('\n').length,
+            firstLine: script.split('\n').find((l) => l.trim()) ?? '',
+            hint: 'omitted — set PINEPAPER_ECHO_CODE=1 to return the generated script with the error',
+        },
+    };
+}
+export function errorResult(code, message, rawDetails, context) {
+    // THE GENERATED SCRIPT IS NOT THE ERROR.
+    //
+    // Most error paths pass the emitted code in `details` as evidence, and for a
+    // long script that is ~12KB of JavaScript in front of a one-line failure —
+    // measured from a pilot session. An agent reading the result pays for all of
+    // it and learns nothing the message does not already say, and on a big
+    // export it can crowd out the result entirely.
+    //
+    // Replaced with its shape and a way to get it back. PINEPAPER_ECHO_CODE=1
+    // returns the script in full, the same switch that governs it on success.
+    const details = redactGeneratedCode(rawDetails);
     // Build error object
     const errorObj = {
         success: false,
@@ -470,7 +729,13 @@ function handleValidationError(error, i18n) {
  *
  * Default is 'on_request' for optimal performance per best practices.
  */
-export async function executeOrGenerate(code, description, options, toolName) {
+export async function executeOrGenerate(code, description, options, toolName, 
+/**
+ * Values too large to live inside the generated code. Written to
+ * window.__ppStage before the run and read back by key — see
+ * ExecuteCodeOptions.stage for why inlining them breaks the governor.
+ */
+stage) {
     const { executeInBrowser, browserController, screenshotMode, executionMode } = options;
     const effectiveExecutionMode = executionMode ?? getExecutionMode();
     const effectiveScreenshotMode = screenshotMode ?? getScreenshotMode();
@@ -604,7 +869,7 @@ ${code}
     if (shouldTakeScreenshot) {
         tracker.startTimer(`${timerId}_screenshot`);
     }
-    const result = await controller.executeCode(code, shouldTakeScreenshot);
+    const result = await controller.executeCode(code, shouldTakeScreenshot, stage ? { stage } : {});
     const browserDuration = tracker.endTimer(`${timerId}_browser_execution`);
     tracker.recordMetric({
         toolName,
@@ -672,19 +937,59 @@ ${code}
  * not a failure, because plenty of emitters return a bare value (an id, a
  * count, a list) and reading absence as refusal would turn every one of those
  * into an error. `ok: false` is included because the export-store emitters use
- * it, and it carries a `reason` rather than an `error`.
+ * it, and it carries a `reason` rather than an `error`. A non-empty `error`
+ * string with no `success: true` beside it is a failure too — it is what the
+ * emitters' catch blocks return.
  */
 export function innerFailure(value) {
     if (!value || typeof value !== 'object')
         return null;
     const r = value;
-    const failed = r.success === false || r.ok === false;
+    // `ok` IS A DOMAIN VERDICT, NOT A TRANSPORT ONE — when `success` disagrees.
+    //
+    // pinepaper_validate answers {success: true, ok: false, diagnostics: [...]}:
+    // the call worked and the SCENE has problems, which is the entire point of
+    // the tool. Treating ok:false as a failure turned that into "the studio
+    // reported failure without naming a reason" and dropped the diagnostics —
+    // this guard, built to stop silent failures, silencing the one tool whose
+    // job is to report them. An explicit success:true wins; ok is only consulted
+    // when nothing else says.
+    // A PAYLOAD CARRYING AN `error` IS A FAILURE, even with no success flag.
+    //
+    // 89 emitted returns in code-generator.ts are `{ error: '…' }` with no
+    // success:false beside them — the shape a try/catch naturally produces. This
+    // guard only looked at success and ok, so those reached the caller wrapped
+    // in a successful tool result with the error nested inside it. Reported for
+    // image_filter on a vector item, where applyImageFilter throws and the catch
+    // returns exactly that shape.
+    //
+    // An explicit success:true still wins, so a tool that legitimately reports a
+    // domain error alongside a successful call is unaffected.
+    const hasError = typeof r.error === 'string' && r.error.length > 0;
+    const failed = r.success === false
+        || (r.success !== true && (r.ok === false || hasError));
     if (!failed)
         return null;
-    const why = typeof r.error === 'string' ? r.error
-        : typeof r.reason === 'string' ? r.reason
-            : 'the studio reported failure without naming a reason';
-    return why;
+    if (typeof r.error === 'string')
+        return r.error;
+    if (typeof r.reason === 'string')
+        return r.reason;
+    // A refusal that carries diagnostics is not reasonless — say what they were
+    // rather than reporting that nothing was said.
+    const detail = Array.isArray(r.diagnostics) ? r.diagnostics
+        : Array.isArray(r.errors) ? r.errors
+            : null;
+    if (detail && detail.length > 0) {
+        const first = detail.slice(0, 3).map((d) => {
+            if (typeof d === 'string')
+                return d;
+            const o = d;
+            return String(o.message ?? o.reason ?? o.code ?? JSON.stringify(o));
+        });
+        return `${detail.length} problem${detail.length > 1 ? 's' : ''}: ${first.join('; ')}`
+            + (detail.length > first.length ? ` (+${detail.length - first.length} more)` : '');
+    }
+    return 'the studio reported failure without naming a reason';
 }
 // =============================================================================
 // I18N HELPER FUNCTIONS
@@ -762,10 +1067,57 @@ function measureResponseBytes(result) {
     }
     return bytes;
 }
+/**
+ * TOP-LEVEL ARGUMENTS A TOOL DROPPED, SAID OUT LOUD.
+ *
+ * z.object() strips unknown keys, so agent_export {loop: true, seamless: true}
+ * answered success and exported exactly what it would have without them — the
+ * caller believed they had a loop setting. create_item / modify_item report
+ * unread PROPERTIES; this is the same idea one level up, for tools listed
+ * here. Keyed to the zod schema the handler parses with, so a key the handler
+ * accepts is never reported, and extended one tool at a time rather than
+ * guessed for all 150.
+ */
+const IGNORED_ARGUMENT_SCHEMAS = {
+    pinepaper_agent_export: AgentExportInputSchema,
+    // A shape property passed beside `properties` instead of inside it is the
+    // common slip here (round 7 retest, 1.63).
+    pinepaper_create_item: CreateItemInputSchema,
+    pinepaper_modify_item: ModifyItemInputSchema,
+};
+const IGNORED_ARGUMENT_HINTS = {
+    pinepaper_create_item: Object.fromEntries(['width', 'height', 'radius', 'color', 'fillColor', 'strokeColor', 'strokeWidth', 'content', 'fontSize', 'fontFamily', 'opacity', 'rotation', 'x', 'y']
+        .map((k) => [k, 'Shape properties go INSIDE properties: {…}; only itemType, position, anchor, properties, animation*, keyframes and data are top-level.'])),
+    pinepaper_modify_item: Object.fromEntries(['width', 'height', 'radius', 'color', 'fillColor', 'strokeColor', 'strokeWidth', 'content', 'fontSize', 'fontFamily', 'opacity', 'rotation', 'x', 'y', 'scale']
+        .map((k) => [k, 'Changes go INSIDE properties: {…}; only itemId, properties and data are top-level.'])),
+    pinepaper_agent_export: {
+        loop: 'There is no loop switch on export: a loop is seamless when the animation is keyed to the SAME state at t = 0 and at t = duration (the export stops one frame before duration, so no frame is doubled at the wrap). GIF exports already loop forever.',
+        seamless: 'A seamless loop is keyed, not a switch: key the animation to the SAME state at t = 0 and at t = duration and export exactly that duration (the export stops one frame before duration, so nothing is doubled at the wrap). A GIF\'s play count is the loop parameter.',
+    },
+};
+export function ignoredArgumentsNote(toolName, args) {
+    let schema = IGNORED_ARGUMENT_SCHEMAS[toolName];
+    if (!schema || !args || typeof args !== 'object')
+        return null;
+    while (schema instanceof z.ZodEffects)
+        schema = schema._def.schema;
+    if (!(schema instanceof z.ZodObject))
+        return null;
+    const known = new Set(Object.keys(schema.shape));
+    const ignored = Object.keys(args).filter((k) => !known.has(k));
+    if (ignored.length === 0)
+        return null;
+    const hints = ignored.map((k) => IGNORED_ARGUMENT_HINTS[toolName]?.[k]).filter(Boolean);
+    return `IGNORED ARGUMENTS: ${ignored.join(', ')} ${ignored.length > 1 ? 'are' : 'is'} not a parameter of ${toolName}, so ${ignored.length > 1 ? 'they had' : 'it had'} no effect.`
+        + (hints.length ? ` ${[...new Set(hints)].join(' ')}` : '');
+}
 export async function handleToolCall(toolName, args, options = {}) {
     const tracker = getPerformanceTracker();
     const baseTimerId = `${toolName}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
     const result = await handleToolCallInner(toolName, args, options, tracker, baseTimerId);
+    const ignoredNote = ignoredArgumentsNote(toolName, args);
+    if (ignoredNote)
+        result.content = [...(result.content ?? []), { type: 'text', text: ignoredNote }];
     // Record response payload size for token estimation
     const responseBytes = measureResponseBytes(result);
     tracker.recordMetric({
@@ -807,7 +1159,11 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 });
                 // Track code generation phase
                 tracker.startTimer(`${baseTimerId}_code_generation`);
-                const code = codeGenerator.generateCreateItem(input);
+                // Whether the CALLER gave a position is only knowable from the raw args:
+                // the schema defaults position to (400, 300), so after the parse above
+                // every call looks like it asked for one — and a pathData path was
+                // moved to the default (1.81, retest: 26241cf's fix was bypassed here).
+                const code = codeGenerator.generateCreateItem(args.position === undefined ? { ...input, position: undefined } : input);
                 const codeGenDuration = tracker.endTimer(`${baseTimerId}_code_generation`);
                 tracker.recordMetric({
                     toolName,
@@ -963,6 +1319,11 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
             }
             case 'pinepaper_query_capabilities': {
                 const input = QueryCapabilitiesInputSchema.parse(args);
+                // `query` is what callers reach for on an action named 'find'; `key`
+                // is what the emitter reads. Accepted as an alias rather than left as
+                // a validation dead end.
+                if (!input.key && input.query)
+                    input.key = input.query;
                 const code = codeGenerator.generateQueryCapabilities(input);
                 return executeOrGenerate(code, `Capabilities: ${input.action || 'list'}`, options, 'pinepaper_query_capabilities');
             }
@@ -1144,11 +1505,35 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
             }
             case 'pinepaper_media': {
                 const input = MediaInputSchema.parse(args);
-                const code = codeGenerator.generateMedia(input);
-                return executeOrGenerate(code, `Media: ${input.action}`, options, 'pinepaper_media');
+                // A LARGE data: URL GOES BESIDE THE CODE — the 1.9 fix, for uploads.
+                // A ~288 KB clip returned an id; a ~2 MB one answered success with no
+                // result, because the bytes were inlined into the generated code and
+                // the governor's transform bails at that size, taking the return value
+                // with it. Same threshold and route as import_image.
+                const isUpload = input.action === 'upload_audio' || input.action === 'upload_video';
+                let url = input.url;
+                // Remote URLs and local paths are fetched/read HERE and arrive in the
+                // page as bytes — see resolveMediaSource.
+                if (isUpload && typeof url === 'string') {
+                    const resolved = await resolveMediaSource(url);
+                    if ('error' in resolved) {
+                        return errorResult(ErrorCodes.INVALID_PARAMS, resolved.error, { url }, { toolName: 'pinepaper_media' });
+                    }
+                    url = resolved.src;
+                }
+                const staged = isUpload && typeof url === 'string' && url.startsWith('data:') && url.length > 64_000;
+                const stageKey = staged ? `media_${Date.now().toString(36)}` : undefined;
+                const forCode = isUpload ? { ...input, url: staged ? `__ppStage:${stageKey}` : url } : input;
+                const code = codeGenerator.generateMedia(forCode);
+                return executeOrGenerate(code, `Media: ${input.action}`, options, 'pinepaper_media', staged ? { [stageKey]: url } : undefined);
             }
             case 'pinepaper_text_style': {
+                // 'list' is an alias for 'list_styles'. pinepaper_text_effect spells
+                // the same action 'list', so an agent moving between the two guesses
+                // wrong — and a rejected enum value is a dead end rather than a hint.
                 const input = TextStyleInputSchema.parse(args);
+                if (input.action === 'list')
+                    input.action = 'list_styles';
                 const code = codeGenerator.generateTextStyle(input);
                 return executeOrGenerate(code, `Text style: ${input.action}`, options, 'pinepaper_text_style');
             }
@@ -1203,6 +1588,142 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 const code = codeGenerator.generateAudioBeats(input);
                 return executeOrGenerate(code, `Audio: ${input.action}`, options, 'pinepaper_audio_beats');
             }
+            case 'pinepaper_accessibility_check': {
+                const input = AccessibilityCheckInputSchema.parse(args);
+                const code = codeGenerator.generateAccessibilityCheck(input);
+                const mode = options.executionMode ?? getExecutionMode();
+                if (mode === 'code' || !options.executeInBrowser) {
+                    return executeOrGenerate(code, 'Accessibility measurements (verdicts need the server: run with a live studio)', options, 'pinepaper_accessibility_check');
+                }
+                const controller = options.browserController || getBrowserController();
+                if (!controller.connected)
+                    await controller.connect();
+                const run = await controller.executeCode(code, false);
+                const m = run.result;
+                if (!run.success || !m)
+                    return errorResult(ErrorCodes.EXECUTION_ERROR, run.error || 'the studio returned no measurements');
+                const report = {};
+                const page = parseCssColor(m.page);
+                if (m.texts) {
+                    const c = checkContrast(m.texts, page);
+                    report.contrast = { pass: c.failing.length === 0, checked: c.checked, failing: c.failing, skipped: c.skipped,
+                        method: 'WCAG 1.4.3 AA (4.5:1, 3:1 for large text) between each text fill and the solid fill of the topmost item under its centre, or the page background' + (c.pageAssumed ? ' (none set, so white was assumed)' : '') + '. Approximate: text over a photo or gradient is not judged.' };
+                }
+                if (m.flashUnavailable)
+                    report.flash = { checked: false, reason: m.flashUnavailable };
+                else if (m.series) {
+                    const f = checkFlashes(m.series, m.fps);
+                    report.flash = { pass: f.failing.length === 0, maxFlashesPerSecond: f.maxFlashesPerSecond, failing: f.failing.map((x) => ({ ...x, region: ['top-left', 'top', 'top-right', 'left', 'centre', 'right', 'bottom-left', 'bottom', 'bottom-right'][x.region] })),
+                        frames: m.series.length, fps: m.fps,
+                        method: 'WCAG 2.3.1 general flash: opposing luminance changes of >= 10% with the darker state below 0.8, over a 3 x 3 grid; more than 3 flashes in any second fails. A heuristic screen, not a certified PSE test (red flashes are not checked).' };
+                }
+                const pass = Object.values(report).every((r) => r.pass !== false);
+                return dataResult({ success: true, pass, ...report });
+            }
+            case 'pinepaper_render_batch': {
+                const input = RenderBatchInputSchema.parse(args);
+                const exportCheck = AgentExportInputSchema.safeParse(input.export);
+                if (!exportCheck.success) {
+                    return errorResult(ErrorCodes.VALIDATION_ERROR, `export options are not valid agent_export options: ${exportCheck.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ')}`);
+                }
+                const itemIds = [...new Set(input.rows.flatMap((r) => Object.keys(r.changes ?? {})))];
+                if (input.estimateOnly) {
+                    // Item ids are checked against the live scene when there is one, so
+                    // a typo shows up in the plan rather than as a failed row.
+                    let missingItems;
+                    if ((options.executionMode ?? getExecutionMode()) !== 'code' && options.executeInBrowser && itemIds.length) {
+                        try {
+                            const controller = options.browserController || getBrowserController();
+                            if (!controller.connected)
+                                await controller.connect();
+                            const r = await controller.executeCode(`(function() { const ids = ${JSON.stringify(itemIds)}; return ids.filter(function(id) { const e = app.itemRegistry && app.itemRegistry.get(id); return !(e && e.item); }); })();`, false);
+                            if (r.success && Array.isArray(r.result))
+                                missingItems = r.result;
+                        }
+                        catch { /* unchecked: said below */ }
+                    }
+                    return dataResult({
+                        rows: input.rows.length, itemsChanged: itemIds, export: input.export,
+                        ...(missingItems ? { missingItems, ok: missingItems.length === 0 } : { itemsChecked: false }),
+                        note: 'nothing rendered. Each row runs modify_item per item, template_params when given, then agent_export.'
+                            + (missingItems && missingItems.length ? ` These items are not on the canvas, so rows naming them would fail: ${missingItems.join(', ')}.` : '')
+                            + (missingItems ? '' : ' Item ids were not checked (no live studio).'),
+                    });
+                }
+                if ((options.executionMode ?? getExecutionMode()) === 'code' || !options.executeInBrowser) {
+                    return errorResult(ErrorCodes.VALIDATION_ERROR, 'render_batch renders each row, so it needs a live studio (browser execution). In code-only mode, call modify_item and agent_export per row yourself.');
+                }
+                const rowResults = [];
+                for (let i = 0; i < input.rows.length; i++) {
+                    const row = input.rows[i];
+                    const out = { index: i, ...(row.id ? { id: row.id } : {}) };
+                    const fail = (stage, r) => {
+                        out.success = false;
+                        out.stage = stage;
+                        out.error = toolText(r).slice(0, 600);
+                    };
+                    let failed = false;
+                    for (const [itemId, properties] of Object.entries(row.changes ?? {})) {
+                        const r = await handleToolCall('pinepaper_modify_item', { itemId, properties }, options);
+                        if (r.isError || /"success":\s*false/.test(toolText(r))) {
+                            fail(`modify ${itemId}`, r);
+                            failed = true;
+                            break;
+                        }
+                        const ignored = /"ignoredProperties":\s*(\[[^\]]*\])/.exec(toolText(r));
+                        if (ignored) {
+                            const bag = (out.ignored ?? {});
+                            bag[itemId] = JSON.parse(ignored[1]);
+                            out.ignored = bag;
+                        }
+                    }
+                    if (!failed && row.template) {
+                        const r = await handleToolCall('pinepaper_template_params', { action: 'apply', templateId: row.template.templateId, params: row.template.params }, options);
+                        if (r.isError || /"success":\s*false/.test(toolText(r))) {
+                            fail('template', r);
+                            failed = true;
+                        }
+                    }
+                    if (!failed) {
+                        // saveToFile: a small still would otherwise come back inline, and a
+                        // batch row must name a file.
+                        const r = await handleToolCall('pinepaper_agent_export', input.export, { ...options, saveToFile: true });
+                        const text = toolText(r);
+                        if (r.isError) {
+                            fail('export', r);
+                        }
+                        else {
+                            const files = [...text.matchAll(/^(?:File|zip|html|backupImage): (\S+)$/gm)].map((m) => m[1]);
+                            if (files.length) {
+                                out.success = true;
+                                out.files = files;
+                            }
+                            else {
+                                out.success = false;
+                                out.stage = 'export';
+                                out.error = 'the export reported success but wrote no file: ' + text.slice(0, 300);
+                            }
+                            const json = text.indexOf('Result: ') >= 0 ? text.slice(text.indexOf('Result: ') + 8) : null;
+                            try {
+                                const parsed = json ? JSON.parse(json) : null;
+                                const warnings = parsed?.fidelity?.warnings;
+                                if (Array.isArray(warnings) && warnings.length)
+                                    out.warnings = warnings.map((w) => ({ code: w.code, message: w.message }));
+                            }
+                            catch { /* the file list stands on its own */ }
+                        }
+                    }
+                    rowResults.push(out);
+                }
+                const ok = rowResults.filter((r) => r.success).length;
+                return dataResult({
+                    success: ok === rowResults.length,
+                    rendered: ok,
+                    failed: rowResults.length - ok,
+                    rows: rowResults,
+                    ...(rowResults.some((r) => r.warnings) ? { note: 'rows with warnings rendered, but read them — text_overflow means copy past its box.' } : {}),
+                });
+            }
             case 'pinepaper_template_params': {
                 const input = TemplateParamsInputSchema.parse(args);
                 const code = codeGenerator.generateTemplateParams(input);
@@ -1468,8 +1989,39 @@ You can now start creating new items on a clean canvas.`,
             // -----------------------------------------------------------------------
             case 'pinepaper_import_svg': {
                 const input = ImportSVGInputSchema.parse(args);
-                const code = codeGenerator.generateImportSVG(input.svgString, input.url, input.position, input.scale, input.source);
-                const description = 'Imports SVG onto the canvas';
+                // Resolve the document HERE, so the page never has to fetch anything.
+                //
+                // Under pinepaper.studio's CSP (connect-src 'self' + the cloud origin)
+                // the page cannot fetch a third-party host at all, so the in-page
+                // inlining could only ever DROP remote images. Fetching the SVG and
+                // its images in this process means the browser receives a document
+                // with no remote references: nothing to fetch, nothing to taint, and
+                // the pictures arrive. The in-page pass stays as a backstop for an
+                // svgString handed straight to the generator elsewhere.
+                let svgText = input.svgString;
+                let svgWarnings = [];
+                if (input.url) {
+                    try {
+                        const res = await fetch(input.url, { redirect: 'follow' });
+                        if (!res.ok) {
+                            return errorResult(ErrorCodes.EXECUTION_ERROR, `the server refused ${input.url} — HTTP ${res.status} ${res.statusText || ''}`.trim());
+                        }
+                        svgText = await res.text();
+                    }
+                    catch (e) {
+                        const why = e instanceof Error ? e.message : 'network request failed';
+                        return errorResult(ErrorCodes.EXECUTION_ERROR, `could not reach ${input.url} — ${why}. This fetch runs in the MCP server rather than the page, so it is not a CSP problem.`);
+                    }
+                }
+                if (svgText && /(?:xlink:)?href\s*=\s*["']https?:/i.test(svgText)) {
+                    const inlined = await inlineSvgImages(svgText);
+                    svgText = inlined.svg;
+                    svgWarnings = inlined.warnings;
+                }
+                const code = codeGenerator.generateImportSVG(svgText, svgText ? undefined : input.url, input.position, input.scale, input.source);
+                const description = svgWarnings.length
+                    ? `Imports SVG onto the canvas (${svgWarnings.length} unreachable image(s) removed)`
+                    : 'Imports SVG onto the canvas';
                 return executeOrGenerate(code, description, options, 'pinepaper_import_svg');
             }
             case 'pinepaper_import_mermaid': {
@@ -1987,9 +2539,34 @@ You can now start creating new items on a clean canvas.`,
                         metadata = result.metadata;
                     }
                     else if (input.url) {
-                        // For URL imports, we'd need to fetch the SVG
-                        // For now, delegate to pinepaper_import_svg
-                        return errorResult(ErrorCodes.INVALID_PARAMS, 'URL imports not yet implemented - use pinepaper_import_svg with url parameter instead', { url: input.url });
+                        // IMPLEMENTED NOW, rather than redirected.
+                        //
+                        // This used to refuse with "URL imports not yet implemented" while
+                        // the agent guide documented the url parameter — the redirect
+                        // named a working alternative, which made it a good refusal, but
+                        // it was still a documented parameter that did nothing. The reason
+                        // it could not be done here was that fetching belonged to the
+                        // page; it does not any more, because the page cannot fetch a
+                        // third-party host under the studio's CSP and this process can.
+                        let res;
+                        try {
+                            res = await fetch(input.url, { redirect: 'follow' });
+                        }
+                        catch (e) {
+                            const why = e instanceof Error ? e.message : 'network request failed';
+                            return errorResult(ErrorCodes.EXECUTION_ERROR, `could not reach ${input.url} — ${why}. This fetch runs in the MCP server rather than the page, so it is not a CSP problem.`);
+                        }
+                        if (!res.ok) {
+                            return errorResult(ErrorCodes.EXECUTION_ERROR, `the server refused ${input.url} — HTTP ${res.status} ${res.statusText || ''}`.trim());
+                        }
+                        const body = await res.text();
+                        if (!/<svg[\s>]/i.test(body)) {
+                            const type = (res.headers.get('content-type') ?? '').split(';')[0].trim();
+                            return errorResult(ErrorCodes.INVALID_PARAMS, `${input.url} served "${type || 'no content-type'}" and its body is not SVG. `
+                                + 'For a raster image use pinepaper_import_image, which accepts a url and inlines it.');
+                        }
+                        svg = body;
+                        metadata = { source: 'url', url: input.url };
                     }
                     // Import the SVG onto canvas using existing import_svg tool
                     const code = codeGenerator.generateImportSVG(svg, undefined, input.position, input.scale);
@@ -2131,7 +2708,12 @@ You can now start creating new items on a clean canvas.`,
                         const previewScreenshot = await endJobController.takeScreenshot();
                         const content = [{
                                 type: 'text',
-                                text: `Executed PinePaper code:\n\n\`\`\`javascript\n${code}\n\`\`\`\n\nFull screenshot saved to: ${filePath} (${(fileSize / 1024).toFixed(1)} KB)\n\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
+                                // The script is not part of the answer here either — same reason
+                                // errors no longer carry it. PINEPAPER_ECHO_CODE=1 brings it back.
+                                text: (process.env.PINEPAPER_ECHO_CODE === '1'
+                                    ? `Executed PinePaper code:\n\n\`\`\`javascript\n${code}\n\`\`\`\n\n`
+                                    : '')
+                                    + `Full screenshot saved to: ${filePath} (${(fileSize / 1024).toFixed(1)} KB)\n\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
                             }];
                         if (previewScreenshot) {
                             content.push({
@@ -2388,7 +2970,29 @@ You can now start creating new items on a clean canvas.`,
                         return errorResult(ErrorCodes.EXECUTION_ERROR, streamError instanceof Error ? streamError.message : 'Paging the export out of the store failed', { code, exportId: exportResult.exportId, size: exportResult.size }, { toolName: 'pinepaper_agent_export', canvasState: canvasState || undefined });
                     }
                 }
-                const shouldSaveToFile = data && typeof data === 'string' && (ALWAYS_SAVE_FORMATS.has(format) ||
+                // AN AD (8.21 / 8.24): the studio sent its widget page; the network
+                // wrapper, the zip and the size check are done here.
+                // SCC (CEA-608, 8.37): the studio sent the cues; encoded here.
+                if (format === 'scc' && Array.isArray(exportResult?.sccCues)) {
+                    const scc = buildScc(exportResult.sccCues);
+                    const { filePath, fileSize } = await saveExportToFile(scc.text, 'scc', input.platform || 'auto');
+                    const warnings = [];
+                    if (scc.truncated)
+                        warnings.push({ code: 'caption_truncated', message: `${scc.truncated} caption(s) did not fit two rows of 32 characters and were cut. Split long captions into more cues.` });
+                    if (scc.replacedChars.length)
+                        warnings.push({ code: 'caption_chars_dropped', message: `characters outside the CEA-608 set were left out: ${scc.replacedChars.join(' ')}. 608 carries Latin letters, digits, common punctuation and a few accented letters.` });
+                    if (scc.delayed.length)
+                        warnings.push({ code: 'caption_delayed', message: `${scc.delayed.length} caption(s) went on late — 608 carries two bytes a frame, so a caption needs time to load before it shows: ${scc.delayed.slice(0, 5).map((d) => `cue ${d.cue + 1} by ${d.frames} frame(s)`).join(', ')}. Leave more time between captions.` });
+                    const { sccCues: _c, ...rest } = exportResult;
+                    void _c;
+                    const cleanResult = { ...rest, filePath, fileSize, frameRate: '29.97 drop-frame', fidelity: { warnings } };
+                    return { content: [{ type: 'text', text: `Export saved to file:\n\nFile: ${filePath}\nFormat: scc (CEA-608, CC1, pop-on)\nSize: ${fileSize} bytes\n\nResult: ${JSON.stringify(cleanResult, null, 2)}` }] };
+                }
+                if ((format === 'html5-ad' || format === 'playable') && typeof exportResult?.adPage === 'string') {
+                    return saveAdExport(exportResult, input, input.platform || 'auto');
+                }
+                const shouldSaveToFile = data && typeof data === 'string' && (options.saveToFile ||
+                    ALWAYS_SAVE_FORMATS.has(format) ||
                     data.length > SAVE_THRESHOLD_BYTES);
                 if (shouldSaveToFile) {
                     try {
@@ -2638,8 +3242,22 @@ You can now start creating new items on a clean canvas.`,
                 if ('error' in resolved) {
                     return errorResult(ErrorCodes.INVALID_PARAMS, resolved.error, { url: parsed.url }, { toolName: 'pinepaper_import_image' });
                 }
-                const code = codeGenerator.generateImportImage({ ...parsed, url: resolved.src });
-                return executeOrGenerate(code, 'Imports image', options, 'pinepaper_import_image');
+                // THE BYTES GO BESIDE THE CODE, NOT INSIDE IT.
+                //
+                // Inlining the data: URL turned a 3000x800 photo into ~630KB of
+                // generated JavaScript. app.runGenerated rewrites what it runs, and its
+                // loop-guard transform bails at that size — "Loop-guard transform
+                // bailed (unusual syntax)" — after which the run reported
+                // itemsCreated: 0 and lost the return value, so the import answered
+                // success with no itemId. Smaller photos were fine, which is exactly
+                // what made it look like a registration bug rather than a size one.
+                const staged = resolved.src.startsWith('data:') && resolved.src.length > 64_000;
+                const stageKey = staged ? `img_${Date.now().toString(36)}` : undefined;
+                const code = codeGenerator.generateImportImage({
+                    ...parsed,
+                    url: staged ? `__ppStage:${stageKey}` : resolved.src,
+                });
+                return executeOrGenerate(code, 'Imports image', options, 'pinepaper_import_image', staged ? { [stageKey]: resolved.src } : undefined);
             }
             // -----------------------------------------------------------------------
             // ONTOLOGY TOOLS — extracted to src/tools/handlers/ontology.ts