@liquid-glass-forge/vue 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,46 @@
-# Temporary Holding Version
+# <img src="https://raw.githubusercontent.com/namipsg/liquid-glass-forge/main/showcase/public/frameworks/vue.svg" width="20" height="20" alt=""> @liquid-glass-forge/vue
 
-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.
+Integrate Forge scenes and glass surfaces into Vue.
+
+[Live showcase](https://namipsg.github.io/liquid-glass-forge/?framework=vue#developers) · [Examples](https://namipsg.github.io/liquid-glass-forge/examples.html) · [Documentation](https://github.com/namipsg/liquid-glass-forge/blob/main/docs/PHASE-8.md) · [Support](https://namipsg.github.io/liquid-glass-forge/support.html)
+
+## Install in Vue
+
+```sh
+npm install @liquid-glass-forge/vue@next @liquid-glass-forge/dom@next
+```
+
+The starter uses CSS glass and expects Vue 3.5.44. Keep the Forge packages at matching versions.
+The [live installer](https://namipsg.github.io/liquid-glass-forge/?framework=vue#developers)
+shows verified exact versions and has a copy button.
+
+[Open the Vue starter](https://github.com/namipsg/liquid-glass-forge/blob/main/docs/QUICKSTART.md#vue) · [Add WebGL refraction](https://github.com/namipsg/liquid-glass-forge/blob/main/docs/QUICKSTART.md#add-webgl-refraction)
+
+[![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/?framework=vue#developers)
+
+## Usage
+
+Experimental preview `0.1.0-rc.2`. The pinned Vue peer is **3.5.44**.
+Vue remains external; the package ships ESM and declarations without bundling it.
+
+Import `GlassSurface`, `GlassSceneProvider` and `useGlassSurface` from
+`@liquid-glass-forge/vue`. Import `@liquid-glass-forge/dom/styles.css` in the
+application for server and no-JavaScript material. JavaScript injects no stylesheet.
+
+`GlassSurface` renders a div, a decorative canvas and ordinary default-slot
+content. Native HTML attributes/events are forwarded to the div. A component ref
+exposes `element`, `target` and `invalidate` (see `GlassSurfaceHandle`). Without a
+provider the surface uses CSS/opaque material.
+
+A provider accepts a `source`/`renderer` pair, `paused`, `timeoutMs` and `onError`.
+It owns one shared scene and borrows reusable source/renderer objects. Mount and
+activation start/resume it; deactivation pauses it; unmount disposes it. Source or
+renderer identity changes replace the scene. Inactive changes wait for activation.
+
+`useGlassSurface({material})` accepts a material value, ref or getter and returns
+`element`, `target` shallow refs plus `invalidate`. Render the target as a dedicated
+direct canvas child with decorative class/attributes. Vue owns both nodes. Do not
+control its backing dimensions or draw into its context while attached.
+
+See the [integration guide](https://github.com/namipsg/liquid-glass-forge/blob/main/docs/PHASE-8.md) for ownership, KeepAlive, exact Vite/Nuxt consumer
+verification and remaining limits.

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import type { HTMLAttributes, MaybeRefOrGetter, PropType, ShallowRef } from 'vue';
+import type { GlassMaterial, GlassRenderer, SceneSource } from '@liquid-glass-forge/dom';
+/** Caller owns source/renderer descriptors. This provider owns engine lifetimes. */
+export declare const GlassSceneProvider: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    source: PropType<SceneSource>;
+    renderer: PropType<GlassRenderer>;
+    timeoutMs: NumberConstructor;
+    paused: BooleanConstructor;
+    onError: PropType<(error: unknown) => void>;
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>[] | undefined, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    source: PropType<SceneSource>;
+    renderer: PropType<GlassRenderer>;
+    timeoutMs: NumberConstructor;
+    paused: BooleanConstructor;
+    onError: PropType<(error: unknown) => void>;
+}>> & Readonly<{}>, {
+    paused: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export interface UseGlassSurfaceOptions {
+    readonly material?: MaybeRefOrGetter<GlassMaterial>;
+}
+export interface GlassSurfaceBinding {
+    readonly element: ShallowRef<HTMLElement | null>;
+    readonly target: ShallowRef<HTMLCanvasElement | null>;
+    readonly invalidate: () => void;
+}
+/** Setup-only composable. Supply a dedicated direct canvas child owned by Vue. */
+export declare function useGlassSurface(options?: UseGlassSurfaceOptions): GlassSurfaceBinding;
+export interface GlassSurfaceHandle {
+    readonly element: HTMLElement | null;
+    readonly target: HTMLCanvasElement | null;
+    readonly invalidate: () => void;
+}
+export interface GlassSurfaceProps extends HTMLAttributes {
+    readonly material?: GlassMaterial;
+}
+/** Stable server/client markup. Native attributes/events and slots remain Vue-owned. */
+export declare const GlassSurface: import("vue").DefineSetupFnComponent<GlassSurfaceProps, {}, {}, GlassSurfaceProps & {}, import("vue").PublicProps>;

package/dist/index.js

@@ -0,0 +1,101 @@
+import { defineComponent, h, inject, mergeProps, onActivated, onBeforeUnmount, onDeactivated, onMounted, provide, shallowRef, toRaw, toValue, watch } from 'vue';
+import { createGlassScene } from '@liquid-glass-forge/dom';
+const SceneKey = Symbol('LiquidGlassForgeScene');
+/** Caller owns source/renderer descriptors. This provider owns engine lifetimes. */
+export const GlassSceneProvider = defineComponent({
+    name: 'GlassSceneProvider',
+    props: {
+        source: Object,
+        renderer: Object,
+        timeoutMs: Number,
+        paused: Boolean,
+        onError: Function,
+    },
+    setup(props, { slots }) {
+        const scene = shallowRef(null);
+        provide(SceneKey, { scene });
+        let mounted = false, active = false, dirty = true;
+        const retire = () => { const old = scene.value; scene.value = null; old?.dispose(); };
+        const start = () => {
+            if (!mounted || !active)
+                return;
+            if (dirty || !scene.value) {
+                retire();
+                const next = createGlassScene({
+                    ...(props.source ? { source: toRaw(props.source) } : {}),
+                    ...(props.renderer ? { renderer: toRaw(props.renderer) } : {}),
+                    ...(props.timeoutMs === undefined ? {} : { timeoutMs: props.timeoutMs }),
+                    onError: cause => props.onError?.(cause),
+                });
+                if (props.paused)
+                    next.pause();
+                scene.value = next;
+                dirty = false;
+            }
+            else if (!props.paused && scene.value.state === 'paused')
+                scene.value.resume();
+        };
+        watch(() => [props.source, props.renderer, props.timeoutMs], () => { dirty = true; retire(); start(); }, { flush: 'post' });
+        watch(() => props.paused, paused => { if (paused)
+            scene.value?.pause();
+        else
+            start(); }, { flush: 'post' });
+        onMounted(() => { mounted = active = true; start(); });
+        onActivated(() => { active = true; start(); });
+        onDeactivated(() => { active = false; scene.value?.pause(); });
+        onBeforeUnmount(() => { mounted = active = false; retire(); });
+        return () => slots.default?.();
+    },
+});
+/** Setup-only composable. Supply a dedicated direct canvas child owned by Vue. */
+export function useGlassSurface(options = {}) {
+    const shared = inject(SceneKey, null);
+    const element = shallowRef(null), target = shallowRef(null);
+    let boundElement = null, boundTarget = null, boundScene = null;
+    let active = false, attachment = null, owned = null;
+    const material = () => options.material === undefined ? 'glass' : toValue(options.material);
+    const detach = () => { attachment?.dispose(); attachment = null; boundElement = boundTarget = null; boundScene = null; };
+    const attach = () => {
+        if (!active || !element.value || !target.value) {
+            detach();
+            return;
+        }
+        if (!shared && !owned)
+            owned = createGlassScene();
+        const scene = shared ? shared.scene.value : owned;
+        if (!scene || scene.state === 'destroyed') {
+            detach();
+            return;
+        }
+        if (attachment && boundScene === scene && boundElement === element.value && boundTarget === target.value)
+            return;
+        detach();
+        if (owned?.state === 'paused')
+            owned.resume();
+        attachment = scene.attach(element.value, { target: target.value, material: material() });
+        boundElement = element.value;
+        boundTarget = target.value;
+        boundScene = scene;
+    };
+    watch([element, target, () => shared?.scene.value], attach, { flush: 'post' });
+    watch(material, value => attachment?.update({ material: value }), { flush: 'post' });
+    onMounted(() => { active = true; attach(); });
+    onActivated(() => { if (active)
+        return; active = true; attach(); });
+    onDeactivated(() => { active = false; detach(); owned?.pause(); });
+    onBeforeUnmount(() => { active = false; detach(); owned?.dispose(); owned = null; });
+    return { element, target, invalidate: () => attachment?.invalidate() };
+}
+/** Stable server/client markup. Native attributes/events and slots remain Vue-owned. */
+export const GlassSurface = defineComponent((props, { attrs, slots, expose }) => {
+    const material = () => props.material ?? 'glass';
+    const binding = useGlassSurface({ material });
+    expose({ get element() { return binding.element.value; }, get target() { return binding.target.value; }, invalidate: binding.invalidate });
+    return () => h('div', mergeProps(attrs, { class: 'lgf-host', ref: binding.element }), [
+        h('canvas', { class: 'lgf-surface', 'data-lgf-material': material(), 'aria-hidden': 'true', role: 'presentation', tabindex: -1, ref: binding.target }),
+        ...(slots.default?.() ?? []),
+    ]);
+}, {
+    name: 'GlassSurface', inheritAttrs: false,
+    props: { material: { type: String, default: 'glass' } },
+});

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@liquid-glass-forge/vue",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-rc.2",
+  "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.2"
+  },
+  "peerDependencies": {
+    "vue": "3.5.44"
+  },
+  "homepage": "https://namipsg.github.io/liquid-glass-forge/?framework=vue#developers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/namipsg/liquid-glass-forge.git",
+    "directory": "packages/vue"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}