@3driseai/3drise-viewer 0.1.39 → 0.1.41

package/dist/components/image/ShardsImage.js

@@ -0,0 +1,470 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import { useFrame } from '@react-three/fiber';
+import { DEFAULT_IMAGE_OBJECTS, IMAGE_OBJECTS_ANIMATABLE } from '@3driseai/3drise-core';
+import { withConfigDefaults } from '../../utils/configAnimations.js';
+import { useObjectReady } from '../../hooks/useObjectReady.js';
+import { useConfigDriver } from '../../hooks/useConfigDriver.js';
+import { stepPointerField, usePointerField } from '../../utils/pointerField.js';
+import { usePictureCycle } from './pictureCycle.js';
+// =============================================================================
+// ShardsImage — one picture as a slab of shards that flip to the next picture
+// =============================================================================
+//
+// Construction (lab: Claude outputs/gallery-lab/shards.mjs): the picture is one slab tessellated into a
+// jittered grid of shards (one InstancedMesh, one draw call). A change of picture is a *front*
+// travelling across the slab (a linear sweep, radial, or random order): each shard, when the front reaches
+// it, lifts off the slab, flips through edge-on about an in-plane axis — the texture is swapped exactly at
+// the edge-on instant, so the swap is never seen — tumbles a little, and lands back in its slot showing
+// the new picture. Nothing moves the slab itself: the shards return exactly to where they started. Idle:
+// slow breathing of the shards and a Ken Burns drift of the picture inside them. The cursor is a field over
+// the slab (tilt / lift / ripple), never a drawn thing.
+//
+// The component keeps the outgoing picture itself while the change plays (uTexA -> uTexB); only the list
+// `config.imageUrls` is stored, shown in turn every `config.interval` seconds (./pictureCycle).
+// `root.userData.applyTexture(url)` is the same door for the displayImage operation (a gallery
+// sending a clicked frame here).
+//
+export const POINTER_MODES = ['tilt', 'lift', 'ripple'];
+export const ORDERS = ['sweep', 'radial', 'random'];
+function mulberry32(a) {
+    return function () {
+        a |= 0;
+        a = (a + 0x6D2B79F5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+const col = (c) => new THREE.Color(c);
+/** A 1×1 dark texture: what the first picture assembles in from. */
+function blankTexture() {
+    const t = new THREE.DataTexture(new Uint8Array([14, 16, 22, 255]), 1, 1);
+    t.colorSpace = THREE.SRGBColorSpace;
+    t.needsUpdate = true;
+    return t;
+}
+// ---------------------------------------------------------------- uniforms
+export function createUniforms() {
+    return {
+        uTexA: { value: null }, uTexB: { value: null },
+        /** cover-fit of each picture into the slab: scale.xy, offset.xy */
+        uFitA: { value: new THREE.Vector4(1, 1, 0, 0) }, uFitB: { value: new THREE.Vector4(1, 1, 0, 0) },
+        uPhase: { value: 1 }, // 1 = idle, showing B
+        uSweep: { value: new THREE.Vector2(1, 0) },
+        uOrder: { value: 0 },
+        uSpread: { value: 0.5 }, uJitter: { value: 0.15 },
+        uLift: { value: 0.35 }, uDrift: { value: 0.08 }, uSpin: { value: 0.6 },
+        uBreathe: { value: 0.5 }, uSeams: { value: 0.12 },
+        uTime: { value: 0 },
+        uHalfH: { value: 0.625 },
+        uKbZoom: { value: 1 }, uKbPan: { value: new THREE.Vector2(0, 0) },
+        uEdgeColor: { value: col('#0b0d12') }, uRimColor: { value: col('#ffd9a6') },
+        uPointerColor: { value: col('#9ad7ff') },
+        uRim: { value: 0.8 }, uIntensity: { value: 1 }, uOpacity: { value: 1 },
+        uPointer: { value: new THREE.Vector3(0, 0, 0) }, uPointerVel: { value: new THREE.Vector3(0, 0, 0) },
+        uPointerActive: { value: 0 }, uPointerMode: { value: 0 },
+        uPointerStrength: { value: 1 }, uPointerRadius: { value: 0.6 }, uPointerT: { value: 0 },
+        uBackColor: { value: col('#101218') }, uFlight: { value: 0 },
+    };
+}
+/** Every non-structural knob reaches a uniform here — the single door; the animatable list is what it writes. */
+export function applyConfig(u, c) {
+    const num = (k, v) => { if (typeof v === 'number')
+        u[k].value = v; };
+    const color = (k, v) => {
+        const target = u[k].value;
+        if (v?.isColor)
+            target.copy(v);
+        else if (typeof v === 'string')
+            target.set(v);
+    };
+    num('uSpread', c.spread);
+    num('uJitter', c.delayJitter);
+    num('uLift', c.lift);
+    num('uDrift', c.drift);
+    num('uSpin', c.spin);
+    num('uBreathe', c.breathe);
+    num('uSeams', c.seams);
+    num('uRim', c.rim);
+    num('uIntensity', c.intensity);
+    num('uOpacity', c.opacity);
+    color('uEdgeColor', c.edgeColor);
+    color('uRimColor', c.rimColor);
+    color('uBackColor', c.backColor);
+    color('uPointerColor', c.pointerColor);
+    num('uPointerStrength', c.pointerStrength);
+    num('uPointerRadius', c.pointerRadius);
+    if (typeof c.pointerMode === 'string')
+        u.uPointerMode.value = POINTER_MODES.indexOf(c.pointerMode);
+    if (typeof c.order === 'string')
+        u.uOrder.value = Math.max(0, ORDERS.indexOf(c.order));
+    if (typeof c.sweepAngle === 'number') {
+        const a = THREE.MathUtils.degToRad(c.sweepAngle);
+        u.uSweep.value.set(Math.cos(a), Math.sin(a));
+    }
+}
+// ---------------------------------------------------------------- GLSL
+const common = /* glsl */ `
+    #define PI 3.14159265
+    vec3 rot(vec3 p, vec3 ax, float a){ float c = cos(a), s = sin(a); return p * c + cross(ax, p) * s + ax * dot(ax, p) * (1.0 - c); }
+    float hash1(float n){ return fract(sin(n * 127.1) * 43758.5453); }
+`;
+const heroVert = /* glsl */ `
+    ${common}
+    attribute vec4 aC0;     // corner 0, corner 1 (slab units)
+    attribute vec4 aC1;     // corner 2, corner 3
+    attribute vec4 aMeta;   // centre.xy, hash, hash2
+    uniform float uPhase, uOrder, uSpread, uJitter, uLift, uDrift, uSpin, uBreathe, uTime, uHalfH;
+    uniform vec2 uSweep;
+    uniform vec3 uPointer; uniform float uPointerActive, uPointerMode, uPointerStrength, uPointerRadius, uPointerT;
+    varying vec2 vUv; varying vec2 vTile; varying vec3 vN; varying vec3 vV;
+    varying float vLayer; varying float vFlight; varying float vPw; varying float vSeamW;
+
+    void main(){
+        vec2 c0 = aC0.xy, c1 = aC0.zw, c2 = aC1.xy, c3 = aC1.zw;
+        vec2 corner = mix(mix(c0, c1, uv.x), mix(c3, c2, uv.x), uv.y);
+        vec2 ctr = aMeta.xy; float h1 = aMeta.z, h2 = aMeta.w;
+        vec2 cn = vec2(ctr.x, ctr.y / uHalfH);           // slab normalised to [-1,1]^2
+
+        // --- departure order: a front travelling over the slab -------------
+        float ord;
+        if (uOrder < 0.5)       ord = dot(cn, uSweep) * 0.5 + 0.5;
+        else if (uOrder < 1.5)  ord = length(cn) * 0.7071;
+        else                    ord = h1;
+        ord = mix(ord, h2, uJitter);
+        float w = max(uSpread, 0.02);
+        float s = clamp((uPhase * (1.0 + w) - ord) / w, 0.0, 1.0);
+        s = s * s * (3.0 - 2.0 * s);
+        float f = sin(PI * s);                            // 0 at rest, 1 at apex, 0 landed
+
+        // --- flip about an in-plane axis, edge-on at s = 0.5 ---------------
+        vec2 axP;
+        if (uOrder < 0.5)      axP = vec2(-uSweep.y, uSweep.x);
+        else if (uOrder < 1.5) axP = vec2(-cn.y, cn.x) / max(length(cn), 1e-3);
+        else                   axP = vec2(cos(h2 * 6.2832), sin(h2 * 6.2832));
+        vec3 axis = normalize(vec3(axP, 0.0));
+        float ang = PI * s - PI * step(0.5, s);           // 0 -> pi/2 | -pi/2 -> 0
+        vec3 lp = vec3(corner - ctr, 0.0) * (1.0 - 0.18 * f);
+        vec3 n = vec3(0.0, 0.0, 1.0);
+        lp = rot(lp, axis, ang); n = rot(n, axis, ang);
+        vec3 tax = normalize(vec3(h1 - 0.5, h2 - 0.5, hash1(h1 + h2) - 0.5));
+        float tum = uSpin * f * (h2 - 0.5) * 2.0;
+        lp = rot(lp, tax, tum); n = rot(n, tax, tum);
+
+        // --- flight path --------------------------------------------------
+        vec3 disp = vec3((vec2(h1, h2) - 0.5) * 2.0 * uDrift * f + uSweep * uDrift * f * 0.5, uLift * f);
+        // idle relief: two slow waves through the slab (shear, no net motion)
+        float br = sin(ctr.x * 2.3 + uTime * 0.35) * sin(ctr.y * 3.1 - uTime * 0.27) + 0.5 * sin((ctr.x + ctr.y) * 4.0 + uTime * 0.5);
+        disp.z += uBreathe * 0.03 * br;
+        float tilt = uBreathe * 0.06 * (sin(ctr.y * 3.1 + uTime * 0.3) * 0.5 + 0.5 * sin(ctr.x * 2.0 - uTime * 0.21));
+        lp = rot(lp, vec3(1.0, 0.0, 0.0), tilt); n = rot(n, vec3(1.0, 0.0, 0.0), tilt);
+
+        // --- pointer field ------------------------------------------------
+        vec2 dp = ctr - uPointer.xy; float d = length(dp);
+        float pw = uPointerActive * smoothstep(uPointerRadius, 0.0, d);
+        if (uPointerMode > -0.5) {
+            if (uPointerMode < 0.5) {                      // tilt: shards face the cursor
+                vec3 tax2 = normalize(vec3(-dp.y, dp.x, 0.0) + 1e-4);
+                float ta = -pw * uPointerStrength * 0.8;
+                lp = rot(lp, tax2, ta); n = rot(n, tax2, ta);
+            } else if (uPointerMode < 1.5) {               // lift: shards float up under the cursor
+                disp.z += pw * uPointerStrength * 0.4;
+                lp *= 1.0 + 0.12 * pw;
+            } else {                                       // ripple: rings run out from the cursor
+                float rp = sin(d * 16.0 - uPointerT * 6.0) * exp(-d * 2.4) * uPointerActive * uPointerStrength * 0.09;
+                disp.z += rp;
+                vec3 tax3 = normalize(vec3(-dp.y, dp.x, 0.0) + 1e-4);
+                float ta = cos(d * 16.0 - uPointerT * 6.0) * exp(-d * 2.4) * uPointerActive * uPointerStrength * 0.35;
+                lp = rot(lp, tax3, ta); n = rot(n, tax3, ta);
+            }
+        } else { pw = 0.0; }
+
+        vec3 p = vec3(ctr, 0.0) + lp + disp;
+        vUv = vec2(corner.x * 0.5 + 0.5, corner.y / uHalfH * 0.5 + 0.5);
+        vTile = uv;
+        vSeamW = 0.009 / max(0.5 * (length(c1 - c0) + length(c3 - c0)), 1e-3);   // seam width in tile uv, constant in slab units
+        vLayer = step(0.5, s);
+        vFlight = f; vPw = pw;
+        vec4 mv = modelViewMatrix * vec4(p, 1.0);
+        vN = normalize(normalMatrix * n); vV = -mv.xyz;
+        gl_Position = projectionMatrix * mv;
+    }
+`;
+const heroFrag = /* glsl */ `
+    uniform sampler2D uTexA, uTexB;
+    uniform vec4 uFitA, uFitB;
+    uniform float uKbZoom; uniform vec2 uKbPan;
+    uniform vec3 uEdgeColor, uRimColor, uPointerColor;
+    uniform float uRim, uIntensity, uOpacity, uSeams;
+    varying vec2 vUv; varying vec2 vTile; varying vec3 vN; varying vec3 vV;
+    varying float vLayer; varying float vFlight; varying float vPw; varying float vSeamW;
+    void main(){
+        vec2 uv = (vUv - 0.5) * uKbZoom + 0.5 + uKbPan;
+        vec3 ca = texture2D(uTexA, uv * uFitA.xy + uFitA.zw).rgb;
+        vec3 cb = texture2D(uTexB, uv * uFitB.xy + uFitB.zw).rgb;
+        vec3 c = mix(ca, cb, vLayer);
+        vec3 N = normalize(vN); vec3 V = normalize(vV);
+        float ndv = abs(dot(N, V));
+        // shards in flight are lit as little slabs; at rest the picture is untouched
+        vec3 L = normalize(vec3(0.35, 0.55, 0.75));
+        float lam = 0.72 + 0.28 * max(dot(N, L), 0.0);
+        c *= mix(1.0, lam, clamp(vFlight * 2.0 + vPw, 0.0, 1.0));
+        // bevel / seam
+        vec2 e = min(vTile, 1.0 - vTile); float dm = min(e.x, e.y);
+        float fw = fwidth(dm) * 1.5;
+        float seam = 1.0 - smoothstep(0.0, min(vSeamW, 0.2) + fw, dm);
+        float seamVis = mix(uSeams * 0.6, 0.85, clamp(vFlight * 3.0 + vPw, 0.0, 1.0));
+        c = mix(c, uEdgeColor, seam * seamVis);
+        // light caught on the tilted faces
+        float rim = pow(1.0 - ndv, 3.0) * uRim * (0.25 + vFlight + vPw * 0.6);
+        vec3 rimCol = mix(uRimColor, uPointerColor, vPw);
+        c += rimCol * rim * (1.0 - seam * 0.5) + uPointerColor * vPw * 0.08;
+        gl_FragColor = vec4(c * uIntensity, uOpacity);
+        #include <tonemapping_fragment>
+        #include <colorspace_fragment>
+    }
+`;
+const backVert = /* glsl */ `
+    varying vec2 vUv;
+    void main(){ vUv = uv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }
+`;
+const backFrag = /* glsl */ `
+    uniform vec3 uBackColor; uniform float uFlight, uOpacity;
+    varying vec2 vUv;
+    void main(){
+        vec2 q = vUv - 0.5; float r = length(q * vec2(1.0, 1.4));
+        float vig = smoothstep(0.2, 0.75, r);
+        vec3 c = uBackColor * (1.0 - 0.6 * vig) * (1.0 - 0.35 * uFlight);
+        float a = (1.0 - smoothstep(0.55, 0.78, r)) * uOpacity;
+        gl_FragColor = vec4(c * a, a);
+        #include <tonemapping_fragment>
+        #include <colorspace_fragment>
+    }
+`;
+/** The slab: a jittered grid of shards (shared corners, so no gaps) and a dark backing. */
+function build(u, c, aspect) {
+    const halfH = 1 / Math.max(0.2, aspect);
+    u.uHalfH.value = halfH;
+    const rnd = mulberry32(c.seed | 0);
+    const cols = Math.max(1, c.cols | 0), rows = Math.max(1, c.rows | 0);
+    const vx = new Float32Array((cols + 1) * (rows + 1) * 2);
+    for (let j = 0; j <= rows; j++)
+        for (let i = 0; i <= cols; i++) {
+            const k = (j * (cols + 1) + i) * 2;
+            const jx = (i === 0 || i === cols) ? 0 : (rnd() - 0.5) * c.tiling * 0.9;
+            const jy = (j === 0 || j === rows) ? 0 : (rnd() - 0.5) * c.tiling * 0.9;
+            vx[k] = -1 + ((i + jx) / cols) * 2;
+            vx[k + 1] = -halfH + ((j + jy) / rows) * 2 * halfH;
+        }
+    const n = cols * rows;
+    const aC0 = new Float32Array(n * 4), aC1 = new Float32Array(n * 4), aMeta = new Float32Array(n * 4);
+    let q = 0;
+    const v = (ii, jj) => { const k = (jj * (cols + 1) + ii) * 2; return [vx[k], vx[k + 1]]; };
+    for (let j = 0; j < rows; j++)
+        for (let i = 0; i < cols; i++) {
+            const p0 = v(i, j), p1 = v(i + 1, j), p2 = v(i + 1, j + 1), p3 = v(i, j + 1);
+            aC0.set([p0[0], p0[1], p1[0], p1[1]], q * 4);
+            aC1.set([p2[0], p2[1], p3[0], p3[1]], q * 4);
+            aMeta.set([(p0[0] + p1[0] + p2[0] + p3[0]) / 4, (p0[1] + p1[1] + p2[1] + p3[1]) / 4, rnd(), rnd()], q * 4);
+            q++;
+        }
+    const geo = new THREE.InstancedBufferGeometry();
+    const base = new THREE.PlaneGeometry(1, 1);
+    geo.index = base.index;
+    geo.attributes.position = base.attributes.position;
+    geo.attributes.uv = base.attributes.uv;
+    geo.setAttribute('aC0', new THREE.InstancedBufferAttribute(aC0, 4));
+    geo.setAttribute('aC1', new THREE.InstancedBufferAttribute(aC1, 4));
+    geo.setAttribute('aMeta', new THREE.InstancedBufferAttribute(aMeta, 4));
+    geo.instanceCount = n;
+    geo.boundingSphere = new THREE.Sphere(new THREE.Vector3(0, 0, 0), 1.8);
+    const heroMat = new THREE.ShaderMaterial({ uniforms: u, vertexShader: heroVert, fragmentShader: heroFrag, side: THREE.DoubleSide, transparent: true, depthWrite: true });
+    const hero = new THREE.Mesh(geo, heroMat);
+    hero.frustumCulled = false;
+    hero.raycast = () => { };
+    const backMat = new THREE.ShaderMaterial({ uniforms: u, vertexShader: backVert, fragmentShader: backFrag, transparent: true, depthWrite: false, premultipliedAlpha: true });
+    const back = new THREE.Mesh(new THREE.PlaneGeometry(2.6, halfH * 2 + 0.6), backMat);
+    back.position.z = -0.05;
+    back.renderOrder = -1;
+    // the picture's pick proxy: clicks (interactions) and the selection box land on the slab
+    const pick = new THREE.Mesh(new THREE.PlaneGeometry(2, halfH * 2), new THREE.MeshBasicMaterial({ visible: false }));
+    const object = new THREE.Group();
+    object.add(back, hero, pick);
+    return {
+        object, halfH,
+        dispose() {
+            geo.dispose();
+            base.dispose();
+            back.geometry.dispose();
+            pick.geometry.dispose();
+            heroMat.dispose();
+            backMat.dispose();
+            pick.material.dispose();
+        },
+    };
+}
+/** cover-fit: the picture (w×h) fills the slab (aspect) — scale.xy, offset.xy for the uv. */
+function fitOf(tex, aspect, out) {
+    const img = tex?.image;
+    const iw = img?.width || 1, ih = img?.height || 1;
+    const ia = iw / ih;
+    if (ia > aspect) {
+        const s = aspect / ia;
+        out.set(s, 1, (1 - s) / 2, 0);
+    }
+    else {
+        const s = ia / aspect;
+        out.set(1, s, 0, (1 - s) / 2);
+    }
+}
+const loader = new THREE.TextureLoader();
+loader.setCrossOrigin('anonymous');
+function loadPicture(url) {
+    return new Promise((resolve, reject) => loader.load(url, (t) => {
+        t.colorSpace = THREE.SRGBColorSpace;
+        t.wrapS = t.wrapT = THREE.ClampToEdgeWrapping;
+        t.anisotropy = 4;
+        resolve(t);
+    }, undefined, reject));
+}
+// =============================================================================
+const DEFAULTS = DEFAULT_IMAGE_OBJECTS.shards;
+/** Knobs that rebuild the object: never live, they change once, on commit. */
+const STRUCTURAL = ['imageUrls', 'cols', 'rows', 'tiling', 'aspect', 'seed'];
+/** Knobs a keyframe or pointer binding may drive per frame — exactly what applyConfig pushes. */
+const ANIMATABLE = new Set(IMAGE_OBJECTS_ANIMATABLE.shards.map((p) => p.value));
+const POINTER_NORMAL = new THREE.Vector3(0, 0, 1);
+const POINTER_ANCHOR = new THREE.Vector3(0, 0, 0);
+/**
+ * A picture tessellated into shards that lift, flip edge-on and land as the next picture in a travelling wave whenever the image changes; the cursor tilts, lifts or ripples the shards. Use for hero images, portfolios and product reveals.
+ */
+const ShardsImage = ({ config, id, keyframes, mouseMove, onObjectReady, onObjectDispose }) => {
+    const rootRef = useRef(null);
+    useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
+    const cfg = useMemo(() => withConfigDefaults(DEFAULTS, config), [config]);
+    const uniforms = useMemo(() => createUniforms(), []);
+    const blank = useMemo(() => blankTexture(), []);
+    // ---- pictures: current (B) and the one leaving (A); the slab's aspect comes from the first picture unless set
+    const st = useRef({
+        aspect: 0, shown: '', texA: null, texB: null,
+        phase: 1, pending: null, loading: '', time: 0, shownT: 0, kbDir: new THREE.Vector2(1, 0), pointerT: 0,
+        cache: new Map(),
+    });
+    const [aspectKey, setAspectKey] = React.useState(0);
+    const aspect = cfg.aspect > 0 ? cfg.aspect : (st.current.aspect || 1.6);
+    const instance = useMemo(() => build(uniforms, cfg, aspect), [uniforms, cfg.cols, cfg.rows, cfg.tiling, cfg.seed, aspect, aspectKey]); // eslint-disable-line react-hooks/exhaustive-deps
+    useEffect(() => () => instance.dispose(), [instance]);
+    useEffect(() => {
+        fitOf(st.current.texA, aspect, uniforms.uFitA.value);
+        fitOf(st.current.texB, aspect, uniforms.uFitB.value);
+    }, [instance, aspect, uniforms]);
+    /** The one door for a picture change: loads it, then runs the change front (queued while one plays). */
+    const show = useCallback((url) => {
+        const s = st.current;
+        if (!url || url === s.shown || url === s.loading)
+            return;
+        s.loading = url;
+        const got = s.cache.get(url);
+        const ready = got ? Promise.resolve(got) : loadPicture(url).then((t) => { s.cache.set(url, t); return t; });
+        ready.then((tex) => {
+            if (s.loading !== url)
+                return; // superseded
+            s.loading = '';
+            if (!s.texB) { // first picture: it assembles in from the backing
+                if (cfg.aspect <= 0) {
+                    const img = tex.image;
+                    s.aspect = img.width / img.height;
+                    setAspectKey((k) => k + 1);
+                }
+                s.texA = blank;
+                s.texB = tex;
+                s.shown = url;
+                s.phase = 0;
+                uniforms.uTexA.value = blank;
+                uniforms.uTexB.value = tex;
+                fitOf(blank, aspect, uniforms.uFitA.value);
+                fitOf(tex, s.aspect || aspect, uniforms.uFitB.value);
+                return;
+            }
+            if (s.phase < 1) {
+                s.pending = url;
+                return;
+            }
+            s.texA = s.texB;
+            s.texB = tex;
+            s.shown = url;
+            s.phase = 0;
+            s.shownT = 0;
+            s.kbDir.set(Math.cos(url.length * 2.4), Math.sin(url.length * 2.4)).normalize();
+            uniforms.uTexA.value = s.texA;
+            uniforms.uTexB.value = tex;
+            fitOf(s.texA, aspect, uniforms.uFitA.value);
+            fitOf(tex, aspect, uniforms.uFitB.value);
+        }).catch(() => { if (s.loading === url)
+            s.loading = ''; }); // a missing picture leaves the current one
+    }, [aspect, blank, cfg.aspect, uniforms]);
+    const preload = useCallback((url) => {
+        const s = st.current;
+        if (s.cache.has(url))
+            return;
+        loadPicture(url).then((t) => { if (!s.cache.has(url))
+            s.cache.set(url, t);
+        else
+            t.dispose(); }).catch(() => { });
+    }, []);
+    const busy = useCallback(() => { const s = st.current; return s.phase < 1 || !!s.loading || !!s.pending; }, []);
+    const { showExternal, feed } = usePictureCycle({ urls: cfg.imageUrls, interval: cfg.interval, show, preload, busy });
+    useEffect(() => {
+        const root = rootRef.current;
+        if (!root)
+            return;
+        root.userData.applyTexture = (url) => showExternal(url);
+        root.userData.feedImage = feed; // a gallery's feeds (gallery/kit/feeds.ts)
+        return () => { delete root.userData.applyTexture; delete root.userData.feedImage; };
+    }, [showExternal, feed]);
+    useEffect(() => () => { for (const t of st.current.cache.values())
+        t.dispose(); blank.dispose(); }, [blank]); // eslint-disable-line react-hooks/exhaustive-deps
+    useLayoutEffect(() => { applyConfig(uniforms, cfg); }, [uniforms, cfg]);
+    const push = useCallback((merged) => { applyConfig(uniforms, merged); }, [uniforms]);
+    useConfigDriver({ rootRef, id, family: 'image', base: cfg, structural: STRUCTURAL, allowed: ANIMATABLE, keyframes, mouseMove, push });
+    const pointer = usePointerField();
+    useFrame((state, delta) => {
+        const dt = Math.min(delta, 0.1);
+        const s = st.current;
+        s.time += dt;
+        uniforms.uTime.value = s.time;
+        if (s.phase < 1) {
+            s.phase = Math.min(1, s.phase + dt / Math.max(0.05, cfg.duration));
+            if (s.phase >= 1) {
+                s.texA = s.texB;
+                uniforms.uTexA.value = s.texB;
+                uniforms.uFitA.value.copy(uniforms.uFitB.value);
+                if (s.pending) {
+                    const p = s.pending;
+                    s.pending = null;
+                    show(p);
+                }
+            }
+        }
+        uniforms.uPhase.value = s.phase;
+        uniforms.uFlight.value = s.phase < 1 ? Math.sin(Math.PI * s.phase) : 0;
+        // ken burns: slow zoom-in with a drift, restarting on each picture
+        s.shownT += dt;
+        const kb = 1 - Math.exp(-s.shownT / 9);
+        const zoom = 1 - cfg.kenBurns * 0.14 * kb;
+        uniforms.uKbZoom.value = zoom;
+        uniforms.uKbPan.value.copy(s.kbDir).multiplyScalar((1 - zoom) * 0.5 * kb);
+        // the cursor on the slab's own plane
+        stepPointerField(uniforms, pointer, state.camera, instance.object, 1, dt, POINTER_ANCHOR, POINTER_NORMAL);
+        if (uniforms.uPointerActive.value > 0.01) {
+            s.pointerT += dt;
+            uniforms.uPointerT.value = s.pointerT;
+        }
+    });
+    if (!cfg.enabled)
+        return null;
+    return (_jsx("group", { ref: rootRef, children: _jsx("primitive", { object: instance.object }) }));
+};
+export default ShardsImage;

package/dist/components/image/core/contour.d.ts

@@ -0,0 +1,126 @@
+import * as THREE from 'three';
+export declare const POINTER_MODES: string[];
+export declare const STRUCTURAL: string[];
+export declare function createUniforms(): {
+    uLevels: {
+        value: number;
+    };
+    uLineW: {
+        value: number;
+    };
+    uDepth: {
+        value: number;
+    };
+    uOpen: {
+        value: number;
+    };
+    uSmooth: {
+        value: number;
+    };
+    uIdle: {
+        value: number;
+    };
+    uTint: {
+        value: number;
+    };
+    uLineColor: {
+        value: THREE.Color;
+    };
+    uTexA: {
+        value: any;
+    };
+    uTexB: {
+        value: any;
+    };
+    uFitA: {
+        value: THREE.Vector2;
+    };
+    uFitB: {
+        value: THREE.Vector2;
+    };
+    uP: {
+        value: number;
+    };
+    uHasA: {
+        value: number;
+    };
+    uSeq: {
+        value: number;
+    };
+    uSize: {
+        value: THREE.Vector2;
+    };
+    uTime: {
+        value: number;
+    };
+    uDir: {
+        value: THREE.Vector2;
+    };
+    uSpread: {
+        value: number;
+    };
+    uBlank: {
+        value: THREE.Color;
+    };
+    uIntensity: {
+        value: number;
+    };
+    uOpacity: {
+        value: number;
+    };
+    uBreathe: {
+        value: number;
+    };
+    uPointer: {
+        value: THREE.Vector3;
+    };
+    uPointerVel: {
+        value: THREE.Vector2;
+    };
+    uPointerActive: {
+        value: number;
+    };
+    uPointerMode: {
+        value: number;
+    };
+    uPointerStrength: {
+        value: number;
+    };
+    uPointerRadius: {
+        value: number;
+    };
+    uPointerColor: {
+        value: THREE.Color;
+    };
+};
+export declare function applyConfig(u: any, c: any): void;
+export declare function build(u: any, c: any): {
+    object: THREE.Group<THREE.Object3DEventMap>;
+    materials: THREE.ShaderMaterial[];
+    controls: {
+        show: (t: any) => void;
+        readonly busy: boolean;
+        pic: {
+            st: {
+                A: any;
+                B: any;
+                aspA: number;
+                aspB: number;
+                p: number;
+                dir: number;
+                pending: any;
+                seq: number;
+                frame: number;
+            };
+            show: (tex: any) => void;
+            jump: (tex: any) => void;
+            step: (dt: any) => void;
+            readonly busy: boolean;
+            dispose(): void;
+        };
+    };
+    apply(k: any): void;
+    update(dt: any, pointer: any): void;
+    dispose(): void;
+};
+//# sourceMappingURL=contour.d.ts.map

package/dist/components/image/core/contour.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contour.d.ts","sourceRoot":"","sources":["../../../../src/components/image/core/contour.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,eAAO,MAAM,aAAa,UAAqB,CAAC;AAEhD,eAAO,MAAM,UAAU,UAAgB,CAAC;AAExC,wBAAgB,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAE7B;AACD,wBAAgB,WAAW,CAAC,CAAC,KAAA,EAAE,CAAC,KAAA,QAG/B;AAgED,wBAAgB,KAAK,CAAC,CAAC,KAAA,EAAE,CAAC,KAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuBzB"}