@image-marker/web 0.1.0

package/lib/module/core/web/browser.js

@@ -0,0 +1,427 @@
+import { createMarkerImageInfo, parseEncodedImageInfo } from '../image-info.js';
+function getBrowserRuntime() {
+    return globalThis;
+}
+function getImageDimensions(image) {
+    const width = image.naturalWidth ?? image.width ?? 0;
+    const height = image.naturalHeight ?? image.height ?? 0;
+    return width > 0 && height > 0 ? { width, height } : null;
+}
+function isImageLike(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    const hasDrawableIdentity = 'naturalWidth' in candidate ||
+        'complete' in candidate ||
+        typeof candidate.decode === 'function' ||
+        typeof candidate.close === 'function' ||
+        typeof candidate.getContext === 'function' ||
+        typeof candidate.videoWidth === 'number';
+    return (hasDrawableIdentity &&
+        Boolean(getImageDimensions(candidate)));
+}
+function isBlobLike(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const tag = Object.prototype.toString.call(value);
+    if (tag === '[object Blob]' || tag === '[object File]') {
+        return true;
+    }
+    const candidate = value;
+    return (typeof candidate.arrayBuffer === 'function' &&
+        typeof candidate.size === 'number' &&
+        typeof candidate.type === 'string');
+}
+function resolveImageUri(source) {
+    if (typeof source === 'string') {
+        return source;
+    }
+    if (!source || typeof source !== 'object') {
+        return null;
+    }
+    const candidate = source;
+    if (typeof candidate.uri === 'string') {
+        return candidate.uri;
+    }
+    if (typeof candidate.src === 'string') {
+        return candidate.src;
+    }
+    if (typeof candidate.href === 'string') {
+        return candidate.href;
+    }
+    if (typeof candidate.default === 'string') {
+        return candidate.default;
+    }
+    if (candidate.default && candidate.default !== source) {
+        return resolveImageUri(candidate.default);
+    }
+    return null;
+}
+function inferImageFormat(uri, mimeType) {
+    const normalizedMimeType = mimeType?.split(';', 1)[0]?.toLowerCase();
+    if (normalizedMimeType === 'image/jpeg')
+        return 'jpeg';
+    if (normalizedMimeType === 'image/png')
+        return 'png';
+    if (normalizedMimeType === 'image/webp')
+        return 'webp';
+    if (normalizedMimeType === 'image/gif')
+        return 'gif';
+    if (normalizedMimeType === 'image/heif' ||
+        normalizedMimeType === 'image/heic' ||
+        normalizedMimeType === 'image/avif') {
+        return 'heif';
+    }
+    if (normalizedMimeType === 'image/bmp')
+        return 'bmp';
+    const pathname = uri?.split(/[?#]/u, 1)[0]?.toLowerCase() ?? '';
+    if (/\.(?:jpe?g)$/u.test(pathname))
+        return 'jpeg';
+    if (/\.png$/u.test(pathname))
+        return 'png';
+    if (/\.webp$/u.test(pathname))
+        return 'webp';
+    if (/\.gif$/u.test(pathname))
+        return 'gif';
+    if (/\.(?:heic|heif|avif)$/u.test(pathname))
+        return 'heif';
+    if (/\.bmp$/u.test(pathname))
+        return 'bmp';
+    return 'unknown';
+}
+function decodeDataUrl(uri) {
+    const match = /^data:([^,]*?),(.*)$/su.exec(uri);
+    if (!match)
+        return null;
+    const metadata = match[1] ?? '';
+    const payload = match[2] ?? '';
+    const mimeType = metadata.split(';', 1)[0] || undefined;
+    try {
+        if (/(?:^|;)base64(?:;|$)/iu.test(metadata)) {
+            const decode = globalThis.atob;
+            if (!decode)
+                return null;
+            const decoded = decode(payload.replace(/\s/gu, ''));
+            const bytes = Uint8Array.from(decoded, (character) => character.charCodeAt(0));
+            return { data: bytes.buffer, mimeType };
+        }
+        return { data: decodePercentEncodedDataUrl(payload), mimeType };
+    }
+    catch {
+        return null;
+    }
+}
+function encodeUtf8(value) {
+    const TextEncoderClass = globalThis.TextEncoder;
+    if (TextEncoderClass) {
+        return new TextEncoderClass().encode(value).buffer;
+    }
+    const bytes = [];
+    for (let index = 0; index < value.length; index += 1) {
+        const first = value.charCodeAt(index);
+        const second = value.charCodeAt(index + 1);
+        let codePoint = first;
+        if (first >= 0xd800 &&
+            first <= 0xdbff &&
+            second >= 0xdc00 &&
+            second <= 0xdfff) {
+            index += 1;
+            codePoint = (first - 0xd800) * 0x400 + second - 0xdc00 + 0x10000;
+        }
+        if (codePoint <= 0x7f) {
+            bytes.push(codePoint);
+        }
+        else if (codePoint <= 0x7ff) {
+            bytes.push(0xc0 + Math.floor(codePoint / 0x40), 0x80 + (codePoint % 0x40));
+        }
+        else if (codePoint <= 0xffff) {
+            bytes.push(0xe0 + Math.floor(codePoint / 0x1000), 0x80 + (Math.floor(codePoint / 0x40) % 0x40), 0x80 + (codePoint % 0x40));
+        }
+        else {
+            bytes.push(0xf0 + Math.floor(codePoint / 0x40000), 0x80 + (Math.floor(codePoint / 0x1000) % 0x40), 0x80 + (Math.floor(codePoint / 0x40) % 0x40), 0x80 + (codePoint % 0x40));
+        }
+    }
+    return Uint8Array.from(bytes).buffer;
+}
+/** Decode `%xx` as bytes, keeping unescaped Unicode text encoded as UTF-8. */
+function decodePercentEncodedDataUrl(payload) {
+    const bytes = [];
+    let text = '';
+    const appendText = () => {
+        if (!text)
+            return;
+        bytes.push(...new Uint8Array(encodeUtf8(text)));
+        text = '';
+    };
+    for (let index = 0; index < payload.length; index += 1) {
+        if (payload[index] !== '%' || index + 2 >= payload.length) {
+            text += payload[index];
+            continue;
+        }
+        const encoded = payload.slice(index + 1, index + 3);
+        if (!/^[\da-f]{2}$/iu.test(encoded)) {
+            text += payload[index];
+            continue;
+        }
+        appendText();
+        bytes.push(Number.parseInt(encoded, 16));
+        index += 2;
+    }
+    appendText();
+    return Uint8Array.from(bytes).buffer;
+}
+async function readEncodedImageSource(source, resources, signal) {
+    if (signal?.aborted)
+        throw createAbortError();
+    if (isBlobLike(source)) {
+        const blob = source;
+        const data = resources?.readBlobBytes
+            ? await resources.readBlobBytes(source)
+            : await blob.arrayBuffer();
+        if (signal?.aborted)
+            throw createAbortError();
+        return { data, mimeType: blob.type || undefined };
+    }
+    const uri = resolveImageUri(source);
+    if (uri?.startsWith('data:')) {
+        if (signal?.aborted)
+            throw createAbortError();
+        return decodeDataUrl(uri);
+    }
+    const fetchImage = globalThis.fetch;
+    if (!uri || !fetchImage) {
+        return null;
+    }
+    try {
+        const response = signal
+            ? await fetchImage(uri, { signal })
+            : await fetchImage(uri);
+        if (!response.ok && !uri.startsWith('data:')) {
+            return null;
+        }
+        const data = await response.arrayBuffer();
+        if (signal?.aborted)
+            throw createAbortError();
+        return {
+            data,
+            mimeType: response.headers.get('content-type') ?? undefined,
+        };
+    }
+    catch {
+        if (signal?.aborted)
+            throw createAbortError();
+        return null;
+    }
+}
+/**
+ * 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 async function getWebImageInfo(source, resources, signal) {
+    if (signal?.aborted)
+        throw createAbortError();
+    const encoded = await readEncodedImageSource(source, resources, signal);
+    if (encoded) {
+        try {
+            const info = parseEncodedImageInfo(encoded.data);
+            return encoded.mimeType && !info.mimeType
+                ? { ...info, mimeType: encoded.mimeType }
+                : info;
+        }
+        catch {
+            // SVG and browser-specific formats can still be drawable. Continue with
+            // decoded dimensions rather than rejecting a valid browser image.
+        }
+    }
+    const loaded = await loadWebImage(source, resources, signal);
+    try {
+        const uri = resolveImageUri(source);
+        const mimeType = encoded?.mimeType ||
+            (isBlobLike(source)
+                ? source.type || undefined
+                : undefined);
+        return createMarkerImageInfo({
+            width: Math.round(loaded.width),
+            height: Math.round(loaded.height),
+            format: inferImageFormat(uri, mimeType),
+            mimeType,
+            orientation: 1,
+        });
+    }
+    finally {
+        loaded.cleanup();
+    }
+}
+function createImageElement(resources) {
+    if (resources?.createImage) {
+        const image = resources.createImage();
+        if (!image || typeof image !== 'object' || !('src' in image)) {
+            throw new Error('Web Marker resource adapter returned an invalid image.');
+        }
+        return image;
+    }
+    const runtime = getBrowserRuntime();
+    if (runtime.Image) {
+        return new runtime.Image();
+    }
+    const element = runtime.document?.createElement('img');
+    if (element && typeof element === 'object') {
+        return element;
+    }
+    throw new Error('WebMarker requires a browser image runtime. Importing it during SSR is supported, but mark*() must run in the browser.');
+}
+function remoteUrl(uri) {
+    return /^(?:https?:)?\/\//i.test(uri);
+}
+function createAbortError() {
+    const error = new Error('Web image loading was aborted.');
+    error.name = 'AbortError';
+    return error;
+}
+/** Load a browser drawable from a URL, data URL, {uri}, Blob/File, or image element. */
+export async function loadWebImage(source, resources, signal) {
+    if (signal?.aborted) {
+        throw createAbortError();
+    }
+    if (isImageLike(source)) {
+        const dimensions = getImageDimensions(source);
+        if (!dimensions) {
+            throw new Error('The supplied image has no drawable dimensions.');
+        }
+        return { image: source, ...dimensions, cleanup() { } };
+    }
+    let objectUrl;
+    let uri = resolveImageUri(source);
+    if (!uri && isBlobLike(source)) {
+        const runtime = getBrowserRuntime();
+        const createObjectURL = resources?.createObjectURL ?? runtime.URL?.createObjectURL;
+        if (!createObjectURL) {
+            throw new Error('This browser cannot load Blob/File image sources.');
+        }
+        objectUrl = createObjectURL(source);
+        uri = objectUrl;
+    }
+    if (!uri) {
+        if (typeof source === 'number') {
+            throw new Error('Numeric React Native asset IDs are not available on web. Pass the bundler-resolved URL, { uri }, a data URL, Blob, or File instead.');
+        }
+        throw new Error('Unsupported web image source. Expected a URL, data URL, { uri }, Blob, File, or loaded image element.');
+    }
+    let image;
+    try {
+        image = createImageElement(resources);
+    }
+    catch (error) {
+        if (objectUrl) {
+            const runtime = getBrowserRuntime();
+            try {
+                (resources?.revokeObjectURL ?? runtime.URL?.revokeObjectURL)?.(objectUrl);
+            }
+            catch {
+                // Preserve the image-factory error; cleanup must not conceal it.
+            }
+        }
+        throw error;
+    }
+    if (remoteUrl(uri)) {
+        image.crossOrigin = 'anonymous';
+    }
+    let cleanedUp = false;
+    const cleanup = () => {
+        if (cleanedUp)
+            return;
+        cleanedUp = true;
+        image.onload = null;
+        image.onerror = null;
+        signal?.removeEventListener('abort', abort);
+        if (objectUrl) {
+            const runtime = getBrowserRuntime();
+            (resources?.revokeObjectURL ?? runtime.URL?.revokeObjectURL)?.(objectUrl);
+            objectUrl = undefined;
+        }
+    };
+    let rejectLoading;
+    const abort = () => {
+        image.src = '';
+        cleanup();
+        rejectLoading?.(createAbortError());
+    };
+    try {
+        await new Promise((resolve, reject) => {
+            rejectLoading = reject;
+            image.onload = () => resolve();
+            image.onerror = () => {
+                const corsHint = remoteUrl(uri)
+                    ? ' The server must allow cross-origin image access with Access-Control-Allow-Origin.'
+                    : '';
+                reject(new Error(`Unable to load web image.${corsHint}`));
+            };
+            image.src = uri;
+            signal?.addEventListener('abort', abort, { once: true });
+            if (signal?.aborted) {
+                abort();
+                return;
+            }
+            if (image.complete && getImageDimensions(image)) {
+                resolve();
+            }
+        });
+        if (image.decode) {
+            try {
+                await image.decode();
+            }
+            catch {
+                // onload already proved that the image is drawable. Some browsers reject
+                // decode() after resolving cached images, so this is intentionally best effort.
+            }
+        }
+        const dimensions = getImageDimensions(image);
+        if (!dimensions) {
+            throw new Error('The loaded image has no drawable dimensions.');
+        }
+        return {
+            image,
+            ...dimensions,
+            cleanup,
+        };
+    }
+    catch (error) {
+        cleanup();
+        throw error;
+    }
+    finally {
+        image.onload = null;
+        image.onerror = null;
+    }
+}
+export function createWebCanvas(width, height, resources) {
+    const runtime = getBrowserRuntime();
+    const canvas = resources?.createCanvas?.(width, height) ??
+        runtime.document?.createElement('canvas');
+    if (!canvas || typeof canvas !== 'object') {
+        throw new Error('WebMarker requires Canvas 2D. Importing it during SSR is supported, but mark*() must run in a browser with canvas support.');
+    }
+    const result = canvas;
+    if (typeof result.getContext !== 'function') {
+        throw new Error('Web Marker resource adapter returned an invalid canvas.');
+    }
+    result.width = Math.max(Math.round(width), 1);
+    result.height = Math.max(Math.round(height), 1);
+    if (!result.getContext('2d')) {
+        throw new Error('Canvas 2D is unavailable in this browser.');
+    }
+    return result;
+}
+export function getCanvasContext(canvas) {
+    const context = canvas.getContext('2d');
+    if (!context) {
+        throw new Error('Canvas 2D is unavailable in this browser.');
+    }
+    return context;
+}
+export function getSecurityErrorMessage(operation) {
+    return `Unable to ${operation} because a remote image tainted the canvas. Configure Access-Control-Allow-Origin on the image server or use a local file/data URL.`;
+}

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

@@ -0,0 +1,41 @@
+import type { PositionOptions } from '../index.js';
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface RotatedBounds extends Size {
+    left: number;
+    top: number;
+}
+export interface CanvasEncoder {
+    width: number;
+    height: number;
+    toDataURL(type?: string, quality?: number): string;
+    toBlob?(callback: (blob: Blob | null) => void, type?: string, quality?: number): void;
+}
+export type WebOutputFormat = 'png' | 'jpg' | 'webp' | 'base64';
+export declare const DEFAULT_WEB_MAX_SIZE = 2048;
+/** Fit an image inside the same square pixel bound used by native loaders. */
+export declare function fitSizeWithinMax(size: Size, maxSize?: number): Size;
+/** Resolve a pixel or percentage value against one canvas axis. */
+export declare function resolveSpreadValue(value: number | string | undefined, relativeTo: number): number | undefined;
+/**
+ * Resolve the top-left point of an item using the same directional semantics
+ * as the native renderers. Named anchors default to a 20px inset; explicit
+ * X/Y values replace the inset on their respective axes.
+ */
+export declare function resolveAnchoredPosition(options: PositionOptions | undefined, canvas: Size, item: Size, unanchoredDefaultInset?: number): Point;
+export declare function degreesToRadians(degrees: number): number;
+/** Bounds of a rectangle rotated around its top-left origin. */
+export declare function getRotatedBounds(size: Size, degrees: number): RotatedBounds;
+export declare function getExpandedCanvasSize(size: Size, degrees: number): Size;
+export declare function normalizeQuality(quality: number | undefined): number;
+export declare function normalizeOutputFormat(format: string | undefined): WebOutputFormat;
+/** Serialize a rendered canvas and turn browser security failures into a useful CORS error. */
+export declare function encodeCanvas(canvas: CanvasEncoder, format: string | undefined, quality: number | undefined): string;
+/** Encode a rendered canvas without expanding its bytes into a data URL. */
+export declare function encodeCanvasToBlob(canvas: CanvasEncoder, format: string | undefined, quality: number | undefined): Promise<Blob>;