@liquid-glass-forge/react 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,29 @@
-# Temporary Holding Version
+# Liquid Glass Forge React
 
-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`. Pinned peers: React and React DOM **19.3.1**.
+Framework peers are imported, never bundled into this package. The ESM entry
+retains `use client` for Next.js client boundaries and has public JSX declarations.
+
+Import `GlassSurface`, `GlassSceneProvider` and `useGlassSurface` from
+`@liquid-glass-forge/react`. Import `@liquid-glass-forge/dom/styles.css` in the
+application for the server/no-JavaScript material baseline. No stylesheet is
+injected by JavaScript.
+
+`GlassSurface` renders a stable div, decorative canvas and ordinary children.
+It forwards the div ref, including callback-ref cleanup. Without a provider it
+uses CSS material. A provider accepts an explicit `source`/`renderer` pair,
+`paused`, `timeoutMs` and `onError`; multiple children share one scene.
+Source or renderer identity changes replace the scene. Keep these objects stable
+between intentional replacements. The caller owns these reusable objects;
+effect cleanup releases scene resources without terminally disposing them.
+
+`useGlassSurface({material})` returns `ref`, `targetRef` and `invalidate`. Render
+the target as a dedicated direct canvas child with the decorative CSS class,
+material data attribute, `aria-hidden`, presentation role and negative tab index.
+React owns both DOM nodes. Do not concurrently control canvas backing dimensions
+or draw into its context while mounted.
+
+See repository `docs/PHASE-7.md` for usage, Strict Mode ownership, exact Vite/Next
+consumer evidence and remaining integration limits. No registry package is published.

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import type { HTMLAttributes, ReactNode, RefCallback } from 'react';
+import type { GlassScene, GlassMaterial, GlassRenderer, SceneSource } from '@liquid-glass-forge/dom';
+export interface GlassSceneProviderProps {
+    readonly children?: ReactNode;
+    readonly source?: SceneSource;
+    readonly renderer?: GlassRenderer;
+    readonly timeoutMs?: number;
+    readonly paused?: boolean;
+    readonly onError?: (error: unknown) => void;
+}
+/** Caller owns source/renderer objects. Each effect owns one engine lifetime. */
+export declare function GlassSceneProvider({ children, source, renderer, timeoutMs, paused, onError }: GlassSceneProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<{
+    readonly scene: GlassScene | null;
+} | null>>;
+export interface UseGlassSurfaceOptions {
+    readonly material?: GlassMaterial;
+}
+export interface GlassSurfaceBinding {
+    readonly ref: RefCallback<HTMLElement>;
+    readonly targetRef: RefCallback<HTMLCanvasElement>;
+    readonly invalidate: () => void;
+}
+/** Supply a dedicated direct canvas child. React retains both DOM nodes. */
+export declare function useGlassSurface({ material }?: UseGlassSurfaceOptions): GlassSurfaceBinding;
+export interface GlassSurfaceProps extends HTMLAttributes<HTMLDivElement>, UseGlassSurfaceOptions {
+    readonly children?: ReactNode;
+}
+/** Stable server/client markup; no DOM access or engine allocation in render. */
+export declare const GlassSurface: import("react").ForwardRefExoticComponent<GlassSurfaceProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/index.js

@@ -0,0 +1,90 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, createElement, forwardRef, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { createGlassScene } from '@liquid-glass-forge/dom';
+const SceneContext = createContext(null);
+/** Caller owns source/renderer objects. Each effect owns one engine lifetime. */
+export function GlassSceneProvider({ children, source, renderer, timeoutMs, paused = false, onError }) {
+    const [scene, setScene] = useState(null);
+    const error = useRef(onError);
+    const pausedRef = useRef(paused);
+    useEffect(() => { error.current = onError; pausedRef.current = paused; }, [onError, paused]);
+    useEffect(() => {
+        const next = createGlassScene({ ...(source ? { source } : {}), ...(renderer ? { renderer } : {}),
+            ...(timeoutMs === undefined ? {} : { timeoutMs }), onError: cause => error.current?.(cause) });
+        if (pausedRef.current)
+            next.pause();
+        setScene(next);
+        return () => { next.dispose(); setScene(null); };
+    }, [source, renderer, timeoutMs]);
+    useEffect(() => {
+        if (!scene || scene.state === 'destroyed')
+            return;
+        if (paused)
+            scene.pause();
+        else if (scene.state === 'paused')
+            scene.resume();
+    }, [scene, paused]);
+    const value = useMemo(() => ({ scene }), [scene]);
+    return createElement(SceneContext.Provider, { value }, children);
+}
+/** Supply a dedicated direct canvas child. React retains both DOM nodes. */
+export function useGlassSurface({ material = 'glass' } = {}) {
+    const shared = useContext(SceneContext);
+    const [element, setElement] = useState(null);
+    const [target, setTarget] = useState(null);
+    const attachment = useRef(null);
+    const materialRef = useRef(material);
+    useEffect(() => { materialRef.current = material; }, [material]);
+    const ref = useCallback((node) => { setElement(node); }, []);
+    const targetRef = useCallback((node) => { setTarget(node); }, []);
+    useEffect(() => {
+        if (!element || !target || (shared && !shared.scene))
+            return;
+        const owned = shared ? null : createGlassScene();
+        const scene = shared?.scene ?? owned;
+        if (scene.state === 'destroyed')
+            return;
+        let current;
+        try {
+            current = scene.attach(element, { target, material: materialRef.current });
+        }
+        catch (cause) {
+            owned?.dispose();
+            throw cause;
+        }
+        attachment.current = current;
+        return () => {
+            if (attachment.current === current)
+                attachment.current = null;
+            current.dispose();
+            owned?.dispose();
+        };
+    }, [element, target, shared?.scene, !!shared]);
+    useEffect(() => { attachment.current?.update({ material }); }, [material]);
+    const invalidate = useCallback(() => { attachment.current?.invalidate(); }, []);
+    return useMemo(() => ({ ref, targetRef, invalidate }), [ref, targetRef, invalidate]);
+}
+/** Stable server/client markup; no DOM access or engine allocation in render. */
+export const GlassSurface = forwardRef(function GlassSurface({ children, material = 'glass', className, ...attributes }, forwardedRef) {
+    const binding = useGlassSurface({ material });
+    const ref = useCallback((node) => {
+        binding.ref(node);
+        if (typeof forwardedRef === 'function') {
+            // ForwardedRef retains its legacy void signature; public RefCallback supports cleanup.
+            const cleanup = forwardedRef(node);
+            if (node)
+                return () => { binding.ref(null); if (typeof cleanup === 'function')
+                    cleanup();
+                else
+                    forwardedRef(null); };
+        }
+        else if (forwardedRef) {
+            forwardedRef.current = node;
+            if (node)
+                return () => { binding.ref(null); forwardedRef.current = null; };
+        }
+        return undefined;
+    }, [binding.ref, forwardedRef]);
+    return _jsxs("div", { ...attributes, className: ['lgf-host', className].filter(Boolean).join(' '), ref: ref, children: [_jsx("canvas", { className: "lgf-surface", "data-lgf-material": material, "aria-hidden": "true", role: "presentation", tabIndex: -1, ref: binding.targetRef }), children] });
+});

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@liquid-glass-forge/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-rc.1",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@liquid-glass-forge/dom": "0.1.0-rc.1"
+  },
+  "peerDependencies": {
+    "react": "19.3.1",
+    "react-dom": "19.3.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/namipsg/liquid-glass-forge.git",
+    "directory": "packages/react"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}