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

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,34 @@
-# Temporary Holding Version
+# @liquid-glass-forge/webgl
 
-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.
+WebGL2 glass refraction and a shared atlas for compositing optical surfaces.
+
+[![A live glass lens bends the lettering beneath it](https://raw.githubusercontent.com/namipsg/liquid-glass-forge/main/docs/assets/glass-playground.gif)](https://namipsg.github.io/liquid-glass-forge/#playground)
+
+[Live showcase](https://namipsg.github.io/liquid-glass-forge/#playground) · [Examples](https://namipsg.github.io/liquid-glass-forge/examples.html) · [Documentation](https://github.com/namipsg/liquid-glass-forge/blob/main/docs/PHASE-6.md) · [Support](https://namipsg.github.io/liquid-glass-forge/support.html) · [Install by framework](https://github.com/namipsg/liquid-glass-forge/blob/main/docs/QUICKSTART.md)
+
+## Install
+
+```sh
+npm install @liquid-glass-forge/webgl@0.1.0-rc.2
+```
+
+Keep the Forge packages at matching versions. This is an experimental preview.
+The [support guide](https://namipsg.github.io/liquid-glass-forge/support.html) describes browser and device qualification.
+
+## Usage
+
+Experimental preview package, `0.1.0-rc.2`. Shared persistent WebGL2 atlas,
+versioned optics, GPU blur and synchronous Canvas2D tile presentation.
+
+Use `WebGLAtlas` from `@liquid-glass-forge/webgl` for owned Canvas2D targets.
+Use `createWebGLRenderer` or `createOpticalRenderer` from
+`@liquid-glass-forge/webgl/dom` with the vanilla host. Import and construction
+allocate no browser resources. Forced modes never downgrade; auto requires an
+explicit `none`, `cpu` or `material` fallback policy. Dispose renderers and release
+standalone canvas frames. The caller owns source bytes and supplied targets.
+
+Core scenes retain 16-host / 4-million-pixel bounds. The direct atlas accepts up
+to 50 small tiles under aggregate pixel, texture-size and image-memory bounds.
+Nonzero GPU blur requires renderable float buffers. No production GPU readback.
+Performance support is limited to named measured workloads. See the repository
+`docs/PHASE-6.md` for API, source ownership, recovery and measured scope.

package/dist/atlas.d.ts

@@ -0,0 +1,111 @@
+import type { PixelSource, SurfaceInput } from '@liquid-glass-forge/core';
+import { type WebGLEffects } from './effects.js';
+export declare class WebGLError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+export declare const WEBGL_ATTRIBUTES: Readonly<{
+    alpha: true;
+    premultipliedAlpha: true;
+    preserveDrawingBuffer: false;
+    antialias: false;
+    depth: false;
+    stencil: false;
+}>;
+export interface WebGLAtlasOptions {
+    readonly maxBytes?: number;
+    readonly maxRestores?: number;
+    readonly canvasFactory?: () => HTMLCanvasElement;
+}
+export interface WebGLTile {
+    readonly surface: SurfaceInput;
+    readonly target: HTMLCanvasElement;
+}
+export interface WebGLUpdate {
+    readonly generation?: number;
+    readonly revision?: number;
+    readonly dirtyIds?: readonly string[];
+    readonly effects?: WebGLEffects;
+    readonly signal?: AbortSignal;
+}
+export declare function webglContextPoolDiagnostics(): Readonly<{
+    contexts: number;
+    leased: number;
+    idle: number;
+    cap: 4;
+}>;
+export declare function releaseIdleWebGLContexts(): void;
+/** Persistent atlas. update() finishes GPU→default framebuffer→Canvas2D copies
+ * synchronously, before returning. Callers own target canvases and source bytes. */
+export declare class WebGLAtlas {
+    #private;
+    constructor(options?: WebGLAtlasOptions);
+    get context(): WebGL2RenderingContext | undefined;
+    get diagnostics(): Readonly<{
+        backend: 'webgl';
+        contextType: "webgl2";
+        state: "disposed" | "lost" | "new" | "ready" | "unavailable";
+        failure: string | undefined;
+        restores: number;
+        handleGeneration: number;
+        width: number;
+        height: number;
+        sourceWidth: number;
+        sourceHeight: number;
+        renderCount: number;
+        batchCount: number;
+        uploadCount: number;
+        targetBytes: number;
+        requestedAttributes: Readonly<{
+            alpha: true;
+            premultipliedAlpha: true;
+            preserveDrawingBuffer: false;
+            antialias: false;
+            depth: false;
+            stencil: false;
+        }>;
+        attributes: WebGLContextAttributes | null | undefined;
+        pool: Readonly<{
+            contexts: number;
+            leased: number;
+            idle: number;
+            cap: 4;
+        }>;
+        resources: Readonly<{
+            contexts: 0 | 1;
+            textures: number;
+            framebuffers: number;
+            programs: number;
+            shaders: number;
+            buffers: 0;
+            vertexArrays: 0;
+        }>;
+        ownedImageBytes: number;
+        lastBatch: Readonly<{
+            dirty: number;
+            gpuSnapshots: number;
+            uploadMs: number;
+            drawMs: number;
+            snapshotMs: number;
+            copyMs: number;
+            batchMs: number;
+            completedAt: readonly number[];
+        }>;
+        sourceDecoding: "calibrated-srgb-texture" | "explicit-shader";
+        decodeProbeMaxByteError: number | undefined;
+        colorConvention: "straight sRGB upload; manual linear-premultiplied sampling/blur; calibrated premultiplied sRGB byte presentation";
+        storageProfile: "nearest" | "upward";
+    }>;
+    initialize(): void;
+    dispose(): void;
+    update(source: PixelSource, entries: readonly WebGLTile[], options?: WebGLUpdate): Readonly<{
+        dirty: number;
+        gpuSnapshots: number;
+        uploadMs: number;
+        drawMs: number;
+        snapshotMs: number;
+        copyMs: number;
+        batchMs: number;
+        completedAt: readonly number[];
+    }>;
+}