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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nami Poursafargholi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,7 @@
+Liquid Glass Forge
+Copyright (c) 2026 Nami Poursafargholi. MIT licensed.
+
+Independent implementation inspired by Apple's Liquid Glass design.
+Not affiliated with, sponsored by or endorsed by Apple Inc.
+Apple and its design/assets remain subject to their respective rights.
+No Apple assets or upstream Liquid Glass/Sileo implementation is included.

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# Liquid Glass Forge DOM sources
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Experimental preview. API and device/performance qualification remain open; iPad is unqualified.
+
+Experimental preview `0.1.0-rc.1` sources, coordinate mapping and vanilla host/lifecycle.
+Requires exact matching core/CPU package versions. ESM and TypeScript
+declarations are included; imports are SSR-safe and start no timers or network.
+
+```ts
+import { SourceProvider, mapSourceRegion, createGlassScene } from '@liquid-glass-forge/dom';
+const p = new SourceProvider({ kind: 'pixels', width: 1, height: 1,
+  data: new Uint8Array([255, 0, 0, 255]) });
+const snapshot = await p.read(); // independent, owned straight-sRGB RGBA8 bytes
+p.destroy();
+```
+
+Sources: explicit bytes, sRGB ImageData, borrowed ImageBitmap, decoded URL image,
+readable canvas/OffscreenCanvas, or borrowed HTMLVideoElement. Inputs remain
+caller-owned. Reads have bounded cancellation and latest-generation semantics.
+For explicit bytes or sRGB ImageData, `readInto(target)` copies every pixel into
+an attached caller-owned RGBA8 view of the exact size. It returns borrowed
+metadata and never transfers or retains the target; source/target aliasing is
+rejected. Reuse the target only after consumers have captured or finished it.
+The ordinary `read()` continues to return a fresh owned snapshot.
+Canvas drawing needs explicit invalidation; video subscription can observe frame
+revisions through a cancellable frame callback or bounded event/timer fallback.
+
+`mapSourceRegion` maps explicit viewport rectangles, object fit/position,
+source-pixel padding, clipping, DPR and positive axis scale/translation. It returns
+typed invalid/empty/unsupported results. Preserve sample/crop/output offsets;
+it does not parse arbitrary CSS or capture DOM.
+
+See the repository [source contract](https://github.com/namipsg/liquid-glass-forge/blob/main/docs/SOURCES.md)
+for full API semantics and limits. `createGlassScene()` mounts CSS/opaque material with bounded lifecycle and shared
+dirty/visibility scheduling. Load the `./styles.css` asset export; JavaScript imports
+inject no styles. `scene.attach(element)`, `ready`, `update`, `pause`, `resume` and
+`dispose` preserve native content and release owned resources. The optional
+source/renderer pair is a low-level adapter seam; `createCpuRenderer` supplies
+JavaScript CPU optics with optional workers, capped backing resolution and
+cancellable update pacing. See the project Phase 5 document for usage and
+source-bound performance/device qualification. A `surface(request)` callback
+can supply per-request radius, bevel and strength; values are validated and
+captured before asynchronous work. Diagnostics report effective optics, actual
+execution start, rate wait and presentation pacing. Active completion pacing is
+included in the documented service measurements; idle hosts schedule no work.
+See the [host contract](https://github.com/namipsg/liquid-glass-forge/blob/main/docs/HOSTS.md).
+Framework adapters and public browser-support tiers are outside this package.
+Performance claims are limited to the repository's measured workload/environment.

package/dist/cpu.d.ts

@@ -0,0 +1,85 @@
+import type { SourceRect } from '@liquid-glass-forge/core';
+import type { CpuEffects, CpuExecutorOptions, CpuTimings } from '@liquid-glass-forge/cpu';
+import type { FramePixels, GlassRenderer, RenderRequest } from './scene.js';
+export interface CpuSurfaceOptions {
+    readonly radius?: number;
+    readonly bevel?: number;
+    readonly strength?: number;
+}
+export interface CpuRendererOptions {
+    readonly executor?: CpuExecutorOptions;
+    /** Distances are measured in effective output backing pixels. */
+    readonly surface?: CpuSurfaceOptions | ((request: RenderRequest) => CpuSurfaceOptions);
+    readonly effects?: CpuEffects;
+    /** Omitted means sample the complete source. */
+    readonly sourceRect?: SourceRect | ((request: RenderRequest) => SourceRect);
+    readonly quality?: {
+        readonly maxPixels?: number;
+        readonly maxWidth?: number;
+        readonly maxHeight?: number;
+        readonly maxUpdatesPerSecond?: number;
+        readonly maxSourcePixels?: number;
+    };
+}
+/** One scene owns this adapter. Initialization owns resources; construction only snapshots data. */
+export declare class CpuRenderer implements GlassRenderer {
+    #private;
+    constructor(options?: CpuRendererOptions);
+    private executorDiagnostics;
+    get diagnostics(): Readonly<{
+        backend: 'cpu';
+        execution: "main" | "worker";
+        disposed: boolean;
+        initialized: boolean;
+        requested: Readonly<{
+            width: number;
+            height: number;
+        }> | undefined;
+        effective: Readonly<{
+            width: number;
+            height: number;
+        }> | undefined;
+        requestedWidth: number | undefined;
+        requestedHeight: number | undefined;
+        effectiveWidth: number | undefined;
+        effectiveHeight: number | undefined;
+        qualityReduced: boolean;
+        reasons: readonly string[];
+        quality: Required<{
+            readonly maxPixels?: number;
+            readonly maxWidth?: number;
+            readonly maxHeight?: number;
+            readonly maxUpdatesPerSecond?: number;
+            readonly maxSourcePixels?: number;
+        }>;
+        timings: (CpuTimings & {
+            readonly captureMs: number;
+            readonly rateWaitMs: number;
+            readonly presentationWaitMs: number;
+        }) | undefined;
+        surface: Readonly<Required<CpuSurfaceOptions>> | undefined;
+        executor: Readonly<{
+            execution: "main" | "worker";
+            inFlight: 0 | 1;
+            pending: 0 | 1;
+            mainCachedBytes: number;
+            workerCachedBytes: number;
+            sharedKernelBytes: number;
+            fixedKernelReservationBytes: number;
+            pooledBytes: number;
+            inputPooledBytes: number;
+            inputPooledBuffers: number;
+            leasedBytes: number;
+            reservedBytes: number;
+            lostBytes: number;
+            completedBatches: number;
+            discardedBatches: number;
+            disposed: boolean;
+            fallbackReason?: string;
+        }> | undefined;
+    }>;
+    initialize(signal: AbortSignal): () => void;
+    render(request: RenderRequest, signal: AbortSignal): Promise<FramePixels>;
+    dispose(): void;
+}
+export declare function createCpuRenderer(options?: CpuRendererOptions): CpuRenderer;

package/dist/cpu.js

@@ -0,0 +1,236 @@
+import { createFrame, MAX_PIXELS, validateSource } from '@liquid-glass-forge/core';
+import { CpuError, CpuExecutor, CpuDeadlineScheduler, snapshotCpuEffects } from '@liquid-glass-forge/cpu';
+function object(input, keys, name) {
+    if (!input || typeof input !== 'object' || Array.isArray(input) || Reflect.ownKeys(input).some(k => typeof k !== 'string' || !keys.includes(k))) {
+        throw new CpuError('INVALID_OPTIONS', `Invalid ${name}`);
+    }
+}
+function finite(value, low, high, name) {
+    if (!Number.isFinite(value) || value < low || value > high)
+        throw new CpuError('INVALID_OPTIONS', `Invalid ${name}`);
+}
+function sourceRect(input) {
+    object(input, ['x', 'y', 'width', 'height'], 'sourceRect');
+    finite(input.x, 0, MAX_PIXELS, 'sourceRect.x');
+    finite(input.y, 0, MAX_PIXELS, 'sourceRect.y');
+    finite(input.width, Number.MIN_VALUE, MAX_PIXELS, 'sourceRect.width');
+    finite(input.height, Number.MIN_VALUE, MAX_PIXELS, 'sourceRect.height');
+    return Object.freeze({ x: input.x, y: input.y, width: input.width, height: input.height });
+}
+function surfaceOptions(input) {
+    object(input, ['radius', 'bevel', 'strength'], 'surface');
+    if ('then' in input)
+        throw new CpuError('INVALID_OPTIONS', 'Surface options must be synchronous data');
+    if (input.radius !== undefined)
+        finite(input.radius, 0, 1_000_000, 'radius');
+    if (input.bevel !== undefined)
+        finite(input.bevel, Number.MIN_VALUE, 1_000_000, 'bevel');
+    if (input.strength !== undefined)
+        finite(input.strength, 0, 1_000_000, 'strength');
+    return Object.freeze({ ...input });
+}
+/** Floor after uniform scaling, then account for min-one rounding on very thin surfaces. */
+function boundedSize(width, height, q) {
+    const scale = Math.min(1, q.maxWidth / width, q.maxHeight / height, Math.sqrt(q.maxPixels / width / height));
+    let w = Math.max(1, Math.floor(width * scale)), h = Math.max(1, Math.floor(height * scale));
+    if (w * h > q.maxPixels) {
+        if (w >= h)
+            w = Math.max(1, Math.floor(q.maxPixels / h));
+        else
+            h = Math.max(1, Math.floor(q.maxPixels / w));
+    }
+    return Object.freeze({ width: w, height: h });
+}
+/** One scene owns this adapter. Initialization owns resources; construction only snapshots data. */
+export class CpuRenderer {
+    #executorOptions;
+    #surface;
+    #lastSurface;
+    #effects;
+    #sourceRect;
+    #quality;
+    #executor;
+    #pacer;
+    #cleanup;
+    #disposed = false;
+    #generation = 0;
+    #revision = 0;
+    #job;
+    #lastStart;
+    #lastReady;
+    #requested;
+    #effective;
+    #reasons = Object.freeze([]);
+    #timings;
+    #lastExecutor;
+    constructor(options = {}) {
+        object(options, ['executor', 'surface', 'effects', 'sourceRect', 'quality'], 'CPU renderer options');
+        const executor = options.executor === undefined ? {} : options.executor;
+        object(executor, ['cacheSources', 'worker', 'workerFactory', 'timeoutMs', 'maxPoolBytes', 'maxOwnedBytes'], 'executor options');
+        // CpuExecutor construction itself is data-only and is the canonical validator.
+        new CpuExecutor(executor);
+        this.#executorOptions = Object.freeze({ cacheSources: true, ...executor });
+        const surface = options.surface === undefined ? {} : options.surface;
+        this.#surface = typeof surface === 'function' ? surface : surfaceOptions(surface);
+        this.#effects = snapshotCpuEffects(options.effects);
+        this.#sourceRect = typeof options.sourceRect === 'function' || options.sourceRect === undefined ? options.sourceRect : sourceRect(options.sourceRect);
+        const quality = options.quality === undefined ? {} : options.quality;
+        object(quality, ['maxPixels', 'maxWidth', 'maxHeight', 'maxUpdatesPerSecond', 'maxSourcePixels'], 'quality');
+        const q = { maxPixels: quality.maxPixels === undefined ? 57600 : quality.maxPixels,
+            maxWidth: quality.maxWidth === undefined ? 320 : quality.maxWidth, maxHeight: quality.maxHeight === undefined ? 180 : quality.maxHeight,
+            maxUpdatesPerSecond: quality.maxUpdatesPerSecond === undefined ? 30 : quality.maxUpdatesPerSecond,
+            maxSourcePixels: quality.maxSourcePixels === undefined ? 230400 : quality.maxSourcePixels };
+        for (const key of ['maxPixels', 'maxWidth', 'maxHeight', 'maxSourcePixels']) {
+            finite(q[key], 1, MAX_PIXELS, key);
+            if (!Number.isSafeInteger(q[key]))
+                throw new CpuError('INVALID_OPTIONS', `${key} must be an integer`);
+        }
+        finite(q.maxUpdatesPerSecond, 1, 30, 'maxUpdatesPerSecond');
+        this.#quality = Object.freeze(q);
+    }
+    executorDiagnostics() { return this.#executor.diagnostics; }
+    get diagnostics() {
+        const executor = this.#executor?.diagnostics ?? this.#lastExecutor;
+        return Object.freeze({ backend: 'cpu', execution: executor?.execution ?? 'main', disposed: this.#disposed,
+            initialized: !!this.#executor, requested: this.#requested, effective: this.#effective,
+            requestedWidth: this.#requested?.width, requestedHeight: this.#requested?.height,
+            effectiveWidth: this.#effective?.width, effectiveHeight: this.#effective?.height,
+            qualityReduced: this.#reasons.length > 0, reasons: this.#reasons, quality: this.#quality,
+            timings: this.#timings, surface: this.#lastSurface, executor });
+    }
+    initialize(signal) {
+        if (this.#disposed)
+            throw new CpuError('DISPOSED', 'CPU renderer disposed');
+        if (signal.aborted)
+            throw new CpuError('ABORTED', 'CPU renderer initialization aborted');
+        this.#cleanup?.();
+        const executor = new CpuExecutor(this.#executorOptions), pacer = new CpuDeadlineScheduler(), generation = ++this.#generation;
+        this.#executor = executor;
+        this.#pacer = pacer;
+        this.#lastStart = undefined;
+        this.#lastReady = undefined;
+        let cleaned = false;
+        const cleanup = () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            signal.removeEventListener('abort', cleanup);
+            if (generation === this.#generation && this.#executor === executor) {
+                this.#generation++;
+                this.#job?.abort(new CpuError('ABORTED', 'CPU renderer initialization ended'));
+                this.#job = undefined;
+                this.#executor = undefined;
+                this.#pacer = undefined;
+                this.#cleanup = undefined;
+                this.#lastReady = undefined;
+            }
+            executor.dispose();
+            pacer.dispose();
+            this.#lastExecutor = executor.diagnostics;
+        };
+        this.#cleanup = cleanup;
+        signal.addEventListener('abort', cleanup, { once: true });
+        if (signal.aborted)
+            cleanup();
+        return cleanup;
+    }
+    async render(request, signal) {
+        if (this.#disposed)
+            throw new CpuError('DISPOSED', 'CPU renderer disposed');
+        const executor = this.#executor, pacer = this.#pacer, generation = this.#generation;
+        if (!executor || !pacer)
+            throw new CpuError('NOT_INITIALIZED', 'Initialize CPU renderer before rendering');
+        this.#job?.abort(new CpuError('SUPERSEDED', 'CPU render superseded'));
+        const controller = new AbortController();
+        this.#job = controller;
+        const abort = () => controller.abort(new CpuError('ABORTED', 'CPU render aborted'));
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted)
+            abort();
+        const current = () => {
+            if (controller.signal.aborted)
+                throw controller.signal.reason;
+            if (this.#disposed || generation !== this.#generation || executor !== this.#executor || this.#job !== controller)
+                throw new CpuError('STALE', 'CPU render no longer current');
+        };
+        try {
+            current();
+            if (!request || !Number.isSafeInteger(request.width) || !Number.isSafeInteger(request.height) || request.width < 1 || request.height < 1)
+                throw new CpuError('INVALID_OPTIONS', 'Invalid requested CPU dimensions');
+            validateSource(request.snapshot.source);
+            const source = request.snapshot.source;
+            if (source.width * source.height > this.#quality.maxSourcePixels)
+                throw new CpuError('SOURCE_LIMIT', 'CPU source exceeds maxSourcePixels');
+            const size = boundedSize(request.width, request.height, this.#quality), reasons = [];
+            if (request.width > this.#quality.maxWidth)
+                reasons.push('maxWidth');
+            if (request.height > this.#quality.maxHeight)
+                reasons.push('maxHeight');
+            if (request.width * request.height > this.#quality.maxPixels)
+                reasons.push('maxPixels');
+            const rect = typeof this.#sourceRect === 'function' ? sourceRect(this.#sourceRect(request)) : this.#sourceRect;
+            const surface = typeof this.#surface === 'function' ? surfaceOptions(this.#surface(request)) : this.#surface;
+            if (this.#revision === Number.MAX_SAFE_INTEGER)
+                throw new CpuError('INVALID_OPTIONS', 'CPU renderer revision exhausted');
+            const frame = createFrame({ contractVersion: 1, generation: request.snapshot.generation, revision: ++this.#revision, sourceRevision: source.revision,
+                surfaces: [{ id: 'cpu', ...size, ...surface, ...(rect === undefined ? {} : { sourceRect: rect }) }] }, source);
+            const effectiveSurface = frame.surfaces[0];
+            this.#lastSurface = Object.freeze({ radius: effectiveSurface.radius, bevel: effectiveSurface.bevel, strength: effectiveSurface.strength });
+            this.#requested = Object.freeze({ width: request.width, height: request.height });
+            this.#effective = size;
+            const period = 1000 / this.#quality.maxUpdatesPerSecond;
+            // Reserve measured computation time before the next presentation. Fast
+            // kernels should wait before execution instead of spending a whole frame
+            // in presentation smoothing. Source capture and cancellation stay owned.
+            const computeMargin = Math.min(period, Math.max(4, (this.#timings?.roundTripMs ?? 0) * 1.25 + 1));
+            const notBefore = this.#lastStart === undefined ? 0 : Math.max(this.#lastStart + period, (this.#lastReady ?? 0) + period - computeMargin);
+            const paceOutput = this.#lastStart !== undefined && performance.now() - this.#lastStart < 2000 / this.#quality.maxUpdatesPerSecond;
+            current();
+            this.#reasons = Object.freeze([...reasons]);
+            // The executor captures owned bytes synchronously before its deferred start.
+            // This avoids a second adapter snapshot during a rate wait.
+            const pending = executor.render(source, frame, {
+                ...(this.#effects === undefined ? {} : { effects: this.#effects }), signal: controller.signal, notBefore,
+                onStart: startedAt => { current(); this.#lastStart = startedAt; }
+            });
+            const batch = await pending;
+            try {
+                current();
+                // Keep completion cadence without an unconditional execution-relative
+                // delay. The next execution already reserves its measured compute time.
+                const presentationWaitMs = paceOutput && this.#lastReady !== undefined
+                    ? await pacer.waitUntil(this.#lastReady + period, controller.signal) : 0;
+                current();
+                const output = batch.surfaces[0], rateWaitMs = batch.timings.scheduledWaitMs ?? 0;
+                if (rateWaitMs > 0 || presentationWaitMs > 0)
+                    reasons.push('maxUpdatesPerSecond');
+                this.#reasons = Object.freeze(reasons);
+                this.#timings = Object.freeze({ ...batch.timings, captureMs: 0, rateWaitMs, presentationWaitMs });
+                this.#lastReady = performance.now();
+                return Object.freeze({ width: output.width, height: output.height, data: output.data, release: () => {
+                        batch.release();
+                        if (this.#executor !== executor && this.#generation === generation + 1)
+                            this.#lastExecutor = executor.diagnostics;
+                    } });
+            }
+            catch (cause) {
+                batch.release();
+                if (this.#executor !== executor && this.#generation === generation + 1)
+                    this.#lastExecutor = executor.diagnostics;
+                throw cause;
+            }
+        }
+        finally {
+            signal.removeEventListener('abort', abort);
+            if (this.#job === controller)
+                this.#job = undefined;
+        }
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#cleanup?.();
+    }
+}
+export function createCpuRenderer(options = {}) { return new CpuRenderer(options); }

package/dist/host.d.ts

@@ -0,0 +1,41 @@
+import { type PixelBytes } from '@liquid-glass-forge/core';
+export type GlassMaterial = 'glass' | 'opaque';
+export interface HostPixels {
+    readonly width: number;
+    readonly height: number;
+    readonly data: PixelBytes;
+}
+export interface HostCanvas {
+    readonly width: number;
+    readonly height: number;
+    readonly canvas: HTMLCanvasElement;
+}
+export interface HostPresented {
+    readonly width: number;
+    readonly height: number;
+    readonly presentedTarget: HTMLCanvasElement;
+}
+export type HostFrame = HostPixels | HostCanvas | HostPresented;
+export interface GlassHostOptions {
+    readonly target?: HTMLCanvasElement;
+    readonly material?: GlassMaterial;
+}
+export interface GlassHost {
+    readonly element: HTMLElement;
+    readonly target: HTMLCanvasElement;
+    measure(): Readonly<{
+        width: number;
+        height: number;
+    }>;
+    setMaterial(material: GlassMaterial): void;
+    prepareCanvas(width: number, height: number): HTMLCanvasElement;
+    present(pixels: HostFrame): void;
+    clear(): void;
+    dispose(): void;
+}
+export declare class HostError extends Error {
+    readonly code: 'INVALID_HOST' | 'INVALID_PIXELS' | 'UNAVAILABLE_HOST' | 'DISPOSED';
+    constructor(code: 'INVALID_HOST' | 'INVALID_PIXELS' | 'UNAVAILABLE_HOST' | 'DISPOSED', message: string, options?: ErrorOptions);
+}
+/** Own only a decorative target and explicitly touched host styles. Never move semantic children. */
+export declare function mountGlassHost(element: HTMLElement, options?: GlassHostOptions): GlassHost;