@bubblebrain-ai/bubble 0.0.12 → 0.0.14

package/dist/tui/global-key-router.js

@@ -0,0 +1,87 @@
+import { isEscapeSequence } from "./prompt-keybindings.js";
+export function normalizeKeyName(name) {
+    const rawName = String(name || "").toLowerCase();
+    if (["arrowleft", "left_arrow", "leftarrow", "cursorleft", "left"].includes(rawName))
+        return "left";
+    if (["arrowright", "right_arrow", "rightarrow", "cursorright", "right"].includes(rawName))
+        return "right";
+    if (["arrowup", "up_arrow", "uparrow", "cursorup", "up"].includes(rawName))
+        return "up";
+    if (["arrowdown", "down_arrow", "downarrow", "cursordown", "down"].includes(rawName))
+        return "down";
+    if (rawName === "return" || rawName === "enter")
+        return "enter";
+    if (rawName === "esc" || rawName === "escape")
+        return "escape";
+    if (rawName === "tab")
+        return "tab";
+    return rawName;
+}
+export function keyNameFromSequence(sequence) {
+    if (!sequence)
+        return "";
+    const kittyName = keyNameFromKittySequence(sequence);
+    if (kittyName)
+        return kittyName;
+    if (sequence === "\x1b[D" || /^\x1b\[[0-9;]*D$/.test(sequence))
+        return "left";
+    if (sequence === "\x1b[C" || /^\x1b\[[0-9;]*C$/.test(sequence))
+        return "right";
+    if (sequence === "\x1b[A" || /^\x1b\[[0-9;]*A$/.test(sequence))
+        return "up";
+    if (sequence === "\x1b[B" || /^\x1b\[[0-9;]*B$/.test(sequence))
+        return "down";
+    if (sequence === "\x1bOD")
+        return "left";
+    if (sequence === "\x1bOC")
+        return "right";
+    if (sequence === "\x1bOA")
+        return "up";
+    if (sequence === "\x1bOB")
+        return "down";
+    if (sequence === "\t")
+        return "tab";
+    if (sequence === "\r" || sequence === "\n")
+        return "enter";
+    if (isEscapeSequence(sequence))
+        return "escape";
+    return "";
+}
+function keyNameFromKittySequence(sequence) {
+    const kittyMatch = /^\x1b\[(\d+)(?:;[1-9]\d*(?::[1-3])?)?u$/.exec(sequence);
+    const kittyCode = kittyMatch?.[1] ? Number(kittyMatch[1]) : NaN;
+    if (!Number.isNaN(kittyCode))
+        return keyNameFromKittyCode(kittyCode);
+    const modifyOtherKeysMatch = /^\x1b\[27;[1-9]\d*(?::[1-3])?;(\d+)~$/.exec(sequence);
+    const modifyOtherKeysCode = modifyOtherKeysMatch?.[1] ? Number(modifyOtherKeysMatch[1]) : NaN;
+    if (!Number.isNaN(modifyOtherKeysCode))
+        return keyNameFromKittyCode(modifyOtherKeysCode);
+    return "";
+}
+function keyNameFromKittyCode(code) {
+    switch (code) {
+        case 27:
+        case 57344:
+            return "escape";
+        case 9:
+        case 57346:
+            return "tab";
+        case 13:
+        case 57345:
+            return "enter";
+        case 57350:
+            return "left";
+        case 57351:
+            return "right";
+        case 57352:
+            return "up";
+        case 57353:
+            return "down";
+        default:
+            return "";
+    }
+}
+export function keyNameFromEvent(event) {
+    const rawName = normalizeKeyName(event?.name || event?.key || event?.input);
+    return rawName || keyNameFromSequence(event?.raw || event?.sequence);
+}

package/dist/tui/image-paste.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Image paste utilities: path detection, file reading, clipboard access, and size-capping.
+ *
+ * Terminals don't forward image bytes to stdin. Paths arrive as text when users
+ * drag files in; Cmd+V of an image produces an empty paste (we probe the
+ * clipboard). macOS screenshot shortcut (Cmd+Shift+Ctrl+4) writes to both a
+ * TemporaryItems path and the clipboard — the path often gets cleaned up before
+ * we can read it, so we fall back to the clipboard.
+ */
+import type { ContentPart } from "../types.js";
+export interface ImageAttachment {
+    base64: string;
+    mediaType: string;
+    /** Raw byte size of the decoded image (not base64). */
+    bytes: number;
+    /** data:<mediaType>;base64,<...> — ready to send as image_url.url. */
+    dataUrl: string;
+    filename?: string;
+    sourcePath?: string;
+}
+export interface ImagePathToken {
+    rawPath: string;
+    start: number;
+    end: number;
+}
+export interface ImageInputResolution {
+    actualInput: string | ContentPart[];
+    displayInput: string;
+    errors: string[];
+    attachments: ImageAttachment[];
+    imagePathCount: number;
+}
+export interface LabeledImageAttachment extends ImageAttachment {
+    label: string;
+}
+export interface ComposerImageResolution {
+    text: string;
+    attachments: LabeledImageAttachment[];
+    errors: string[];
+    imagePathCount: number;
+    nextLabelIndex: number;
+}
+export declare function isImageFilePath(raw: string): boolean;
+export declare function extractImagePathTokens(input: string): ImagePathToken[];
+export declare function removeImagePathTokens(input: string, tokens: ImagePathToken[]): string;
+export declare function imageAttachmentLabel(att: ImageAttachment, index: number): string;
+export declare function imageAttachmentReference(att: ImageAttachment, index: number): string;
+export declare function imageAttachmentLabelPattern(): RegExp;
+export declare function buildImageContentParts(promptText: string, attachments: ImageAttachment[]): ContentPart[];
+export declare function formatImageDisplayInput(promptText: string, attachments: ImageAttachment[], labelStart?: number): string;
+export declare function buildImageContentPartsFromLabels(input: string, attachmentsByLabel: Map<string, ImageAttachment>): {
+    actualInput?: ContentPart[];
+    displayInput: string;
+    usedLabels: string[];
+};
+/**
+ * Split a pasted blob into candidate path tokens.
+ *
+ * Multi-drag from Finder delivers a mix of newline- and space-separated
+ * absolute paths. Spaces inside a single path are escaped (`\ `) — we split
+ * only on a space that is followed by the start of a new absolute path.
+ */
+export declare function splitPastedPaths(pasted: string): string[];
+export declare function readImageFromPath(rawPath: string): Promise<ImageAttachment | null>;
+/** macOS screenshot shortcut writes to these paths and they may be auto-cleaned. */
+export declare function isScreenshotTempPath(s: string): boolean;
+export declare function getImageFromClipboard(): Promise<ImageAttachment | null>;
+/**
+ * If the image is close to the API size cap, try to downscale it in place.
+ * Uses the OS-native tools that are typically available:
+ *   - macOS: `sips` (always present)
+ *   - linux: ImageMagick `convert` (if installed)
+ * Returns the original attachment if resize isn't needed or can't run.
+ */
+export declare function maybeResizeImage(att: ImageAttachment): Promise<ImageAttachment>;
+export interface ValidationResult {
+    ok: boolean;
+    reason?: string;
+}
+export declare function validateImageSize(att: ImageAttachment): ValidationResult;
+/** End-to-end: given a file path, read -> resize-if-needed -> validate. */
+export declare function ingestImagePath(p: string): Promise<{
+    attachment?: ImageAttachment;
+    error?: string;
+}>;
+export declare function ingestClipboardImage(): Promise<{
+    attachment?: ImageAttachment;
+    error?: string;
+}>;
+export declare function resolveImageInput(input: string, options?: {
+    labelStart?: number;
+}): Promise<ImageInputResolution>;
+export declare function resolveComposerImagePaths(input: string, options?: {
+    labelStart?: number;
+}): Promise<ComposerImageResolution>;

package/dist/tui/image-paste.js

@@ -0,0 +1,505 @@
+/**
+ * Image paste utilities: path detection, file reading, clipboard access, and size-capping.
+ *
+ * Terminals don't forward image bytes to stdin. Paths arrive as text when users
+ * drag files in; Cmd+V of an image produces an empty paste (we probe the
+ * clipboard). macOS screenshot shortcut (Cmd+Shift+Ctrl+4) writes to both a
+ * TemporaryItems path and the clipboard — the path often gets cleaned up before
+ * we can read it, so we fall back to the clipboard.
+ */
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const IMAGE_EXT = /\.(png|jpe?g|gif|webp|bmp)$/i;
+const IMAGE_EXT_SOURCE = String.raw `(?:png|jpe?g|gif|webp|bmp)`;
+// Anthropic/OpenAI image uploads cap at ~5MB base64. We target a bit below so
+// the base64 inflation (4/3) doesn't push us over.
+const MAX_BASE64_BYTES = 5 * 1024 * 1024;
+const RESIZE_TRIGGER_BYTES = Math.floor(MAX_BASE64_BYTES * 0.95);
+// Target max dimension for auto-resize.
+const RESIZE_MAX_DIM = 2048;
+export function isImageFilePath(raw) {
+    const s = raw.trim();
+    if (!s)
+        return false;
+    if (!IMAGE_EXT.test(s))
+        return false;
+    // Require an absolute or home-relative path. Pasted arbitrary text shouldn't
+    // be treated as a path.
+    return path.isAbsolute(s) || s.startsWith("~") || /^[A-Za-z]:\\/.test(s);
+}
+export function extractImagePathTokens(input) {
+    const pattern = new RegExp(String.raw `(^|\s)(?:"([^"]+\.${IMAGE_EXT_SOURCE})"|'([^']+\.${IMAGE_EXT_SOURCE})'|((?:~|\/|[A-Za-z]:\\)(?:\\ |[^\s"'<>])+\.${IMAGE_EXT_SOURCE}))(?=$|\s)`, "gi");
+    const tokens = [];
+    for (const match of input.matchAll(pattern)) {
+        const leading = match[1] ?? "";
+        const rawPath = match[2] ?? match[3] ?? match[4];
+        if (!rawPath || !isImageFilePath(rawPath))
+            continue;
+        const start = (match.index ?? 0) + leading.length;
+        const end = (match.index ?? 0) + match[0].length;
+        tokens.push({ rawPath, start, end });
+    }
+    return tokens;
+}
+export function removeImagePathTokens(input, tokens) {
+    if (tokens.length === 0)
+        return input.trim();
+    let out = "";
+    let cursor = 0;
+    for (const token of tokens) {
+        out += input.slice(cursor, token.start);
+        out += " ";
+        cursor = token.end;
+    }
+    out += input.slice(cursor);
+    return out
+        .replace(/[ \t]+/g, " ")
+        .replace(/ *\n */g, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+export function imageAttachmentLabel(att, index) {
+    return `image#${index}${imageExtension(att)}`;
+}
+export function imageAttachmentReference(att, index) {
+    return `[${imageAttachmentLabel(att, index)}]`;
+}
+export function imageAttachmentLabelPattern() {
+    return /\[image#(\d+)\.[^\]\s]+\]/g;
+}
+function defaultImagePrompt(count) {
+    return count === 1
+        ? "Please analyze the attached image."
+        : "Please analyze the attached images.";
+}
+function imageExtension(att) {
+    const fromPath = path.extname(att.filename ?? att.sourcePath ?? "").toLowerCase();
+    if (fromPath)
+        return fromPath;
+    if (att.mediaType === "image/jpeg")
+        return ".jpg";
+    if (att.mediaType === "image/webp")
+        return ".webp";
+    if (att.mediaType === "image/gif")
+        return ".gif";
+    if (att.mediaType === "image/bmp")
+        return ".bmp";
+    return ".png";
+}
+export function buildImageContentParts(promptText, attachments) {
+    const text = promptText.trim() || defaultImagePrompt(attachments.length);
+    return [
+        { type: "text", text },
+        ...attachments.map((attachment) => ({
+            type: "image_url",
+            image_url: { url: attachment.dataUrl },
+        })),
+    ];
+}
+export function formatImageDisplayInput(promptText, attachments, labelStart = 1) {
+    const text = promptText.trim() || defaultImagePrompt(attachments.length);
+    const imageLines = attachments.map((attachment, index) => imageAttachmentReference(attachment, labelStart + index));
+    return `${text}\n${imageLines.join("\n")}`;
+}
+export function buildImageContentPartsFromLabels(input, attachmentsByLabel) {
+    const matches = Array.from(input.matchAll(imageAttachmentLabelPattern()));
+    const usedLabels = [];
+    const parts = [];
+    let cursor = 0;
+    for (const match of matches) {
+        const label = match[0].slice(1, -1);
+        const attachment = attachmentsByLabel.get(label);
+        if (!attachment)
+            continue;
+        const start = match.index ?? 0;
+        const before = input.slice(cursor, start).trim();
+        if (before)
+            parts.push({ type: "text", text: before });
+        parts.push({ type: "image_url", image_url: { url: attachment.dataUrl } });
+        usedLabels.push(label);
+        cursor = start + match[0].length;
+    }
+    if (usedLabels.length === 0)
+        return { displayInput: input, usedLabels: [] };
+    const rest = input.slice(cursor).trim();
+    if (rest)
+        parts.push({ type: "text", text: rest });
+    if (!parts.some((part) => part.type === "text")) {
+        parts.unshift({ type: "text", text: defaultImagePrompt(usedLabels.length) });
+    }
+    return {
+        actualInput: parts,
+        displayInput: input.trim() || usedLabels.map((label) => `[${label}]`).join("\n"),
+        usedLabels,
+    };
+}
+/**
+ * Split a pasted blob into candidate path tokens.
+ *
+ * Multi-drag from Finder delivers a mix of newline- and space-separated
+ * absolute paths. Spaces inside a single path are escaped (`\ `) — we split
+ * only on a space that is followed by the start of a new absolute path.
+ */
+export function splitPastedPaths(pasted) {
+    const out = [];
+    for (const line of pasted.split(/\r?\n/)) {
+        for (const piece of line.split(/ (?=\/|[A-Za-z]:\\)/)) {
+            const t = piece.trim();
+            if (t)
+                out.push(t);
+        }
+    }
+    return out;
+}
+function mediaTypeFromExt(p) {
+    const ext = path.extname(p).toLowerCase();
+    if (ext === ".jpg" || ext === ".jpeg")
+        return "image/jpeg";
+    if (ext === ".gif")
+        return "image/gif";
+    if (ext === ".webp")
+        return "image/webp";
+    if (ext === ".bmp")
+        return "image/bmp";
+    return "image/png";
+}
+function resolveHome(p) {
+    if (p.startsWith("~/") || p === "~") {
+        return path.join(os.homedir(), p.slice(1));
+    }
+    return p;
+}
+function unescapeShell(p) {
+    return p.replace(/\\ /g, " ");
+}
+function attachmentFromBuffer(buffer, mediaType, meta = {}) {
+    const base64 = buffer.toString("base64");
+    return {
+        base64,
+        mediaType,
+        bytes: buffer.length,
+        dataUrl: `data:${mediaType};base64,${base64}`,
+        filename: meta.filename,
+        sourcePath: meta.sourcePath,
+    };
+}
+export async function readImageFromPath(rawPath) {
+    const resolved = resolveHome(unescapeShell(rawPath.trim()));
+    try {
+        const stat = await fs.stat(resolved);
+        if (!stat.isFile())
+            return null;
+        const buffer = await fs.readFile(resolved);
+        return attachmentFromBuffer(buffer, mediaTypeFromExt(resolved), {
+            filename: path.basename(resolved),
+            sourcePath: resolved,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/** macOS screenshot shortcut writes to these paths and they may be auto-cleaned. */
+export function isScreenshotTempPath(s) {
+    return /\/TemporaryItems\/.*screencaptureui.*\/Screenshot/i.test(s);
+}
+export async function getImageFromClipboard() {
+    switch (process.platform) {
+        case "darwin":
+            return getClipboardImageDarwin();
+        case "linux":
+            return getClipboardImageLinux();
+        case "win32":
+            return getClipboardImageWindows();
+        default:
+            return null;
+    }
+}
+async function getClipboardImageDarwin() {
+    // Probe first — `as «class PNGf»` throws if clipboard has no image.
+    try {
+        await execFileAsync("osascript", ["-e", "the clipboard as «class PNGf»"], {
+            timeout: 5000,
+        });
+    }
+    catch {
+        return null;
+    }
+    const tmp = path.join(os.tmpdir(), `bubble_clip_${Date.now()}_${process.pid}.png`);
+    const script = `set png_data to (the clipboard as «class PNGf»)\n` +
+        `set fp to open for access POSIX file "${tmp}" with write permission\n` +
+        `write png_data to fp\n` +
+        `close access fp`;
+    try {
+        await execFileAsync("osascript", ["-e", script], { timeout: 5000 });
+        const buf = await fs.readFile(tmp);
+        return attachmentFromBuffer(buf, "image/png");
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await fs.unlink(tmp).catch(() => undefined);
+    }
+}
+async function getClipboardImageLinux() {
+    const candidates = [
+        ["xclip", ["-selection", "clipboard", "-t", "image/png", "-o"]],
+        ["wl-paste", ["--type", "image/png"]],
+    ];
+    for (const [cmd, args] of candidates) {
+        try {
+            // encoding: "buffer" makes stdout a Buffer instead of a string so PNG
+            // bytes survive without UTF-8 mangling.
+            const result = await execFileAsync(cmd, args, {
+                timeout: 5000,
+                encoding: "buffer",
+            });
+            const buf = result.stdout;
+            if (buf && buf.length > 0) {
+                return attachmentFromBuffer(buf, "image/png");
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+async function getClipboardImageWindows() {
+    const tmp = path.join(os.tmpdir(), `bubble_clip_${Date.now()}_${process.pid}.png`);
+    const tmpPs = tmp.replace(/\\/g, "\\\\");
+    const script = `Add-Type -AssemblyName System.Drawing; ` +
+        `$img = Get-Clipboard -Format Image; ` +
+        `if ($img) { $img.Save('${tmpPs}', [System.Drawing.Imaging.ImageFormat]::Png); Write-Output 'OK' } ` +
+        `else { Write-Output 'NONE' }`;
+    try {
+        const result = await execFileAsync("powershell", ["-NoProfile", "-Command", script], { timeout: 5000 });
+        if (!String(result.stdout).includes("OK"))
+            return null;
+        const buf = await fs.readFile(tmp);
+        return attachmentFromBuffer(buf, "image/png");
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await fs.unlink(tmp).catch(() => undefined);
+    }
+}
+async function which(cmd) {
+    try {
+        await execFileAsync(process.platform === "win32" ? "where" : "which", [cmd], {
+            timeout: 1500,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * If the image is close to the API size cap, try to downscale it in place.
+ * Uses the OS-native tools that are typically available:
+ *   - macOS: `sips` (always present)
+ *   - linux: ImageMagick `convert` (if installed)
+ * Returns the original attachment if resize isn't needed or can't run.
+ */
+export async function maybeResizeImage(att) {
+    if (att.base64.length < RESIZE_TRIGGER_BYTES)
+        return att;
+    const tmpDir = os.tmpdir();
+    const stamp = `${Date.now()}_${process.pid}`;
+    const inExt = path.extname(att.filename ?? att.sourcePath ?? `.png`).toLowerCase() || ".png";
+    const tmpIn = path.join(tmpDir, `bubble_img_in_${stamp}${inExt}`);
+    const tmpOut = path.join(tmpDir, `bubble_img_out_${stamp}.jpg`);
+    try {
+        await fs.writeFile(tmpIn, Buffer.from(att.base64, "base64"));
+        let ok = false;
+        if (process.platform === "darwin") {
+            try {
+                await execFileAsync("sips", ["-Z", String(RESIZE_MAX_DIM), "-s", "format", "jpeg", "-s", "formatOptions", "80", tmpIn, "--out", tmpOut], { timeout: 10000 });
+                ok = true;
+            }
+            catch {
+                ok = false;
+            }
+        }
+        else if (await which("convert")) {
+            try {
+                await execFileAsync("convert", [tmpIn, "-resize", `${RESIZE_MAX_DIM}x${RESIZE_MAX_DIM}>`, "-quality", "80", tmpOut], { timeout: 10000 });
+                ok = true;
+            }
+            catch {
+                ok = false;
+            }
+        }
+        if (!ok)
+            return att;
+        const resized = await fs.readFile(tmpOut);
+        if (resized.length >= att.bytes)
+            return att;
+        return attachmentFromBuffer(resized, "image/jpeg", {
+            filename: att.filename,
+            sourcePath: att.sourcePath,
+        });
+    }
+    catch {
+        return att;
+    }
+    finally {
+        await fs.unlink(tmpIn).catch(() => undefined);
+        await fs.unlink(tmpOut).catch(() => undefined);
+    }
+}
+export function validateImageSize(att) {
+    if (att.base64.length > MAX_BASE64_BYTES) {
+        const kb = Math.round(att.base64.length / 1024);
+        const max = Math.round(MAX_BASE64_BYTES / 1024);
+        const hint = process.platform === "darwin"
+            ? " (install/confirm `sips` on PATH to auto-resize)"
+            : process.platform === "linux"
+                ? " (install ImageMagick `convert` to auto-resize)"
+                : "";
+        return {
+            ok: false,
+            reason: `image base64 is ${kb}KB, exceeds ${max}KB API cap${hint}`,
+        };
+    }
+    return { ok: true };
+}
+/** End-to-end: given a file path, read -> resize-if-needed -> validate. */
+export async function ingestImagePath(p) {
+    const raw = await readImageFromPath(p);
+    if (!raw)
+        return { error: `cannot read image at ${p}` };
+    const sized = await maybeResizeImage(raw);
+    const validation = validateImageSize(sized);
+    if (!validation.ok)
+        return { error: validation.reason };
+    return { attachment: sized };
+}
+export async function ingestClipboardImage() {
+    const raw = await getImageFromClipboard();
+    if (!raw)
+        return { error: "clipboard has no image" };
+    const sized = await maybeResizeImage(raw);
+    const validation = validateImageSize(sized);
+    if (!validation.ok)
+        return { error: validation.reason };
+    return { attachment: sized };
+}
+export async function resolveImageInput(input, options = {}) {
+    const tokens = extractImagePathTokens(input);
+    if (tokens.length === 0) {
+        return {
+            actualInput: input,
+            displayInput: input,
+            errors: [],
+            attachments: [],
+            imagePathCount: 0,
+        };
+    }
+    const attachments = [];
+    const errors = [];
+    const attachmentsByToken = new Map();
+    let nextLabelIndex = options.labelStart ?? 1;
+    for (const token of tokens) {
+        const result = await ingestImagePath(token.rawPath);
+        if (result.attachment) {
+            attachments.push(result.attachment);
+            attachmentsByToken.set(token, {
+                attachment: result.attachment,
+                label: imageAttachmentLabel(result.attachment, nextLabelIndex++),
+            });
+        }
+        else {
+            errors.push(`${token.rawPath}: ${result.error ?? "could not attach image"}`);
+        }
+    }
+    if (attachments.length === 0) {
+        return {
+            actualInput: input,
+            displayInput: input,
+            errors,
+            attachments: [],
+            imagePathCount: tokens.length,
+        };
+    }
+    const parts = [];
+    let displayInput = "";
+    let cursor = 0;
+    for (const token of tokens) {
+        const entry = attachmentsByToken.get(token);
+        if (!entry)
+            continue;
+        const before = input.slice(cursor, token.start);
+        displayInput += before;
+        const text = before.trim();
+        if (text)
+            parts.push({ type: "text", text });
+        parts.push({ type: "image_url", image_url: { url: entry.attachment.dataUrl } });
+        displayInput += `[${entry.label}]`;
+        cursor = token.end;
+    }
+    const rest = input.slice(cursor);
+    displayInput += rest;
+    const restText = rest.trim();
+    if (restText)
+        parts.push({ type: "text", text: restText });
+    if (!parts.some((part) => part.type === "text")) {
+        parts.unshift({ type: "text", text: defaultImagePrompt(attachments.length) });
+    }
+    return {
+        actualInput: parts,
+        displayInput: displayInput.trim(),
+        errors,
+        attachments,
+        imagePathCount: tokens.length,
+    };
+}
+export async function resolveComposerImagePaths(input, options = {}) {
+    const tokens = extractImagePathTokens(input);
+    let nextLabelIndex = options.labelStart ?? 1;
+    if (tokens.length === 0) {
+        return {
+            text: input,
+            attachments: [],
+            errors: [],
+            imagePathCount: 0,
+            nextLabelIndex,
+        };
+    }
+    const errors = [];
+    const attachments = [];
+    const replacements = new Map();
+    for (const token of tokens) {
+        const result = await ingestImagePath(token.rawPath);
+        if (!result.attachment) {
+            errors.push(`${token.rawPath}: ${result.error ?? "could not attach image"}`);
+            continue;
+        }
+        const label = imageAttachmentLabel(result.attachment, nextLabelIndex++);
+        attachments.push({ ...result.attachment, label });
+        replacements.set(token, `[${label}]`);
+    }
+    let text = "";
+    let cursor = 0;
+    for (const token of tokens) {
+        text += input.slice(cursor, token.start);
+        text += replacements.get(token) ?? input.slice(token.start, token.end);
+        cursor = token.end;
+    }
+    text += input.slice(cursor);
+    return {
+        text,
+        attachments,
+        errors,
+        imagePathCount: tokens.length,
+        nextLabelIndex,
+    };
+}