@pathscale/ui 1.2.9 → 1.2.11

package/dist/components/metal-border/engine/renderer/core.js

@@ -0,0 +1,156 @@
+import { CANONICAL_GL_SIZE, GL_DPR_CAP } from "../perfConfig.js";
+import { PRESETS } from "../presets.js";
+import { FRAG_SHADER_SRC, VERT_SHADER_SRC, compileShader, linkProgram } from "../shaders.js";
+const CANONICAL_PILL_W = 140;
+const CANONICAL_PILL_H = 40;
+const PILL_SHADER_SCALE = 1.6;
+const CIRCLE_SHADER_SCALE = 1.3;
+let SHARED = null;
+let _onContextRestored = null;
+function setContextRestoredCallback(cb) {
+    _onContextRestored = cb;
+}
+const UNIFORM_NAMES = [
+    "u_resolution",
+    "u_time",
+    "u_color1",
+    "u_color2",
+    "u_color3",
+    "u_color4",
+    "u_color5",
+    "u_color6",
+    "u_color7",
+    "u_alpha1",
+    "u_alpha2",
+    "u_alpha3",
+    "u_alpha4",
+    "u_alpha5",
+    "u_alpha6",
+    "u_alpha7",
+    "u_intensity",
+    "u_scale",
+    "u_direction",
+    "u_softness",
+    "u_distortion",
+    "u_complexity",
+    "u_shape",
+    "u_vignette",
+    "u_vigOpacity",
+    "u_blur",
+    "u_shaderOpacity"
+];
+function buildGLPipeline(gl) {
+    gl.enable(gl.BLEND);
+    gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+    const vert = compileShader(gl, gl.VERTEX_SHADER, VERT_SHADER_SRC);
+    const frag = compileShader(gl, gl.FRAGMENT_SHADER, FRAG_SHADER_SRC);
+    const program = linkProgram(gl, vert, frag);
+    gl.useProgram(program);
+    const buffer = gl.createBuffer();
+    if (!buffer) throw new Error("metal-fx: gl.createBuffer returned null");
+    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([
+        -1,
+        -1,
+        1,
+        -1,
+        -1,
+        1,
+        -1,
+        1,
+        1,
+        -1,
+        1,
+        1
+    ]), gl.STATIC_DRAW);
+    const posLoc = gl.getAttribLocation(program, "a_position");
+    gl.enableVertexAttribArray(posLoc);
+    gl.vertexAttribPointer(posLoc, 2, gl.FLOAT, false, 0, 0);
+    const uniforms = {};
+    for (const n of UNIFORM_NAMES)uniforms[n] = gl.getUniformLocation(program, n);
+    return {
+        program,
+        buffer,
+        uniforms
+    };
+}
+function ensureSharedRenderer() {
+    if (SHARED) return SHARED;
+    const dpr = Math.min(GL_DPR_CAP, "u" > typeof window ? window.devicePixelRatio || 1 : 1);
+    const size = Math.round(CANONICAL_GL_SIZE * dpr);
+    const useOffscreen = "u" > typeof OffscreenCanvas;
+    let glCanvas;
+    let gl;
+    if (useOffscreen) {
+        glCanvas = new OffscreenCanvas(size, size);
+        gl = glCanvas.getContext("webgl", {
+            alpha: true,
+            premultipliedAlpha: false,
+            antialias: false
+        });
+    } else {
+        const htmlCanvas = document.createElement("canvas");
+        htmlCanvas.width = size;
+        htmlCanvas.height = size;
+        gl = htmlCanvas.getContext("webgl", {
+            alpha: true,
+            premultipliedAlpha: false,
+            antialias: false,
+            preserveDrawingBuffer: true
+        }) ?? htmlCanvas.getContext("experimental-webgl");
+        glCanvas = htmlCanvas;
+    }
+    if (!gl) throw new Error("metal-fx: WebGL not supported");
+    const { program, buffer, uniforms } = buildGLPipeline(gl);
+    const onContextLost = (e)=>{
+        e.preventDefault();
+        if (SHARED) SHARED.contextLost = true;
+    };
+    const onContextRestored = ()=>{
+        if (!SHARED) return;
+        const rebuilt = buildGLPipeline(SHARED.gl);
+        SHARED.program = rebuilt.program;
+        SHARED.buffer = rebuilt.buffer;
+        SHARED.uniforms = rebuilt.uniforms;
+        SHARED.presetDirty = true;
+        SHARED.contextLost = false;
+        _onContextRestored?.();
+    };
+    glCanvas.addEventListener("webglcontextlost", onContextLost, false);
+    glCanvas.addEventListener("webglcontextrestored", onContextRestored, false);
+    SHARED = {
+        glCanvas,
+        gl,
+        program,
+        buffer,
+        uniforms,
+        preset: PRESETS.chromatic.modes.dark,
+        presetName: "chromatic",
+        presetTheme: "dark",
+        presetDirty: true,
+        contextLost: false,
+        useOffscreen,
+        startMs: performance.now(),
+        pausedMs: 0,
+        pausedAtMs: null,
+        rafId: 0,
+        dpr,
+        instances: new Set(),
+        frameCount: 0,
+        glowPixels: new Uint8Array(size * size * 4),
+        glowPixelsW: size,
+        glowPixelsH: size
+    };
+    return SHARED;
+}
+function teardownSharedRenderer() {
+    if (!SHARED) return;
+    const { gl, program, buffer } = SHARED;
+    try {
+        gl.deleteBuffer(buffer);
+        gl.deleteProgram(program);
+        gl.getExtension("WEBGL_lose_context")?.loseContext();
+    } catch  {}
+    SHARED = null;
+}
+export { CANONICAL_PILL_H, CANONICAL_PILL_W, CIRCLE_SHADER_SCALE, PILL_SHADER_SCALE, SHARED, ensureSharedRenderer, setContextRestoredCallback, teardownSharedRenderer };

package/dist/components/metal-border/engine/renderer/loop.d.ts

@@ -0,0 +1,30 @@
+import { type PresetName, type PresetTheme } from "../presets";
+import { type MetalFxInstance } from "./core";
+interface CreateInstanceOptions {
+    hostCanvas: HTMLCanvasElement;
+    cssWidth: number;
+    cssHeight: number;
+    cornerRadius: number;
+    kind: "pill" | "circle";
+    presetName: PresetName;
+    presetTheme: PresetTheme;
+    shaderScale?: number;
+    ringCssPx?: number;
+    opacityMul?: number;
+    paused?: boolean;
+    scale?: number;
+    onAfterFrame?: () => void;
+    onFirstCopy?: () => void;
+}
+export declare function createInstance(opts: CreateInstanceOptions): MetalFxInstance;
+export declare function destroyInstance(inst: MetalFxInstance): void;
+export declare function registerGlowInstance(inst: MetalFxInstance): void;
+export declare function unregisterGlowInstance(inst: MetalFxInstance): void;
+export declare function updateInstance(inst: MetalFxInstance, patch: Partial<Pick<MetalFxInstance, "cssWidth" | "cssHeight" | "cornerRadius" | "kind" | "shaderScale" | "ringCssPx" | "opacityMul" | "paused" | "presetName" | "presetTheme" | "scale">>): void;
+export declare function setInstanceVisible(inst: MetalFxInstance, visible: boolean): void;
+export declare function pauseShared(): void;
+export declare function resumeShared(): void;
+export declare function getSharedFrameCount(): number;
+export type GlowCallback = (inst: MetalFxInstance, nowMs: number) => void;
+export declare function setGlowCallback(cb: GlowCallback | null): void;
+export {};

package/dist/components/metal-border/engine/renderer/loop.js

@@ -0,0 +1,248 @@
+import { hexToRgb } from "../color.js";
+import { FRAME_INTERVAL_MS, GLOW_SKIP_FRAMES } from "../perfConfig.js";
+import { PRESETS } from "../presets.js";
+import { CANONICAL_PILL_H, CANONICAL_PILL_W, CIRCLE_SHADER_SCALE, PILL_SHADER_SCALE, SHARED, ensureSharedRenderer, setContextRestoredCallback, teardownSharedRenderer } from "./core.js";
+import { refreshGlowPixels } from "./sampling.js";
+setContextRestoredCallback(()=>{
+    if (SHARED && SHARED.instances.size > 0 && null === SHARED.pausedAtMs) startSharedLoop();
+});
+if ("u" > typeof document) document.addEventListener("visibilitychange", ()=>{
+    if (!SHARED || null !== SHARED.pausedAtMs || SHARED.contextLost) return;
+    if (document.hidden) stopSharedLoop();
+    else if (SHARED.instances.size > 0) startSharedLoop();
+});
+function createInstance(opts) {
+    const renderer = ensureSharedRenderer();
+    const ctx = opts.hostCanvas.getContext("2d", {
+        alpha: true
+    });
+    if (!ctx) throw new Error("metal-fx: canvas 2D context unavailable");
+    const scale = opts.scale ?? 1;
+    const inst = {
+        canvas: opts.hostCanvas,
+        ctx,
+        cssWidth: opts.cssWidth,
+        cssHeight: opts.cssHeight,
+        cornerRadius: opts.cornerRadius,
+        kind: opts.kind,
+        ringCssPx: opts.ringCssPx ?? ("circle" === opts.kind ? 2 : 1) * scale,
+        shaderScale: opts.shaderScale ?? ("circle" === opts.kind ? CIRCLE_SHADER_SCALE : PILL_SHADER_SCALE) * scale,
+        opacityMul: opts.opacityMul ?? 1,
+        visible: true,
+        paused: opts.paused ?? false,
+        everCopied: false,
+        dpr: "u" > typeof window ? window.devicePixelRatio || 1 : 1,
+        presetName: opts.presetName,
+        presetTheme: opts.presetTheme,
+        glowEnabled: false,
+        scale,
+        onAfterFrame: opts.onAfterFrame,
+        onFirstCopy: opts.onFirstCopy
+    };
+    resizeInstanceCanvas(inst);
+    renderer.instances.add(inst);
+    if (0 === renderer.rafId && null === renderer.pausedAtMs) startSharedLoop();
+    return inst;
+}
+function destroyInstance(inst) {
+    if (!SHARED) return;
+    SHARED.instances["delete"](inst);
+    if (0 === SHARED.instances.size) {
+        stopSharedLoop();
+        teardownSharedRenderer();
+    }
+}
+function registerGlowInstance(inst) {
+    inst.glowEnabled = true;
+}
+function unregisterGlowInstance(inst) {
+    inst.glowEnabled = false;
+}
+function updateInstance(inst, patch) {
+    let dirty = false;
+    if (void 0 !== patch.cssWidth && patch.cssWidth !== inst.cssWidth) {
+        inst.cssWidth = patch.cssWidth;
+        dirty = true;
+    }
+    if (void 0 !== patch.cssHeight && patch.cssHeight !== inst.cssHeight) {
+        inst.cssHeight = patch.cssHeight;
+        dirty = true;
+    }
+    if (void 0 !== patch.cornerRadius) inst.cornerRadius = patch.cornerRadius;
+    if (void 0 !== patch.scale) inst.scale = patch.scale;
+    if (void 0 !== patch.kind && patch.kind !== inst.kind) {
+        inst.kind = patch.kind;
+        if (void 0 === patch.shaderScale) inst.shaderScale = ("circle" === patch.kind ? CIRCLE_SHADER_SCALE : PILL_SHADER_SCALE) * inst.scale;
+        if (void 0 === patch.ringCssPx) inst.ringCssPx = ("circle" === patch.kind ? 2 : 1) * inst.scale;
+    }
+    if (void 0 !== patch.shaderScale) inst.shaderScale = patch.shaderScale;
+    if (void 0 !== patch.ringCssPx) inst.ringCssPx = patch.ringCssPx;
+    if (void 0 !== patch.opacityMul) inst.opacityMul = patch.opacityMul;
+    if (void 0 !== patch.presetName) inst.presetName = patch.presetName;
+    if (void 0 !== patch.presetTheme) inst.presetTheme = patch.presetTheme;
+    if (void 0 !== patch.paused && patch.paused !== inst.paused) {
+        inst.paused = patch.paused;
+        if (!patch.paused && SHARED && 0 === SHARED.rafId && null === SHARED.pausedAtMs && !SHARED.contextLost) startSharedLoop();
+    }
+    if (dirty) resizeInstanceCanvas(inst);
+}
+function setInstanceVisible(inst, visible) {
+    inst.visible = visible;
+    if (visible && SHARED && 0 === SHARED.rafId && null === SHARED.pausedAtMs && !SHARED.contextLost) startSharedLoop();
+}
+function syncRendererPreset(name, theme) {
+    const shared = ensureSharedRenderer();
+    if (shared.presetName === name && shared.presetTheme === theme && !shared.presetDirty) return;
+    shared.preset = PRESETS[name].modes[theme];
+    shared.presetName = name;
+    shared.presetTheme = theme;
+    shared.presetDirty = true;
+}
+function pauseShared() {
+    if (!SHARED || null !== SHARED.pausedAtMs) return;
+    SHARED.pausedAtMs = performance.now();
+    stopSharedLoop();
+}
+function resumeShared() {
+    if (!SHARED || null === SHARED.pausedAtMs) return;
+    SHARED.pausedMs += performance.now() - SHARED.pausedAtMs;
+    SHARED.pausedAtMs = null;
+    if (SHARED.instances.size > 0) startSharedLoop();
+}
+function getSharedFrameCount() {
+    return SHARED?.frameCount ?? 0;
+}
+let _glowCallback = null;
+function setGlowCallback(cb) {
+    _glowCallback = cb;
+}
+function resizeInstanceCanvas(inst) {
+    inst.dpr = "u" > typeof window ? window.devicePixelRatio || 1 : 1;
+    const w = Math.max(1, Math.round(inst.cssWidth * inst.dpr));
+    const h = Math.max(1, Math.round(inst.cssHeight * inst.dpr));
+    if (inst.canvas.width !== w) inst.canvas.width = w;
+    if (inst.canvas.height !== h) inst.canvas.height = h;
+}
+function punchInnerHole(inst) {
+    const { ctx, dpr, canvas } = inst;
+    const stroke = inst.ringCssPx * dpr;
+    const w = canvas.width;
+    const h = canvas.height;
+    const innerR = Math.max(0, (inst.cornerRadius - inst.ringCssPx) * dpr);
+    ctx.save();
+    ctx.globalCompositeOperation = "destination-out";
+    ctx.fillStyle = "#000";
+    ctx.beginPath();
+    ctx.roundRect(stroke, stroke, w - 2 * stroke, h - 2 * stroke, innerR);
+    ctx.fill();
+    ctx.restore();
+}
+function copyShaderToInstance(inst) {
+    if (!SHARED) return;
+    const src = SHARED.glCanvas;
+    const dpr = inst.dpr;
+    const dw = inst.canvas.width;
+    const dh = inst.canvas.height;
+    if (dw < 1 || dh < 1) return;
+    const cw = SHARED.glCanvas.width;
+    const ch = SHARED.glCanvas.height;
+    const bdW = CANONICAL_PILL_W * dpr;
+    const bdH = CANONICAL_PILL_H * dpr;
+    let srcW = cw / bdW * dw / inst.shaderScale;
+    let srcH = ch / bdH * dh / inst.shaderScale;
+    if (srcW > cw) srcW = cw;
+    if (srcH > ch) srcH = ch;
+    const sx = Math.max(0, (cw - srcW) / 2);
+    const sy = Math.max(0, (ch - srcH) / 2);
+    inst.ctx.clearRect(0, 0, dw, dh);
+    if (inst.opacityMul < 1) inst.ctx.globalAlpha = inst.opacityMul;
+    inst.ctx.drawImage(src, sx, sy, srcW, srcH, 0, 0, dw, dh);
+    if (inst.opacityMul < 1) inst.ctx.globalAlpha = 1;
+    punchInnerHole(inst);
+    if (inst.onFirstCopy) {
+        const cb = inst.onFirstCopy;
+        inst.onFirstCopy = void 0;
+        cb();
+    }
+    inst.onAfterFrame?.();
+}
+function uploadPresetUniforms() {
+    if (!SHARED) return;
+    const { gl, uniforms, preset, glCanvas } = SHARED;
+    if (uniforms.u_resolution) gl.uniform2f(uniforms.u_resolution, glCanvas.width, glCanvas.height);
+    for(let i = 0; i < 7; i++){
+        const cLoc = uniforms[`u_color${i + 1}`];
+        if (cLoc) {
+            const [r, g, b] = hexToRgb(preset.colors[i]);
+            gl.uniform3f(cLoc, r, g, b);
+        }
+        const aLoc = uniforms[`u_alpha${i + 1}`];
+        if (aLoc) gl.uniform1f(aLoc, preset.alphas[i]);
+    }
+    if (uniforms.u_intensity) gl.uniform1f(uniforms.u_intensity, preset.intensity);
+    if (uniforms.u_scale) gl.uniform1f(uniforms.u_scale, preset.scale);
+    if (uniforms.u_direction) gl.uniform1f(uniforms.u_direction, preset.direction * Math.PI / 180);
+    if (uniforms.u_softness) gl.uniform1f(uniforms.u_softness, preset.softness);
+    if (uniforms.u_distortion) gl.uniform1f(uniforms.u_distortion, preset.distortion);
+    if (uniforms.u_complexity) gl.uniform1f(uniforms.u_complexity, preset.complexity);
+    if (uniforms.u_shape) gl.uniform1f(uniforms.u_shape, preset.shape);
+    if (uniforms.u_vignette) gl.uniform1f(uniforms.u_vignette, preset.vignette);
+    if (uniforms.u_vigOpacity) gl.uniform1f(uniforms.u_vigOpacity, preset.vigOpacity);
+    if (uniforms.u_blur) gl.uniform1f(uniforms.u_blur, preset.blur);
+    if (uniforms.u_shaderOpacity) gl.uniform1f(uniforms.u_shaderOpacity, preset.shaderOpacity);
+    SHARED.presetDirty = false;
+}
+function renderSharedFrame(now, presetName, presetTheme) {
+    if (!SHARED) return;
+    syncRendererPreset(presetName, presetTheme);
+    const { gl, uniforms, preset, glCanvas } = SHARED;
+    const t = (now - SHARED.startMs - SHARED.pausedMs) / 1000 * preset.speed;
+    gl.viewport(0, 0, glCanvas.width, glCanvas.height);
+    gl.clearColor(0, 0, 0, 0);
+    gl.clear(gl.COLOR_BUFFER_BIT);
+    if (SHARED.presetDirty) uploadPresetUniforms();
+    if (uniforms.u_time) gl.uniform1f(uniforms.u_time, t);
+    gl.drawArrays(gl.TRIANGLES, 0, 6);
+    SHARED.frameCount++;
+}
+let lastFrameMs = 0;
+function tick(now) {
+    if (!SHARED) return;
+    if (SHARED.contextLost) {
+        SHARED.rafId = 0;
+        return;
+    }
+    let anyWork = false;
+    for (const inst of SHARED.instances)if (inst.visible && (!inst.paused || !inst.everCopied)) {
+        anyWork = true;
+        break;
+    }
+    if (!anyWork) {
+        SHARED.rafId = 0;
+        return;
+    }
+    SHARED.rafId = requestAnimationFrame(tick);
+    if (now - lastFrameMs < FRAME_INTERVAL_MS) return;
+    lastFrameMs = now;
+    for (const inst of SHARED.instances)if (inst.visible) {
+        if (!inst.paused || !inst.everCopied) {
+            renderSharedFrame(now, inst.presetName, inst.presetTheme);
+            copyShaderToInstance(inst);
+            inst.everCopied = true;
+            if (_glowCallback && inst.glowEnabled && !inst.paused && SHARED.frameCount % GLOW_SKIP_FRAMES === 0) {
+                refreshGlowPixels();
+                _glowCallback(inst, now);
+            }
+        }
+    }
+}
+function startSharedLoop() {
+    if (!SHARED || 0 !== SHARED.rafId) return;
+    SHARED.rafId = requestAnimationFrame(tick);
+}
+function stopSharedLoop() {
+    if (!SHARED) return;
+    if (0 !== SHARED.rafId) cancelAnimationFrame(SHARED.rafId);
+    SHARED.rafId = 0;
+}
+export { createInstance, destroyInstance, getSharedFrameCount, pauseShared, registerGlowInstance, resumeShared, setGlowCallback, setInstanceVisible, unregisterGlowInstance, updateInstance };

package/dist/components/metal-border/engine/renderer/sampling.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Pixel readback and luminance/colour sampling from the shared GL canvas.
+ *
+ * All glow luminance/color sampling reads from a shared pixel buffer
+ * (SHARED.glowPixels). The buffer is refreshed via gl.readPixels at most
+ * every GLOW_READBACK_INTERVAL_MS to avoid the expensive GPU→CPU pipeline
+ * flush on every frame. The plasma shader evolves slowly so 200ms-stale
+ * data is visually indistinguishable.
+ */
+import { type MetalFxInstance, type ShaderRGB } from "./core";
+export declare function refreshGlowPixels(): void;
+export declare function sampleShaderLumAt(inst: MetalFxInstance, cssPxX: number, cssPxY: number, radius: number): number;
+export declare function sampleShaderRGBAt(inst: MetalFxInstance, cssPxX: number, cssPxY: number, radius: number): ShaderRGB;
+export declare function sampleShaderRGBChromatic(inst: MetalFxInstance, cssPxX: number, cssPxY: number, radius: number): ShaderRGB;

package/dist/components/metal-border/engine/renderer/sampling.js

@@ -0,0 +1,145 @@
+import { CANONICAL_PILL_H, CANONICAL_PILL_W, SHARED } from "./core.js";
+function refreshGlowPixels() {
+    if (!SHARED) return;
+    const { gl, glCanvas } = SHARED;
+    const cw = glCanvas.width;
+    const ch = glCanvas.height;
+    if (SHARED.glowPixelsW !== cw || SHARED.glowPixelsH !== ch) {
+        SHARED.glowPixelsW = cw;
+        SHARED.glowPixelsH = ch;
+        SHARED.glowPixels = new Uint8Array(cw * ch * 4);
+    }
+    gl.readPixels(0, 0, cw, ch, gl.RGBA, gl.UNSIGNED_BYTE, SHARED.glowPixels);
+}
+const _map = {
+    bx: 0,
+    by: 0
+};
+function mapToGlowBuf(inst, cssPxX, cssPxY) {
+    if (!SHARED) {
+        _map.bx = 0;
+        _map.by = 0;
+        return _map;
+    }
+    const { glCanvas } = SHARED;
+    const cw = glCanvas.width;
+    const ch = glCanvas.height;
+    const dpr = inst.dpr;
+    const dw = inst.cssWidth * dpr;
+    const dh = inst.cssHeight * dpr;
+    const bdW = CANONICAL_PILL_W * dpr;
+    const bdH = CANONICAL_PILL_H * dpr;
+    let srcW = cw / bdW * dw / inst.shaderScale;
+    let srcH = ch / bdH * dh / inst.shaderScale;
+    if (srcW > cw) srcW = cw;
+    if (srcH > ch) srcH = ch;
+    const sx = (cw - srcW) / 2;
+    const sy = (ch - srcH) / 2;
+    const glX = sx + cssPxX / inst.cssWidth * srcW;
+    const glY = sy + cssPxY / inst.cssHeight * srcH;
+    _map.bx = Math.round(glX);
+    _map.by = Math.round(ch - 1 - glY);
+    return _map;
+}
+const _sr = {
+    r: 0,
+    g: 0,
+    b: 0,
+    lum: 0,
+    count: 0
+};
+function sampleRegion(buf, W, H, bx, by, radius) {
+    const r = Math.max(1, 0 | radius);
+    const x0 = Math.max(0, bx - r);
+    const x1 = Math.min(W, bx + r + 1);
+    const y0 = Math.max(0, by - r);
+    const y1 = Math.min(H, by + r + 1);
+    _sr.r = 0;
+    _sr.g = 0;
+    _sr.b = 0;
+    _sr.lum = 0;
+    _sr.count = 0;
+    for(let py = y0; py < y1; py++){
+        const row = py * W;
+        for(let px = x0; px < x1; px++){
+            const i = (row + px) * 4;
+            _sr.r += buf[i];
+            _sr.g += buf[i + 1];
+            _sr.b += buf[i + 2];
+            _sr.lum += (0.2126 * buf[i] + 0.7152 * buf[i + 1] + 0.0722 * buf[i + 2]) / 255;
+            _sr.count++;
+        }
+    }
+    return _sr;
+}
+const _rgb = {
+    r: 255,
+    g: 255,
+    b: 255
+};
+function sampleShaderLumAt(inst, cssPxX, cssPxY, radius) {
+    if (!SHARED) return 0;
+    const m = mapToGlowBuf(inst, cssPxX, cssPxY);
+    const s = sampleRegion(SHARED.glowPixels, SHARED.glowPixelsW, SHARED.glowPixelsH, m.bx, m.by, radius);
+    return s.count > 0 ? s.lum / s.count : 0;
+}
+function sampleShaderRGBAt(inst, cssPxX, cssPxY, radius) {
+    if (!SHARED) {
+        _rgb.r = 255;
+        _rgb.g = 255;
+        _rgb.b = 255;
+        return _rgb;
+    }
+    const m = mapToGlowBuf(inst, cssPxX, cssPxY);
+    const s = sampleRegion(SHARED.glowPixels, SHARED.glowPixelsW, SHARED.glowPixelsH, m.bx, m.by, radius);
+    if (0 === s.count) {
+        _rgb.r = 255;
+        _rgb.g = 255;
+        _rgb.b = 255;
+        return _rgb;
+    }
+    _rgb.r = s.r / s.count;
+    _rgb.g = s.g / s.count;
+    _rgb.b = s.b / s.count;
+    return _rgb;
+}
+function sampleShaderRGBChromatic(inst, cssPxX, cssPxY, radius) {
+    if (!SHARED) {
+        _rgb.r = 255;
+        _rgb.g = 255;
+        _rgb.b = 255;
+        return _rgb;
+    }
+    const m = mapToGlowBuf(inst, cssPxX, cssPxY);
+    const { glowPixels: buf, glowPixelsW: W, glowPixelsH: H } = SHARED;
+    const r = Math.max(1, 0 | radius);
+    const x0 = Math.max(0, m.bx - r);
+    const x1 = Math.min(W, m.bx + r + 1);
+    const y0 = Math.max(0, m.by - r);
+    const y1 = Math.min(H, m.by + r + 1);
+    let bestScore = -1;
+    _rgb.r = 255;
+    _rgb.g = 255;
+    _rgb.b = 255;
+    for(let py = y0; py < y1; py++){
+        const row = py * W;
+        for(let px = x0; px < x1; px++){
+            const i = (row + px) * 4;
+            const rr = buf[i];
+            const gg = buf[i + 1];
+            const bb = buf[i + 2];
+            const maxC = Math.max(rr, gg, bb);
+            const minC = Math.min(rr, gg, bb);
+            const sat = maxC > 0 ? (maxC - minC) / maxC : 0;
+            const score = sat * (0.35 + maxC / 255 * 0.65);
+            if (score > bestScore) {
+                bestScore = score;
+                _rgb.r = rr;
+                _rgb.g = gg;
+                _rgb.b = bb;
+            }
+        }
+    }
+    return _rgb;
+}
+export { refreshGlowPixels, sampleShaderLumAt, sampleShaderRGBAt, sampleShaderRGBChromatic };

package/dist/components/metal-border/engine/shaders.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Vertex + fragment shader for the metal-fx effect.
+ *
+ * Source-of-truth: the `FRAG_SRC` block at L3626–4179 of the canonical
+ * `Image loader/index.html` engine. The chromatic / silver / gold presets all
+ * run `effectIndex: 1` (Plasma), so we ship ONLY that branch — the original
+ * carries 24 effects plus a dot-mode raster grid that this library does not
+ * expose. Everything else (warp, snoise, fbm, palette, paletteAlpha, vignette,
+ * gamma) is preserved character-for-character so the visible output matches
+ * `metal.html` 1:1.
+ *
+ * Uniforms:
+ *   u_resolution      vec2  — destination pixel buffer (DPR-scaled)
+ *   u_time            float — seconds since boot, JS-side multiplied by speed
+ *   u_color1..u_color5 vec3 — palette stops (effect 1 uses 5; uniforms 6/7 are
+ *                            still uploaded for forward-compat with effect 24)
+ *   u_color6, u_color7 vec3 — extra stops, unused at effect 1
+ *   u_alpha1..u_alpha7 float
+ *   u_intensity       float — amplitude of the wave field
+ *   u_scale           float — noise zoom (smaller = chunkier features)
+ *   u_direction       float — drift angle (radians)
+ *   u_softness        float — kept for shader parity (effect 1 ignores)
+ *   u_distortion      float — warp strength on the sin band field
+ *   u_complexity      float — fbm octaves + frequency multiplier
+ *   u_shape           float — kept for shader parity (effect 1 ignores)
+ *   u_vignette        float — vignette range (0..1)
+ *   u_vigOpacity      float — vignette darkening strength (0..1)
+ *   u_blur            float — sample-radius for the 9-tap blur (0..1)
+ *   u_shaderOpacity   float — final alpha multiplier (0..1)
+ */
+export declare const VERT_SHADER_SRC = "\n  attribute vec2 a_position;\n  void main() { gl_Position = vec4(a_position, 0.0, 1.0); }\n";
+export declare const FRAG_SHADER_SRC = "\n  precision highp float;\n\n  uniform vec2 u_resolution;\n  uniform float u_time;\n  uniform vec3 u_color1, u_color2, u_color3, u_color4, u_color5, u_color6, u_color7;\n  uniform float u_alpha1, u_alpha2, u_alpha3, u_alpha4, u_alpha5, u_alpha6, u_alpha7;\n  uniform float u_intensity, u_scale, u_direction;\n  uniform float u_softness, u_distortion, u_complexity, u_shape;\n  uniform float u_vignette, u_vigOpacity, u_blur, u_shaderOpacity;\n\n  vec3 mod289(vec3 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }\n  vec2 mod289v2(vec2 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }\n  vec3 permute(vec3 x) { return mod289((x * 34.0 + 1.0) * x); }\n\n  float snoise(vec2 v) {\n    const vec4 C = vec4(0.211324865405187, 0.366025403784439,\n                        -0.577350269189626, 0.024390243902439);\n    vec2 i = floor(v + dot(v, C.yy));\n    vec2 x0 = v - i + dot(i, C.xx);\n    vec2 i1 = (x0.x > x0.y) ? vec2(1.0, 0.0) : vec2(0.0, 1.0);\n    vec4 x12 = x0.xyxy + C.xxzz;\n    x12.xy -= i1;\n    i = mod289v2(i);\n    vec3 p = permute(permute(i.y + vec3(0.0, i1.y, 1.0)) + i.x + vec3(0.0, i1.x, 1.0));\n    vec3 m = max(0.5 - vec3(dot(x0, x0), dot(x12.xy, x12.xy), dot(x12.zw, x12.zw)), 0.0);\n    m = m * m; m = m * m;\n    vec3 x_ = 2.0 * fract(p * C.www) - 1.0;\n    vec3 h = abs(x_) - 0.5;\n    vec3 ox = floor(x_ + 0.5);\n    vec3 a0 = x_ - ox;\n    m *= 1.79284291400159 - 0.85373472095314 * (a0 * a0 + h * h);\n    vec3 g;\n    g.x = a0.x * x0.x + h.x * x0.y;\n    g.yz = a0.yz * x12.xz + h.yz * x12.yw;\n    return 130.0 * dot(m, g);\n  }\n\n  float fbm(vec2 p, float oct) {\n    float val = 0.0, amp = 0.5;\n    int n = int(oct);\n    for (int i = 0; i < 7; i++) {\n      if (i >= n) break;\n      val += amp * snoise(p);\n      p *= 2.0;\n      amp *= 0.5;\n    }\n    return val;\n  }\n\n  float nfbm(vec2 p) { return fbm(p, 3.0 + u_complexity * 4.0); }\n\n  /* 5-stop palette used by effect 1 (Plasma) \u2014 direct port of `palette` from\n   * the canonical engine. Stops at t = 0, 0.25, 0.5, 0.75, 1.0. */\n  vec3 palette(float t) {\n    t = clamp(t, 0.0, 1.0);\n    t = t * t * (3.0 - 2.0 * t);\n    float k = 64.0;\n    float w1 = u_alpha1 * exp(-k * t * t);\n    float w2 = u_alpha2 * exp(-k * (t - 0.25) * (t - 0.25));\n    float w3 = u_alpha3 * exp(-k * (t - 0.5)  * (t - 0.5));\n    float w4 = u_alpha4 * exp(-k * (t - 0.75) * (t - 0.75));\n    float w5 = u_alpha5 * exp(-k * (t - 1.0)  * (t - 1.0));\n    float total = w1 + w2 + w3 + w4 + w5 + 0.0001;\n    return (u_color1 * w1 + u_color2 * w2 + u_color3 * w3 +\n            u_color4 * w4 + u_color5 * w5) / total;\n  }\n\n  /* Per-pixel alpha that re-introduces transparency when the user dials any\n   * palette stop's alpha below 1. Same `paletteAlpha` from the canonical\n   * engine. With every preset shipping all-1 alphas, this returns ~1 for every\n   * pixel \u2014 but mirroring it keeps custom-preset behaviour identical. */\n  float paletteAlpha(float t) {\n    t = clamp(t, 0.0, 1.0);\n    t = t * t * (3.0 - 2.0 * t);\n    float k = 64.0;\n    float w1 = u_alpha1 * exp(-k * t * t);\n    float w2 = u_alpha2 * exp(-k * (t - 0.25) * (t - 0.25));\n    float w3 = u_alpha3 * exp(-k * (t - 0.5)  * (t - 0.5));\n    float w4 = u_alpha4 * exp(-k * (t - 0.75) * (t - 0.75));\n    float w5 = u_alpha5 * exp(-k * (t - 1.0)  * (t - 1.0));\n    float totalW = w1 + w2 + w3 + w4 + w5 + 0.0001;\n    float rawW = exp(-k * t * t)\n               + exp(-k * (t - 0.25) * (t - 0.25))\n               + exp(-k * (t - 0.5)  * (t - 0.5))\n               + exp(-k * (t - 0.75) * (t - 0.75))\n               + exp(-k * (t - 1.0)  * (t - 1.0))\n               + 0.0001;\n    return totalW / rawW;\n  }\n\n  vec2 warp(vec2 p, float t) {\n    float str = u_distortion * 2.0;\n    return vec2(\n      nfbm(p + vec2(t * 0.1, 0.0)),\n      nfbm(p + vec2(0.0, t * 0.12) + 5.0)\n    ) * str;\n  }\n\n  /* Plasma: four sine bands warped by an FBM field, mapped through the\n   * 5-stop palette. Identical to effect 1 in the canonical engine. */\n  vec3 computeEffect(vec2 uv, float aspect, float t, float dist, float cpx) {\n    vec2 p = (uv - 0.5) * u_scale;\n    p.x *= aspect;\n    p += vec2(cos(u_direction), sin(u_direction)) * t * 0.15;\n\n    float freq = 3.0 + cpx * 8.0;\n    float val = 0.0;\n    val += sin(p.x * freq + t);\n    val += sin(p.y * freq + t * 1.3);\n    val += sin((p.x + p.y) * freq * 0.7 + t * 0.7);\n    val += sin(length(p) * freq * 0.8 - t * 1.5);\n    vec2 w = warp(p, t);\n    val += (w.x + w.y) * dist;\n    val = val * 0.2 * u_intensity + 0.5;\n\n    return palette(clamp(val, 0.0, 1.0));\n  }\n\n  void main() {\n    vec2 uv = gl_FragCoord.xy / u_resolution;\n    float aspect = u_resolution.x / u_resolution.y;\n    float t = u_time;          // JS already multiplied u_time by preset.speed.\n    float dist = u_distortion;\n    float cpx = u_complexity;\n\n    /* 5-tap cross blur (center + cardinal offsets). The chromatic/silver/gold\n     * presets all ship with blur=1 so this path is always active. 5 taps\n     * instead of the canonical engine's 9 saves ~44% fragment work; the\n     * perceptual difference is nil because the output is already soft from\n     * the plasma's low spatial frequency and CSS blur on reflections. */\n    vec3 col;\n    if (u_blur < 0.01) {\n      col = computeEffect(uv, aspect, t, dist, cpx);\n    } else {\n      float r = u_blur * 0.02;\n      col  = computeEffect(uv,                  aspect, t, dist, cpx) * 0.4;\n      col += computeEffect(uv + vec2( r, 0.0),  aspect, t, dist, cpx) * 0.15;\n      col += computeEffect(uv + vec2(-r, 0.0),  aspect, t, dist, cpx) * 0.15;\n      col += computeEffect(uv + vec2(0.0,  r),  aspect, t, dist, cpx) * 0.15;\n      col += computeEffect(uv + vec2(0.0, -r),  aspect, t, dist, cpx) * 0.15;\n    }\n\n    /* Gamma punch \u2014 adds the contrast pop that defines the chromatic\n     * highlights. From the canonical engine: `col = pow(col, vec3(1.3))`. */\n    col = pow(col, vec3(1.3));\n\n    /* Vignette \u2014 soft edge darkening so corners read as recessed. The 40-px\n     * scale at the bottom of the formula is hard-coded in the canonical\n     * engine; we keep it for visual parity. */\n    float edgeDist = min(min(uv.x, 1.0 - uv.x), min(uv.y, 1.0 - uv.y));\n    float vigPx = 40.0 / min(u_resolution.x, u_resolution.y);\n    float vigRange = vigPx * (1.0 + u_vignette * 3.0);\n    float vig = edgeDist * edgeDist / (vigRange * vigRange);\n    vig = smoothstep(0.0, 1.0, vig);\n    col *= mix(1.0, vig, u_vignette * u_vigOpacity);\n\n    /* Per-pixel alpha. With all-1 alphas the formula collapses to ~1 but the\n     * computation matches the canonical engine so custom presets behave the\n     * same. */\n    float colorAlpha = (u_alpha1 + u_alpha2 + u_alpha3 + u_alpha4 + u_alpha5) / 5.0;\n    if (colorAlpha < 0.999) {\n      vec3 c1d = col - u_color1, c2d = col - u_color2, c3d = col - u_color3,\n           c4d = col - u_color4, c5d = col - u_color5;\n      float prox1 = exp(-8.0 * dot(c1d, c1d));\n      float prox2 = exp(-8.0 * dot(c2d, c2d));\n      float prox3 = exp(-8.0 * dot(c3d, c3d));\n      float prox4 = exp(-8.0 * dot(c4d, c4d));\n      float prox5 = exp(-8.0 * dot(c5d, c5d));\n      float pTotal = prox1 + prox2 + prox3 + prox4 + prox5 + 0.0001;\n      colorAlpha = (prox1 * u_alpha1 + prox2 * u_alpha2 + prox3 * u_alpha3 +\n                    prox4 * u_alpha4 + prox5 * u_alpha5) / pTotal;\n    }\n    float alpha = colorAlpha;\n\n    /* Touch the unused-at-effect-1 uniforms so GL drivers that complain about\n     * declared-but-unread uniforms (some Mali / Adreno builds do) keep them\n     * live. The contribution is provably zero. */\n    alpha += 0.0 * (u_softness + u_shape +\n                    u_alpha6 + u_alpha7 +\n                    u_color6.x + u_color7.x);\n\n    gl_FragColor = vec4(col, alpha * u_shaderOpacity);\n  }\n";
+/** Compile a single shader stage. Throws with the GL info log on failure. */
+export declare function compileShader(gl: WebGLRenderingContext, type: number, source: string): WebGLShader;
+/** Link a vertex + fragment shader pair into a complete program. */
+export declare function linkProgram(gl: WebGLRenderingContext, vert: WebGLShader, frag: WebGLShader): WebGLProgram;