@pinepaper.studio/mcp-server 1.6.8 → 1.6.10

package/dist/tools/handlers.js

@@ -10,7 +10,7 @@ import { CreateItemInputSchema, ModifyItemInputSchema, DeleteItemInputSchema, Ad
 // Diagram schemas
 CreateDiagramShapeInputSchema, ConnectInputSchema, ConnectPortsInputSchema, AddPortsInputSchema, AutoLayoutInputSchema, GetDiagramShapesInputSchema, UpdateConnectorInputSchema, RemoveConnectorInputSchema, DiagramModeInputSchema, 
 // Agent flow mode schemas
-AgentStartJobInputSchema, AgentEndJobInputSchema, AgentResetInputSchema, AgentBatchExecuteInputSchema, AgentExportInputSchema, AgentAnalyzeInputSchema, 
+AgentStartJobInputSchema, AgentEndJobInputSchema, AgentResetInputSchema, AgentBatchExecuteInputSchema, AgentExportInputSchema, ExportStoreInputSchema, AgentAnalyzeInputSchema, 
 // Letter collage schemas
 CreateLetterCollageInputSchema, AnimateLetterCollageInputSchema, 
 // Map schemas
@@ -29,9 +29,10 @@ ManageScenesInputSchema, ScenePlaybackInputSchema, SceneGraphInputSchema, Sequen
 // 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 { writeFile, mkdir, appendFile, unlink } from 'node:fs/promises';
+import { writeFile, mkdir, appendFile, unlink, readFile, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { getBrowserController, resetBrowserController, } from '../browser/puppeteer-controller.js';
 import { sameStudioTarget, validateStudioUrl } from '../browser/url-target.js';
 import { getPerformanceTracker } from '../metrics/index.js';
@@ -84,6 +85,80 @@ function getExportDir() {
 // 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
+/**
+ * Governor budget for the export run itself.
+ *
+ * FxTool's runGenerated defaults to a 10s async-tail timeout — right for a
+ * scene-building script that has no business running longer, and fatal for an
+ * export, which renders frame by frame and is capped at 600s of footage. The
+ * export died at ten seconds with a PP_TIMEOUT that read like a bug in the
+ * scene. This raises the budget rather than bypassing the governor, so the
+ * report, the item budget and the seeded PRNG all survive.
+ *
+ * PINEPAPER_EXPORT_TIMEOUT overrides it. The default matches the floor put on
+ * CDP's own per-call timeout (MIN_PROTOCOL_TIMEOUT_MS in
+ * puppeteer-controller.ts), so raising this past the default without also
+ * raising PINEPAPER_TIMEOUT just moves the execution to a protocol error —
+ * which is why that case says so out loud rather than failing obscurely later.
+ */
+const EXPORT_GOVERNOR_DEFAULT_MS = 300_000;
+function exportGovernorTimeoutMs() {
+    const raw = Number(process.env.PINEPAPER_EXPORT_TIMEOUT);
+    if (!Number.isFinite(raw) || raw <= 0)
+        return EXPORT_GOVERNOR_DEFAULT_MS;
+    const protocolFloor = Math.max(Number(process.env.PINEPAPER_TIMEOUT) || 0, EXPORT_GOVERNOR_DEFAULT_MS);
+    if (raw > protocolFloor) {
+        console.error(`[PinePaper] PINEPAPER_EXPORT_TIMEOUT=${raw}ms is above the browser's protocol timeout (${protocolFloor}ms) — ` +
+            'raise PINEPAPER_TIMEOUT to match, or an export past that point fails as a protocol error rather than a governor timeout.');
+    }
+    return raw;
+}
+/**
+ * Turn whatever the caller named into something the page can load.
+ *
+ * http(s) and data URLs pass straight through — the page fetches those itself,
+ * and it reports the reason when it cannot. A LOCAL PATH is read here, because
+ * a browser page cannot open file:// and refusing it outright left an agent
+ * holding images it could not import with nothing to try instead.
+ *
+ * Bounded deliberately: an image extension, an existing regular file, and a
+ * size cap. This reads the user's disk on their instruction, the same as the
+ * export side writes to it, and neither should be a wildcard.
+ */
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.bmp', '.avif']);
+const MAX_LOCAL_IMAGE_BYTES = 32 * 1024 * 1024;
+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',
+};
+export async function resolveImageSource(input) {
+    const raw = input.trim();
+    if (/^(https?:|data:)/i.test(raw))
+        return { src: raw };
+    const path = raw.startsWith('file://') ? fileURLToPath(raw) : raw;
+    const ext = extname(path).toLowerCase();
+    if (!IMAGE_EXTENSIONS.has(ext)) {
+        return {
+            error: `"${input}" is neither an http(s) URL nor a path to an image file. `
+                + `Recognised image extensions: ${[...IMAGE_EXTENSIONS].join(', ')}.`,
+        };
+    }
+    let bytes;
+    try {
+        const info = await stat(path);
+        if (!info.isFile())
+            return { error: `"${path}" is not a file.` };
+        if (info.size > MAX_LOCAL_IMAGE_BYTES) {
+            return { error: `"${path}" is ${(info.size / 1024 / 1024).toFixed(1)} MB, above the ${MAX_LOCAL_IMAGE_BYTES / 1024 / 1024} MB import cap. Resize it, or serve it over http.` };
+        }
+        bytes = await readFile(path);
+    }
+    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.` };
+    }
+    return { src: `data:${IMAGE_MIME[ext] ?? 'application/octet-stream'};base64,${bytes.toString('base64')}` };
+}
 export function getFileExtension(format) {
     const extMap = { mp4: 'mp4', webm: 'webm', gif: 'gif', pdf: 'pdf', png: 'png', svg: 'svg', wav: 'wav' };
     return extMap[format] || format;
@@ -122,6 +197,8 @@ async function saveExportToFile(data, format, platform) {
  * recoverable. `releaseExport` runs only once the whole file is written.
  */
 async function streamRetainedExportToFile(controller, retained, platform) {
+    // Reassigned once if the store corrects the size below.
+    let corrected = false;
     const exportDir = getExportDir();
     await mkdir(exportDir, { recursive: true });
     const ext = getFileExtension(retained.format);
@@ -139,18 +216,78 @@ async function streamRetainedExportToFile(controller, retained, platform) {
             await unlink(filePath);
         }
         catch { /* nothing written yet */ }
-        return new Error(`${why} (export "${retained.exportId}" is still held in the studio, ${offset} of ${retained.size} bytes read; ` +
-            `it can be paged again, and is released only once a whole file is written)`);
+        return new Error(
+        // The promise now names the call that keeps it. It was true before and
+        // unreachable: reading a held export mutates nothing, so "it can be paged
+        // again" was always correct and there was no door to page it through.
+        `${why} (export "${retained.exportId}" is still held in the studio, ${offset} of ${retained.size} bytes read; ` +
+            `page it out with pinepaper_export_store action 'save', exportId "${retained.exportId}" — reading is idempotent, ` +
+            'so retrying costs nothing and the export is released only once a whole file is written. Do it BEFORE the next ' +
+            'export: a new one evicts the oldest held bytes to make room)');
     };
+    // A READ THAT FAILS ON SIZE IS NOT A READ THAT FAILS.
+    //
+    // A 17 MB memphis chunk died on its FOURTH 4 MB read — three had already
+    // landed — with "Failed to write data to data pipe". That is CDP refusing to
+    // carry one oversized value across the bridge, not the store refusing to
+    // serve it: the render had succeeded and the bytes were sitting right there.
+    // The loop abandoned the whole export anyway, and the caller was left with an
+    // error that explained the bytes were still held and no way to go get them.
+    //
+    // So a transport failure halves the request and asks again, down to a floor,
+    // before giving up. The offset does not move, so a retry costs one re-read,
+    // never a corrupt file. A refusal from the STORE (evicted, out of range) is
+    // NOT retried — that answer will not change with a smaller window, and
+    // retrying it would only spend the caller's time to reach the same place.
+    const MIN_CHUNK_BYTES = 256 * 1024;
+    let window = chunkBytes;
     for (;;) {
-        const code = codeGenerator.generateReadExportChunk(retained.exportId, offset, Math.min(chunkBytes, retained.size - offset));
+        const want = Math.min(window, retained.size - offset);
+        const code = codeGenerator.generateReadExportChunk(retained.exportId, offset, want);
+        // Deliberately governed at the default budget: a chunk read is a slice of a
+        // string already in memory. If one of these ever needs ten seconds, the
+        // store is wedged and a timeout is the correct answer, not a longer wait.
         const run = await controller.executeCode(code, false);
-        if (!run.success)
-            throw await abandon(`reading the export failed: ${run.error || 'unknown error'}`);
+        if (!run.success) {
+            if (want > MIN_CHUNK_BYTES) {
+                window = Math.max(MIN_CHUNK_BYTES, Math.floor(want / 2));
+                console.error(`[PinePaper] a ${want}-byte read of "${retained.exportId}" failed (${run.error || 'unknown error'}); `
+                    + `retrying the same offset at ${window} bytes`);
+                continue;
+            }
+            throw await abandon(`reading the export failed even at the ${MIN_CHUNK_BYTES}-byte floor: ${run.error || 'unknown error'}`);
+        }
         const chunk = run.result;
         if (!chunk || chunk.ok !== true) {
+            // A RANGE REFUSAL IS A CORRECTION, and it carries the real size.
+            //
+            // readExport refuses an out-of-range read by name rather than clamping —
+            // deliberately, so a miscounting caller is told instead of handed a short
+            // chunk it treats as the tail, which surfaces later as a truncated video
+            // with nothing pointing back at the cause. The size this loop is working
+            // from came from the export result, and `save` works from a listing; when
+            // either disagrees with the file, the refusal is the authority. Take it
+            // ONCE — a second disagreement is not a miscount, it is a moving target.
+            // Only when it DISAGREES. Every range refusal quotes the real size,
+            // including the ones that are refusing for some other reason — so
+            // matching the number alone treated an eviction as a miscount, spent the
+            // one correction on a no-op re-read, and hid the actual reason for an
+            // iteration.
+            const stated = /\(size (\d+)\)/.exec(chunk?.reason ?? '');
+            if (stated && !corrected && Number(stated[1]) !== retained.size) {
+                corrected = true;
+                const was = retained.size;
+                retained = { ...retained, size: Number(stated[1]) };
+                console.error(`[PinePaper] the store reports "${retained.exportId}" as ${retained.size} bytes, not ${was}; `
+                    + "taking the store's number and continuing");
+                continue;
+            }
             // An evicted id is its own failure: a later export reclaimed the space.
-            // Re-exporting is the caller's decision, never this loop's.
+            // Re-exporting is the caller's decision, never this loop's. The engine
+            // records an eviction in browser storage so it survives a reload, but
+            // that storage is best-effort — a private window, cleared site data or
+            // storage switched off all fall back to memory-only. So `evicted` being
+            // ABSENT means unknown, never that the export was not there.
             throw await abandon(chunk?.evicted
                 ? `the export was evicted mid-read: ${chunk.reason}`
                 : `the studio refused the read: ${chunk?.reason || 'no reason given'}`);
@@ -240,10 +377,25 @@ function executedResult(code, result, screenshot, description, report) {
         if (Object.keys(governor).length)
             resultObj.governor = governor;
     }
+    // THE CODE ECHO WAS 90% OF THE RESPONSE, AND THE AGENT WROTE THE REQUEST.
+    //
+    // Measured on a 50-item batch create: 8,740 characters of echoed source
+    // against 983 characters of actual result. A tester's cost study found the
+    // same thing from outside — response verbosity alone was 86% of the native
+    // path's token cost, and it is what makes enumerating 50 creates through
+    // tools 33x more expensive than a loop that produces the same picture.
+    //
+    // On a SUCCESSFUL browser run the code has already done its job and the
+    // caller knows what it asked for. It is still returned where it is the
+    // deliverable — 'code' execution mode — and where it is the evidence: every
+    // error path passes it in `details`. PINEPAPER_ECHO_CODE=1 brings it back
+    // for anyone debugging a generator.
     const content = [
         { type: 'text', text: JSON.stringify(resultObj, null, 2) },
-        { type: 'text', text: `Generated code:\n\`\`\`javascript\n${code}\n\`\`\`` },
     ];
+    if (process.env.PINEPAPER_ECHO_CODE === '1') {
+        content.push({ type: 'text', text: `Generated code:\n\`\`\`javascript\n${code}\n\`\`\`` });
+    }
     if (screenshot) {
         content.push({
             type: 'image',
@@ -493,8 +645,47 @@ ${code}
             canvasState: canvasState || undefined,
         });
     }
+    // TWO VERDICTS. `result.success` says the CODE RAN. The emitted code has its
+    // own verdict, and almost every emitter in this repo returns
+    // `{ success: false, error }` when it cannot do the thing — a guard that
+    // found a subsystem missing, an engine call that refused, a precondition that
+    // was not met. Nothing here read it, so every one of those came back to the
+    // agent as a success with an error buried in the payload.
+    //
+    // Measured twice by a beta tester: two of five video chunks silently lost,
+    // and a rigging session where "app.riggingSystem unavailable" rode inside an
+    // outer success and the agent kept building on a rig that did not exist.
+    // pinepaper_agent_export got this check in 1.6.9; it belongs HERE, where
+    // every tool inherits it.
+    const inner = innerFailure(result.result);
+    if (inner) {
+        const canvasState = await captureCanvasState(controller);
+        return errorResult(ErrorCodes.EXECUTION_ERROR, inner, { code, result: result.result, governorReport: result.report }, { toolName, canvasState: canvasState || undefined });
+    }
     return executedResult(code, result.result, result.screenshot, description, result.report);
 }
+/**
+ * The emitted code's own verdict, when it reported one and it was a failure.
+ *
+ * Deliberately narrow. `success: false` is the shape this repo's emitters use
+ * and the only one treated as a failure — a result merely LACKING `success` is
+ * 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`.
+ */
+export function innerFailure(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const r = value;
+    const failed = r.success === false || r.ok === false;
+    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;
+}
 // =============================================================================
 // I18N HELPER FUNCTIONS
 // =============================================================================
@@ -2021,6 +2212,74 @@ You can now start creating new items on a clean canvas.`,
                 }
                 return batchResult;
             }
+            case 'pinepaper_export_store': {
+                const input = ExportStoreInputSchema.parse(args);
+                const controller = options.browserController || getBrowserController();
+                if (!controller.connected) {
+                    try {
+                        await controller.connect();
+                    }
+                    catch (connectError) {
+                        return errorResult(ErrorCodes.EXECUTION_ERROR, `the export store lives in the studio, and connecting to it failed: ${connectError instanceof Error ? connectError.message : 'unknown error'}`, {}, { toolName: 'pinepaper_export_store' });
+                    }
+                }
+                const held = await controller.executeCode(codeGenerator.generateListExports(), false);
+                if (!held.success) {
+                    return errorResult(ErrorCodes.EXECUTION_ERROR, `listing the export store failed: ${held.error || 'unknown error'}`, {}, { toolName: 'pinepaper_export_store' });
+                }
+                const listing = held.result;
+                if (!listing || listing.ok !== true) {
+                    return errorResult(ErrorCodes.EXECUTION_ERROR, listing?.reason || 'the studio did not answer with a listing', {}, { toolName: 'pinepaper_export_store' });
+                }
+                const exports = listing.exports ?? [];
+                if (input.action === 'list') {
+                    return dataResult({
+                        exports,
+                        held: exports.length,
+                        heldBytes: exports.reduce((n, e) => n + (e.size || 0), 0),
+                        note: exports.length > 1
+                            ? 'A later export evicts the OLDEST held ones to make room. Save or release each before starting the next.'
+                            : undefined,
+                    });
+                }
+                // Both remaining actions name an id, and an id the store does not have
+                // is the one thing worth saying carefully. The engine records an
+                // eviction durably enough to survive a reload, so a read of that id
+                // will usually say "evicted" — but the record is best-effort browser
+                // storage and a listing cannot consult it at all. Absence of the id
+                // here is therefore "gone, cause unknown", and stating one cause as
+                // fact would be inventing the more interesting half of the answer.
+                const entry = exports.find((e) => e.id === input.exportId);
+                if (!entry) {
+                    return errorResult(ErrorCodes.INVALID_PARAMS, `the studio is not holding "${input.exportId}". It was released, evicted to make room for a later export, `
+                        + `or never existed here — a listing cannot tell which. `
+                        + `${exports.length ? `Held right now: ${exports.map((e) => e.id).join(', ')}.` : 'The store is empty.'}`, { exportId: input.exportId, held: exports.map((e) => e.id) }, { toolName: 'pinepaper_export_store' });
+                }
+                if (input.action === 'release') {
+                    const dropped = await controller.executeCode(codeGenerator.generateReleaseExport(entry.id), false);
+                    const outcome = dropped.result;
+                    if (!dropped.success || outcome?.ok !== true) {
+                        return errorResult(ErrorCodes.EXECUTION_ERROR, `releasing "${entry.id}" failed: ${dropped.error || outcome?.reason || 'unknown error'}`, { exportId: entry.id }, { toolName: 'pinepaper_export_store' });
+                    }
+                    return dataResult({ released: entry.id, freedBytes: entry.size });
+                }
+                // save: the same pager agent_export uses, pointed at an id instead of a
+                // fresh render. Reading is idempotent, so a save that failed halfway
+                // can simply be run again — there is no partial state to clean up here.
+                try {
+                    const { filePath, fileSize, chunks } = await streamRetainedExportToFile(controller, { exportId: entry.id, size: entry.size, format: entry.format }, input.platform || 'recovered');
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `Export recovered from the studio's store:\n\nFile: ${filePath}\nFormat: ${entry.format}\n`
+                                    + `Size: ${(fileSize / 1024).toFixed(1)} KB\nPaged out in ${chunks} chunk${chunks === 1 ? '' : 's'}, then released\n`,
+                            }],
+                    };
+                }
+                catch (streamError) {
+                    return errorResult(ErrorCodes.EXECUTION_ERROR, streamError instanceof Error ? streamError.message : 'paging the export out of the store failed', { exportId: entry.id, size: entry.size }, { toolName: 'pinepaper_export_store' });
+                }
+            }
             case 'pinepaper_agent_export': {
                 const input = AgentExportInputSchema.parse(args);
                 const code = codeGenerator.generateAgentExport(input);
@@ -2048,12 +2307,46 @@ You can now start creating new items on a clean canvas.`,
                 if (!exportSessionManager.hasActiveJob()) {
                     exportSessionManager.startJob({ name: 'auto_session', screenshotPolicy: 'on_complete' });
                 }
-                const exportBrowserResult = await controller.executeCode(code, false);
+                const exportBrowserResult = await controller.executeCode(code, false, {
+                    governorTimeoutMs: exportGovernorTimeoutMs(),
+                });
                 if (!exportBrowserResult.success) {
                     const canvasState = await captureCanvasState(controller);
                     return errorResult(ErrorCodes.EXECUTION_ERROR, exportBrowserResult.error || 'Export failed', { code }, { toolName: 'pinepaper_agent_export', canvasState: canvasState || undefined });
                 }
                 const exportResult = exportBrowserResult.result;
+                // TWO VERDICTS, and only one of them was being read.
+                //
+                // `exportBrowserResult.success` says the CODE RAN. The export's own
+                // verdict is `exportResult.success`, and every emitted branch that
+                // cannot deliver returns `{ success: false, error }` — a studio without
+                // the renderer, an encoder that died, a blob past the inline ceiling.
+                // None of that was checked: the value fell through to the inline return
+                // below, which reports a success and hands back a result object nobody
+                // reads past the first line.
+                //
+                // Measured cost: a five-chunk video where two chunks came back
+                // `success: false, error: "export failed: Failed to write data to data
+                // pipe"` under an outer `"success": true`. The caller shipped a
+                // three-chunk video believing it had five. A silent success is the one
+                // failure mode this surface can never afford, because nothing
+                // downstream has any reason to look again.
+                if (exportResult && exportResult.success === false) {
+                    const canvasState = await captureCanvasState(controller);
+                    // A "data pipe" failure is the BROWSER TRANSPORT refusing to carry
+                    // the result back, not the encoder refusing to make it — the string
+                    // exists nowhere in the engine. So the render may well have finished
+                    // and the bytes may be sitting in the export store right now. Saying
+                    // so is the difference between recovering an export and re-rendering
+                    // one, and re-rendering is what evicts an earlier chunk's bytes.
+                    const looksLikeTransport = /data pipe/i.test(String(exportResult.error ?? ''));
+                    return errorResult(ErrorCodes.EXECUTION_ERROR, `export failed: ${exportResult.error || 'the studio reported failure without naming a reason'}`
+                        + (looksLikeTransport
+                            ? ' — that is the browser transport failing to carry the result back, not necessarily the render failing.'
+                                + " Call pinepaper_export_store action 'list' BEFORE re-rendering: the bytes may already be held, and a"
+                                + ' fresh export can evict an earlier one to make room.'
+                            : ''), { code, format: exportResult.format ?? input.format, result: exportResult }, { toolName: 'pinepaper_agent_export', canvasState: canvasState || undefined });
+                }
                 const format = exportResult?.format || input.format || 'png';
                 const data = exportResult?.data;
                 // RETAINED: the studio held the encoded file in its export store rather
@@ -2145,6 +2438,18 @@ You can now start creating new items on a clean canvas.`,
                         }
                         return dataResult(sys);
                     }
+                    case 'list_motion': {
+                        // Curves and durations together, because a motion token is a shape
+                        // AND a length. The curves were published and the durations beside
+                        // them in the same store were not, so a caller could match a
+                        // system's easing and had to invent its timing.
+                        const easings = designSystems.listEasings(input.authoredOnly);
+                        const durations = designSystems.listDurations(input.authoredOnly);
+                        return dataResult({
+                            easings, durations,
+                            note: 'These are the licensed SYSTEMS\' motion scales. An aesthetic style (bauhaus_geometric, memphis_group) carries no upstream motion data — pair one of these with a style rather than expecting the style to name its own.',
+                        });
+                    }
                     case 'list_easings':
                         return dataResult({ easings: designSystems.listEasings(input.authoredOnly) });
                     case 'list_styles':
@@ -2312,7 +2617,19 @@ You can now start creating new items on a clean canvas.`,
             // -----------------------------------------------------------------------
             case 'pinepaper_import_image': {
                 const parsed = ImportImageInputSchema.parse(args);
-                const code = codeGenerator.generateImportImage(parsed);
+                // A LOCAL PATH IS THE COMMON CASE AND WAS THE REJECTED ONE.
+                //
+                // The browser cannot open file:// from a page, so this tool took URLs
+                // only — which leaves an agent that has just generated or downloaded
+                // ten images with no way in, and no alternative named. The server CAN
+                // read the file, so it reads it and hands the page a data URL. Nothing
+                // about the page changes; the bytes simply arrive by a route the
+                // browser is allowed to use.
+                const resolved = await resolveImageSource(parsed.url);
+                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');
             }
             // -----------------------------------------------------------------------