@image-marker/web 0.1.0

package/lib/module/core/trace-runtime.js

@@ -0,0 +1,89 @@
+import { runWatermarkBatch } from './batch.js';
+import { detectInvisibleWatermarkPixelsAsync, embedInvisibleWatermarkPixels, validateDetectInvisibleOptions, validateEmbedInvisibleOptions, } from './invisible-watermark.js';
+const DEFAULT_RUNTIME_MAX_SIZE = 2048;
+function validatePositiveInteger(value, label) {
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+        throw new Error(`${label} must be a positive finite integer.`);
+    }
+}
+function validateDecodedImage(image, maxSize) {
+    if (!image ||
+        !(image.data instanceof Uint8Array ||
+            image.data instanceof Uint8ClampedArray)) {
+        throw new Error('codec.decode() must return RGBA Uint8Array pixels.');
+    }
+    validatePositiveInteger(image.width, 'decoded image width');
+    validatePositiveInteger(image.height, 'decoded image height');
+    if (Math.max(image.width, image.height) > maxSize) {
+        throw new Error('codec.decode() returned an image larger than maxSize.');
+    }
+    if (image.data.length !== image.width * image.height * 4) {
+        throw new Error('codec.decode() RGBA byte length must exactly match width × height × 4.');
+    }
+}
+function snapshotEmbedOptions(options) {
+    return { ...options, image: { ...options?.image } };
+}
+function snapshotDetectOptions(options) {
+    return { ...options, image: { ...options?.image } };
+}
+/**
+ * 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 function createInvisibleWatermarkRuntime(options) {
+    if (!options?.codec || typeof options.codec.decode !== 'function') {
+        throw new Error('codec.decode must be a function.');
+    }
+    if (typeof options.codec.encode !== 'function') {
+        throw new Error('codec.encode must be a function.');
+    }
+    const maximumConcurrency = options.maxConcurrency ?? 4;
+    validatePositiveInteger(maximumConcurrency, 'maxConcurrency');
+    const embedInvisible = async (input) => {
+        const snapshot = snapshotEmbedOptions(input);
+        validateEmbedInvisibleOptions(snapshot);
+        const saveFormat = snapshot.saveFormat;
+        if (saveFormat === 'base64') {
+            throw new Error('The generic invisible watermark runtime does not support base64 output.');
+        }
+        const maxSize = snapshot.maxSize ?? DEFAULT_RUNTIME_MAX_SIZE;
+        const decoded = await options.codec.decode(snapshot.image.src, { maxSize });
+        validateDecodedImage(decoded, maxSize);
+        const outputPixels = {
+            data: new Uint8ClampedArray(decoded.data),
+            width: decoded.width,
+            height: decoded.height,
+        };
+        embedInvisibleWatermarkPixels(outputPixels, snapshot);
+        return options.codec.encode(outputPixels, {
+            format: saveFormat === 'png' ? 'png' : 'jpeg',
+            quality: snapshot.quality ?? 90,
+            filename: snapshot.filename,
+        });
+    };
+    const detectInvisible = async (input) => {
+        const snapshot = snapshotDetectOptions(input);
+        validateDetectInvisibleOptions(snapshot);
+        const maxSize = snapshot.maxSize ?? DEFAULT_RUNTIME_MAX_SIZE;
+        const decoded = await options.codec.decode(snapshot.image.src, { maxSize });
+        validateDecodedImage(decoded, maxSize);
+        return detectInvisibleWatermarkPixelsAsync(decoded, snapshot);
+    };
+    return {
+        embedInvisible,
+        detectInvisible,
+        embedInvisibleMany(inputs, batchOptions) {
+            const snapshots = Array.isArray(inputs)
+                ? inputs.map((input) => snapshotEmbedOptions(input))
+                : inputs;
+            return runWatermarkBatch(snapshots, embedInvisible, batchOptions, maximumConcurrency, 'trace runtime embedInvisibleMany');
+        },
+        detectInvisibleMany(inputs, batchOptions) {
+            const snapshots = Array.isArray(inputs)
+                ? inputs.map((input) => snapshotDetectOptions(input))
+                : inputs;
+            return runWatermarkBatch(snapshots, detectInvisible, batchOptions, maximumConcurrency, 'trace runtime detectInvisibleMany');
+        },
+    };
+}

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

@@ -0,0 +1,4 @@
+import type { ImageMarkOptions, MarkOptions, TextMarkOptions } from './index.js';
+export declare function validateTextMarkOptions(options: TextMarkOptions): void;
+export declare function validateImageMarkOptions(options: ImageMarkOptions): void;
+export declare function validateMarkOptions(options: MarkOptions): void;

package/lib/module/core/validate.js

@@ -0,0 +1,187 @@
+const SUPPORTED_BLEND_MODES = new Set([
+    'normal',
+    'multiply',
+    'screen',
+    'overlay',
+    'darken',
+    'lighten',
+]);
+function validateQuality(options) {
+    const { quality } = options;
+    if (quality !== undefined &&
+        (!Number.isFinite(quality) ||
+            !Number.isInteger(quality) ||
+            quality < 0 ||
+            quality > 100)) {
+        throw new Error('quality must be a finite integer between 0 and 100.');
+    }
+}
+function validateMaxSize(options) {
+    const { maxSize } = options;
+    if (maxSize !== undefined &&
+        (!Number.isFinite(maxSize) || !Number.isInteger(maxSize) || maxSize <= 0)) {
+        throw new Error('maxSize must be a positive finite integer.');
+    }
+}
+function validateAlpha(options, path) {
+    const alpha = options?.alpha;
+    if (alpha !== undefined &&
+        (!Number.isFinite(alpha) || alpha < 0 || alpha > 1)) {
+        throw new Error(`${path}.alpha must be a finite number between 0 and 1.`);
+    }
+}
+function validateBlendMode(blendMode, path) {
+    if (blendMode !== undefined && !SUPPORTED_BLEND_MODES.has(blendMode)) {
+        throw new Error(`${path}.blendMode is not supported: ${String(blendMode)}.`);
+    }
+}
+function validateCommonOptions(options) {
+    validateQuality(options);
+    validateMaxSize(options);
+    validateAlpha(options.backgroundImage, 'backgroundImage');
+    const saveFormat = options.saveFormat;
+    if (saveFormat !== undefined &&
+        saveFormat !== 'jpg' &&
+        saveFormat !== 'png' &&
+        saveFormat !== 'webp' &&
+        saveFormat !== 'base64') {
+        throw new Error(`saveFormat is not supported: ${String(saveFormat)}.`);
+    }
+}
+function validateLayoutValue(value, path, nonNegative) {
+    if (value === undefined) {
+        return;
+    }
+    const normalized = typeof value === 'string' ? value.trim() : value;
+    const valid = typeof normalized === 'number'
+        ? Number.isFinite(normalized)
+        : /^([+-]?(?:\d+(?:\.\d+)?|\.\d+))(%)?$/.test(normalized);
+    if (!valid) {
+        throw new Error(`${path} must be a finite number or percentage.`);
+    }
+    if (nonNegative && Number.parseFloat(String(normalized)) < 0) {
+        throw new Error(`${path} must be non-negative.`);
+    }
+}
+function validateWatermarkLayout(layout, hasPosition, path) {
+    if (!layout) {
+        return;
+    }
+    if (typeof layout !== 'object' || Array.isArray(layout)) {
+        throw new Error(`${path} must be an object.`);
+    }
+    const type = layout.type ?? 'single';
+    if (type !== 'single' && type !== 'tile') {
+        throw new Error(`${path}.type must be "single" or "tile".`);
+    }
+    if (type === 'tile' && hasPosition) {
+        throw new Error(`${path} cannot be combined with position.`);
+    }
+    const runtimeLayout = layout;
+    validateLayoutValue(runtimeLayout.gapX, `${path}.gapX`, true);
+    validateLayoutValue(runtimeLayout.gapY, `${path}.gapY`, true);
+    validateLayoutValue(runtimeLayout.offsetX, `${path}.offsetX`, false);
+    validateLayoutValue(runtimeLayout.offsetY, `${path}.offsetY`, false);
+    if (runtimeLayout.stagger !== undefined &&
+        typeof runtimeLayout.stagger !== 'boolean') {
+        throw new Error(`${path}.stagger must be a boolean.`);
+    }
+}
+function validateTextOptions(options, path) {
+    if (Object.prototype.hasOwnProperty.call(options, 'positionOptions')) {
+        throw new Error(`${path}.positionOptions was removed in v2; use position instead.`);
+    }
+    validateAlpha(options, path);
+    validateBlendMode(options.blendMode, path);
+    const fontFallbacks = options.style?.fontFallbacks;
+    if (fontFallbacks !== undefined &&
+        (!Array.isArray(fontFallbacks) ||
+            fontFallbacks.some((font) => typeof font !== 'string' || font.trim().length === 0))) {
+        throw new Error(`${path}.style.fontFallbacks must contain non-empty font family names.`);
+    }
+    const style = options.style;
+    if (style?.maxWidth !== undefined) {
+        validateLayoutValue(style.maxWidth, `${path}.style.maxWidth`, true);
+        if (Number.parseFloat(String(style.maxWidth)) <= 0) {
+            throw new Error(`${path}.style.maxWidth must be greater than zero.`);
+        }
+    }
+    if (style?.lineHeight !== undefined &&
+        (!Number.isFinite(style.lineHeight) || style.lineHeight <= 0)) {
+        throw new Error(`${path}.style.lineHeight must be a finite number greater than zero.`);
+    }
+    if (style?.letterSpacing !== undefined &&
+        !Number.isFinite(style.letterSpacing)) {
+        throw new Error(`${path}.style.letterSpacing must be a finite number.`);
+    }
+    if (style?.maxLines !== undefined &&
+        (!Number.isFinite(style.maxLines) ||
+            !Number.isInteger(style.maxLines) ||
+            style.maxLines < 1)) {
+        throw new Error(`${path}.style.maxLines must be a positive integer.`);
+    }
+    if (style?.direction !== undefined &&
+        !['auto', 'ltr', 'rtl'].includes(style.direction)) {
+        throw new Error(`${path}.style.direction must be "auto", "ltr", or "rtl".`);
+    }
+    if (style?.wrap !== undefined &&
+        !['word', 'character', 'none'].includes(style.wrap)) {
+        throw new Error(`${path}.style.wrap must be "word", "character", or "none".`);
+    }
+    if (style?.overflow !== undefined &&
+        !['clip', 'ellipsis'].includes(style.overflow)) {
+        throw new Error(`${path}.style.overflow must be "clip" or "ellipsis".`);
+    }
+    const strokeStyle = options.style?.strokeStyle;
+    if (strokeStyle) {
+        if (!Number.isFinite(strokeStyle.width) || strokeStyle.width < 0) {
+            throw new Error(`${path}.style.strokeStyle.width must be a non-negative finite number.`);
+        }
+        if (typeof strokeStyle.color !== 'string' || !strokeStyle.color.trim()) {
+            throw new Error(`${path}.style.strokeStyle.color must be a non-empty string.`);
+        }
+    }
+    validateWatermarkLayout(options.layout, options.position !== undefined, `${path}.layout`);
+}
+function validateImageOptions(options, path, hasExternalPosition = false) {
+    validateAlpha(options, path);
+    validateBlendMode(options.blendMode, path);
+    validateWatermarkLayout(options.layout, options.position !== undefined || hasExternalPosition, `${path}.layout`);
+}
+export function validateTextMarkOptions(options) {
+    validateCommonOptions(options);
+    options.watermarkTexts.forEach((textOptions, index) => {
+        validateTextOptions(textOptions, `watermarkTexts[${index}]`);
+    });
+}
+export function validateImageMarkOptions(options) {
+    validateCommonOptions(options);
+    if (Object.prototype.hasOwnProperty.call(options, 'watermarkImage') ||
+        Object.prototype.hasOwnProperty.call(options, 'watermarkPositions')) {
+        throw new Error('watermarkImage and watermarkPositions were removed in v2; use watermarkImages[].position.');
+    }
+    options.watermarkImages?.forEach((imageOptions, index) => {
+        validateImageOptions(imageOptions, `watermarkImages[${index}]`);
+    });
+}
+export function validateMarkOptions(options) {
+    validateCommonOptions(options);
+    if (Object.prototype.hasOwnProperty.call(options, 'watermarkImage') ||
+        Object.prototype.hasOwnProperty.call(options, 'watermarkPositions')) {
+        throw new Error('watermarkImage and watermarkPositions were removed in v2; use watermarks with an image layer.');
+    }
+    options.watermarkImages?.forEach((imageOptions, index) => {
+        validateImageOptions(imageOptions, `watermarkImages[${index}]`);
+    });
+    options.watermarks?.forEach((layer, index) => {
+        if (layer.type === 'image') {
+            validateImageOptions(layer, `watermarks[${index}]`);
+        }
+        else {
+            validateTextOptions(layer, `watermarks[${index}]`);
+        }
+    });
+    options.watermarkTexts?.forEach((textOptions, index) => {
+        validateTextOptions(textOptions, `watermarkTexts[${index}]`);
+    });
+}

package/lib/module/core/web/browser.d.ts

@@ -0,0 +1,105 @@
+import type { MarkerImageInfo } from '../image-info.js';
+export interface WebCanvas {
+    width: number;
+    height: number;
+    getContext(contextId: '2d'): WebCanvasContext | null;
+    toDataURL(type?: string, quality?: number): string;
+    toBlob(callback: (blob: Blob | null) => void, type?: string, quality?: number): void;
+}
+export interface WebCanvasContext {
+    [key: string]: unknown;
+    canvas: WebCanvas;
+    globalAlpha: number;
+    globalCompositeOperation: string;
+    fillStyle: unknown;
+    font: string;
+    textAlign: string;
+    textBaseline: string;
+    direction?: string;
+    letterSpacing?: string;
+    shadowBlur: number;
+    shadowColor: string;
+    shadowOffsetX: number;
+    shadowOffsetY: number;
+    imageSmoothingEnabled: boolean;
+    lineJoin: string;
+    lineWidth: number;
+    strokeStyle: unknown;
+    save(): void;
+    restore(): void;
+    beginPath(): void;
+    closePath(): void;
+    clip(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
+    rect(x: number, y: number, width: number, height: number): void;
+    fill(): void;
+    fillRect(x: number, y: number, width: number, height: number): void;
+    translate(x: number, y: number): void;
+    rotate(angle: number): void;
+    scale(x: number, y: number): void;
+    transform(a: number, b: number, c: number, d: number, e: number, f: number): void;
+    drawImage(...args: unknown[]): void;
+    fillText(text: string, x: number, y: number): void;
+    strokeText(text: string, x: number, y: number): void;
+    measureText(text: string): WebTextMetrics;
+    getImageData(sx: number, sy: number, sw: number, sh: number): WebImageData;
+    putImageData(imageData: WebImageData, dx: number, dy: number): void;
+}
+export interface WebImageData {
+    data: Uint8Array | Uint8ClampedArray;
+    width?: number;
+    height?: number;
+}
+export interface WebTextMetrics {
+    width: number;
+    actualBoundingBoxAscent?: number;
+    actualBoundingBoxDescent?: number;
+    fontBoundingBoxAscent?: number;
+    fontBoundingBoxDescent?: number;
+}
+export interface WebImageElement {
+    src: string;
+    crossOrigin?: string | null;
+    complete?: boolean;
+    width?: number;
+    height?: number;
+    naturalWidth?: number;
+    naturalHeight?: number;
+    onload: (() => void) | null;
+    onerror: ((event?: unknown) => void) | null;
+    decode?: () => Promise<void>;
+}
+/**
+ * DOM-adjacent resources used by a Web Marker instance. Providing this object
+ * keeps object-URL ownership with the instance and makes browser APIs
+ * replaceable by a desktop host without changing rendering algorithms.
+ */
+export interface WebResourceAdapter {
+    /** Standard `new Image()` and `document.createElement('img')` both fit. */
+    createImage?: () => unknown;
+    /** Standard `document.createElement('canvas')` fits without a cast. */
+    createCanvas?: (width: number, height: number) => unknown;
+    createObjectURL?: (source: Blob) => string;
+    revokeObjectURL?: (url: string) => void;
+    /** Optional byte reader for File/Blob policy boundaries. */
+    readBlobBytes?: (source: Blob) => Promise<ArrayBuffer>;
+}
+export interface LoadedWebImage {
+    image: unknown;
+    width: number;
+    height: number;
+    cleanup(): void;
+}
+/**
+ * Read dimensions, encoded format, and orientation without rendering a
+ * composition. Encoded bytes are preferred so EXIF orientation remains
+ * observable; drawable dimensions are the cross-origin fallback.
+ */
+export declare function getWebImageInfo(source: unknown, resources?: WebResourceAdapter, signal?: AbortSignal): Promise<MarkerImageInfo>;
+/** Load a browser drawable from a URL, data URL, {uri}, Blob/File, or image element. */
+export declare function loadWebImage(source: unknown, resources?: WebResourceAdapter, signal?: AbortSignal): Promise<LoadedWebImage>;
+export declare function createWebCanvas(width: number, height: number, resources?: WebResourceAdapter): WebCanvas;
+export declare function getCanvasContext(canvas: WebCanvas): WebCanvasContext;
+export declare function getSecurityErrorMessage(operation: string): string;