@liquid-glass-forge/dom 0.0.0-stage → 0.1.0-rc.2

package/dist/host.js

@@ -0,0 +1,244 @@
+import { createSource, MAX_PIXELS } from '@liquid-glass-forge/core';
+export class HostError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'HostError';
+    }
+}
+const owners = new WeakMap();
+const materialValid = (value) => value === 'glass' || value === 'opaque';
+/** Own only a decorative target and explicitly touched host styles. Never move semantic children. */
+export function mountGlassHost(element, options = {}) {
+    const doc = element?.ownerDocument, view = doc?.defaultView;
+    if (!view || !(element instanceof view.HTMLElement) ||
+        ['IMG', 'INPUT', 'CANVAS', 'VIDEO', 'AUDIO', 'TEXTAREA', 'SELECT', 'IFRAME', 'BR', 'HR', 'LINK', 'META'].includes(element.tagName) ||
+        ['inline', 'contents'].includes(view.getComputedStyle(element).display))
+        throw new HostError('INVALID_HOST', 'Expected an HTML block or inline-block container');
+    const position = view.getComputedStyle(element).position;
+    const needsPosition = !position || position === 'static';
+    if (owners.has(element))
+        throw new HostError('INVALID_HOST', 'Element already has a glass host');
+    if (!materialValid(options.material ?? 'glass'))
+        throw new HostError('INVALID_HOST', 'Invalid material');
+    const supplied = options.target !== undefined;
+    const target = options.target ?? doc.createElement('canvas');
+    if (!(target instanceof view.HTMLCanvasElement) || (supplied && target.parentElement !== element)) {
+        throw new HostError('INVALID_HOST', 'Supplied target must be a dedicated canvas child of the host');
+    }
+    const originalWidth = target.width, originalHeight = target.height;
+    let originalPixels;
+    let context = null;
+    if (supplied) {
+        if (originalWidth * originalHeight > MAX_PIXELS)
+            throw new HostError('INVALID_HOST', 'Supplied backing exceeds core pixel bound');
+        try {
+            context = target.getContext('2d', { colorSpace: 'srgb', willReadFrequently: true });
+            if (!context)
+                throw new Error('Canvas2D unavailable');
+            if (originalWidth && originalHeight)
+                originalPixels = context.getImageData(0, 0, originalWidth, originalHeight);
+        }
+        catch (cause) {
+            throw new HostError('UNAVAILABLE_HOST', 'Supplied target must have a readable 2D backing', { cause });
+        }
+    }
+    const originalStyleAttributes = new Map([[element, element.getAttribute('style')], [target, target.getAttribute('style')]]);
+    const undo = [];
+    const styleRecords = new Map();
+    const style = (node, key, value) => {
+        let records = styleRecords.get(node.style);
+        if (!records) {
+            records = new Map();
+            styleRecords.set(node.style, records);
+        }
+        let record = records.get(key);
+        if (!record) {
+            record = { value: node.style.getPropertyValue(key), priority: node.style.getPropertyPriority(key), ownedValue: '', ownedPriority: '' };
+            records.set(key, record);
+            const saved = record;
+            undo.push(() => {
+                if (node.style.getPropertyValue(key) !== saved.ownedValue || node.style.getPropertyPriority(key) !== saved.ownedPriority)
+                    return;
+                if (saved.value)
+                    node.style.setProperty(key, saved.value, saved.priority);
+                else
+                    node.style.removeProperty(key);
+            });
+        }
+        node.style.setProperty(key, value);
+        record.ownedValue = node.style.getPropertyValue(key);
+        record.ownedPriority = node.style.getPropertyPriority(key);
+    };
+    const attrRecords = new Map();
+    const attr = (key, value) => {
+        let record = attrRecords.get(key);
+        if (!record) {
+            record = { value: target.getAttribute(key), owned: value };
+            attrRecords.set(key, record);
+            const saved = record;
+            undo.push(() => { if (target.getAttribute(key) === saved.owned) {
+                if (saved.value === null)
+                    target.removeAttribute(key);
+                else
+                    target.setAttribute(key, saved.value);
+            } });
+        }
+        target.setAttribute(key, value);
+        record.owned = value;
+    };
+    const token = (node, name) => {
+        if (!node.classList.contains(name)) {
+            const hadClass = node.hasAttribute('class');
+            node.classList.add(name);
+            undo.push(() => { node.classList.remove(name); if (!node.className && !hadClass)
+                node.removeAttribute('class'); });
+        }
+    };
+    let disposed = false, ownedWidth = target.width, ownedHeight = target.height, backingTouched = false;
+    let presentationImage;
+    const alive = () => { if (disposed)
+        throw new HostError('DISPOSED', 'Host is disposed'); };
+    const restore = () => {
+        if (backingTouched && target.width === ownedWidth && target.height === ownedHeight) {
+            target.width = supplied ? originalWidth : 0;
+            target.height = supplied ? originalHeight : 0;
+            if (supplied && originalPixels)
+                target.getContext('2d')?.putImageData(originalPixels, 0, 0);
+        }
+        originalPixels = undefined;
+        presentationImage = undefined;
+        for (const release of undo.reverse()) {
+            try {
+                release();
+            }
+            catch { /* Continue releasing independent ownership. */ }
+        }
+        for (const [node, text] of originalStyleAttributes) {
+            const expected = doc.createElement('div').style;
+            expected.cssText = text ?? '';
+            const keys = new Set([...Array.from(node.style), ...Array.from(expected)]);
+            if ([...keys].every(key => node.style.getPropertyValue(key) === expected.getPropertyValue(key) && node.style.getPropertyPriority(key) === expected.getPropertyPriority(key))) {
+                if (text === null)
+                    node.removeAttribute('style');
+                else
+                    node.setAttribute('style', text);
+            }
+            if (text === null && node.style.cssText === '' && node.getAttribute('style') !== null)
+                node.removeAttribute('style');
+        }
+        if (!supplied)
+            target.remove();
+        context = null;
+        owners.delete(element);
+    };
+    const host = Object.freeze({
+        element, target,
+        measure() { alive(); return Object.freeze({ width: element.clientWidth, height: element.clientHeight }); },
+        setMaterial(material) {
+            alive();
+            if (!materialValid(material))
+                throw new HostError('INVALID_HOST', 'Invalid material');
+            attr('data-lgf-material', material);
+            style(target, 'background-color', material === 'opaque' ? 'Canvas' : 'var(--lgf-tint, rgba(245,248,255,0.78))');
+            const filter = material === 'opaque' ? 'none' : 'blur(var(--lgf-blur, 12px)) saturate(1.1)';
+            style(target, 'backdrop-filter', filter);
+            style(target, '-webkit-backdrop-filter', filter);
+        },
+        prepareCanvas(width, height) {
+            alive();
+            if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width < 1 || height < 1 || width * height > MAX_PIXELS)
+                throw new HostError('INVALID_PIXELS', 'Invalid native canvas size');
+            context ??= target.getContext('2d', { colorSpace: 'srgb', willReadFrequently: true });
+            if (!context)
+                throw new HostError('UNAVAILABLE_HOST', 'Canvas2D unavailable');
+            ownedWidth = width;
+            ownedHeight = height;
+            backingTouched = true;
+            presentationImage = undefined;
+            if (target.width !== width)
+                target.width = width;
+            if (target.height !== height)
+                target.height = height;
+            return target;
+        },
+        present(pixels) {
+            alive();
+            if ('presentedTarget' in pixels) {
+                if (pixels.presentedTarget !== target || target.width !== pixels.width || target.height !== pixels.height || pixels.width !== ownedWidth || pixels.height !== ownedHeight || !backingTouched)
+                    throw new HostError('INVALID_PIXELS', 'Unprepared native presentation');
+                return;
+            }
+            if ('canvas' in pixels) {
+                const canvas = pixels.canvas, frameView = canvas?.ownerDocument?.defaultView;
+                if (!frameView || !(canvas instanceof frameView.HTMLCanvasElement) || canvas === target || canvas.width !== pixels.width || canvas.height !== pixels.height)
+                    throw new HostError('INVALID_PIXELS', 'Invalid canvas frame');
+                host.prepareCanvas(pixels.width, pixels.height);
+                if (typeof context.reset === 'function')
+                    context.reset();
+                else
+                    target.width = pixels.width;
+                context.globalCompositeOperation = 'copy';
+                context.imageSmoothingEnabled = false;
+                context.drawImage(canvas, 0, 0);
+                return;
+            }
+            try {
+                createSource({ contractVersion: 1, width: pixels.width, height: pixels.height, data: pixels.data, revision: 0, ownership: 'borrowed', colorSpace: 'srgb', alphaMode: 'straight' });
+            }
+            catch (cause) {
+                throw new HostError('INVALID_PIXELS', 'Expected bounded RGBA8 output', { cause });
+            }
+            context ??= target.getContext('2d', { colorSpace: 'srgb', willReadFrequently: true });
+            if (!context)
+                throw new HostError('UNAVAILABLE_HOST', 'Canvas2D is unavailable');
+            if (target.width !== pixels.width)
+                target.width = pixels.width;
+            if (target.height !== pixels.height)
+                target.height = pixels.height;
+            ownedWidth = pixels.width;
+            ownedHeight = pixels.height;
+            backingTouched = true;
+            if (!presentationImage || presentationImage.width !== pixels.width || presentationImage.height !== pixels.height) {
+                presentationImage = context.createImageData(pixels.width, pixels.height);
+            }
+            presentationImage.data.set(pixels.data);
+            context.putImageData(presentationImage, 0, 0);
+        },
+        clear() { alive(); presentationImage = undefined; target.width = 0; target.height = 0; ownedWidth = 0; ownedHeight = 0; backingTouched = true; },
+        dispose() { if (disposed)
+            return; disposed = true; restore(); }
+    });
+    try {
+        token(element, 'lgf-host');
+        token(target, 'lgf-surface');
+        if (needsPosition) {
+            style(element, 'position', 'relative');
+            for (const key of ['top', 'right', 'bottom', 'left'])
+                style(element, key, 'auto');
+        }
+        style(element, 'isolation', 'isolate');
+        for (const [key, value] of Object.entries({ display: 'block', 'box-sizing': 'border-box', 'margin-top': '0px', 'margin-right': '0px', 'margin-bottom': '0px', 'margin-left': '0px', 'border-width': '0px', padding: '0px', position: 'absolute', top: '0px', right: '0px', bottom: '0px', left: '0px', width: '100%', height: '100%', 'pointer-events': 'none', 'z-index': '-1', 'border-radius': 'inherit' }))
+            style(target, key, value);
+        attr('aria-hidden', 'true');
+        attr('role', 'presentation');
+        attr('tabindex', '-1');
+        host.setMaterial(options.material ?? 'glass');
+        if (!supplied) {
+            target.width = 0;
+            target.height = 0;
+            ownedWidth = 0;
+            ownedHeight = 0;
+            backingTouched = true;
+            element.prepend(target);
+        }
+        owners.set(element, host);
+        return host;
+    }
+    catch (cause) {
+        disposed = true;
+        restore();
+        throw cause;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './providers.js';
+export * from './mapping.js';
+export * from './host.js';
+export * from './scene.js';
+export * from './cpu.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './providers.js';
+export * from './mapping.js';
+export * from './host.js';
+export * from './scene.js';
+export * from './cpu.js';

package/dist/mapping.d.ts

@@ -0,0 +1,60 @@
+export interface Size {
+    readonly width: number;
+    readonly height: number;
+}
+export interface Rect extends Size {
+    readonly x: number;
+    readonly y: number;
+}
+export interface AxisTransform {
+    readonly a: number;
+    readonly b: number;
+    readonly c: number;
+    readonly d: number;
+    readonly e: number;
+    readonly f: number;
+}
+export interface MappingInput {
+    readonly source: Size;
+    /** Untransformed content box. x/y are viewport coordinates of its local origin. */
+    readonly box: Rect;
+    /** Desired output rectangle in viewport CSS pixels, including any clipped area. */
+    readonly target: Rect;
+    readonly fit?: 'fill' | 'contain' | 'cover' | 'none' | 'scale-down';
+    /** Fractions of remaining space, plus local CSS pixel offsets; not a CSS string parser. */
+    readonly position?: {
+        readonly x: number;
+        readonly y: number;
+        readonly offsetX?: number;
+        readonly offsetY?: number;
+    };
+    /** Additional viewport clip. The content box also clips the painted object. */
+    readonly clip?: Rect;
+    /** Extra intrinsic source pixels around the visible sample, clamped to its bounds. */
+    readonly padding?: number;
+    readonly dpr?: number;
+    /** local -> viewport: box.origin + (a*x + e, d*y + f). Origin adjustments belong in e/f. */
+    readonly transform?: AxisTransform;
+}
+export type MappingResult = Readonly<{
+    ok: true;
+    /** Padded crop, suitable for a core source crop. */
+    crop: Rect;
+    /** Unpadded visible sample in intrinsic source coordinates. */
+    sample: Rect;
+    /** Sample origin relative to crop, so padding never stretches the visible output. */
+    sampleOffset: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    /** Visible output region within backing, in backing pixels; may be fractional. */
+    output: Rect;
+    backing: Size;
+    visible: Rect;
+}> | Readonly<{
+    ok: false;
+    code: 'INVALID_GEOMETRY' | 'UNSUPPORTED_TRANSFORM' | 'EMPTY_CLIP';
+    message: string;
+}>;
+/** Pure geometry; callers supply fresh viewport boxes on scroll/resize. No DOM capture. */
+export declare function mapSourceRegion(input: MappingInput): MappingResult;

package/dist/mapping.js

@@ -0,0 +1,92 @@
+import { MAX_PIXELS } from '@liquid-glass-forge/core';
+const frozenRect = (r) => Object.freeze(r);
+const fail = (code, message) => Object.freeze({ ok: false, code, message });
+const positive = (n) => Number.isFinite(n) && n > 0;
+function validRect(r) {
+    return !!r && Number.isFinite(r.x) && Number.isFinite(r.y) && positive(r.width) && positive(r.height) &&
+        Number.isFinite(r.x + r.width) && Number.isFinite(r.y + r.height);
+}
+function intersection(a, b) {
+    const x = Math.max(a.x, b.x), y = Math.max(a.y, b.y);
+    return { x, y, width: Math.max(0, Math.min(a.x + a.width, b.x + b.width) - x),
+        height: Math.max(0, Math.min(a.y + a.height, b.y + b.height) - y) };
+}
+/** Pure geometry; callers supply fresh viewport boxes on scroll/resize. No DOM capture. */
+export function mapSourceRegion(input) {
+    if (!input || !input.source || !Number.isSafeInteger(input.source.width) || !Number.isSafeInteger(input.source.height) ||
+        !positive(input.source.width) || !positive(input.source.height) || input.source.width * input.source.height > MAX_PIXELS ||
+        !validRect(input.box) || !validRect(input.target) || (input.clip !== undefined && !validRect(input.clip))) {
+        return fail('INVALID_GEOMETRY', 'Expected bounded intrinsic dimensions and finite positive viewport rectangles');
+    }
+    const { source, box, target } = input;
+    const t = input.transform ?? { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 };
+    if (![t.a, t.b, t.c, t.d, t.e, t.f].every(Number.isFinite) || t.a <= 0 || t.d <= 0 || t.b !== 0 || t.c !== 0 ||
+        Object.keys(t).some(key => !['a', 'b', 'c', 'd', 'e', 'f'].includes(key))) {
+        return fail('UNSUPPORTED_TRANSFORM', 'Only finite positive axis scale and translation are supported');
+    }
+    const dpr = input.dpr ?? 1, padding = input.padding ?? 0;
+    const position = input.position ?? { x: 0.5, y: 0.5 };
+    if (!positive(dpr) || !Number.isFinite(padding) || padding < 0 ||
+        ![position.x, position.y, position.offsetX ?? 0, position.offsetY ?? 0].every(Number.isFinite)) {
+        return fail('INVALID_GEOMETRY', 'Expected finite position, nonnegative source padding and positive DPR');
+    }
+    const backing = { width: Math.round(target.width * dpr), height: Math.round(target.height * dpr) };
+    if (!Number.isSafeInteger(backing.width) || !Number.isSafeInteger(backing.height) || backing.width < 1 || backing.height < 1 ||
+        backing.width * backing.height > MAX_PIXELS)
+        return fail('INVALID_GEOMETRY', 'Output backing exceeds the core pixel limit');
+    let width, height;
+    const contain = Math.min(box.width / source.width, box.height / source.height);
+    switch (input.fit ?? 'fill') {
+        case 'fill':
+            width = box.width;
+            height = box.height;
+            break;
+        case 'contain':
+            width = source.width * contain;
+            height = source.height * contain;
+            break;
+        case 'cover': {
+            const scale = Math.max(box.width / source.width, box.height / source.height);
+            width = source.width * scale;
+            height = source.height * scale;
+            break;
+        }
+        case 'none':
+            width = source.width;
+            height = source.height;
+            break;
+        case 'scale-down':
+            width = source.width * Math.min(1, contain);
+            height = source.height * Math.min(1, contain);
+            break;
+        default: return fail('INVALID_GEOMETRY', 'Unsupported object-fit');
+    }
+    const object = { x: box.x + t.e + ((box.width - width) * position.x + (position.offsetX ?? 0)) * t.a,
+        y: box.y + t.f + ((box.height - height) * position.y + (position.offsetY ?? 0)) * t.d,
+        width: width * t.a, height: height * t.d };
+    const viewportBox = { x: box.x + t.e, y: box.y + t.f, width: box.width * t.a, height: box.height * t.d };
+    if (!validRect(object) || !validRect(viewportBox))
+        return fail('INVALID_GEOMETRY', 'Transformed geometry overflow');
+    let visible = intersection(intersection(target, object), viewportBox);
+    if (input.clip)
+        visible = intersection(visible, input.clip);
+    if (visible.width <= 0 || visible.height <= 0)
+        return fail('EMPTY_CLIP', 'No readable source intersects the target');
+    const clampX = (x) => Math.min(source.width, Math.max(0, x));
+    const clampY = (y) => Math.min(source.height, Math.max(0, y));
+    const x = clampX((visible.x - object.x) / object.width * source.width);
+    const y = clampY((visible.y - object.y) / object.height * source.height);
+    const right = clampX((visible.x + visible.width - object.x) / object.width * source.width);
+    const bottom = clampY((visible.y + visible.height - object.y) / object.height * source.height);
+    const sample = { x, y, width: right - x, height: bottom - y };
+    if (sample.width <= 0 || sample.height <= 0)
+        return fail('EMPTY_CLIP', 'Source intersection has no representable area');
+    const cropX = clampX(x - padding), cropY = clampY(y - padding);
+    const crop = { x: cropX, y: cropY, width: clampX(right + padding) - cropX, height: clampY(bottom + padding) - cropY };
+    const output = { x: (visible.x - target.x) / target.width * backing.width,
+        y: (visible.y - target.y) / target.height * backing.height,
+        width: visible.width / target.width * backing.width, height: visible.height / target.height * backing.height };
+    return Object.freeze({ ok: true, crop: frozenRect(crop), sample: frozenRect(sample),
+        sampleOffset: Object.freeze({ x: x - cropX, y: y - cropY }), output: frozenRect(output),
+        backing: Object.freeze(backing), visible: frozenRect(visible) });
+}

package/dist/providers.d.ts

@@ -0,0 +1,58 @@
+import { type PixelBytes, type PixelSource } from '@liquid-glass-forge/core';
+export type SourceErrorCode = 'INVALID_SOURCE' | 'UNSUPPORTED_SOURCE' | 'UNREADABLE_SOURCE' | 'UNAVAILABLE_SOURCE' | 'DECODE_FAILED' | 'ABORTED' | 'TIMEOUT' | 'SUPERSEDED' | 'PAUSED' | 'DESTROYED';
+export declare class SourceError extends Error {
+    readonly code: SourceErrorCode;
+    constructor(code: SourceErrorCode, message: string, options?: ErrorOptions);
+}
+export type SourceSpec = {
+    readonly kind: 'pixels';
+    readonly width: number;
+    readonly height: number;
+    readonly data: PixelBytes;
+} | {
+    readonly kind: 'image-data';
+    readonly value: ImageData;
+} | {
+    readonly kind: 'bitmap';
+    readonly value: ImageBitmap;
+} | {
+    readonly kind: 'canvas';
+    readonly value: HTMLCanvasElement | OffscreenCanvas;
+} | {
+    readonly kind: 'video';
+    readonly value: HTMLVideoElement;
+} | {
+    readonly kind: 'image';
+    readonly url: string;
+    readonly crossOrigin?: 'anonymous' | 'use-credentials' | 'none';
+};
+export interface SourceSnapshot {
+    readonly source: PixelSource;
+    readonly generation: number;
+    readonly revision: number;
+}
+export interface SourceProviderOptions {
+    readonly timeoutMs?: number;
+}
+/** Explicit borrowed inputs; read() returns a fresh owned snapshot. Latest read wins. */
+export declare class SourceProvider {
+    #private;
+    constructor(spec: SourceSpec, options?: SourceProviderOptions);
+    get generation(): number;
+    get revision(): number;
+    get state(): 'ready' | 'paused' | 'destroyed';
+    /** Observe invalidation, not pixel delivery. Exceptions from listeners are isolated. */
+    subscribe(listener: () => void): () => void;
+    replace(spec: SourceSpec): void;
+    invalidate(): void;
+    pause(): void;
+    resume(): void;
+    destroy(): void;
+    read(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<SourceSnapshot>;
+    /** Full synchronous RGBA8 capture into caller-owned storage; never transferred or retained. */
+    readInto(target: PixelBytes, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<SourceSnapshot>;
+}