@cerebriline/core 4.100.248 → 4.100.250

package/dist/extensions/tools/transform-image.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Resize, crop and convert an image that is already a file.
+ *
+ * Asked for by the first person to generate images with this in earnest: "the
+ * harness needs the ability to dynamically change the image size", and to crop.
+ * An image model draws at the sizes it knows, a README wants 1200 pixels across
+ * and an installer wants an `.ico`, and until now the model's only way from one
+ * to the other was a shell command for a program that might not be installed.
+ *
+ * The work is done by the browser `render_image` already uses: it decodes
+ * every format a page can show and encodes the three that matter. So there is
+ * no image library here, and nothing new to ship.
+ */
+import { type AgentTool } from "@cerebriline/shared";
+import { type RenderDriver, type RenderRegion, type RenderResult } from "./render-image";
+export declare const TRANSFORM_IMAGE_TOOL_NAME = "transform_image";
+export declare const TRANSFORM_IMAGE_TOOL_DESCRIPTION = "Resize, crop or convert an image file in the workspace and save the result as a new file. Use it to change an image's dimensions, cut a region out of it, change its format, or make an icon file from it. The source is never modified.\n\n- `image` \u2014 workspace path of the source: PNG, JPEG, WebP, GIF, BMP, AVIF, ICO or SVG.\n- `path` \u2014 where to save, relative to the workspace. The extension chooses the format: `.png`, `.jpg`, `.webp`, `.ico` or `.icns`. Optional; defaults to a file beside the source with the new size in its name.\n- `width`, `height` \u2014 the new size in pixels. Give one and the other follows the proportions.\n- `fit` \u2014 with both given: `inside` (default; the whole image, within the box, proportions kept), `cover` (fills the box, the overflow cut off), `pad` (the whole image, padded to exactly the box) or `stretch`.\n- `crop` \u2014 `\"x,y,width,height\"` in pixels of the source, taken before resizing.\n- `background` \u2014 a CSS colour for padding and for what was transparent. Optional; transparency is kept where the format has it, and JPEG gets white.\n- `quality` \u2014 1 to 100 for `.jpg` and `.webp`, default 90.\n- `sizes` \u2014 for `.ico` and `.icns`, the sizes to hold, e.g. `\"16,32,48,256\"`. Optional; the usual set when left out.";
+export declare const TRANSFORM_IMAGE_TOOL_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly image: {
+            readonly type: "string";
+            readonly description: "Workspace path of the source image.";
+        };
+        readonly path: {
+            readonly type: "string";
+            readonly description: "Where to save (.png, .jpg, .webp, .ico or .icns), relative to the workspace. Optional.";
+        };
+        readonly width: {
+            readonly type: "number";
+            readonly description: "New width in pixels. Optional.";
+        };
+        readonly height: {
+            readonly type: "number";
+            readonly description: "New height in pixels. Optional.";
+        };
+        readonly fit: {
+            readonly type: "string";
+            readonly enum: readonly ["inside", "cover", "pad", "stretch"];
+            readonly description: "How the image meets a box of both sizes. Optional.";
+        };
+        readonly crop: {
+            readonly type: "string";
+            readonly description: "\"x,y,width,height\" in source pixels. Optional.";
+        };
+        readonly background: {
+            readonly type: "string";
+            readonly description: "A CSS colour. Optional.";
+        };
+        readonly quality: {
+            readonly type: "number";
+            readonly description: "1 to 100, for .jpg and .webp. Optional.";
+        };
+        readonly sizes: {
+            readonly type: "string";
+            readonly description: "For .ico and .icns: sizes to hold, e.g. \"16,32,48,256\".";
+        };
+    };
+    readonly required: readonly ["image"];
+};
+export type ImageFit = "inside" | "cover" | "pad" | "stretch";
+export interface TransformPlan {
+    /** The part of the source that is drawn. */
+    sx: number;
+    sy: number;
+    sw: number;
+    sh: number;
+    /** The size of the result. */
+    width: number;
+    height: number;
+    /** Where the source lands in it. */
+    dx: number;
+    dy: number;
+    dw: number;
+    dh: number;
+}
+/**
+ * Where a source of this size goes in a result of that one.
+ *
+ * Written to stand alone, with nothing declared outside it and no function
+ * inside it: the page that draws the image runs this same text.
+ */
+export declare function planTransform(sourceWidth: number, sourceHeight: number, crop: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null, width: number | null, height: number | null, fit: string): TransformPlan | null;
+export interface TransformSpec {
+    crop?: RenderRegion;
+    width?: number;
+    height?: number;
+    fit: ImageFit;
+    /** Painted under the image, over the whole result. */
+    background?: string;
+}
+/** The page that draws one image at its new size. */
+export declare function buildTransformDocument(sourceUrl: string, spec: TransformSpec): string;
+/** One image, drawn at a new size by the host's browser. */
+export declare function transformWithDriver(driver: RenderDriver, input: {
+    sourcePath: string;
+    baseDir: string;
+    spec: TransformSpec;
+    format?: "png" | "jpeg" | "webp";
+    quality?: number;
+    signal?: AbortSignal;
+}): Promise<RenderResult>;
+/** An `.ico`: a directory of images, each one a PNG. */
+export declare function encodeIco(images: {
+    size: number;
+    png: Buffer;
+}[]): Buffer;
+/** An `.icns`: the same idea, with a name per size. */
+export declare function encodeIcns(images: {
+    size: number;
+    png: Buffer;
+}[]): Buffer;
+export declare const ICO_SIZES: number[];
+export declare const ICNS_SIZES: number[];
+/** The sizes an icon file is asked to hold, or why not those. */
+export declare function parseIconSizes(value: unknown, container: "ico" | "icns"): number[] | {
+    error: string;
+};
+/** Every size of an icon, from one source, as square PNGs. */
+export declare function renderIconSizes(driver: RenderDriver, input: {
+    sourcePath: string;
+    baseDir: string;
+    sizes: number[];
+    crop?: RenderRegion;
+    background?: string;
+    signal?: AbortSignal;
+}): Promise<{
+    size: number;
+    png: Buffer;
+}[]>;
+export declare class UnreadableImageError extends Error {
+    constructor();
+}
+export interface TransformImageToolOptions {
+    cwd: string;
+    createDriver: () => RenderDriver | Promise<RenderDriver>;
+    /** Whether the source is there: the browser says nothing useful about a missing file. */
+    fileExists: (absolutePath: string) => Promise<boolean>;
+    writeFile: (absolutePath: string, data: Buffer) => Promise<void>;
+    onError?: (message: string, error: unknown) => void;
+}
+/** Create the `transform_image` tool. */
+export declare function createTransformImageTool(options: TransformImageToolOptions): AgentTool;