@image-marker/web 0.1.0

package/lib/module/core/job.d.ts

@@ -0,0 +1,57 @@
+import type { MarkerOperation, MarkerResult } from './result.js';
+import { type MarkerResultDescriptor } from './result.js';
+export type ImageMarkerErrorCode = 'ABORTED' | 'TIMEOUT' | 'INVALID_OPTIONS' | 'LINKING_ERROR' | 'NATIVE_ERROR' | 'RENDER_FAILED' | 'ENCODE_FAILED' | 'DECODE_FAILED' | 'UNKNOWN';
+export type MarkerJobPhase = 'queued' | 'validating' | 'rendering' | 'detecting' | 'encoding' | 'completed';
+export interface MarkerJobProgress {
+    jobId: string;
+    operation: MarkerOperation;
+    phase: MarkerJobPhase;
+    completed: number;
+    total: 1;
+    progress: number;
+}
+export interface MarkerJobOptions {
+    signal?: AbortSignal;
+    /** Reject and cancel the native operation after this many milliseconds. */
+    timeoutMs?: number;
+    /** Observer failures never interrupt image processing. */
+    onProgress?: (progress: MarkerJobProgress) => void;
+}
+export declare class ImageMarkerError extends Error {
+    readonly code: ImageMarkerErrorCode;
+    readonly jobId?: string;
+    readonly operation?: MarkerOperation;
+    readonly cause?: unknown;
+    constructor(code: ImageMarkerErrorCode, message: string, context?: {
+        jobId?: string;
+        operation?: MarkerOperation;
+        cause?: unknown;
+    });
+}
+export declare function createMarkerJobId(operation: MarkerOperation): string;
+export declare function normalizeMarkerError(error: unknown, context: {
+    jobId: string;
+    operation: MarkerOperation;
+}): ImageMarkerError;
+interface RunControlledMarkerJobOptions<Result> {
+    operation: MarkerOperation;
+    control?: MarkerJobOptions;
+    task: (jobId: string) => Promise<Result>;
+    cancel?: (jobId: string) => Promise<unknown> | unknown;
+    workPhase?: Extract<MarkerJobPhase, 'rendering' | 'detecting'>;
+    finishingPhase?: Extract<MarkerJobPhase, 'encoding'>;
+}
+export interface ControlledMarkerJobResult<Result> {
+    jobId: string;
+    durationMs: number;
+    value: Result;
+}
+export declare function runControlledMarkerJob<Result>({ operation, control, task, cancel, workPhase, finishingPhase, }: RunControlledMarkerJobOptions<Result>): Promise<ControlledMarkerJobResult<Result>>;
+interface RunMarkerJobOptions {
+    descriptor: MarkerResultDescriptor;
+    control?: MarkerJobOptions;
+    task: (jobId: string) => Promise<string>;
+    cancel?: (jobId: string) => Promise<unknown> | unknown;
+}
+export declare function runMarkerJob({ descriptor, control, task, cancel, }: RunMarkerJobOptions): Promise<MarkerResult>;
+export {};

package/lib/module/core/job.js

@@ -0,0 +1,143 @@
+import { createMarkerResult } from './result.js';
+export class ImageMarkerError extends Error {
+    constructor(code, message, context = {}) {
+        super(message);
+        this.name = 'ImageMarkerError';
+        this.code = code;
+        this.jobId = context.jobId;
+        this.operation = context.operation;
+        this.cause = context.cause;
+    }
+}
+let jobSequence = 0;
+export function createMarkerJobId(operation) {
+    jobSequence = (jobSequence + 1) % Number.MAX_SAFE_INTEGER;
+    return `${operation}-${Date.now().toString(36)}-${jobSequence.toString(36)}`;
+}
+function validateControlOptions(options) {
+    if (options.timeoutMs !== undefined &&
+        (!Number.isFinite(options.timeoutMs) ||
+            !Number.isInteger(options.timeoutMs) ||
+            options.timeoutMs <= 0)) {
+        throw new ImageMarkerError('INVALID_OPTIONS', 'timeoutMs must be a positive finite integer.');
+    }
+}
+function report(options, jobId, operation, phase, progress) {
+    try {
+        options.onProgress?.({
+            jobId,
+            operation,
+            phase,
+            completed: phase === 'completed' ? 1 : 0,
+            total: 1,
+            progress,
+        });
+    }
+    catch {
+        // Progress observers cannot change operation results.
+    }
+}
+function inferErrorCode(error) {
+    const message = error instanceof Error
+        ? error.message.toLowerCase()
+        : String(error).toLowerCase();
+    if (message.includes('link') || message.includes('expo go')) {
+        return 'LINKING_ERROR';
+    }
+    if (message.includes('decode') || message.includes('load image')) {
+        return 'DECODE_FAILED';
+    }
+    if (message.includes('encode') || message.includes('save')) {
+        return 'ENCODE_FAILED';
+    }
+    if (message.includes('required') ||
+        message.includes('invalid') ||
+        message.includes('must be') ||
+        message.includes('please set')) {
+        return 'INVALID_OPTIONS';
+    }
+    if (message.includes('render') || message.includes('watermark')) {
+        return 'RENDER_FAILED';
+    }
+    return 'NATIVE_ERROR';
+}
+export function normalizeMarkerError(error, context) {
+    if (error instanceof ImageMarkerError) {
+        return error;
+    }
+    const message = error instanceof Error && error.message
+        ? error.message
+        : 'Image marker operation failed.';
+    return new ImageMarkerError(inferErrorCode(error), message, {
+        ...context,
+        cause: error,
+    });
+}
+export async function runControlledMarkerJob({ operation, control = {}, task, cancel, workPhase = 'rendering', finishingPhase, }) {
+    validateControlOptions(control);
+    const jobId = createMarkerJobId(operation);
+    const startedAt = Date.now();
+    let timeout;
+    let rejectControl;
+    let controlSettled = false;
+    const cancelWith = (code, message) => {
+        if (controlSettled)
+            return;
+        controlSettled = true;
+        Promise.resolve(cancel?.(jobId)).catch(() => {
+            // The original abort/timeout remains authoritative.
+        });
+        rejectControl?.(new ImageMarkerError(code, message, {
+            jobId,
+            operation,
+        }));
+    };
+    const onAbort = () => cancelWith('ABORTED', 'Image marker operation was aborted.');
+    if (control.signal?.aborted) {
+        throw new ImageMarkerError('ABORTED', 'Image marker operation was aborted before it started.', { jobId, operation });
+    }
+    const controlPromise = new Promise((_resolve, reject) => {
+        rejectControl = reject;
+    });
+    control.signal?.addEventListener('abort', onAbort, { once: true });
+    if (control.timeoutMs !== undefined) {
+        timeout = setTimeout(() => cancelWith('TIMEOUT', `Image marker operation timed out after ${control.timeoutMs}ms.`), control.timeoutMs);
+    }
+    report(control, jobId, operation, 'queued', 0);
+    report(control, jobId, operation, 'validating', 0.1);
+    try {
+        report(control, jobId, operation, workPhase, 0.25);
+        const value = await Promise.race([task(jobId), controlPromise]);
+        controlSettled = true;
+        if (finishingPhase) {
+            report(control, jobId, operation, finishingPhase, 0.85);
+        }
+        const result = {
+            jobId,
+            durationMs: Math.max(0, Date.now() - startedAt),
+            value,
+        };
+        report(control, jobId, operation, 'completed', 1);
+        return result;
+    }
+    catch (error) {
+        throw normalizeMarkerError(error, { jobId, operation });
+    }
+    finally {
+        controlSettled = true;
+        if (timeout !== undefined)
+            clearTimeout(timeout);
+        control.signal?.removeEventListener('abort', onAbort);
+    }
+}
+export async function runMarkerJob({ descriptor, control = {}, task, cancel, }) {
+    const result = await runControlledMarkerJob({
+        operation: descriptor.operation,
+        control,
+        task,
+        cancel,
+        workPhase: 'rendering',
+        finishingPhase: 'encoding',
+    });
+    return createMarkerResult(result.jobId, result.value, result.durationMs, descriptor);
+}

package/lib/module/core/layout.d.ts

@@ -0,0 +1,19 @@
+import type { WatermarkLayout } from './index.js';
+export declare const MAX_TILE_COPIES = 4096;
+export interface LayoutSize {
+    width: number;
+    height: number;
+}
+export interface LayoutPoint {
+    x: number;
+    y: number;
+}
+export type TileWatermarkLayout = Extract<WatermarkLayout, {
+    type: 'tile';
+}>;
+export declare function resolveLayoutValue(value: number | string | undefined, relativeTo: number, label: string): number;
+/**
+ * Resolve the top-left visible bounds for every tile. Rows and columns begin
+ * one step outside the canvas so partial edge tiles preserve the grid phase.
+ */
+export declare function resolveTilePlacements(layout: TileWatermarkLayout, canvas: LayoutSize, item: LayoutSize): LayoutPoint[];

package/lib/module/core/layout.js

@@ -0,0 +1,70 @@
+export const MAX_TILE_COPIES = 4096;
+function assertSize(size, label) {
+    if (!Number.isFinite(size.width) ||
+        !Number.isFinite(size.height) ||
+        size.width <= 0 ||
+        size.height <= 0) {
+        throw new Error(`${label} dimensions must be finite numbers greater than 0.`);
+    }
+}
+export function resolveLayoutValue(value, relativeTo, label) {
+    if (value === undefined) {
+        return 0;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new Error(`${label} must be a finite number or percentage.`);
+        }
+        return value;
+    }
+    const normalized = value.trim();
+    const match = /^([+-]?(?:\d+(?:\.\d+)?|\.\d+))(%)?$/.exec(normalized);
+    if (!match) {
+        throw new Error(`${label} must be a finite number or percentage.`);
+    }
+    const parsed = Number(match[1]);
+    return match[2] ? (relativeTo * parsed) / 100 : parsed;
+}
+function normalizedOffset(value, step) {
+    return ((value % step) + step) % step;
+}
+/**
+ * Resolve the top-left visible bounds for every tile. Rows and columns begin
+ * one step outside the canvas so partial edge tiles preserve the grid phase.
+ */
+export function resolveTilePlacements(layout, canvas, item) {
+    assertSize(canvas, 'canvas');
+    assertSize(item, 'watermark');
+    const gapX = resolveLayoutValue(layout.gapX, canvas.width, 'layout.gapX');
+    const gapY = resolveLayoutValue(layout.gapY, canvas.height, 'layout.gapY');
+    if (gapX < 0 || gapY < 0) {
+        throw new Error('layout gaps must be non-negative.');
+    }
+    const offsetX = resolveLayoutValue(layout.offsetX, canvas.width, 'layout.offsetX');
+    const offsetY = resolveLayoutValue(layout.offsetY, canvas.height, 'layout.offsetY');
+    const stepX = item.width + gapX;
+    const stepY = item.height + gapY;
+    if (!Number.isFinite(stepX) || !Number.isFinite(stepY)) {
+        throw new Error('tile layout step must be finite.');
+    }
+    const phaseX = normalizedOffset(offsetX, stepX);
+    const phaseY = normalizedOffset(offsetY, stepY);
+    const placements = [];
+    for (let row = -1, y = phaseY - stepY; y < canvas.height; row += 1, y += stepY) {
+        if (y + item.height <= 0) {
+            continue;
+        }
+        const staggerOffset = layout.stagger && row % 2 !== 0 ? stepX / 2 : 0;
+        const rowPhaseX = normalizedOffset(phaseX + staggerOffset, stepX);
+        for (let x = rowPhaseX - stepX; x < canvas.width; x += stepX) {
+            if (x + item.width <= 0) {
+                continue;
+            }
+            placements.push({ x, y });
+            if (placements.length > MAX_TILE_COPIES) {
+                throw new Error(`tile layout exceeds the maximum of ${MAX_TILE_COPIES} copies per layer.`);
+            }
+        }
+    }
+    return placements;
+}

package/lib/module/core/marker.d.ts

@@ -0,0 +1 @@
+export { default } from './web/index.js';

package/lib/module/core/marker.js

@@ -0,0 +1,4 @@
+// The default implementation is browser-safe so standard web bundlers and
+// server-side rendering can import the package without loading React Native's
+// NativeModules. Metro selects marker.native.ts on iOS and Android.
+export { default } from './web/index.js';

package/lib/module/core/recipe.d.ts

@@ -0,0 +1,44 @@
+import { WATERMARK_RECIPE_SCHEMA_VERSION, type LegacyWatermarkRecipeDefinition as SharedLegacyWatermarkRecipeDefinition, type WatermarkRecipeCondition as SharedWatermarkRecipeCondition, type WatermarkRecipeDefinition as SharedWatermarkRecipeDefinition, type WatermarkRecipeDefinitionLayer as SharedWatermarkRecipeDefinitionLayer, type WatermarkRecipeDocument as SharedWatermarkRecipeDocument, type WatermarkRecipeInput as SharedWatermarkRecipeInput, type WatermarkRecipeLayer as SharedWatermarkRecipeLayer, type WatermarkRecipeOptions as SharedWatermarkRecipeOptions, type WatermarkRecipeOutputOptions as SharedWatermarkRecipeOutputOptions, type WatermarkRecipeSchemaVersion as SharedWatermarkRecipeSchemaVersion, type WatermarkRecipeVariable as SharedWatermarkRecipeVariable } from '@image-marker/recipe';
+import type { MarkOptions } from './index.js';
+import type { MarkerResult } from './result.js';
+import type { MarkerJobOptions } from './job.js';
+import type { WatermarkBatchOptions, WatermarkBatchResult } from './batch.js';
+export type { WatermarkBatchAbortedResult, WatermarkBatchFulfilledResult, WatermarkBatchOptions, WatermarkBatchProgress, WatermarkBatchRejectedResult, WatermarkBatchResult, } from './batch.js';
+export { WATERMARK_RECIPE_SCHEMA_VERSION };
+export type WatermarkRecipeSchemaVersion = SharedWatermarkRecipeSchemaVersion;
+export type WatermarkRecipeVariable = SharedWatermarkRecipeVariable;
+export type WatermarkRecipeCondition = SharedWatermarkRecipeCondition;
+export type WatermarkRecipeLayer = SharedWatermarkRecipeLayer<any>;
+export type WatermarkRecipeDefinitionLayer = SharedWatermarkRecipeDefinitionLayer<any>;
+export type WatermarkRecipeOutputOptions = SharedWatermarkRecipeOutputOptions;
+export type WatermarkRecipeOptions = SharedWatermarkRecipeOptions<any>;
+export type WatermarkRecipeDefinition = SharedWatermarkRecipeDefinition<any>;
+export type LegacyWatermarkRecipeDefinition = SharedLegacyWatermarkRecipeDefinition<any>;
+export type WatermarkRecipeDocument = SharedWatermarkRecipeDocument<any>;
+export type WatermarkRecipeInput = SharedWatermarkRecipeInput<any>;
+/** Return the Core 2 structured result. */
+export interface WatermarkMarkerResultRecipeOptions {
+    resultType?: 'result';
+}
+/** Return encoded browser bytes without creating an object URL. Web only. */
+export interface WatermarkBlobRecipeResultOptions {
+    resultType: 'blob';
+}
+export type WatermarkRecipeResultOptions = WatermarkMarkerResultRecipeOptions | WatermarkBlobRecipeResultOptions;
+export interface WatermarkRecipe<Result = MarkerResult> {
+    /** Version of the serializable recipe definition. */
+    readonly schemaVersion: WatermarkRecipeSchemaVersion;
+    /** Return a detached definition suitable for JSON persistence. */
+    toJSON(): WatermarkRecipeDefinition;
+    /** Apply the saved layers and output settings to one source image. */
+    apply(input: WatermarkRecipeInput, control?: MarkerJobOptions): Promise<Result>;
+    /** Apply the recipe to many images while preserving input result order. */
+    applyMany(inputs: readonly WatermarkRecipeInput[], options?: WatermarkBatchOptions<Result>): Promise<Array<WatermarkBatchResult<Result>>>;
+}
+type RecipeRenderer<Result> = (options: MarkOptions, control?: MarkerJobOptions) => Promise<Result>;
+/**
+ * Upgrade a serialized Recipe v1 document to the v2 layer/output structure.
+ */
+export declare function migrateWatermarkRecipe(document: WatermarkRecipeDocument): WatermarkRecipeDefinition;
+export declare function createWatermarkRecipe<Result>(options: WatermarkRecipeOptions, renderer: RecipeRenderer<Result>, maximumConcurrency?: number): WatermarkRecipe<Result>;
+export declare function importWatermarkRecipe<Result>(document: WatermarkRecipeDocument, renderer: RecipeRenderer<Result>, maximumConcurrency?: number): WatermarkRecipe<Result>;

package/lib/module/core/recipe.js

@@ -0,0 +1,169 @@
+import { cloneRecipeValue, createWatermarkRecipeDefinition, materializeWatermarkRecipe, migrateWatermarkRecipe as migrateSharedRecipe, WATERMARK_RECIPE_SCHEMA_VERSION, } from '@image-marker/recipe';
+import { validateMarkOptions } from './validate.js';
+import { runWatermarkBatch } from './batch.js';
+export { WATERMARK_RECIPE_SCHEMA_VERSION };
+function toRenderLayer(layer) {
+    const renderLayer = { ...layer };
+    delete renderLayer.id;
+    delete renderLayer.name;
+    delete renderLayer.visible;
+    delete renderLayer.locked;
+    delete renderLayer.groupId;
+    delete renderLayer.visibleWhen;
+    return renderLayer;
+}
+function snapshotRecipeOptions(options) {
+    if (!options || !Array.isArray(options.layers)) {
+        throw new Error('createRecipe requires an ordered layers array.');
+    }
+    if (options.schemaVersion !== undefined &&
+        options.schemaVersion !== WATERMARK_RECIPE_SCHEMA_VERSION) {
+        throw new Error(`Unsupported recipe schemaVersion: ${String(options.schemaVersion)}.`);
+    }
+    if (options.layers.length === 0) {
+        throw new Error('createRecipe requires at least one layer.');
+    }
+    const ids = new Set();
+    options.layers.forEach((layer, index) => {
+        if (layer.type === 'image' && !layer.src) {
+            throw new Error(`layers[${index}].src is required.`);
+        }
+        const id = layer.id ?? `layer-${index + 1}`;
+        if (ids.has(id))
+            throw new Error(`Duplicate layer id "${id}".`);
+        ids.add(id);
+    });
+    const runtimeOptions = options;
+    const unsupportedKey = [
+        'backgroundImage',
+        'filename',
+        'watermarkTexts',
+        'watermarkImage',
+        'watermarkPositions',
+        'watermarkImages',
+        'watermarks',
+        'quality',
+        'saveFormat',
+        'matteColor',
+        'rotationCanvasMode',
+        'maxSize',
+    ].find((key) => Object.prototype.hasOwnProperty.call(runtimeOptions, key));
+    if (unsupportedKey) {
+        throw new Error(`createRecipe does not accept "${unsupportedKey}" in Recipe v2; use ordered layers, put encoding options under output, and pass per-image fields to apply().`);
+    }
+    const definition = createWatermarkRecipeDefinition(options);
+    definition.layers.forEach((layer, index) => {
+        const original = options.layers[index];
+        if (layer.type === 'image' && original?.type === 'image') {
+            layer.src = original.src;
+        }
+    });
+    validateMarkOptions({
+        backgroundImage: { src: 'recipe-validation-placeholder' },
+        watermarks: definition.layers.map(toRenderLayer),
+        ...definition.output,
+    });
+    return definition;
+}
+/**
+ * Upgrade a serialized Recipe v1 document to the v2 layer/output structure.
+ */
+export function migrateWatermarkRecipe(document) {
+    return snapshotRecipeOptions(migrateSharedRecipe(document));
+}
+function snapshotInput(input) {
+    return {
+        backgroundImage: input?.backgroundImage
+            ? { ...input.backgroundImage }
+            : input?.backgroundImage,
+        filename: input?.filename,
+        variables: input?.variables ? { ...input.variables } : input?.variables,
+    };
+}
+function createMarkOptions(recipe, input, index) {
+    const materialized = materializeWatermarkRecipe(recipe, {
+        filename: input.filename,
+        index,
+        variables: input.variables,
+    });
+    const imageSources = new Map();
+    recipe.layers.forEach((layer) => {
+        if (layer.type === 'image') {
+            imageSources.set(layer.id, layer.src);
+        }
+    });
+    materialized.layers.forEach((layer) => {
+        if (layer.type === 'image' && imageSources.has(layer.id)) {
+            layer.src = imageSources.get(layer.id);
+        }
+    });
+    return {
+        backgroundImage: { ...input.backgroundImage },
+        watermarks: materialized.layers.map(toRenderLayer),
+        filename: input.filename,
+        ...materialized.output,
+    };
+}
+function canonicalOutputFilename(filename, saveFormat) {
+    const trimmed = filename.trim();
+    if (!trimmed)
+        return undefined;
+    const knownExtension = ['.jpeg', '.jpg', '.png', '.webp'].find((extension) => trimmed.toLowerCase().endsWith(extension));
+    const stem = knownExtension
+        ? trimmed.slice(0, -knownExtension.length)
+        : trimmed;
+    const extension = saveFormat === 'png' ? '.png' : saveFormat === 'webp' ? '.webp' : '.jpg';
+    return `${stem}${extension}`.toLowerCase();
+}
+function validateUniqueFilenames(inputs, saveFormat) {
+    const seen = new Map();
+    inputs.forEach((input, index) => {
+        if (input.filename === undefined)
+            return;
+        if (typeof input.filename !== 'string') {
+            throw new Error(`inputs[${index}].filename must be a string.`);
+        }
+        const canonical = canonicalOutputFilename(input.filename, saveFormat);
+        if (!canonical)
+            return;
+        const previousIndex = seen.get(canonical);
+        if (previousIndex !== undefined) {
+            throw new Error(`Duplicate output filename "${canonical}" for inputs ${previousIndex} and ${index}.`);
+        }
+        seen.set(canonical, index);
+    });
+}
+export function createWatermarkRecipe(options, renderer, maximumConcurrency = 1) {
+    const recipe = snapshotRecipeOptions(options);
+    const applySnapshot = (input, index, control) => {
+        if (!input?.backgroundImage?.src) {
+            return Promise.reject(new Error('please set image!'));
+        }
+        try {
+            return renderer(createMarkOptions(recipe, input, index), control);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    };
+    return {
+        schemaVersion: WATERMARK_RECIPE_SCHEMA_VERSION,
+        toJSON() {
+            return cloneRecipeValue(recipe);
+        },
+        apply(input, control) {
+            return applySnapshot(snapshotInput(input), 0, control);
+        },
+        async applyMany(inputs, batchOptions = {}) {
+            if (!Array.isArray(inputs)) {
+                throw new Error('applyMany inputs must be an array.');
+            }
+            const queuedInputs = inputs.map(snapshotInput);
+            validateUniqueFilenames(queuedInputs, recipe.output.saveFormat);
+            return runWatermarkBatch(queuedInputs, (input, index) => applySnapshot(input, index, { signal: batchOptions.signal }), batchOptions, maximumConcurrency, 'applyMany');
+        },
+    };
+}
+export function importWatermarkRecipe(document, renderer, maximumConcurrency = 1) {
+    return createWatermarkRecipe(migrateWatermarkRecipe(document), renderer, maximumConcurrency);
+}

package/lib/module/core/result.d.ts

@@ -0,0 +1,34 @@
+export type MarkerOperation = 'mark' | 'markText' | 'markImage' | 'embedInvisible' | 'detectInvisible';
+export type MarkerOutputFormat = 'png' | 'jpeg' | 'webp';
+export interface MarkerMetadataResult {
+    /** Source orientation is applied to pixels and output orientation is upright. */
+    orientation: 'normalized';
+    /**
+     * Core v2 strips EXIF/GPS and other source metadata by default so stale or
+     * sensitive source claims are not copied onto newly rendered pixels.
+     */
+    policy: 'strip';
+}
+export interface MarkerResult {
+    /** Stable identifier shared by progress, errors, and native cancellation. */
+    jobId: string;
+    /** Public operation that produced this result. */
+    operation: MarkerOperation;
+    /** File path/URI on native or data URL in a browser/base64 request. */
+    uri: string;
+    /** Whether `uri` points at a file or embeds the encoded bytes. */
+    output: 'file' | 'data-url';
+    format: MarkerOutputFormat;
+    mimeType: 'image/png' | 'image/jpeg' | 'image/webp';
+    /** Total JavaScript-observed operation duration. */
+    durationMs: number;
+    metadata: MarkerMetadataResult;
+    /** Requested output basename, when supplied. */
+    filename?: string;
+}
+export interface MarkerResultDescriptor {
+    operation: MarkerOperation;
+    saveFormat?: 'png' | 'jpg' | 'webp' | 'base64';
+    filename?: string;
+}
+export declare function createMarkerResult(jobId: string, uri: string, durationMs: number, descriptor: MarkerResultDescriptor): MarkerResult;

package/lib/module/core/result.js

@@ -0,0 +1,38 @@
+function resolveFormat(saveFormat, uri) {
+    if (uri?.startsWith('data:image/png'))
+        return 'png';
+    if (uri?.startsWith('data:image/jpeg'))
+        return 'jpeg';
+    if (uri?.startsWith('data:image/webp'))
+        return 'webp';
+    if (saveFormat === 'webp')
+        return 'webp';
+    return saveFormat === 'png' || saveFormat === 'base64' ? 'png' : 'jpeg';
+}
+export function createMarkerResult(jobId, uri, durationMs, descriptor) {
+    if (typeof uri !== 'string' || !uri) {
+        throw new Error('The renderer returned an empty output URI.');
+    }
+    const format = resolveFormat(descriptor.saveFormat, uri);
+    const result = {
+        jobId,
+        operation: descriptor.operation,
+        uri,
+        output: uri.startsWith('data:') ? 'data-url' : 'file',
+        format,
+        mimeType: format === 'png'
+            ? 'image/png'
+            : format === 'webp'
+                ? 'image/webp'
+                : 'image/jpeg',
+        durationMs: Math.max(0, durationMs),
+        metadata: {
+            orientation: 'normalized',
+            policy: 'strip',
+        },
+    };
+    if (descriptor.filename !== undefined) {
+        result.filename = descriptor.filename;
+    }
+    return result;
+}

package/lib/module/core/trace-runtime.d.ts

@@ -0,0 +1,43 @@
+import type { WatermarkBatchOptions, WatermarkBatchResult } from './batch.js';
+import type { DetectInvisibleWatermarkOptions, EmbedInvisibleWatermarkOptions, InvisibleWatermarkDetectionData, InvisibleWatermarkPixelBuffer } from './invisible-watermark.js';
+/** RGBA pixels decoded in display orientation by a server-side image codec. */
+export interface InvisibleWatermarkDecodedImage extends InvisibleWatermarkPixelBuffer {
+}
+/** Image I/O boundary used by the dependency-free trace runtime. */
+export interface InvisibleWatermarkCodec<Source, Output> {
+    decode(source: Source, options: {
+        maxSize: number;
+    }): Promise<InvisibleWatermarkDecodedImage>;
+    encode(image: InvisibleWatermarkDecodedImage, options: {
+        format: 'jpeg' | 'png';
+        quality: number;
+        filename?: string;
+    }): Promise<Output>;
+}
+export interface InvisibleWatermarkRuntimeOptions<Source, Output> {
+    codec: InvisibleWatermarkCodec<Source, Output>;
+    /** Hard upper bound for parallel codec/CPU work. @defaultValue 4 */
+    maxConcurrency?: number;
+}
+export type RuntimeEmbedInvisibleWatermarkOptions<Source> = Omit<EmbedInvisibleWatermarkOptions, 'image' | 'saveFormat'> & {
+    image: {
+        src: Source;
+    };
+    saveFormat?: 'png' | 'jpg';
+};
+export type RuntimeDetectInvisibleWatermarkOptions<Source> = Omit<DetectInvisibleWatermarkOptions, 'image' | 'worker'> & {
+    image: {
+        src: Source;
+    };
+};
+export interface InvisibleWatermarkRuntime<Source, Output> {
+    embedInvisible(options: RuntimeEmbedInvisibleWatermarkOptions<Source>): Promise<Output>;
+    detectInvisible(options: RuntimeDetectInvisibleWatermarkOptions<Source>): Promise<InvisibleWatermarkDetectionData>;
+    embedInvisibleMany(inputs: readonly RuntimeEmbedInvisibleWatermarkOptions<Source>[], options?: WatermarkBatchOptions<Output>): Promise<Array<WatermarkBatchResult<Output>>>;
+    detectInvisibleMany(inputs: readonly RuntimeDetectInvisibleWatermarkOptions<Source>[], options?: WatermarkBatchOptions<InvisibleWatermarkDetectionData>): Promise<Array<WatermarkBatchResult<InvisibleWatermarkDetectionData>>>;
+}
+/**
+ * Create a DOM-free invisible watermark runtime around an injected image codec.
+ * The core package does not install or choose a server-side image dependency.
+ */
+export declare function createInvisibleWatermarkRuntime<Source, Output>(options: InvisibleWatermarkRuntimeOptions<Source, Output>): InvisibleWatermarkRuntime<Source, Output>;