@wildo-ai/presets-components-3d 1.1.6

package/dist/esm/frame/frame-renderer.js

@@ -0,0 +1,635 @@
+import { CustomBlending, Mesh, MinEquation, PlaneGeometry, ShaderMaterial, Vector2, Vector3 } from 'three';
+import { ShellRegion } from '@wildo-ai/presets-components-models';
+import { FRAME_BODY_FRAGMENT_SHADER, FRAME_SHADOW_FRAGMENT_SHADER, FRAME_VERTEX_SHADER } from './frame-shaders.js';
+import { regionCentreInFrameUnits } from '../shell-region-measurement.js';
+import { frameChoreography, rimsFocusedZone } from '../layout/layout-3d-transition-choreography.js';
+import { Layout3DFrameChoreography, Layout3DZoneFocusTransition } from '../layout/layout-3d-vocabulary.js';
+/** Draw order: the background, then every shadow, then every body — so no shadow lands on a slab. */
+var FrameRenderOrder;
+(function (FrameRenderOrder) {
+    FrameRenderOrder[FrameRenderOrder["BACKGROUND"] = 0] = "BACKGROUND";
+    FrameRenderOrder[FrameRenderOrder["SHADOW"] = 1] = "SHADOW";
+    FrameRenderOrder[FrameRenderOrder["BODY"] = 2] = "BODY";
+    /** The focused zone's rim, over the content slab it sits in. */
+    FrameRenderOrder[FrameRenderOrder["ZONE_RIM"] = 3] = "ZONE_RIM";
+})(FrameRenderOrder || (FrameRenderOrder = {}));
+/**
+ * What starts a transition of the frame (#1826). The driver reports each start to its host, which is how a live
+ * probe tells that a choreography ran rather than inferring it from draws.
+ */
+export var FrameTransitionTrigger;
+(function (FrameTransitionTrigger) {
+    /** A structural zone's top entry became another place. Plays the layout's `navigation` choreography. */
+    FrameTransitionTrigger["NAVIGATION"] = "navigation";
+    /** The sidebar's width changed while it stayed on screen. Plays the layout's `sidebarResize` choreography. */
+    FrameTransitionTrigger["SIDEBAR_RESIZE"] = "sidebar-resize";
+    /** The focused zone of a split changed, and the layout rims it. */
+    FrameTransitionTrigger["ZONE_FOCUS"] = "zone-focus";
+})(FrameTransitionTrigger || (FrameTransitionTrigger = {}));
+/** What a {@link FrameRenderer.pulse} call did. */
+export var FramePulseOutcome;
+(function (FramePulseOutcome) {
+    /** Nothing plays: no choreography for the trigger, reduced motion, or no appearance yet. */
+    FramePulseOutcome["NOT_PLAYED"] = "not-played";
+    /** A new pulse started (from rest, or a new rise out of a settle): a transition the driver reports. */
+    FramePulseOutcome["STARTED"] = "started";
+    /** The trigger's pulse was already rising and keeps rising: nothing new to report. */
+    FramePulseOutcome["ALREADY_RISING"] = "already-rising";
+})(FramePulseOutcome || (FramePulseOutcome = {}));
+const PRESENCE = 18;
+const SLAB_SIZE = PRESENCE + 1;
+/** A spring is considered at rest once it is this close to its target and this slow. */
+const SPRING_REST = 1e-3;
+/** Integration step for a spring, in seconds: small enough to stay stable for any stiffness a theme declares. */
+const SPRING_STEP_SECONDS = 1 / 240;
+/**
+ * The frame's scene, driven imperatively (#1823).
+ *
+ * It owns the meshes and their uniforms and nothing else: WHEN to draw is the canvas driver's decision. Every
+ * method is a plain state change plus {@link tick}, which applies the state for an instant and says whether
+ * anything is still animating — so the whole scene logic runs, and is tested, without a WebGL context.
+ *
+ * Hover emphasises the RIM only, and its progress is clamped to 0–1 even when a spring overshoots. The frost never
+ * changes on hover, so hover cannot take a colour outside the contrast bound the appearance derivation proved.
+ */
+export class FrameRenderer {
+    group;
+    geometry = new PlaneGeometry(1, 1);
+    backgroundMesh;
+    slabs = [];
+    boxes = [];
+    viewport = { width: 0, height: 0 };
+    layoutSignature = '';
+    /** What is on screen now: the last frame applied, mid-cross-fade included. A new appearance fades FROM this. */
+    shown = null;
+    tween = null;
+    appearance = null;
+    hovered = null;
+    hover = new Map();
+    choreographies;
+    rimsFocusedZone;
+    pulses = new Map();
+    /** The zone the rim is moving toward, or null. */
+    rimmed = null;
+    zones = [];
+    zoneSignature = '';
+    focusedZone = null;
+    /** Each zone's rim emphasis, 0 to 1, stepped exactly like a hover emphasis. */
+    zoneEmphasis = new Map();
+    zoneRims = [];
+    /**
+     * @param transitions What the layout plays on a navigation, a sidebar resize and a zone focus. Defaults to nothing:
+     *   a renderer with no layout behind it (a test, a probe) draws the regions and moves only on appearance and hover.
+     */
+    constructor(group, transitions = {
+        navigation: Layout3DFrameChoreography.NONE,
+        sidebarResize: Layout3DFrameChoreography.NONE,
+        zoneFocus: Layout3DZoneFocusTransition.NONE,
+    }) {
+        this.group = group;
+        this.choreographies = {
+            [FrameTransitionTrigger.NAVIGATION]: frameChoreography(transitions.navigation),
+            [FrameTransitionTrigger.SIDEBAR_RESIZE]: frameChoreography(transitions.sidebarResize),
+        };
+        this.rimsFocusedZone = rimsFocusedZone(transitions.zoneFocus);
+        this.backgroundMesh = new Mesh(this.geometry, bodyMaterial());
+        this.backgroundMesh.renderOrder = FrameRenderOrder.BACKGROUND;
+        this.backgroundMesh.visible = false;
+        group.add(this.backgroundMesh);
+    }
+    /**
+     * The appearance to draw. With `animate`, the change cross-fades over the appearance's transition time —
+     * except when the FOREGROUND changed (a light/dark switch): text switches colour at once, and a backdrop
+     * halfway between two modes is bounded against neither foreground, so the frame switches at once too.
+     */
+    setAppearance(appearance, options) {
+        const previous = this.appearance;
+        const target = displayedOf(appearance, this.shown);
+        if (appearance)
+            this.appearance = appearance;
+        // Reduced motion turned on mid-hover: the frame is static from now on, so the emphasis goes at once.
+        if (appearance && !appearance.hoverResponse) {
+            this.hovered = null;
+            this.hover.clear();
+            this.pulses.clear();
+            this.zoneEmphasis.clear();
+        }
+        // A reduced-motion switch (either way) or a new gesture spring changes what the focused zone's rim should do.
+        this.retargetZoneEmphasis();
+        const seconds = appearance?.transitionSeconds ?? 0;
+        const foregroundChanged = Boolean(previous && appearance && !sameColor(previous.foreground, appearance.foreground));
+        if (!options.animate || !this.shown || seconds <= 0 || foregroundChanged) {
+            this.shown = target;
+            this.tween = null;
+            return;
+        }
+        this.tween = { from: fadeInFrom(this.shown, target), to: target, start: null, seconds, easing: appearance?.transitionEasing ?? [0, 0, 1, 1] };
+    }
+    /** The measured regions. Returns false when nothing moved, so the caller can skip the frame entirely. */
+    setLayout(boxes, viewport) {
+        const signature = `${viewport.width}x${viewport.height}|${boxes.map((b) => `${b.region}:${b.left},${b.top},${b.width},${b.height},${b.glass ? 'g' : ''}`).join(';')}`;
+        this.boxes = boxes;
+        this.viewport = viewport;
+        // A region that left takes its hover state with it (an organization switch remounts regions).
+        const present = new Set(boxes.map((box) => box.element));
+        for (const key of this.hover.keys())
+            if (!present.has(key))
+                this.hover.delete(key);
+        if (this.hovered && !present.has(this.hovered))
+            this.hovered = null;
+        if (signature === this.layoutSignature)
+            return false;
+        this.layoutSignature = signature;
+        return true;
+    }
+    /**
+     * The region element under the pointer, or null. Its rim moves toward the hover opacity — unless the
+     * appearance says the frame is static (reduced motion). Returns whether anything will change on screen.
+     */
+    setHovered(element) {
+        const next = this.appearance?.hoverResponse ? element : null;
+        if (next === this.hovered)
+            return false;
+        for (const [key, target] of [[this.hovered, 0], [next, 1]]) {
+            if (!key)
+                continue;
+            const state = this.hover.get(key) ?? { value: 0, target: 0, velocity: 0, tween: null, spring: null, lastTick: null };
+            state.target = target;
+            state.spring = this.appearance?.hoverSpring ?? null;
+            state.tween = state.spring ? null : { from: state.value, to: target, start: null, seconds: this.appearance?.hoverSeconds ?? 0, easing: this.appearance?.hoverEasing ?? [0, 0, 1, 1] };
+            state.lastTick = null;
+            this.hover.set(key, state);
+        }
+        this.hovered = next;
+        return true;
+    }
+    /**
+     * A shell state changed (#1826): play the layout's choreography for that trigger. Nothing plays when the layout
+     * declares none for it, under reduced motion (the frame is static), or when the theme's motion duration is zero.
+     * Says whether a pulse STARTED, was already rising, or nothing plays.
+     */
+    pulse(trigger) {
+        const appearance = this.appearance;
+        const choreography = this.choreographies[trigger];
+        if (!choreography.plays || !appearance || !appearance.hoverResponse || appearance.transitionSeconds <= 0)
+            return FramePulseOutcome.NOT_PLAYED;
+        // Already rising: let it rise. Restarting would re-anchor its clock on every call, and a sidebar calls on every
+        // frame of its width animation, so the pulse would never leave where it stood until the sidebar stopped.
+        if (this.pulses.get(trigger)?.rising)
+            return FramePulseOutcome.ALREADY_RISING;
+        const halfSeconds = (appearance.transitionSeconds * choreography.durationFactor) / 2;
+        const from = this.pulses.get(trigger)?.value ?? 0;
+        this.pulses.set(trigger, { rising: true, value: from, tween: { from, to: 1, start: null, seconds: halfSeconds, easing: appearance.transitionEasing } });
+        return FramePulseOutcome.STARTED;
+    }
+    /** The zone whose rim is shown or moving in, or null: what the driver compares to report a zone-focus transition. */
+    rimmedZone() {
+        return this.rimmed;
+    }
+    /**
+     * The navigation zones inside the content region, and the focused one (the navigation state's `focusedZone`), or
+     * null. When the layout rims the focused zone and two or more zones are side by side, the focused one's rim moves
+     * toward full emphasis and every other zone's back to none. Returns whether anything will change on screen.
+     */
+    setZones(zones, focused) {
+        const signature = zones.map((zone) => `${zone.left},${zone.top},${zone.width},${zone.height}`).join(';');
+        const moved = signature !== this.zoneSignature;
+        this.zoneSignature = signature;
+        this.zones = zones;
+        const present = new Set(zones.map((zone) => zone.element));
+        for (const key of this.zoneEmphasis.keys())
+            if (!present.has(key))
+                this.zoneEmphasis.delete(key);
+        this.focusedZone = focused && present.has(focused) ? focused : null;
+        return this.retargetZoneEmphasis() || moved;
+    }
+    /** Whether a cross-fade, a hover or zone emphasis, or a pulse is still moving: the only reasons to draw when no region moved. */
+    hasPendingMotion() {
+        if (this.tween || this.pulses.size > 0)
+            return true;
+        for (const state of this.hover.values())
+            if (!hoverSettled(state))
+                return true;
+        for (const state of this.zoneEmphasis.values())
+            if (!hoverSettled(state))
+                return true;
+        return false;
+    }
+    /** Apply the state for instant `now` (ms). Returns true while a cross-fade or a hover emphasis is still moving. */
+    tick(now) {
+        if (this.tween) {
+            const { eased, done } = advance(this.tween, now);
+            if (done) {
+                this.shown = this.tween.to;
+                this.tween = null;
+            }
+            else {
+                this.shown = interpolateFrame(this.tween.from, this.tween.to, eased);
+            }
+        }
+        for (const [key, state] of this.hover) {
+            stepHover(state, now);
+            if (hoverSettled(state) && state.target === 0)
+                this.hover.delete(key);
+        }
+        for (const [key, state] of this.zoneEmphasis) {
+            stepHover(state, now);
+            if (hoverSettled(state) && state.target === 0)
+                this.zoneEmphasis.delete(key);
+        }
+        for (const [trigger, pulse] of this.pulses) {
+            const { eased, done } = advance(pulse.tween, now);
+            const { from, to } = pulse.tween;
+            pulse.value = from + (to - from) * eased;
+            if (done && pulse.rising) {
+                const easing = this.appearance?.transitionEasing ?? [0, 0, 1, 1];
+                this.pulses.set(trigger, { rising: false, value: 1, tween: { from: 1, to: 0, start: now, seconds: pulse.tween.seconds, easing } });
+            }
+            else if (done) {
+                this.pulses.delete(trigger);
+            }
+        }
+        this.apply(this.shown);
+        return this.hasPendingMotion();
+    }
+    dispose() {
+        this.group.remove(this.backgroundMesh);
+        this.backgroundMesh.material.dispose();
+        for (const slab of this.slabs) {
+            this.group.remove(slab.body, slab.shadow);
+            slab.body.material.dispose();
+            slab.shadow.material.dispose();
+        }
+        this.slabs.length = 0;
+        for (const rim of this.zoneRims) {
+            this.group.remove(rim);
+            rim.material.dispose();
+        }
+        this.zoneRims.length = 0;
+        this.geometry.dispose();
+    }
+    apply(frame) {
+        const { width, height } = this.viewport;
+        // Each pulse's strength, 0 at rest: `sin` shapes the rise-and-settle into one smooth swell. Two pulses at once (a
+        // navigation that also resized the sidebar) combine by their MAXIMUM, never by summing: the frame never moves
+        // further than one choreography would move it.
+        let lightSweepDeg = 0;
+        let shadowSpread = 0;
+        let rimLift = 0;
+        for (const [trigger, pulse] of this.pulses) {
+            const strength = Math.sin((Math.PI / 2) * clamp01(pulse.value));
+            const choreography = this.choreographies[trigger];
+            lightSweepDeg = Math.max(lightSweepDeg, choreography.lightSweepDeg * strength);
+            shadowSpread = Math.max(shadowSpread, choreography.shadowSpread * strength);
+            rimLift = Math.max(rimLift, choreography.rimLift * strength);
+        }
+        const light = frame ? (frame.lightAngleDeg + lightSweepDeg) * (Math.PI / 180) : 0;
+        const lightDir = new Vector2(Math.cos(light), Math.sin(light));
+        const background = frame?.background;
+        this.backgroundMesh.visible = Boolean(background && background[6] > 0 && width > 0 && height > 0);
+        if (background && this.backgroundMesh.visible) {
+            setBody(this.backgroundMesh.material, {
+                size: [width, height],
+                quad: [width + 2, height + 2],
+                radius: 0,
+                fillFrom: background.slice(0, 3),
+                fillTo: background.slice(3, 6),
+                fillAlpha: 1,
+                rim: [0, 0, 0],
+                rimAlpha: 0,
+                rimWidth: 0,
+                lightDir,
+                presence: background[6],
+            });
+            this.backgroundMesh.scale.set(width + 2, height + 2, 1);
+            this.backgroundMesh.position.set(0, 0, 0);
+        }
+        while (this.slabs.length < this.boxes.length)
+            this.slabs.push(this.createSlab());
+        this.slabs.forEach((slab, index) => {
+            const box = this.boxes[index];
+            const params = box && frame ? frame.regions[box.region] : undefined;
+            const presence = params && box && !box.glass ? params[PRESENCE] : 0;
+            slab.body.visible = presence > 0;
+            slab.shadow.visible = presence > 0 && params[17] > 0 && this.backgroundMesh.visible;
+            if (!box || !params || presence <= 0)
+                return;
+            const centre = regionCentreInFrameUnits(box, this.viewport);
+            const radius = params[13];
+            // The content slab carries the lift: its rim toward the hover opacity (never past it), its shadow further.
+            const isContent = box.region === ShellRegion.CONTENT;
+            const hover = Math.max(clamp01(this.hover.get(box.element)?.value ?? 0), isContent ? rimLift : 0);
+            setBody(slab.body.material, {
+                size: [box.width, box.height],
+                quad: [box.width + 2, box.height + 2],
+                radius,
+                fillFrom: params.slice(0, 3),
+                fillTo: params.slice(3, 6),
+                fillAlpha: params[6],
+                rim: params.slice(7, 10),
+                rimAlpha: params[10] + (params[11] - params[10]) * hover,
+                rimWidth: params[12],
+                lightDir,
+                presence,
+            });
+            slab.body.scale.set(box.width + 2, box.height + 2, 1);
+            slab.body.position.set(centre.x, centre.y, 0);
+            if (!slab.shadow.visible)
+                return;
+            // Blur and offset grow with the lift; the opacity never does (the frost bound covers the strongest shadow's opacity anywhere).
+            const spread = 1 + (isContent ? shadowSpread : 0);
+            const [offsetX, offsetY, blur, alpha] = [params[14] * spread, params[15] * spread, params[16] * spread, params[17]];
+            const margin = blur + 2;
+            const u = slab.shadow.material.uniforms;
+            u.uSize.value.set(box.width, box.height);
+            u.uQuad.value.set(box.width + 2 * margin, box.height + 2 * margin);
+            u.uRadius.value = radius;
+            u.uBlur.value = blur;
+            u.uAlpha.value = alpha;
+            u.uPresence.value = presence;
+            u.uBgFrom.value.set(background[0], background[1], background[2]);
+            u.uBgTo.value.set(background[3], background[4], background[5]);
+            u.uBgSize.value.set(width, height);
+            u.uLightDir.value.copy(lightDir);
+            slab.shadow.scale.set(box.width + 2 * margin, box.height + 2 * margin, 1);
+            // The DOM's y axis points down and three.js' up, so a downward CSS offset is a negative y.
+            slab.shadow.position.set(centre.x + offsetX, centre.y - offsetY, 0);
+        });
+        this.applyZoneRims(frame, lightDir);
+    }
+    /**
+     * The focused zone's rim, drawn over the content slab: the content slab's rim colour and width, at most its HOVER
+     * opacity, and no fill. Each rim is inset from the content box by the content rim's own width, so it never lands
+     * on the content slab's rim band — where it is drawn, it is exactly the case the contrast bound was proved for.
+     */
+    applyZoneRims(frame, lightDir) {
+        const content = this.boxes.find((box) => box.region === ShellRegion.CONTENT);
+        const params = frame?.regions[ShellRegion.CONTENT];
+        const drawable = Boolean(content && params && !content.glass && params[PRESENCE] > 0);
+        const shown = drawable ? this.zones.filter((zone) => (this.zoneEmphasis.get(zone.element)?.value ?? 0) > 0) : [];
+        while (this.zoneRims.length < shown.length) {
+            const rim = new Mesh(this.geometry, bodyMaterial());
+            rim.renderOrder = FrameRenderOrder.ZONE_RIM;
+            this.group.add(rim);
+            this.zoneRims.push(rim);
+        }
+        this.zoneRims.forEach((rim, index) => {
+            const zone = shown[index];
+            rim.visible = false;
+            if (!zone || !content || !params)
+                return;
+            const inset = params[12] + 1;
+            const left = Math.max(zone.left, content.left + inset);
+            const top = Math.max(zone.top, content.top + inset);
+            const right = Math.min(zone.left + zone.width, content.left + content.width - inset);
+            const bottom = Math.min(zone.top + zone.height, content.top + content.height - inset);
+            if (right - left <= 0 || bottom - top <= 0)
+                return;
+            const emphasis = clamp01(this.zoneEmphasis.get(zone.element)?.value ?? 0);
+            const box = { left, top, width: right - left, height: bottom - top };
+            const centre = regionCentreInFrameUnits(box, this.viewport);
+            rim.visible = true;
+            setBody(rim.material, {
+                size: [box.width, box.height],
+                quad: [box.width + 2, box.height + 2],
+                radius: Math.max(0, params[13] - inset),
+                fillFrom: params.slice(0, 3),
+                fillTo: params.slice(3, 6),
+                fillAlpha: 0,
+                rim: params.slice(7, 10),
+                rimAlpha: params[11] * emphasis,
+                rimWidth: params[12],
+                lightDir,
+                presence: params[PRESENCE],
+            });
+            rim.scale.set(box.width + 2, box.height + 2, 1);
+            rim.position.set(centre.x, centre.y, 0);
+        });
+    }
+    /** Point every zone's rim emphasis at its target: 1 for the focused zone of a split, 0 otherwise. Returns whether any target moved. */
+    retargetZoneEmphasis() {
+        const active = this.rimsFocusedZone && Boolean(this.appearance?.hoverResponse) && this.zones.length >= 2 ? this.focusedZone : null;
+        this.rimmed = active;
+        let changed = false;
+        for (const zone of this.zones) {
+            const target = zone.element === active ? 1 : 0;
+            const state = this.zoneEmphasis.get(zone.element);
+            if ((state?.target ?? 0) === target)
+                continue;
+            const next = state ?? { value: 0, target: 0, velocity: 0, tween: null, spring: null, lastTick: null };
+            next.target = target;
+            next.spring = this.appearance?.hoverSpring ?? null;
+            next.tween = next.spring ? null : { from: next.value, to: target, start: null, seconds: this.appearance?.hoverSeconds ?? 0, easing: this.appearance?.hoverEasing ?? [0, 0, 1, 1] };
+            next.lastTick = null;
+            this.zoneEmphasis.set(zone.element, next);
+            changed = true;
+        }
+        return changed;
+    }
+    createSlab() {
+        const body = new Mesh(this.geometry, bodyMaterial());
+        body.renderOrder = FrameRenderOrder.BODY;
+        const shadow = new Mesh(this.geometry, shadowMaterial());
+        shadow.renderOrder = FrameRenderOrder.SHADOW;
+        this.group.add(shadow, body);
+        return { body, shadow };
+    }
+}
+/** A cubic-Bézier easing evaluated at `x` in 0–1, as CSS `cubic-bezier()` defines it (x → y, solved by Newton then bisection). */
+export function evaluateEasing([x1, y1, x2, y2], x) {
+    if (x <= 0)
+        return 0;
+    if (x >= 1)
+        return 1;
+    const sample = (a, b, t) => ((1 - 3 * b + 3 * a) * t + (3 * b - 6 * a)) * t * t + 3 * a * t;
+    const slope = (a, b, t) => 3 * (1 - 3 * b + 3 * a) * t * t + 2 * (3 * b - 6 * a) * t + 3 * a;
+    let t = x;
+    for (let i = 0; i < 8; i += 1) {
+        const error = sample(x1, x2, t) - x;
+        if (Math.abs(error) < 1e-6)
+            return sample(y1, y2, t);
+        const d = slope(x1, x2, t);
+        if (Math.abs(d) < 1e-6)
+            break;
+        t -= error / d;
+    }
+    let low = 0;
+    let high = 1;
+    t = x;
+    for (let i = 0; i < 30; i += 1) {
+        const value = sample(x1, x2, t);
+        if (Math.abs(value - x) < 1e-6)
+            break;
+        if (value < x)
+            low = t;
+        else
+            high = t;
+        t = (low + high) / 2;
+    }
+    return sample(y1, y2, t);
+}
+/**
+ * A tween's progress at `now`.
+ *
+ * - `eased` is CLAMPED to 0–1. A theme's easing token may overshoot (a y control point above 1 — the engine's own
+ *   `emphasized` easing does), and an overshooting cross-fade would pass its target: colours outside 0–1, a frost
+ *   more opaque than the bound was computed for. The frame follows the curve's shape inside the range only.
+ * - `done` is decided by ELAPSED TIME, never by the eased value: an overshooting curve reaches 1 early, and ending
+ *   the tween there would cut the transition short.
+ */
+function advance(tween, now) {
+    if (tween.seconds <= 0)
+        return { eased: 1, done: true };
+    if (tween.start === null)
+        tween.start = now;
+    const linear = Math.min(1, Math.max(0, (now - tween.start) / (tween.seconds * 1000)));
+    return linear >= 1 ? { eased: 1, done: true } : { eased: clamp01(evaluateEasing(tween.easing, linear)), done: false };
+}
+function stepHover(state, now) {
+    if (state.tween) {
+        const { eased, done } = advance(state.tween, now);
+        state.value = state.tween.from + (state.tween.to - state.tween.from) * eased;
+        if (done)
+            state.tween = null;
+        return;
+    }
+    if (!state.spring)
+        return;
+    const last = state.lastTick ?? now;
+    state.lastTick = now;
+    let remaining = Math.min(0.25, Math.max(0, (now - last) / 1000));
+    const { stiffness, damping, mass } = state.spring;
+    while (remaining > 0) {
+        const dt = Math.min(SPRING_STEP_SECONDS, remaining);
+        const acceleration = (-stiffness * (state.value - state.target) - damping * state.velocity) / mass;
+        state.velocity += acceleration * dt;
+        state.value += state.velocity * dt;
+        remaining -= dt;
+    }
+    if (Math.abs(state.value - state.target) < SPRING_REST && Math.abs(state.velocity) < SPRING_REST) {
+        state.value = state.target;
+        state.velocity = 0;
+    }
+}
+function hoverSettled(state) {
+    if (state.tween)
+        return false;
+    return state.value === state.target && state.velocity === 0;
+}
+function clamp01(value) {
+    return Math.min(1, Math.max(0, value));
+}
+function sameColor(a, b) {
+    return a.every((channel, i) => Math.abs(channel - b[i]) < 1e-9);
+}
+function slabVector(slab) {
+    return [
+        ...slab.fillFrom, ...slab.fillTo, slab.fillAlpha,
+        ...slab.rim, slab.rimAlpha, slab.rimHoverAlpha, slab.rimWidthPx, slab.radiusPx,
+        slab.shadowOffsetXPx, slab.shadowOffsetYPx, slab.shadowBlurPx, slab.shadowAlpha,
+        slab.visible ? 1 : 0,
+    ];
+}
+/**
+ * The numbers to display for an appearance. A null appearance (or an invisible slab) keeps the PREVIOUS colours
+ * with presence 0, so a fade-out fades the colours that were on screen instead of flashing to black.
+ */
+function displayedOf(appearance, previous) {
+    const regions = {};
+    for (const region of Object.values(ShellRegion)) {
+        const slab = appearance?.regions[region];
+        const prior = previous?.regions[region];
+        if (slab?.visible)
+            regions[region] = slabVector(slab);
+        else
+            regions[region] = prior ? [...prior.slice(0, PRESENCE), 0] : new Array(SLAB_SIZE).fill(0);
+    }
+    const background = appearance?.background
+        ? [...appearance.background.from, ...appearance.background.to, 1]
+        : previous ? [...previous.background.slice(0, 6), 0] : [0, 0, 0, 0, 0, 0, 0];
+    return { regions, background, lightAngleDeg: appearance?.lightAngleDeg ?? previous?.lightAngleDeg ?? 0 };
+}
+/**
+ * The start of a cross-fade: what is on screen, except that anything NOT on screen (presence 0) starts from the
+ * TARGET's colours. A slab appearing then fades in as itself — only its presence moves — instead of passing
+ * through black, which no contrast bound covers.
+ */
+function fadeInFrom(shown, target) {
+    const regions = {};
+    for (const region of Object.values(ShellRegion)) {
+        const current = shown.regions[region];
+        regions[region] = current[PRESENCE] > 0 ? current : [...target.regions[region].slice(0, PRESENCE), 0];
+    }
+    const background = shown.background[6] > 0 ? shown.background : [...target.background.slice(0, 6), 0];
+    return { regions, background, lightAngleDeg: shown.lightAngleDeg };
+}
+function interpolateFrame(from, to, t) {
+    const lerp = (a, b) => a.map((value, i) => value + (b[i] - value) * t);
+    const regions = {};
+    for (const region of Object.values(ShellRegion))
+        regions[region] = lerp(from.regions[region], to.regions[region]);
+    return { regions, background: lerp(from.background, to.background), lightAngleDeg: from.lightAngleDeg + (to.lightAngleDeg - from.lightAngleDeg) * t };
+}
+function bodyMaterial() {
+    return new ShaderMaterial({
+        vertexShader: FRAME_VERTEX_SHADER,
+        fragmentShader: FRAME_BODY_FRAGMENT_SHADER,
+        transparent: true,
+        depthTest: false,
+        depthWrite: false,
+        toneMapped: false,
+        uniforms: {
+            uSize: { value: new Vector2() },
+            uQuad: { value: new Vector2() },
+            uRadius: { value: 0 },
+            uFillFrom: { value: new Vector3() },
+            uFillTo: { value: new Vector3() },
+            uFillAlpha: { value: 0 },
+            uRim: { value: new Vector3() },
+            uRimAlpha: { value: 0 },
+            uRimWidth: { value: 0 },
+            uLightDir: { value: new Vector2(0, 1) },
+            uPresence: { value: 0 },
+        },
+    });
+}
+/** The shadow writes an opaque, darkened background with MIN blending: overlapping shadows never stack. */
+function shadowMaterial() {
+    return new ShaderMaterial({
+        vertexShader: FRAME_VERTEX_SHADER,
+        fragmentShader: FRAME_SHADOW_FRAGMENT_SHADER,
+        transparent: true,
+        depthTest: false,
+        depthWrite: false,
+        toneMapped: false,
+        blending: CustomBlending,
+        blendEquation: MinEquation,
+        uniforms: {
+            uSize: { value: new Vector2() },
+            uQuad: { value: new Vector2() },
+            uRadius: { value: 0 },
+            uBlur: { value: 0 },
+            uAlpha: { value: 0 },
+            uPresence: { value: 0 },
+            uBgFrom: { value: new Vector3() },
+            uBgTo: { value: new Vector3() },
+            uBgSize: { value: new Vector2() },
+            uLightDir: { value: new Vector2(0, 1) },
+        },
+    });
+}
+function setBody(material, values) {
+    const u = material.uniforms;
+    u.uSize.value.set(...values.size);
+    u.uQuad.value.set(...values.quad);
+    u.uRadius.value = values.radius;
+    u.uFillFrom.value.set(values.fillFrom[0], values.fillFrom[1], values.fillFrom[2]);
+    u.uFillTo.value.set(values.fillTo[0], values.fillTo[1], values.fillTo[2]);
+    u.uFillAlpha.value = values.fillAlpha;
+    u.uRim.value.set(values.rim[0], values.rim[1], values.rim[2]);
+    u.uRimAlpha.value = values.rimAlpha;
+    u.uRimWidth.value = values.rimWidth;
+    u.uLightDir.value.copy(values.lightDir);
+    u.uPresence.value = values.presence;
+}
+//# sourceMappingURL=frame-renderer.js.map