@3driseai/3drise-viewer 0.1.22 → 0.1.24

package/dist/components/ledArray/LedArray.js

@@ -0,0 +1,243 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// =============================================================================
+// LedArray — a point light drawn as the dies that make it
+// =============================================================================
+//
+// Rendered by LightObject for `config.type === 'ledArray'`. Like spotBeam, this
+// is a light rather than a lamp: the geometry is the emitters themselves (and
+// can be switched off), because the object is meant to be dropped into whatever
+// housing the scene already has.
+//
+// What makes it read as LED rather than a small bulb:
+//   - it comes on instantly — no thermal lag, the opposite of a filament;
+//   - `pwm` puts back the high-frequency chop a dimmed LED runs on, which a
+//     camera (and a 60 Hz render) sees as a slow strobe rather than a flat dim;
+//   - `diffuser` both fades the dies into one sheet and widens the light's own
+//     shadow radius, because those are the same fact: a bigger apparent source
+//     casts a softer shadow;
+//   - 'rgb' colour mode runs a hue across the array and can chase along it,
+//     which is what an addressable strip actually is. The light itself takes the
+//     average of the dies, the way the room would.
+//
+import { useEffect, useMemo, useRef } from 'react';
+import { useFrame } from '@react-three/fiber';
+import { BoxGeometry, Color, InstancedBufferAttribute, Matrix4, PlaneGeometry } from 'three';
+import { SELF_OWNED_MATERIAL_KEY } from '@3driseai/3drise-core';
+import { useObjectReady } from '../../hooks/useObjectReady.js';
+import { useLightShadow } from '../../hooks/useLightShadow.js';
+import { useLightConfig } from '../../hooks/useLightConfig.js';
+import { kelvinToColor } from '../lightBulb/kelvin.js';
+import { createLedArrayMaterials, disposeLedArrayMaterials } from './ledMaterials.js';
+import { placeDies } from './ledLayout.js';
+const num = (v, fallback) => (typeof v === 'number' && Number.isFinite(v) ? v : fallback);
+const clamp01 = (v) => Math.min(Math.max(v, 0), 1);
+const hash = (n) => {
+    const s = Math.sin(n * 127.1) * 43758.5453;
+    return s - Math.floor(s);
+};
+const noise1 = (x) => {
+    const i = Math.floor(x), f = x - i, u = f * f * (3 - 2 * f);
+    return hash(i) * (1 - u) + hash(i + 1) * u;
+};
+const scratchMatrix = new Matrix4();
+const LedArray = ({ id, config, animations, mouseMove, settings, onObjectReady, onObjectDispose }) => {
+    const groupRef = useRef(null);
+    const lightRef = useRef(null);
+    const diesRef = useRef(null);
+    const glowRef = useRef(null);
+    const diffuserRef = useRef(null);
+    useObjectReady(groupRef, settings, onObjectReady, onObjectDispose);
+    useLightShadow(lightRef, config.shadow);
+    const { merged } = useLightConfig(groupRef, lightRef, id, config, animations, mouseMove);
+    const layout = (config.layout ?? 'panel');
+    const spacing = Math.max(num(config.spacing, 0.06), 0.005);
+    const dieSize = Math.max(num(config.dieSize, 0.022), 0.002);
+    const emitter = (config.emitter ?? 'dies');
+    // --- where the dies sit; rebuilt only when the array's shape changes ---
+    const place = useMemo(() => placeDies(layout, config.count, config.rows, spacing), [layout, config.count, config.rows, spacing]);
+    const geometry = useMemo(() => ({
+        // a flat chip, so a die reads as a surface rather than a cube
+        die: new BoxGeometry(1, 0.35, 1),
+        glow: new PlaneGeometry(2, 2),
+        sheet: new PlaneGeometry(1, 1),
+    }), []);
+    useEffect(() => () => {
+        geometry.die.dispose();
+        geometry.glow.dispose();
+        geometry.sheet.dispose();
+    }, [geometry]);
+    const mats = useMemo(() => createLedArrayMaterials(), []);
+    useEffect(() => () => disposeLedArrayMaterials(mats), [mats]);
+    /** One colour per die, reused every frame instead of reallocated. */
+    const dieColors = useMemo(() => {
+        const list = [];
+        for (let i = 0; i < place.count; i++)
+            list.push(new Color());
+        return list;
+    }, [place]);
+    // Instance transforms + the per-die colour attribute the glow shader reads.
+    useEffect(() => {
+        const dies = diesRef.current;
+        const glow = glowRef.current;
+        const { positions, count } = place;
+        const colors = new Float32Array(count * 3).fill(1);
+        for (let i = 0; i < count; i++) {
+            const x = positions[i * 3], z = positions[i * 3 + 2];
+            scratchMatrix.makeScale(dieSize, dieSize, dieSize);
+            scratchMatrix.setPosition(x, 0, z);
+            dies?.setMatrixAt(i, scratchMatrix);
+            glow?.setMatrixAt(i, scratchMatrix);
+        }
+        if (dies) {
+            dies.count = count;
+            dies.instanceMatrix.needsUpdate = true;
+        }
+        if (glow) {
+            glow.count = count;
+            glow.instanceMatrix.needsUpdate = true;
+            glow.geometry.setAttribute('aColor', new InstancedBufferAttribute(colors, 3));
+        }
+        mats.diffuser.uniforms.uPitch.value = Math.max(place.pitchX, 1);
+    }, [place, dieSize, mats]);
+    // The light owns its materials and its shadow flags.
+    useEffect(() => {
+        const group = groupRef.current;
+        if (!group)
+            return;
+        group.userData[SELF_OWNED_MATERIAL_KEY] = true;
+        return () => { delete group.userData[SELF_OWNED_MATERIAL_KEY]; };
+    }, []);
+    // The dies sit millimetres from the light; the point shadow camera's default
+    // near of 0.5 would clip the whole array out of its own shadow map.
+    const shadowNear = config.shadow?.cameraNear;
+    useEffect(() => {
+        const light = lightRef.current;
+        if (!light || shadowNear !== undefined)
+            return;
+        light.shadow.camera.near = 0.02;
+        light.shadow.camera.updateProjectionMatrix();
+    }, [shadowNear]);
+    const colorMode = (config.colorMode ?? 'temperature');
+    const lightColor = useMemo(() => (colorMode === 'temperature'
+        ? kelvinToColor(config.temperature ?? 5000)
+        : new Color(config.color || '#ffffff')), [colorMode, config.color, config.temperature]);
+    const power = useRef({
+        level: (config.on ?? true) ? 1 : 0,
+        base: config.intensity ?? 1,
+        written: Number.NaN,
+        seed: Math.random() * 1000,
+    });
+    const scratch = useMemo(() => ({ mean: new Color(), glow: new Color(), tmp: new Color() }), []);
+    useFrame(({ clock }, delta) => {
+        const light = lightRef.current;
+        if (!light)
+            return;
+        const cfg = merged.current;
+        const p = power.current;
+        // Adopt any intensity we did not write ourselves as the new base, so the
+        // multiplier below never compounds and animations stay in charge.
+        if (light.intensity !== p.written)
+            p.base = light.intensity;
+        const on = cfg.on ?? true;
+        // An LED has no thermal lag: the default is a hard switch, and `warmup`
+        // is there only for someone who wants a fade.
+        const warmup = Math.max(num(cfg.warmup, 0), 0);
+        const target = on ? 1 : 0;
+        p.level = warmup <= 0
+            ? target
+            : p.level + (target - p.level) * (1 - Math.exp(-Math.min(delta, 0.1) * 3 / warmup));
+        if (Math.abs(target - p.level) < 1e-4)
+            p.level = target;
+        const t = clock.elapsedTime;
+        // PWM: a real dimmed LED is fully on for part of each cycle and fully off
+        // for the rest. At ~118 Hz against a 60 Hz frame that beats slowly, which
+        // is exactly the strobe a camera picks up.
+        const pwm = clamp01(num(cfg.pwm, 0));
+        const chop = pwm > 0 ? 1 - pwm * 0.5 * (0.5 + 0.5 * Math.sin(t * Math.PI * 2 * 118)) : 1;
+        const flicker = clamp01(num(cfg.flicker, 0));
+        let flick = 1;
+        if (flicker > 0) {
+            const ft = t + p.seed;
+            flick = 1 - flicker * (0.1 * noise1(ft * 13) + 0.6 * Math.pow(noise1(ft * 3.1), 4));
+        }
+        const output = p.level * chop * flick;
+        light.intensity = p.base * output;
+        p.written = light.intensity;
+        const baseIntensity = Math.max(num(config.intensity, 1), 1e-4);
+        const glowK = Math.min(output * (p.base / baseIntensity), 3);
+        // --- colour: one per die, and the light takes their mean ---
+        const rgbSpread = num(cfg.rgbSpread, 1);
+        const rgbSpeed = num(cfg.rgbSpeed, 0.2);
+        const mean = scratch.mean.setRGB(0, 0, 0);
+        const n = dieColors.length || 1;
+        for (let i = 0; i < dieColors.length; i++) {
+            const c = dieColors[i];
+            if (colorMode === 'rgb')
+                c.setHSL(((i / n) * rgbSpread + t * rgbSpeed) % 1, 1, 0.5);
+            else
+                c.copy(light.color);
+            mean.r += c.r / n;
+            mean.g += c.g / n;
+            mean.b += c.b / n;
+        }
+        // In RGB mode the light is the mix of the dies, not one of them. This runs
+        // after useLightConfig's own write, which is the point: the array owns its
+        // colour the way the bulb's filament owns its heat.
+        if (colorMode === 'rgb' && dieColors.length)
+            light.color.copy(mean);
+        const glowColor = scratch.glow.copy(colorMode === 'rgb' ? mean : light.color);
+        // --- diffuser: fades the dies out and softens the shadow with them ---
+        const diffuser = clamp01(num(cfg.diffuser, 0));
+        const dieVisible = emitter === 'dies' && glowK > 0.005;
+        const dieK = glowK * (1 - diffuser * 0.85);
+        const dies = diesRef.current;
+        const glow = glowRef.current;
+        if (dies) {
+            dies.visible = dieVisible;
+            if (dieVisible) {
+                for (let i = 0; i < dieColors.length; i++)
+                    dies.setColorAt(i, scratch.tmp.copy(dieColors[i]).multiplyScalar(Math.min(0.06 + dieK * 1.8, 4)));
+                if (dies.instanceColor)
+                    dies.instanceColor.needsUpdate = true;
+            }
+        }
+        if (glow) {
+            glow.visible = dieVisible;
+            const attr = glow.geometry.getAttribute('aColor');
+            if (dieVisible && attr) {
+                const arr = attr.array;
+                for (let i = 0; i < dieColors.length; i++) {
+                    const c = dieColors[i];
+                    arr[i * 3] = c.r;
+                    arr[i * 3 + 1] = c.g;
+                    arr[i * 3 + 2] = c.b;
+                }
+                attr.needsUpdate = true;
+            }
+            // Every die adds to the same pixels, so the per-die glow has to stay
+            // small and faint or a panel fuses into one white slab.
+            mats.dieGlow.uniforms.uStrength.value = dieK * 0.34;
+            mats.dieGlow.uniforms.uSize.value = Math.min(dieSize * 3.6, spacing * 0.85);
+        }
+        const sheet = diffuserRef.current;
+        if (sheet) {
+            sheet.visible = diffuser > 0.01 && glowK > 0.005;
+            mats.diffuser.uniforms.uColor.value.copy(glowColor);
+            mats.diffuser.uniforms.uStrength.value = diffuser * glowK * 0.85;
+            mats.diffuser.uniforms.uBlend.value = diffuser;
+        }
+        // A diffuser is a physically bigger source, so it blurs the shadow. Only
+        // when the config has not set a radius of its own.
+        if (config.shadow?.radius === undefined)
+            light.shadow.radius = 1 + diffuser * 11;
+        const halo = Math.max(num(cfg.halo, 1), 0);
+        mats.halo.uniforms.uColor.value.copy(glowColor);
+        mats.halo.uniforms.uStrength.value = halo * glowK * (0.12 + diffuser * 0.2);
+        // Sized to the array, not the world: a strip and a panel glow differently.
+        mats.halo.uniforms.uRadius.value = Math.max(place.width, place.depth) * 1.5;
+    });
+    // The diffuser sits just in front of the dies, facing down with them.
+    const sheetSize = [place.width * 1.12, place.depth * 1.12];
+    return (_jsxs("group", { ref: groupRef, children: [_jsx("pointLight", { ref: lightRef, color: lightColor, intensity: config.intensity ?? 1, decay: config.decay ?? 1, distance: config.distance ?? 0 }), _jsx("instancedMesh", { ref: diesRef, args: [geometry.die, mats.die, place.count], renderOrder: 2, frustumCulled: false }), _jsx("instancedMesh", { ref: glowRef, args: [geometry.glow, mats.dieGlow, place.count], renderOrder: 3, frustumCulled: false }), _jsx("mesh", { ref: diffuserRef, material: mats.diffuser, position: [0, -Math.max(dieSize * 1.4, 0.012), 0], rotation: [-Math.PI / 2, 0, 0], scale: [sheetSize[0], sheetSize[1], 1], geometry: geometry.sheet, renderOrder: 4, frustumCulled: false }), _jsx("mesh", { material: mats.halo, geometry: geometry.glow, renderOrder: 5, frustumCulled: false })] }));
+};
+export default LedArray;

package/dist/components/ledArray/index.d.ts

@@ -0,0 +1,7 @@
+export { default as LedArray } from './LedArray';
+export type { LedArrayProps } from './LedArray';
+export { createLedArrayMaterials, disposeLedArrayMaterials } from './ledMaterials';
+export type { LedArrayMaterials } from './ledMaterials';
+export { LED_LAYOUTS, MAX_DIES, placeDies } from './ledLayout';
+export type { LedLayout, LedPlacement } from './ledLayout';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/ledArray/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/ledArray/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,YAAY,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AACnF,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC/D,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/components/ledArray/index.js

@@ -0,0 +1,4 @@
+// An array of LED dies with a real point light (config.type 'ledArray').
+export { default as LedArray } from './LedArray.js';
+export { createLedArrayMaterials, disposeLedArrayMaterials } from './ledMaterials.js';
+export { LED_LAYOUTS, MAX_DIES, placeDies } from './ledLayout.js';

package/dist/components/ledArray/ledLayout.d.ts

@@ -0,0 +1,22 @@
+export type LedLayout = 'single' | 'strip' | 'panel' | 'ring';
+export declare const LED_LAYOUTS: LedLayout[];
+/** Instances are cheap but not free, and a 64x12 panel is already 768 dies. */
+export declare const MAX_DIES = 512;
+export interface LedPlacement {
+    /** x, y, z per die, flat. */
+    positions: Float32Array;
+    /** How many dies were actually placed (after the cap). */
+    count: number;
+    /** Footprint in object space, for the diffuser and the halo. */
+    width: number;
+    depth: number;
+    /** Hot spots across the diffuser's width, for its ripple. */
+    pitchX: number;
+    pitchZ: number;
+}
+/**
+ * Lay the dies out for a layout. `count` is the number along the main axis;
+ * `rows` only means anything for a panel.
+ */
+export declare function placeDies(layout: LedLayout, countRaw: unknown, rowsRaw: unknown, spacing: number): LedPlacement;
+//# sourceMappingURL=ledLayout.d.ts.map

package/dist/components/ledArray/ledLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledLayout.d.ts","sourceRoot":"","sources":["../../../src/components/ledArray/ledLayout.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9D,eAAO,MAAM,WAAW,EAAE,SAAS,EAAyC,CAAC;AAE7E,+EAA+E;AAC/E,eAAO,MAAM,QAAQ,MAAM,CAAC;AAE5B,MAAM,WAAW,YAAY;IACzB,6BAA6B;IAC7B,SAAS,EAAE,YAAY,CAAC;IACxB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAClB;AAOD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,CA8C/G"}

package/dist/components/ledArray/ledLayout.js

@@ -0,0 +1,59 @@
+export const LED_LAYOUTS = ['single', 'strip', 'panel', 'ring'];
+/** Instances are cheap but not free, and a 64x12 panel is already 768 dies. */
+export const MAX_DIES = 512;
+const clampInt = (v, lo, hi, fallback) => {
+    const n = typeof v === 'number' && Number.isFinite(v) ? Math.round(v) : fallback;
+    return Math.min(Math.max(n, lo), hi);
+};
+/**
+ * Lay the dies out for a layout. `count` is the number along the main axis;
+ * `rows` only means anything for a panel.
+ */
+export function placeDies(layout, countRaw, rowsRaw, spacing) {
+    const pitch = Math.max(spacing, 0.005);
+    let count = clampInt(countRaw, 1, 64, 8);
+    let rows = clampInt(rowsRaw, 1, 12, 4);
+    if (layout === 'single') {
+        count = 1;
+        rows = 1;
+    }
+    else if (layout !== 'panel')
+        rows = 1;
+    // Keep the instance count sane whatever the knobs say.
+    while (count * rows > MAX_DIES) {
+        if (rows > 1)
+            rows -= 1;
+        else
+            count -= 1;
+    }
+    const total = count * rows;
+    const positions = new Float32Array(total * 3);
+    if (layout === 'ring') {
+        // A ring of `count`, sized so neighbours sit one pitch apart.
+        const radius = count > 1 ? (pitch * count) / (2 * Math.PI) : 0;
+        for (let i = 0; i < count; i++) {
+            const a = (i / count) * Math.PI * 2;
+            positions[i * 3] = Math.cos(a) * radius;
+            positions[i * 3 + 2] = Math.sin(a) * radius;
+        }
+        const span = radius * 2 + pitch;
+        return { positions, count, width: span, depth: span, pitchX: Math.max(count / 4, 1), pitchZ: Math.max(count / 4, 1) };
+    }
+    const spanX = (count - 1) * pitch;
+    const spanZ = (rows - 1) * pitch;
+    let i = 0;
+    for (let r = 0; r < rows; r++) {
+        for (let c = 0; c < count; c++, i++) {
+            positions[i * 3] = c * pitch - spanX / 2;
+            positions[i * 3 + 2] = r * pitch - spanZ / 2;
+        }
+    }
+    return {
+        positions,
+        count: total,
+        width: spanX + pitch,
+        depth: spanZ + pitch,
+        pitchX: Math.max(count / 2, 1),
+        pitchZ: Math.max(rows / 2, 1),
+    };
+}

package/dist/components/ledArray/ledMaterials.d.ts

@@ -0,0 +1,14 @@
+import { MeshBasicMaterial, ShaderMaterial } from 'three';
+export interface LedArrayMaterials {
+    /** The dies themselves: emissive squares, per-instance colour. */
+    die: MeshBasicMaterial;
+    /** One additive billboard per die. */
+    dieGlow: ShaderMaterial;
+    /** The sheet in front of the dies, lit from behind. */
+    diffuser: ShaderMaterial;
+    /** One big camera-facing halo for the array as a whole. */
+    halo: ShaderMaterial;
+}
+export declare function createLedArrayMaterials(): LedArrayMaterials;
+export declare function disposeLedArrayMaterials(m: LedArrayMaterials): void;
+//# sourceMappingURL=ledMaterials.d.ts.map

package/dist/components/ledArray/ledMaterials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledMaterials.d.ts","sourceRoot":"","sources":["../../../src/components/ledArray/ledMaterials.ts"],"names":[],"mappings":"AAeA,OAAO,EAAuC,iBAAiB,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAE/F,MAAM,WAAW,iBAAiB;IAC9B,kEAAkE;IAClE,GAAG,EAAE,iBAAiB,CAAC;IACvB,sCAAsC;IACtC,OAAO,EAAE,cAAc,CAAC;IACxB,uDAAuD;IACvD,QAAQ,EAAE,cAAc,CAAC;IACzB,2DAA2D;IAC3D,IAAI,EAAE,cAAc,CAAC;CACxB;AA+HD,wBAAgB,uBAAuB,IAAI,iBAAiB,CAO3D;AAED,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAKnE"}

package/dist/components/ledArray/ledMaterials.js

@@ -0,0 +1,151 @@
+// =============================================================================
+// ledMaterials — the dies, their per-die glow, the diffuser and the halo
+// =============================================================================
+//
+// The viewer has no tone mapping and no bloom, so every bright thing here is
+// drawn by hand. An LED array is a set of very small, very bright sources, so
+// the glow is per die rather than one blob: a billboard quad per instance,
+// coloured from an instanced attribute so RGB mode can run a different hue down
+// the array.
+//
+// The diffuser is the other half of the look. A bare die is a point source with
+// a hard-edged shadow; a diffuser turns the whole array into one large soft
+// source. The slab drawn here is that surface — and the component couples the
+// same knob to the light's shadow radius, because the two are the same physics.
+//
+import { AdditiveBlending, Color, DoubleSide, MeshBasicMaterial, ShaderMaterial } from 'three';
+const OUTPUT = /* glsl */ `
+    #include <tonemapping_fragment>
+    #include <colorspace_fragment>
+`;
+/**
+ * A billboard per instance. The quad is built in view space from the instance's
+ * own origin, so the dies always face the camera however the array is turned.
+ */
+function dieGlowMaterial() {
+    return new ShaderMaterial({
+        uniforms: {
+            uStrength: { value: 0 },
+            uSize: { value: 0.09 },
+        },
+        vertexShader: /* glsl */ `
+            attribute vec3 aColor;
+            uniform float uSize;
+            varying vec2 vUv;
+            varying vec3 vColor;
+            void main() {
+                vColor = aColor;
+                vUv = position.xy;
+                // instance origin → view space, then the quad is laid out there
+                vec4 mv = modelViewMatrix * instanceMatrix * vec4(0.0, 0.0, 0.0, 1.0);
+                float s = length(modelMatrix[0].xyz) * uSize;
+                mv.xy += position.xy * s;
+                gl_Position = projectionMatrix * mv;
+            }`,
+        fragmentShader: /* glsl */ `
+            uniform float uStrength;
+            varying vec2 vUv;
+            varying vec3 vColor;
+            void main() {
+                float d = length(vUv);
+                // a tight core with a wide, faint skirt — how a small very bright
+                // source reads through a lens
+                float a = exp(-d * 11.0) + exp(-d * d * 6.0) * 0.35;
+                a *= 1.0 - smoothstep(0.7, 1.0, d);
+                gl_FragColor = vec4(vColor * uStrength * a, 1.0);
+                ${OUTPUT}
+            }`,
+        transparent: true,
+        depthWrite: false,
+        blending: AdditiveBlending,
+    });
+}
+/**
+ * The diffuser sheet. Brightest where the dies are (a soft periodic ripple that
+ * fades out as the sheet thickens), dimmer towards the rim where light escapes.
+ */
+function diffuserMaterial() {
+    return new ShaderMaterial({
+        uniforms: {
+            uColor: { value: new Color(1, 1, 1) },
+            uStrength: { value: 0 },
+            /** 0 = the dies still show through, 1 = a single even sheet. */
+            uBlend: { value: 0.5 },
+            /** How many die pitches across the sheet, for the hot-spot ripple. */
+            uPitch: { value: 4 },
+        },
+        vertexShader: /* glsl */ `
+            varying vec2 vUv;
+            void main() {
+                vUv = uv;
+                gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+            }`,
+        fragmentShader: /* glsl */ `
+            uniform vec3 uColor;
+            uniform float uStrength;
+            uniform float uBlend;
+            uniform float uPitch;
+            varying vec2 vUv;
+            void main() {
+                vec2 p = vUv * 2.0 - 1.0;
+                // light leaks away at the rim of any real diffuser
+                float edge = (1.0 - smoothstep(0.72, 1.0, abs(p.x))) * (1.0 - smoothstep(0.72, 1.0, abs(p.y)));
+                // hot spots over each die, washed out as the sheet thickens
+                vec2 c = cos(vUv * uPitch * 6.2831853);
+                float dots = (c.x * c.y) * 0.5 + 0.5;
+                float lit = mix(0.45 + dots * 0.75, 1.0, uBlend);
+                gl_FragColor = vec4(uColor * uStrength * lit * edge, 1.0);
+                ${OUTPUT}
+            }`,
+        transparent: true,
+        depthWrite: false,
+        side: DoubleSide,
+        blending: AdditiveBlending,
+    });
+}
+function haloMaterial() {
+    return new ShaderMaterial({
+        uniforms: {
+            uColor: { value: new Color(1, 1, 1) },
+            uStrength: { value: 0 },
+            uRadius: { value: 0.55 },
+        },
+        vertexShader: /* glsl */ `
+            uniform float uRadius;
+            varying vec2 vUv;
+            void main() {
+                vec4 mv = modelViewMatrix * vec4(0.0, 0.0, 0.0, 1.0);
+                float s = length(modelMatrix[0].xyz) * uRadius;
+                mv.xy += position.xy * s;
+                vUv = position.xy;
+                gl_Position = projectionMatrix * mv;
+            }`,
+        fragmentShader: /* glsl */ `
+            uniform vec3 uColor;
+            uniform float uStrength;
+            varying vec2 vUv;
+            void main() {
+                float d = length(vUv);
+                float a = (exp(-d * 8.0) + exp(-d * d * 4.0) * 0.3) * (1.0 - smoothstep(0.65, 1.0, d));
+                gl_FragColor = vec4(uColor * uStrength * a, 1.0);
+                ${OUTPUT}
+            }`,
+        transparent: true,
+        depthWrite: false,
+        blending: AdditiveBlending,
+    });
+}
+export function createLedArrayMaterials() {
+    return {
+        die: new MeshBasicMaterial({ color: 0xffffff, toneMapped: false }),
+        dieGlow: dieGlowMaterial(),
+        diffuser: diffuserMaterial(),
+        halo: haloMaterial(),
+    };
+}
+export function disposeLedArrayMaterials(m) {
+    m.die.dispose();
+    m.dieGlow.dispose();
+    m.diffuser.dispose();
+    m.halo.dispose();
+}

package/dist/components/lightBulb/LightBulb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LightBulb.d.ts","sourceRoot":"","sources":["../../../src/components/lightBulb/LightBulb.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAqC,MAAM,OAAO,CAAC;AAK1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAMtG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAIhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG;IAC5C,8EAA8E;IAC9E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,eAAe,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAChC,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACzD,CAAC;AAsBF,QAAA,MAAM,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC,cAAc,CAsHvC,CAAC;AACF,eAAe,SAAS,CAAC"}
+{"version":3,"file":"LightBulb.d.ts","sourceRoot":"","sources":["../../../src/components/lightBulb/LightBulb.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAqC,MAAM,OAAO,CAAC;AAK1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAItG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAIhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG;IAC5C,8EAA8E;IAC9E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,eAAe,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAChC,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACzD,CAAC;AAuBF,QAAA,MAAM,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC,cAAc,CAqHvC,CAAC;AACF,eAAe,SAAS,CAAC"}

package/dist/components/lightBulb/LightBulb.js

@@ -7,8 +7,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // is the filament centre, which is where the point light sits; the bulb stands
 // upright (base down, -Y) — rotate the object 180° for a pendant.
 //
-// Intensity ownership: useLightAnimation / useLightMouseMove (and R3F's
-// `intensity` prop) write `light.intensity` as usual. This component then
+// Intensity ownership: useLightConfig (keyframes + pointer bindings) and R3F's
+// `intensity` prop write `light.intensity` as usual. This component then
 // multiplies in the power level (on/off, warm-up, flicker) each frame. Any
 // intensity it did not write itself is adopted as the new base, so the
 // multiplier never compounds and external writers stay in charge of the base.
@@ -26,9 +26,7 @@ import { Color } from 'three';
 import { SELF_OWNED_MATERIAL_KEY } from '@3driseai/3drise-core';
 import { useObjectReady } from '../../hooks/useObjectReady.js';
 import { useLightShadow } from '../../hooks/useLightShadow.js';
-import { useLightAnimation } from '../../hooks/useLightAnimation.js';
-import { useLightMouseMove } from '../../hooks/useLightMouseMove.js';
-import { useLightLive } from '../../hooks/useLightLive.js';
+import { useLightConfig } from '../../hooks/useLightConfig.js';
 import { buildBulbShape, disposeBulbShape } from './bulbShapes.js';
 import { applyGlass, createBulbMaterials, disposeBulbMaterials, GLASS_RESPONSE } from './bulbMaterials.js';
 import { kelvinToColor } from './kelvin.js';
@@ -53,10 +51,9 @@ const LightBulb = ({ id, config, animations, mouseMove, settings, onObjectReady,
     const lightRef = useRef(null);
     useObjectReady(groupRef, settings, onObjectReady, onObjectDispose);
     useLightShadow(lightRef, config.shadow);
-    useLightAnimation(lightRef, animations);
-    useLightMouseMove(lightRef, mouseMove, { lightConfig: config });
-    // Slider drags: light props land on the light; flicker / halo / warmup are read per frame below.
-    const live = useLightLive(groupRef, lightRef, id, config);
+    // Keyframes, pointer bindings and slider drags: the light's own knobs land on
+    // the light, and the merged config is what the filament, glow and halo read.
+    const { merged } = useLightConfig(groupRef, lightRef, id, config, animations, mouseMove);
     const glass = config.glass ?? 'clear';
     const glassTint = config.glassTint ?? '#ffb070';
     const on = config.on ?? true;
@@ -99,10 +96,10 @@ const LightBulb = ({ id, config, animations, mouseMove, settings, onObjectReady,
         if (!light)
             return;
         const p = power.current;
-        const lv = live.current;
-        const warmup = Math.max(num(lv.warmup, config.warmup ?? 0.25), 0);
-        const flicker = Math.min(Math.max(num(lv.flicker, config.flicker ?? 0), 0), 1);
-        const haloAmount = Math.min(Math.max(num(lv.halo, config.halo ?? 1), 0), 2);
+        const cfg = merged.current;
+        const warmup = Math.max(num(cfg.warmup, 0.25), 0);
+        const flicker = Math.min(Math.max(num(cfg.flicker, 0), 0), 1);
+        const haloAmount = Math.min(Math.max(num(cfg.halo, 1), 0), 2);
         if (light.intensity !== p.written)
             p.base = light.intensity;
         const target = on ? 1 : 0;

package/dist/components/particles/BioluminescentWakeParticles.d.ts

@@ -1,7 +1,9 @@
 import React from 'react';
-import type { ObjectAnimations, BioluminescentWakeParticlesConfig } from '@3driseai/3drise-core';
+import type { ObjectAnimations, BioluminescentWakeParticlesConfig, MouseMoveDomain } from '@3driseai/3drise-core';
 import type { ObjectReadyProps } from '../../types/objectReady';
 export interface BioluminescentWakeParticlesProps extends ObjectReadyProps {
+    /** Pointer bindings for this object's config knobs (mouseMove.particles). */
+    mouseMove?: MouseMoveDomain;
     /** Scene object id: the controller finds the live-edit handle by it. */
     id?: string;
     /** World size of the object (units); the object's transform scales it further. */

package/dist/components/particles/BioluminescentWakeParticles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BioluminescentWakeParticles.d.ts","sourceRoot":"","sources":["../../../src/components/particles/BioluminescentWakeParticles.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmE,MAAM,OAAO,CAAC;AAIxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,iCAAiC,EAAE,MAAM,uBAAuB,CAAC;AAMjG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,MAAM,WAAW,gCAAiC,SAAQ,gBAAgB;IACtE,wEAAwE;IACxE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iCAAiC,CAAC;IAC1C,sFAAsF;IACtF,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACjC;AA09BD,QAAA,MAAM,2BAA2B,EAAE,KAAK,CAAC,EAAE,CAAC,gCAAgC,CAiD3E,CAAC;AAEF,eAAe,2BAA2B,CAAC"}
+{"version":3,"file":"BioluminescentWakeParticles.d.ts","sourceRoot":"","sources":["../../../src/components/particles/BioluminescentWakeParticles.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmE,MAAM,OAAO,CAAC;AAIxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,iCAAiC,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAMlH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,MAAM,WAAW,gCAAiC,SAAQ,gBAAgB;IACtE,6EAA6E;IAC7E,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,wEAAwE;IACxE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iCAAiC,CAAC;IAC1C,sFAAsF;IACtF,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACjC;AA09BD,QAAA,MAAM,2BAA2B,EAAE,KAAK,CAAC,EAAE,CAAC,gCAAgC,CAqD3E,CAAC;AAEF,eAAe,2BAA2B,CAAC"}

package/dist/components/particles/BioluminescentWakeParticles.js

@@ -3,7 +3,7 @@ import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react'
 import * as THREE from 'three';
 import { useFrame } from '@react-three/fiber';
 import { GENERATIVE_PARTICLES_ANIMATABLE } from '@3driseai/3drise-core';
-import { applyConfigKeyframeAnimations } from '../../utils/configAnimations.js';
+import { applyConfigKeyframeAnimations, applyConfigMouseMove } from '../../utils/configAnimations.js';
 import { createPointerUniforms, stepPointerField, usePointerField } from '../../utils/pointerField.js';
 import { createTrailUniforms, applyTrailConfig, createCpuTrail } from '../../utils/particleTrails.js';
 import { useObjectReady } from '../../hooks/useObjectReady.js';
@@ -1103,7 +1103,7 @@ const DEFAULTS = {
 const STRUCTURAL = ['particleCount', 'seed', 'quality'];
 /** Knobs an animation (or mouse move) may drive per frame — generated from applyConfig. */
 const ANIMATABLE = new Set(GENERATIVE_PARTICLES_ANIMATABLE.bioluminescentWake.map((p) => p.value));
-const BioluminescentWakeParticles = ({ id, size, config, animations, onObjectReady, onObjectDispose }) => {
+const BioluminescentWakeParticles = ({ id, size, config, animations, mouseMove, onObjectReady, onObjectDispose }) => {
     const rootRef = useRef(null);
     useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
     const s = size > 0 ? size : 1;
@@ -1135,8 +1135,12 @@ const BioluminescentWakeParticles = ({ id, size, config, animations, onObjectRea
     const pointer = usePointerField();
     useFrame((state, delta) => {
         instance.update(Math.min(delta, 0.1), state.camera, pointer);
-        if (keyframes?.length) {
+        // Keyframes first, pointer on top: a knob bound to both follows the cursor.
+        const pointerBound = !!mouseMove?.enabled && !!mouseMove.properties?.length;
+        if (keyframes?.length || pointerBound) {
             applyConfigKeyframeAnimations(keyframes, animFrom.current, cfg, animOverride.current, performance.now() - animStart.current, ANIMATABLE);
+            if (pointerBound)
+                applyConfigMouseMove(mouseMove.properties, cfg, animOverride.current, state.pointer, ANIMATABLE);
             push(live.current);
         }
     });

package/dist/components/particles/BrownianDustParticles.d.ts

@@ -1,7 +1,9 @@
 import React from 'react';
-import type { ObjectAnimations, BrownianDustParticlesConfig } from '@3driseai/3drise-core';
+import type { ObjectAnimations, BrownianDustParticlesConfig, MouseMoveDomain } from '@3driseai/3drise-core';
 import type { ObjectReadyProps } from '../../types/objectReady';
 export interface BrownianDustParticlesProps extends ObjectReadyProps {
+    /** Pointer bindings for this object's config knobs (mouseMove.particles). */
+    mouseMove?: MouseMoveDomain;
     /** Scene object id: the controller finds the live-edit handle by it. */
     id?: string;
     /** World size of the object (units); the object's transform scales it further. */

package/dist/components/particles/BrownianDustParticles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BrownianDustParticles.d.ts","sourceRoot":"","sources":["../../../src/components/particles/BrownianDustParticles.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmE,MAAM,OAAO,CAAC;AAIxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAM3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,MAAM,WAAW,0BAA2B,SAAQ,gBAAgB;IAChE,wEAAwE;IACxE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,2BAA2B,CAAC;IACpC,sFAAsF;IACtF,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACjC;AA4qBD,QAAA,MAAM,qBAAqB,EAAE,KAAK,CAAC,EAAE,CAAC,0BAA0B,CAiD/D,CAAC;AAEF,eAAe,qBAAqB,CAAC"}
+{"version":3,"file":"BrownianDustParticles.d.ts","sourceRoot":"","sources":["../../../src/components/particles/BrownianDustParticles.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmE,MAAM,OAAO,CAAC;AAIxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAM5G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,MAAM,WAAW,0BAA2B,SAAQ,gBAAgB;IAChE,6EAA6E;IAC7E,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,wEAAwE;IACxE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,2BAA2B,CAAC;IACpC,sFAAsF;IACtF,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACjC;AA4qBD,QAAA,MAAM,qBAAqB,EAAE,KAAK,CAAC,EAAE,CAAC,0BAA0B,CAqD/D,CAAC;AAEF,eAAe,qBAAqB,CAAC"}