pixeli 0.1.9 → 1.0.4

package/dist/core/pipeline/mergePipeline.js

@@ -0,0 +1,122 @@
+import sharp from 'sharp';
+import { MergeError } from '../mergeError.js';
+import { MESSAGES } from '../modules/messages.js';
+import chalk from 'chalk';
+/**
+ * Pipeline orchestrator for running a sequence of merge steps that
+ * progressively build or modify a final merged image.
+ *
+ * Generic type parameters:
+ * - TOptions: the shape of the validated options object passed to each step.
+ * - TState: the shape of the pipeline's runtime state held in MergeContext.
+ *
+ * The pipeline:
+ * - Validates incoming options via a Zod schema (see createPipeline).
+ * - Maintains an ordered list of MergeStep functions to execute.
+ * - Provides optional progress reporting via an OnProgress callback.
+ *
+ * Usage:
+ * - Create an instance via createPipeline to ensure options are validated and
+ *   progressInfo is initialized on the supplied MergeContext.
+ * - Register steps with use(...).
+ * - Execute with run() — in normal usage this returns a Buffer containing the
+ *   final image. When run in "test" mode (testOptions supplied) the pipeline
+ *   may perform a dry-run and return void.
+ *
+ * Errors:
+ * - Validation-related errors thrown from createPipeline are surfaced as
+ *   MergeError instances with type 'validation' or 'internal'.
+ * - During execution, any thrown non-MergeError is converted into a runtime
+ *   Error indicating the offending step name.
+ *
+ * @template TOptions - Validated options shape used by registered steps.
+ * @template TState - Context/state shape managed by the pipeline.
+ */
+export class MergePipeline {
+    options;
+    context;
+    onProgress;
+    steps = [];
+    optionsCounter = 0;
+    stateCounter = 0;
+    constructor(options, context, onProgress) {
+        this.options = options;
+        this.context = context;
+        this.onProgress = onProgress;
+    }
+    static async createPipeline(schema, options, context, onProgress) {
+        const { success, data, error } = await schema.safeParseAsync(options);
+        if (success) {
+            // Initialize progressInfo
+            const progressInfo = {
+                completed: 0,
+                total: context.inputs.length,
+                phase: 'Initializing',
+            };
+            // Initialize mergeContext
+            const mergeContext = {
+                ...context,
+                progressInfo,
+            };
+            // Return the pipeline
+            return new MergePipeline(data, mergeContext, onProgress);
+        }
+        else {
+            const path = error.issues[0]?.path;
+            const err = error.issues[0]?.message;
+            if (!path || !err) {
+                throw new MergeError(MESSAGES.ERROR.INTERNAL.message, { type: 'internal', cause: error });
+            }
+            const errorText = path.length > 0 ? `Invalid value at ${path.join('/')}: ${err}` : `Error: ${err}`;
+            throw new MergeError(errorText, { type: 'validation' });
+        }
+    }
+    use(step) {
+        this.steps.push(step);
+        return this;
+    }
+    async run(testOptions) {
+        let finalImage;
+        if (testOptions)
+            this.logForDebugging(testOptions);
+        for (const step of this.steps) {
+            // Use a copy of this.options to ensure that merge steps cannot mutate the original
+            const result = await step(this.context, { ...this.options }, this.onProgress);
+            if (testOptions)
+                this.logForDebugging(testOptions);
+            // If the result is a sharp instance, update finalImage
+            if (result instanceof Buffer) {
+                finalImage = result;
+            }
+        }
+        // If finalImage has a value, return it
+        if (finalImage) {
+            return finalImage;
+        }
+        // During a dry run, void returns are allowed (for debugging)
+        if (testOptions) {
+            return;
+        }
+        // Normal runs must have a final sharp image produced.
+        throw new Error('No merge step produced a final Sharp image.');
+    }
+    logForDebugging(testOptions) {
+        if (testOptions.logOptions) {
+            // Log
+            console.log(chalk.bgBlueBright(` OPTIONS ${this.optionsCounter++}: `));
+            console.log(this.options);
+        }
+        // Whitespace
+        if (testOptions.logOptions && testOptions.logContext)
+            console.log();
+        if (testOptions.logContext) {
+            // Replace images and inputs with their lengths to make context readable
+            const { images, inputs, ...trimmedContext } = this.context;
+            const modifiedContext = { totalImages: images.length, totalInputs: inputs.length, ...trimmedContext };
+            // Log
+            console.log(chalk.bgGreen(` CONTEXT ${this.stateCounter++}: `));
+            console.log(modifiedContext);
+        }
+        console.log();
+    }
+}

package/dist/core/schemas/collage.d.ts

@@ -0,0 +1,26 @@
+import z from 'zod';
+export declare const collageSchema: z.ZodObject<{
+    shuffle: z.ZodDefault<z.ZodBoolean>;
+    cornerRadius: z.ZodDefault<z.ZodNumber>;
+    gap: z.ZodDefault<z.ZodNumber>;
+    canvasColor: z.ZodPrefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<import("../utils/colors/types.js").RGBA, string>>, z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+        alpha: z.ZodNumber;
+    }, z.z.core.$strip>]>>;
+    borderWidth: z.ZodDefault<z.ZodNumber>;
+    borderColor: z.ZodPrefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<import("../utils/colors/types.js").RGBA, string>>, z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+        alpha: z.ZodNumber;
+    }, z.z.core.$strip>]>>;
+    format: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<"webp" | "gif" | "jpeg" | "jpg" | "png" | "tiff" | "avif", string>>>;
+    aspectRatio: z.ZodPrefault<z.ZodPipe<z.z.ZodCoercedString<unknown>, z.ZodTransform<number, string>>>;
+    imageWidth: z.ZodOptional<z.ZodNumber>;
+    columns: z.ZodDefault<z.ZodNumber>;
+    overlapPercentage: z.ZodDefault<z.ZodNumber>;
+    rotationRange: z.ZodDefault<z.ZodNumber>;
+    imageWidthVariance: z.ZodDefault<z.ZodNumber>;
+}, z.z.core.$strict>;

package/dist/core/schemas/collage.js

@@ -0,0 +1,17 @@
+import z from 'zod';
+import { VALIDATORS } from '../../validators/index.js';
+export const collageSchema = z.strictObject({
+    shuffle: VALIDATORS.shuffle.default(false),
+    cornerRadius: VALIDATORS.cornerRadius.default(0),
+    gap: VALIDATORS.gap.default(50),
+    canvasColor: VALIDATORS.canvasColor.prefault('#fff'),
+    borderWidth: VALIDATORS.imageWidthVariance.default(20),
+    borderColor: VALIDATORS.borderColor.prefault('#000'),
+    format: VALIDATORS.format.default('png'),
+    aspectRatio: VALIDATORS.aspectRatio.prefault('1:1'),
+    imageWidth: VALIDATORS.imageWidth.optional(),
+    columns: VALIDATORS.columns.default(4),
+    overlapPercentage: VALIDATORS.overlapPercentage.default(25),
+    rotationRange: VALIDATORS.rotationRange.default(7),
+    imageWidthVariance: VALIDATORS.imageWidthVariance.default(10),
+});

package/dist/core/schemas/grid.d.ts

@@ -0,0 +1,32 @@
+import z from 'zod';
+export declare const gridSchema: z.ZodObject<{
+    shuffle: z.ZodDefault<z.ZodBoolean>;
+    cornerRadius: z.ZodDefault<z.ZodNumber>;
+    gap: z.ZodDefault<z.ZodNumber>;
+    canvasColor: z.ZodPrefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<import("../utils/colors/types.js").RGBA, string>>, z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+        alpha: z.ZodNumber;
+    }, z.z.core.$strip>]>>;
+    borderWidth: z.ZodDefault<z.ZodNumber>;
+    borderColor: z.ZodPrefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<import("../utils/colors/types.js").RGBA, string>>, z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+        alpha: z.ZodNumber;
+    }, z.z.core.$strip>]>>;
+    format: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<"webp" | "gif" | "jpeg" | "jpg" | "png" | "tiff" | "avif", string>>>;
+    aspectRatio: z.ZodPrefault<z.ZodPipe<z.z.ZodCoercedString<unknown>, z.ZodTransform<number, string>>>;
+    imageWidth: z.ZodOptional<z.ZodNumber>;
+    columns: z.ZodDefault<z.ZodNumber>;
+    caption: z.ZodDefault<z.ZodBoolean>;
+    captions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    captionColor: z.ZodPrefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<import("../utils/colors/types.js").RGBA, string>>, z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+        alpha: z.ZodNumber;
+    }, z.z.core.$strip>]>>;
+    maxCaptionSize: z.ZodDefault<z.ZodNumber>;
+}, z.z.core.$strict>;

package/dist/core/schemas/grid.js

@@ -0,0 +1,29 @@
+import z from 'zod';
+import { VALIDATORS } from '../../validators/index.js';
+export const gridSchema = z
+    .strictObject({
+    shuffle: VALIDATORS.shuffle.default(false),
+    cornerRadius: VALIDATORS.cornerRadius.default(0),
+    gap: VALIDATORS.gap.default(50),
+    canvasColor: VALIDATORS.canvasColor.prefault('#fff'),
+    borderWidth: VALIDATORS.borderWidth.default(0),
+    borderColor: VALIDATORS.borderColor.prefault('#000'),
+    format: VALIDATORS.format.default('png'),
+    aspectRatio: VALIDATORS.aspectRatio.prefault('1:1'),
+    imageWidth: VALIDATORS.imageWidth.optional(),
+    columns: VALIDATORS.columns.default(4),
+    caption: VALIDATORS.caption.default(false),
+    captions: VALIDATORS.captions.nonempty().optional(),
+    captionColor: VALIDATORS.captionColor.prefault('#000'),
+    maxCaptionSize: VALIDATORS.maxCaptionSize.default(100),
+})
+    .superRefine((opts, ctx) => {
+    // Ensure captions are given if caption is set to true
+    if (opts.caption && (!opts.captions || opts.captions.length === 0)) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'Caption texts must be provided.',
+            path: ['captions'],
+        });
+    }
+});

package/dist/core/schemas/masonry.d.ts

@@ -0,0 +1,56 @@
+import z from 'zod';
+export declare const masonrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    flow: z.ZodLiteral<"horizontal">;
+    rowHeight: z.ZodOptional<z.ZodNumber>;
+    canvasWidth: z.ZodNumber;
+    hAlign: z.ZodDefault<z.ZodEnum<{
+        left: "left";
+        center: "center";
+        right: "right";
+        justified: "justified";
+    }>>;
+    shuffle: z.ZodDefault<z.ZodBoolean>;
+    cornerRadius: z.ZodDefault<z.ZodNumber>;
+    gap: z.ZodDefault<z.ZodNumber>;
+    canvasColor: z.ZodPrefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<import("../utils/colors/types.js").RGBA, string>>, z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+        alpha: z.ZodNumber;
+    }, z.z.core.$strip>]>>;
+    format: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<"webp" | "gif" | "jpeg" | "jpg" | "png" | "tiff" | "avif", string>>>;
+    borderWidth: z.ZodDefault<z.ZodNumber>;
+    borderColor: z.ZodPrefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<import("../utils/colors/types.js").RGBA, string>>, z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+        alpha: z.ZodNumber;
+    }, z.z.core.$strip>]>>;
+}, z.z.core.$strip>, z.ZodObject<{
+    flow: z.ZodLiteral<"vertical">;
+    columnWidth: z.ZodOptional<z.ZodNumber>;
+    canvasHeight: z.ZodNumber;
+    vAlign: z.ZodDefault<z.ZodEnum<{
+        justified: "justified";
+        top: "top";
+        middle: "middle";
+        bottom: "bottom";
+    }>>;
+    shuffle: z.ZodDefault<z.ZodBoolean>;
+    cornerRadius: z.ZodDefault<z.ZodNumber>;
+    gap: z.ZodDefault<z.ZodNumber>;
+    canvasColor: z.ZodPrefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<import("../utils/colors/types.js").RGBA, string>>, z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+        alpha: z.ZodNumber;
+    }, z.z.core.$strip>]>>;
+    format: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<"webp" | "gif" | "jpeg" | "jpg" | "png" | "tiff" | "avif", string>>>;
+    borderWidth: z.ZodDefault<z.ZodNumber>;
+    borderColor: z.ZodPrefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<import("../utils/colors/types.js").RGBA, string>>, z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+        alpha: z.ZodNumber;
+    }, z.z.core.$strip>]>>;
+}, z.z.core.$strip>], "flow">;

package/dist/core/schemas/masonry.js

@@ -0,0 +1,43 @@
+import z from 'zod';
+import { VALIDATORS } from '../../validators/index.js';
+const baseMasonrySchema = z.object({
+    shuffle: VALIDATORS.shuffle.default(false),
+    cornerRadius: VALIDATORS.cornerRadius.default(0),
+    gap: VALIDATORS.gap.default(50),
+    canvasColor: VALIDATORS.canvasColor.prefault('#fff'),
+    format: VALIDATORS.format.default('png'),
+    borderWidth: VALIDATORS.borderWidth.default(0),
+    borderColor: VALIDATORS.borderColor.prefault('#000'),
+});
+const horizontalMasonrySchema = z.object({
+    ...baseMasonrySchema.shape,
+    flow: z.literal('horizontal'),
+    rowHeight: VALIDATORS.rowHeight.optional(),
+    canvasWidth: VALIDATORS.canvasWidth,
+    hAlign: VALIDATORS.hAlign.default('justified'),
+});
+const verticalMasonrySchema = z.object({
+    ...baseMasonrySchema.shape,
+    flow: z.literal('vertical'),
+    columnWidth: VALIDATORS.rowHeight.optional(),
+    canvasHeight: VALIDATORS.canvasHeight,
+    vAlign: VALIDATORS.vAlign.default('justified'),
+});
+export const masonrySchema = z
+    .discriminatedUnion('flow', [horizontalMasonrySchema, verticalMasonrySchema])
+    .superRefine((opts, ctx) => {
+    if (opts.flow === 'horizontal' && opts.canvasWidth <= opts.gap * 2) {
+        ctx.addIssue({
+            code: 'custom',
+            message: "Canvas is too small to place images in. Increase 'canvasWidth'.",
+            path: ['canvasWidth'],
+        });
+    }
+    if (opts.flow === 'vertical' && opts.canvasHeight <= opts.gap * 2) {
+        ctx.addIssue({
+            code: 'custom',
+            message: "Canvas is too small to place images in. Increase 'canvasHeight'.",
+            path: ['canvasHeight'],
+        });
+    }
+});

package/dist/core/schemas/mergeJob.d.ts

@@ -0,0 +1,11 @@
+import z from 'zod';
+export declare const mergeJobSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        template: "template";
+        grid: "grid";
+        masonry: "masonry";
+        collage: "collage";
+    }>;
+    inputs: z.ZodArray<z.ZodString>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.z.core.$strict>;

package/dist/core/schemas/mergeJob.js

@@ -0,0 +1,6 @@
+import z from 'zod';
+export const mergeJobSchema = z.strictObject({
+    type: z.enum(['grid', 'masonry', 'collage', 'template']),
+    inputs: z.array(z.string()).min(1),
+    options: z.record(z.string(), z.any()).optional(),
+});

package/dist/core/schemas/template.d.ts

@@ -0,0 +1,34 @@
+import z from 'zod';
+export declare const templateSchema: z.ZodObject<{
+    shuffle: z.ZodDefault<z.ZodBoolean>;
+    cornerRadius: z.ZodDefault<z.ZodNumber>;
+    gap: z.ZodDefault<z.ZodNumber>;
+    canvasColor: z.ZodPrefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<import("../utils/colors/types.js").RGBA, string>>, z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+        alpha: z.ZodNumber;
+    }, z.z.core.$strip>]>>;
+    format: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<"webp" | "gif" | "jpeg" | "jpg" | "png" | "tiff" | "avif", string>>>;
+    template: z.ZodObject<{
+        canvas: z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            columns: z.ZodNumber;
+            rows: z.ZodNumber;
+        }, z.z.core.$strip>;
+        slots: z.ZodArray<z.ZodObject<{
+            col: z.ZodNumber;
+            row: z.ZodNumber;
+            colSpan: z.ZodNumber;
+            rowSpan: z.ZodNumber;
+        }, z.z.core.$strip>>;
+    }, z.z.core.$strip>;
+    borderWidth: z.ZodDefault<z.ZodNumber>;
+    borderColor: z.ZodPrefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<import("../utils/colors/types.js").RGBA, string>>, z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+        alpha: z.ZodNumber;
+    }, z.z.core.$strip>]>>;
+}, z.z.core.$strict>;

package/dist/core/schemas/template.js

@@ -0,0 +1,88 @@
+import z from 'zod';
+import { VALIDATORS } from '../../validators/index.js';
+export const templateSchema = z
+    .strictObject({
+    shuffle: VALIDATORS.shuffle.default(false),
+    cornerRadius: VALIDATORS.cornerRadius.default(0),
+    gap: VALIDATORS.gap.default(50),
+    canvasColor: VALIDATORS.canvasColor.prefault('#fff'),
+    format: VALIDATORS.format.default('png'),
+    template: VALIDATORS.template,
+    borderWidth: VALIDATORS.borderWidth.default(0),
+    borderColor: VALIDATORS.borderColor.prefault('#000'),
+})
+    .superRefine((opts, ctx) => {
+    // Ensure canvas is wide enough for at least a single 1px column
+    if (opts.template.canvas.width <= opts.gap * 2) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `Canvas width must be greater than ${opts.gap * 2}.`,
+            path: ['template', 'canvas', 'width'],
+        });
+    }
+    // Ensure canvas is long enough for at least a single 1px row
+    if (opts.template.canvas.height <= opts.gap * 2) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `Canvas height must be greater than ${opts.gap * 2}.`,
+            path: ['template', 'canvas', 'height'],
+        });
+    }
+    // Calculate column width and row height
+    const workableCanvasWidth = opts.template.canvas.width - opts.gap * (opts.template.canvas.columns + 1);
+    const workableCanvasHeight = opts.template.canvas.height - opts.gap * (opts.template.canvas.rows + 1);
+    const columnWidth = Math.floor(workableCanvasWidth / opts.template.canvas.columns);
+    const rowHeight = Math.floor(workableCanvasHeight / opts.template.canvas.rows);
+    // Ensure columns are thick enough
+    if (columnWidth <= 0) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `Columns are too thin. Increase canvas width, reduce gap, or reduce number of columns.`,
+            path: ['template', 'canvas', 'columns'],
+        });
+    }
+    // Ensure rows are thick enough
+    if (rowHeight <= 0) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `Rows are too thin. Increase canvas height or reduce number of rows.`,
+            path: ['template', 'canvas', 'rows'],
+        });
+    }
+    // For each slot...
+    for (let i = 0; i < opts.template.slots.length; i++) {
+        const slot = opts.template.slots[i];
+        // Ensure slot is placed inside given canvas columns
+        if (slot.col > opts.template.canvas.columns) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `"col" must be between 1 and ${opts.template.canvas.columns}.`,
+                path: ['template', 'slots', i, 'col'],
+            });
+        }
+        // Ensure slot is placed inside given canvas rows
+        if (slot.row > opts.template.canvas.rows) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `"row" must be between 1 and ${opts.template.canvas.rows}.`,
+                path: ['template', 'slots', i, 'row'],
+            });
+        }
+        // Ensure slot spans within given canvas columns
+        if (slot.col + slot.colSpan - 1 > opts.template.canvas.columns) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `slot spans past the right edge of the grid (col + colSpan exceeds columns).`,
+                path: ['template', 'slots', i],
+            });
+        }
+        // Ensure slot spans within given canvas rows
+        if (slot.row + slot.rowSpan - 1 > opts.template.canvas.rows) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `slot spans past the bottom edge of the grid (row + rowSpan exceeds rows).`,
+                path: ['template', 'slots', i],
+            });
+        }
+    }
+});

package/dist/core/utils/colors/hexToRgba.d.ts

@@ -0,0 +1,2 @@
+import type { RGBA } from './types.js';
+export declare const hexToRgba: (color: string) => RGBA;

package/dist/core/utils/colors/hexToRgba.js

@@ -0,0 +1,25 @@
+export const hexToRgba = (color) => {
+    // 3. Normalize hex → RGBA
+    let r, g, b, alpha;
+    const hexValue = color.slice(1);
+    // #rgb
+    if (hexValue.length === 3) {
+        r = parseInt(hexValue.charAt(0) + hexValue.charAt(0), 16);
+        g = parseInt(hexValue.charAt(1) + hexValue.charAt(1), 16);
+        b = parseInt(hexValue.charAt(2) + hexValue.charAt(2), 16);
+        alpha = 1;
+    } // #rrggbb
+    else if (hexValue.length === 6) {
+        r = parseInt(hexValue.slice(0, 2), 16);
+        g = parseInt(hexValue.slice(2, 4), 16);
+        b = parseInt(hexValue.slice(4, 6), 16);
+        alpha = 1;
+    } // #rrggbbaa
+    else {
+        r = parseInt(hexValue.slice(0, 2), 16);
+        g = parseInt(hexValue.slice(2, 4), 16);
+        b = parseInt(hexValue.slice(4, 6), 16);
+        alpha = Number((parseInt(hexValue.slice(6, 8), 16) / 255).toFixed(2));
+    }
+    return { r, g, b, alpha };
+};

package/dist/core/utils/colors/rgbaToHex.d.ts

@@ -0,0 +1,2 @@
+import type { RGBA } from './types.js';
+export declare const rgbaToHex: (rgba: RGBA) => string;

package/dist/core/utils/colors/rgbaToHex.js

@@ -0,0 +1,15 @@
+export const rgbaToHex = (rgba) => {
+    // Function to convert a number to a 2-digit hex string
+    const componentToHex = (c) => {
+        const hex = c.toString(16);
+        return hex.length === 1 ? '0' + hex : hex;
+    };
+    // Convert r, g, b (0-255)
+    const rHex = componentToHex(rgba.r);
+    const gHex = componentToHex(rgba.g);
+    const bHex = componentToHex(rgba.b);
+    // Convert alpha (0-1) to 0-255 range, then to 2-digit hex
+    const aVal = Math.round(rgba.alpha * 255);
+    const aHex = componentToHex(aVal);
+    return `#${rHex}${gHex}${bHex}${aHex}`;
+};

package/dist/core/utils/colors/types.d.ts

@@ -0,0 +1,7 @@
+export type RGBA = {
+    r: number;
+    g: number;
+    b: number;
+    alpha: number;
+};
+export type Color = string | RGBA;

package/dist/core/utils/colors/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/utils/fonts/getFontSize.d.ts

@@ -0,0 +1,9 @@
+interface GetFontSizeOptions {
+    text: string;
+    maxWidth: number;
+    maxHeight: number;
+    initialFontSize?: number;
+    minFontSize?: number;
+}
+export declare const getFontSize: ({ text, maxWidth, maxHeight, initialFontSize, minFontSize }: GetFontSizeOptions) => Promise<number>;
+export {};

package/dist/core/utils/fonts/getFontSize.js

@@ -0,0 +1,40 @@
+import sharp from 'sharp';
+import { escapeXML } from '../../helpers.js';
+export const getFontSize = async ({ text, maxWidth, maxHeight, initialFontSize = 100, minFontSize = 2 }) => {
+    const FONT_FAMILY = 'sans-serif';
+    const THRESHOLD = 200;
+    const SMALL_CHANGE = 2;
+    const LARGE_CHANGE = 5;
+    let fontSize = initialFontSize;
+    while (fontSize >= minFontSize) {
+        // No width or viewport given so that the actual size can be determined after rasterization
+        const svg = `
+    <svg xmlns="http://www.w3.org/2000/svg">
+      <text
+        x="${maxWidth / 2}"
+        y="10"
+        font-size="${fontSize}"
+        font-family="${FONT_FAMILY}"
+        fill="#000000"
+        text-anchor="middle"
+        dominant-baseline="middle">
+        ${escapeXML(text)}
+      </text>
+    </svg>
+    `;
+        // Rasterize SVG: measure actual rendered size
+        const raster = await sharp(Buffer.from(svg)).png().toBuffer();
+        const meta = await sharp(raster).metadata();
+        if (meta.width <= maxWidth && meta.height <= maxHeight) {
+            return fontSize;
+        }
+        // If the difference is greater than the threshold, use large change
+        if (meta.width - maxWidth > THRESHOLD || meta.height - maxHeight > THRESHOLD) {
+            fontSize -= LARGE_CHANGE;
+        }
+        else {
+            fontSize -= SMALL_CHANGE;
+        }
+    }
+    return minFontSize;
+};

package/dist/core/utils/images/addImageBorder.d.ts

@@ -0,0 +1,13 @@
+import sharp from 'sharp';
+import type { RGBA } from '../colors/types.js';
+interface Options {
+    borderWidth: number;
+    borderHeight: number;
+    borderColor: RGBA;
+    cornerRadius: number;
+    imageWidth: number;
+    imageHeight: number;
+    finalizePipeline?: boolean;
+}
+export declare const addImageBorder: (image: sharp.Sharp, { borderWidth, borderHeight, borderColor, imageWidth, imageHeight, cornerRadius, finalizePipeline }: Options) => Promise<sharp.Sharp>;
+export {};

package/dist/core/utils/images/addImageBorder.js

@@ -0,0 +1,33 @@
+import sharp from 'sharp';
+export const addImageBorder = async (image, { borderWidth, borderHeight, borderColor, imageWidth, imageHeight, cornerRadius = 0, finalizePipeline = false }) => {
+    // Only add borders to an image if needed
+    if (borderWidth <= 0)
+        return image;
+    // Create background to act as border
+    const background = sharp({
+        create: {
+            width: imageWidth,
+            height: imageHeight,
+            channels: 4,
+            background: borderColor,
+        },
+    }).toFormat('png');
+    // Crop image
+    const croppedImage = image.resize({
+        width: imageWidth - borderWidth * 2,
+        height: imageHeight - borderHeight * 2,
+    });
+    // Put cropped image on the background
+    background.composite([
+        {
+            input: await croppedImage.toBuffer(),
+            top: borderWidth,
+            left: borderHeight,
+        },
+    ]);
+    // Finalize image if needed
+    if (finalizePipeline) {
+        return sharp(await background.toBuffer());
+    }
+    return background;
+};

package/dist/core/utils/images/getImageHeights.d.ts

@@ -0,0 +1,2 @@
+import sharp from 'sharp';
+export declare const getImageHeights: (images: sharp.Sharp[]) => Promise<number[]>;

package/dist/core/utils/images/getImageHeights.js

@@ -0,0 +1,9 @@
+import sharp from 'sharp';
+export const getImageHeights = async (images) => {
+    const heights = [];
+    for (const image of images) {
+        const meta = await image.metadata();
+        heights.push(meta.height);
+    }
+    return heights;
+};

package/dist/core/utils/images/getImageWidths.d.ts

@@ -0,0 +1,2 @@
+import sharp from 'sharp';
+export declare const getImageWidths: (images: sharp.Sharp[]) => Promise<number[]>;