@sharedex/ui 0.0.0-stage → 0.9.0

package/dist/backgrounds/runtime/scroll.js

@@ -0,0 +1,25 @@
+// ---------------------------------------------------------------------------
+// Scroll progress of a background's box through the viewport. Pure (tested);
+// the hook in hooks.ts measures the box and writes the result as CSS variables.
+// ---------------------------------------------------------------------------
+/** Where scroll effects rest: on the server, before the first measure, and under reduced motion `still`. */
+export const RESTING_SCROLL = { progress: 0.5, exit: 0 };
+const clamp01 = (n) => (n <= 0 ? 0 : n > 1 ? 1 : n); // <= also turns -0 into 0
+/** `top` and `height` of the box (from getBoundingClientRect) and the viewport height, all px. */
+export function scrollProgress(top, height, viewport) {
+    const travel = viewport + height;
+    return {
+        progress: travel > 0 ? clamp01((viewport - top) / travel) : RESTING_SCROLL.progress,
+        exit: height > 0 ? clamp01(-top / height) : RESTING_SCROLL.exit,
+    };
+}
+/**
+ * The layer variables a scroll effect reads: `--sx-bg-p` (the chosen progress,
+ * 0–1) and `--sx-bg-p0` (its resting value, so `p - p0` is 0 at rest). The
+ * fallbacks are the resting values, so server HTML renders the resting frame.
+ */
+export function scrollVars(range) {
+    return range === "exit"
+        ? { "--sx-bg-p": `var(--sx-scroll-exit, ${RESTING_SCROLL.exit})`, "--sx-bg-p0": RESTING_SCROLL.exit }
+        : { "--sx-bg-p": `var(--sx-scroll, ${RESTING_SCROLL.progress})`, "--sx-bg-p0": RESTING_SCROLL.progress };
+}

package/dist/backgrounds/runtime/tier.d.ts

@@ -0,0 +1,26 @@
+import type { DeviceTier, EffectTier } from "../types.js";
+export interface TierSignals {
+    /** navigator.hardwareConcurrency (undefined when hidden). */
+    readonly cores?: number;
+    /** navigator.deviceMemory in GB (Chromium only). */
+    readonly memoryGb?: number;
+    /** A touch screen is the main input. */
+    readonly coarsePointer: boolean;
+    /** The user asked to save data. */
+    readonly saveData: boolean;
+    /** Highest WebGL version available: 0, 1 or 2. */
+    readonly webgl: 0 | 1 | 2;
+    /** UNMASKED_RENDERER_WEBGL, when the browser shares it. */
+    readonly renderer?: string;
+}
+/**
+ * Mobile GPUs strong enough for the `high` tier: Adreno 730 and up (Snapdragon 8 Gen 1 onwards; 710-725 are
+ * mid-range), Adreno 8xx, Arm Immortalis, Mali-G71x / G72x / G9xx (Dimensity 9000, Tensor G2 onwards), Samsung
+ * Xclipse 920 and up. iPhones report only "Apple GPU", so they keep the cautious `mid`.
+ */
+export declare const FLAGSHIP_MOBILE_GPU: RegExp;
+export declare function classifyTier(s: TierSignals): DeviceTier;
+/** Whether an effect of `tier` runs on a device of `device`. */
+export declare function tierAllows(device: DeviceTier, tier: EffectTier): boolean;
+/** Browser only. */
+export declare function readTierSignals(): TierSignals;

package/dist/backgrounds/runtime/tier.js

@@ -0,0 +1,72 @@
+// ---------------------------------------------------------------------------
+// Device tier: what this device can carry. `classifyTier` is pure (tested);
+// `readTierSignals` reads the browser.
+//
+// The browser exposes little, so this is a cautious guess. Touch devices top
+// out at `mid`: a phone that claims many cores may still be a budget phone, and
+// a wrong "high" costs battery and heat. The exception is a phone whose GPU
+// names a flagship family (`FLAGSHIP_MOBILE_GPU`): measured on a Galaxy S23
+// Ultra (Adreno 740, 2026-11-07), every high-tier effect held 60 fps forced on.
+// Pass `quality` to override.
+// ---------------------------------------------------------------------------
+const SOFTWARE_GPU = /swiftshader|llvmpipe|software|basic render/i;
+/**
+ * Mobile GPUs strong enough for the `high` tier: Adreno 730 and up (Snapdragon 8 Gen 1 onwards; 710-725 are
+ * mid-range), Adreno 8xx, Arm Immortalis, Mali-G71x / G72x / G9xx (Dimensity 9000, Tensor G2 onwards), Samsung
+ * Xclipse 920 and up. iPhones report only "Apple GPU", so they keep the cautious `mid`.
+ */
+export const FLAGSHIP_MOBILE_GPU = /adreno\D{0,8}(7[3-9]\d|[89]\d\d)\b|immortalis|mali-g(7[12]\d|9\d\d)\b|xclipse\s*9[2-9]\d/i;
+export function classifyTier(s) {
+    if (s.saveData || s.webgl === 0)
+        return "low";
+    if (s.renderer && SOFTWARE_GPU.test(s.renderer))
+        return "low";
+    if (s.memoryGb !== undefined && s.memoryGb <= 2)
+        return "low";
+    const cores = s.cores ?? 4;
+    if (cores <= 2)
+        return "low";
+    const memoryCap = s.memoryGb !== undefined && s.memoryGb <= 4 ? "mid" : "high";
+    if (s.coarsePointer) {
+        if (cores < 6 || s.webgl !== 2)
+            return "low";
+        return cores >= 8 && s.renderer && FLAGSHIP_MOBILE_GPU.test(s.renderer) ? memoryCap : "mid";
+    }
+    if (cores >= 8 && s.webgl === 2)
+        return memoryCap;
+    return "mid";
+}
+const DEVICE_RANK = { low: 0, mid: 1, high: 2 };
+const EFFECT_RANK = { all: 0, mid: 1, high: 2 };
+/** Whether an effect of `tier` runs on a device of `device`. */
+export function tierAllows(device, tier) {
+    return DEVICE_RANK[device] >= EFFECT_RANK[tier];
+}
+/** Browser only. */
+export function readTierSignals() {
+    const nav = navigator;
+    let webgl = 0;
+    let renderer;
+    try {
+        const canvas = document.createElement("canvas");
+        const gl = canvas.getContext("webgl2") ?? canvas.getContext("webgl");
+        if (gl) {
+            webgl = typeof WebGL2RenderingContext !== "undefined" && gl instanceof WebGL2RenderingContext ? 2 : 1;
+            const info = gl.getExtension("WEBGL_debug_renderer_info");
+            if (info)
+                renderer = String(gl.getParameter(info.UNMASKED_RENDERER_WEBGL));
+            gl.getExtension("WEBGL_lose_context")?.loseContext();
+        }
+    }
+    catch {
+        webgl = 0;
+    }
+    return {
+        cores: nav.hardwareConcurrency || undefined,
+        memoryGb: nav.deviceMemory,
+        coarsePointer: matchMedia("(pointer: coarse)").matches,
+        saveData: nav.connection?.saveData === true,
+        webgl,
+        ...(renderer ? { renderer } : {}),
+    };
+}

package/dist/backgrounds/runtime/webgl.d.ts

@@ -0,0 +1,81 @@
+import type { GpuContext, GpuFrame, GpuProgram, UniformValue } from "../types.js";
+/** The uniforms every one-pass shader gets without declaring them. */
+export declare const STANDARD_UNIFORMS: readonly ["u_time", "u_resolution", "u_dpr", "u_pointer", "u_pointer_in", "u_rtl"];
+/** Prepended to every one-pass effect's fragment source. */
+export declare const FRAGMENT_HEADER = "#ifdef GL_FRAGMENT_PRECISION_HIGH\nprecision highp float;\n#else\nprecision mediump float;\n#endif\nvarying vec2 v_uv;\nuniform float u_time;\nuniform vec2 u_resolution;\nuniform float u_dpr;\nuniform vec2 u_pointer;\nuniform float u_pointer_in;\nuniform float u_rtl;\n";
+/** One triangle larger than the screen covers every pixel with no diagonal seam. */
+export declare const FULLSCREEN_VERTEX = "attribute vec2 a_pos;\nvarying vec2 v_uv;\nvoid main() {\n  v_uv = a_pos * 0.5 + 0.5;\n  gl_Position = vec4(a_pos, 0.0, 1.0);\n}";
+/** Names of the uniforms a GLSL source declares. */
+export declare function declaredUniforms(source: string): string[];
+/** Names of the `u_…` identifiers a GLSL source reads. */
+export declare function usedUniforms(source: string): string[];
+/** Thrown when the device cannot run an effect (no WebGL, a missing extension, a failed compile); the host shows the fallback. */
+export declare class WebglUnavailable extends Error {
+}
+export interface Linked {
+    readonly program: WebGLProgram;
+    /** Cached uniform location (null when the compiler optimised it away). */
+    loc(name: string): WebGLUniformLocation | null;
+    dispose(): void;
+}
+/**
+ * Compiles and links. `attribs` are bound to locations 0, 1, 2 … in order, so
+ * a shared buffer can be bound without looking locations up.
+ */
+export declare function link(gl: GpuContext, vertex: string, fragment: string, attribs?: readonly string[]): Linked;
+export declare function setUniform(gl: GpuContext, where: WebGLUniformLocation | null, value: UniformValue): void;
+/** The full-screen triangle, as attribute 0. */
+export declare function fullscreenTriangle(gl: GpuContext): {
+    draw(): void;
+    dispose(): void;
+};
+/** A texture you can render into. */
+export interface Target {
+    readonly texture: WebGLTexture;
+    readonly fbo: WebGLFramebuffer;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * A render target. `float` needs WebGL2 + EXT_color_buffer_float (half-float
+ * RGBA, filterable in WebGL2); without it, plain 8-bit RGBA. Throws
+ * `WebglUnavailable` when the framebuffer cannot be completed.
+ */
+export declare function createTarget(gl: GpuContext, width: number, height: number, opts?: {
+    float?: boolean;
+    linear?: boolean;
+}): Target;
+export declare function disposeTarget(gl: GpuContext, target: Target): void;
+/** Two targets read from one, written to the other, then swapped: state that carries over between frames. */
+export interface PingPong {
+    readonly read: Target;
+    readonly write: Target;
+    swap(): void;
+    dispose(): void;
+}
+export declare function pingPong(gl: GpuContext, width: number, height: number, opts?: {
+    float?: boolean;
+    linear?: boolean;
+}): PingPong;
+/** Draw into `target` (or the canvas when null) at its full size. */
+export declare function renderTo(gl: GpuContext, target: Target | null, width: number, height: number): void;
+/** Bind `texture` to texture unit `unit` and point the sampler uniform at it. */
+export declare function bindTexture(gl: GpuContext, where: WebGLUniformLocation | null, texture: WebGLTexture, unit: number): void;
+/** WebGL2 with half-float render targets, or `WebglUnavailable`. */
+export declare function requireFloatTargets(gl: GpuContext): WebGL2RenderingContext;
+interface FragmentState {
+    readonly linked: Linked;
+    readonly triangle: {
+        draw(): void;
+        dispose(): void;
+    };
+    readonly colorLocs: readonly (WebGLUniformLocation | null)[];
+}
+/**
+ * One fragment shader over the whole layer. The effect's own uniforms are set
+ * once (an option change rebuilds the program); the standard ones per frame.
+ */
+export declare function fragmentProgram(fragment: string, uniforms: Readonly<Record<string, UniformValue>>, colorCount: number): GpuProgram<FragmentState>;
+/** A frame with neutral input, for warm-up and tests. */
+export declare function idleFrame(over?: Partial<GpuFrame>): GpuFrame;
+export {};

package/dist/backgrounds/runtime/webgl.js

@@ -0,0 +1,250 @@
+// ---------------------------------------------------------------------------
+// WebGL building blocks. Most effects are one fragment shader over one
+// triangle that covers the layer (`fragmentProgram`): that is all the atlas's
+// "Three.js shader" rows actually use Three.js for, so this replaces ~160 KB
+// with a few KB. Effects that need more (passes, simulation state, meshes)
+// write a GpuProgram with the helpers below.
+//
+// `declaredUniforms` / `usedUniforms` are pure (tests check every shader's
+// uniforms against what its effect feeds it); the rest needs a browser.
+// ---------------------------------------------------------------------------
+/** The uniforms every one-pass shader gets without declaring them. */
+export const STANDARD_UNIFORMS = ["u_time", "u_resolution", "u_dpr", "u_pointer", "u_pointer_in", "u_rtl"];
+/** Prepended to every one-pass effect's fragment source. */
+export const FRAGMENT_HEADER = `#ifdef GL_FRAGMENT_PRECISION_HIGH
+precision highp float;
+#else
+precision mediump float;
+#endif
+varying vec2 v_uv;
+uniform float u_time;
+uniform vec2 u_resolution;
+uniform float u_dpr;
+uniform vec2 u_pointer;
+uniform float u_pointer_in;
+uniform float u_rtl;
+`;
+/** One triangle larger than the screen covers every pixel with no diagonal seam. */
+export const FULLSCREEN_VERTEX = `attribute vec2 a_pos;
+varying vec2 v_uv;
+void main() {
+  v_uv = a_pos * 0.5 + 0.5;
+  gl_Position = vec4(a_pos, 0.0, 1.0);
+}`;
+/** Names of the uniforms a GLSL source declares. */
+export function declaredUniforms(source) {
+    return [...source.matchAll(/\buniform\s+\w+\s+([\w\s,[\]]+?)\s*;/g)].flatMap((m) => (m[1] ?? "").split(",").map((n) => n.trim().replace(/\[\d+\]$/, "")));
+}
+/** Names of the `u_…` identifiers a GLSL source reads. */
+export function usedUniforms(source) {
+    const body = source.replace(/\buniform\s+\w+\s+[\w\s,[\]]+;/g, "");
+    return [...new Set([...body.matchAll(/\bu_\w+/g)].map((m) => m[0]))];
+}
+/** Thrown when the device cannot run an effect (no WebGL, a missing extension, a failed compile); the host shows the fallback. */
+export class WebglUnavailable extends Error {
+}
+/**
+ * Compiles and links. `attribs` are bound to locations 0, 1, 2 … in order, so
+ * a shared buffer can be bound without looking locations up.
+ */
+export function link(gl, vertex, fragment, attribs = ["a_pos"]) {
+    const compile = (type, source) => {
+        const shader = gl.createShader(type);
+        if (!shader)
+            throw new WebglUnavailable("could not create a shader");
+        gl.shaderSource(shader, source);
+        gl.compileShader(shader);
+        if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS) && !gl.isContextLost()) {
+            const log = gl.getShaderInfoLog(shader) ?? "";
+            gl.deleteShader(shader);
+            throw new WebglUnavailable(`shader did not compile: ${log}`);
+        }
+        return shader;
+    };
+    const vs = compile(gl.VERTEX_SHADER, vertex);
+    const fs = compile(gl.FRAGMENT_SHADER, fragment);
+    const program = gl.createProgram();
+    if (!program)
+        throw new WebglUnavailable("could not create a program");
+    gl.attachShader(program, vs);
+    gl.attachShader(program, fs);
+    attribs.forEach((name, i) => gl.bindAttribLocation(program, i, name));
+    gl.linkProgram(program);
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS) && !gl.isContextLost()) {
+        throw new WebglUnavailable(`program did not link: ${gl.getProgramInfoLog(program) ?? ""}`);
+    }
+    const cache = new Map();
+    return {
+        program,
+        loc(name) {
+            if (!cache.has(name))
+                cache.set(name, gl.getUniformLocation(program, name));
+            return cache.get(name) ?? null;
+        },
+        dispose() {
+            gl.deleteProgram(program);
+            gl.deleteShader(vs);
+            gl.deleteShader(fs);
+        },
+    };
+}
+export function setUniform(gl, where, value) {
+    if (!where)
+        return; // declared but optimised away: nothing to set
+    if (typeof value === "number")
+        gl.uniform1f(where, value);
+    else if (value.length === 2)
+        gl.uniform2f(where, value[0], value[1]);
+    else if (value.length === 3)
+        gl.uniform3f(where, value[0], value[1], value[2]);
+    else
+        gl.uniform4f(where, value[0], value[1], value[2], value[3]);
+}
+/** The full-screen triangle, as attribute 0. */
+export function fullscreenTriangle(gl) {
+    const buffer = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
+    return {
+        draw() {
+            gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+            gl.enableVertexAttribArray(0);
+            gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);
+            gl.drawArrays(gl.TRIANGLES, 0, 3);
+        },
+        dispose() {
+            gl.deleteBuffer(buffer);
+        },
+    };
+}
+/**
+ * A render target. `float` needs WebGL2 + EXT_color_buffer_float (half-float
+ * RGBA, filterable in WebGL2); without it, plain 8-bit RGBA. Throws
+ * `WebglUnavailable` when the framebuffer cannot be completed.
+ */
+export function createTarget(gl, width, height, opts = {}) {
+    const texture = gl.createTexture();
+    const fbo = gl.createFramebuffer();
+    if (!texture || !fbo)
+        throw new WebglUnavailable("could not create a render target");
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    const filter = opts.linear === false ? gl.NEAREST : gl.LINEAR;
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    if (opts.float) {
+        const gl2 = gl;
+        gl2.texImage2D(gl2.TEXTURE_2D, 0, gl2.RGBA16F, width, height, 0, gl2.RGBA, gl2.HALF_FLOAT, null);
+    }
+    else {
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+    }
+    gl.bindFramebuffer(gl.FRAMEBUFFER, fbo);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texture, 0);
+    const complete = gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE;
+    gl.viewport(0, 0, width, height);
+    gl.clearColor(0, 0, 0, 0);
+    gl.clear(gl.COLOR_BUFFER_BIT);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    if (!complete)
+        throw new WebglUnavailable("render target is not supported on this device");
+    return { texture, fbo, width, height };
+}
+export function disposeTarget(gl, target) {
+    gl.deleteTexture(target.texture);
+    gl.deleteFramebuffer(target.fbo);
+}
+export function pingPong(gl, width, height, opts = {}) {
+    let a = createTarget(gl, width, height, opts);
+    let b = createTarget(gl, width, height, opts);
+    return {
+        get read() {
+            return a;
+        },
+        get write() {
+            return b;
+        },
+        swap() {
+            [a, b] = [b, a];
+        },
+        dispose() {
+            disposeTarget(gl, a);
+            disposeTarget(gl, b);
+        },
+    };
+}
+/** Draw into `target` (or the canvas when null) at its full size. */
+export function renderTo(gl, target, width, height) {
+    gl.bindFramebuffer(gl.FRAMEBUFFER, target ? target.fbo : null);
+    gl.viewport(0, 0, target ? target.width : width, target ? target.height : height);
+}
+/** Bind `texture` to texture unit `unit` and point the sampler uniform at it. */
+export function bindTexture(gl, where, texture, unit) {
+    gl.activeTexture(gl.TEXTURE0 + unit);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    if (where)
+        gl.uniform1i(where, unit);
+}
+/** WebGL2 with half-float render targets, or `WebglUnavailable`. */
+export function requireFloatTargets(gl) {
+    if (typeof WebGL2RenderingContext === "undefined" || !(gl instanceof WebGL2RenderingContext)) {
+        throw new WebglUnavailable("WebGL2 is not available");
+    }
+    if (!gl.getExtension("EXT_color_buffer_float") && !gl.getExtension("EXT_color_buffer_half_float")) {
+        throw new WebglUnavailable("float render targets are not available");
+    }
+    return gl;
+}
+/**
+ * One fragment shader over the whole layer. The effect's own uniforms are set
+ * once (an option change rebuilds the program); the standard ones per frame.
+ */
+export function fragmentProgram(fragment, uniforms, colorCount) {
+    return {
+        api: "webgl",
+        warmup: 0,
+        init(gl) {
+            const linked = link(gl, FULLSCREEN_VERTEX, FRAGMENT_HEADER + fragment);
+            const triangle = fullscreenTriangle(gl);
+            gl.useProgram(linked.program);
+            for (const [name, value] of Object.entries(uniforms))
+                setUniform(gl, linked.loc(name), value);
+            return { linked, triangle, colorLocs: Array.from({ length: colorCount }, (_, i) => linked.loc(`u_c${i}`)) };
+        },
+        frame(gl, state, f) {
+            const { linked } = state;
+            renderTo(gl, null, f.width, f.height);
+            gl.useProgram(linked.program);
+            setUniform(gl, linked.loc("u_time"), f.time);
+            setUniform(gl, linked.loc("u_resolution"), [f.width, f.height]);
+            setUniform(gl, linked.loc("u_dpr"), f.dpr);
+            setUniform(gl, linked.loc("u_pointer"), f.pointer);
+            setUniform(gl, linked.loc("u_pointer_in"), f.pointerIn ? 1 : 0);
+            setUniform(gl, linked.loc("u_rtl"), f.rtl ? 1 : 0);
+            state.colorLocs.forEach((where, i) => setUniform(gl, where, f.colors[i] ?? [0, 0, 0, 1]));
+            state.triangle.draw();
+        },
+        dispose(gl, state) {
+            state.triangle.dispose();
+            state.linked.dispose();
+        },
+    };
+}
+/** A frame with neutral input, for warm-up and tests. */
+export function idleFrame(over = {}) {
+    return {
+        time: 0,
+        delta: 1 / 60,
+        width: 1,
+        height: 1,
+        dpr: 1,
+        pointer: [0.5, 0.5],
+        pointerIn: false,
+        taps: [],
+        rtl: false,
+        coarse: false,
+        colors: [],
+        ...over,
+    };
+}