@3driseai/3drise-viewer 0.1.35 → 0.1.38

package/dist/components/effects/harmonicShellField.js

@@ -0,0 +1,752 @@
+// =============================================================================
+// Harmonic Shell field — the one definition of "where the shell's surface is".
+// =============================================================================
+//
+// The shell is a field, not a mesh: a unit sphere displaced by 24 real spherical
+// harmonics (the `hshSh` polynomial), and, when the shell has a target, a signed
+// distance field the sphere's vertices trace onto:
+//   • text / shape   a 2D distance field drawn on a canvas, extruded to `depth`
+//   • object         the object's own 3D distance field, baked once from its geometry
+//
+// Everything that needs to know the shell reads THIS module: the shell's own
+// material (HarmonicShellEffect) and the `inShell` object effect, whose layer
+// asks, per pixel and per vertex, "where am I in the shell?". The uniform objects
+// here are shared: the shell writes them, the effect reads them.
+//
+// Names are prefixed `uHsh…` / `hsh…` so the GLSL can live inside a layered
+// built-in material next to other effects.
+import * as THREE from 'three';
+import { MeshBVH } from 'three-mesh-bvh';
+// ---------------------------------------------------------------- harmonics
+/** Band (l) of each of the 24 real-SH terms in the shader. */
+const SH_BANDS = [1, 1, 1, 2, 2, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3, 4, 4, 4, 4, 4, 4, 4, 4, 4];
+function mulberry32(seed) {
+    return () => {
+        seed |= 0;
+        seed = (seed + 0x6d2b79f5) | 0;
+        let r = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+        r = (r + Math.imul(r ^ (r >>> 7), 61 | r)) ^ r;
+        return ((r ^ (r >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** Fixed per-term frequencies and phases, so the same config always moves the same way. */
+export function createHarmonicState() {
+    const rand = mulberry32(7);
+    const f1 = new Float32Array(24), f2 = new Float32Array(24), p1 = new Float32Array(24), p2 = new Float32Array(24);
+    for (let i = 0; i < 24; i++) {
+        f1[i] = 0.13 + 0.3 * rand();
+        f2[i] = 0.07 + 0.2 * rand();
+        p1[i] = rand() * Math.PI * 2;
+        p2[i] = rand() * Math.PI * 2;
+    }
+    return { f1, f2, p1, p2, gate: new Float32Array([0, 0, 0, 0, 0]) };
+}
+/**
+ * Writes the 24 weights for time T into `out`. Bands above `degree` fade
+ * out; the top band leads and lower bands sit at about half strength.
+ */
+export function updateHarmonicWeights(state, out, T, degree, dt) {
+    const deg = Math.round(Math.min(Math.max(degree, 1), 4));
+    const ease = Math.min(1, dt * 2.5);
+    let energy = 0;
+    for (let l = 1; l <= 4; l++) {
+        // l = 1 only shifts the shell sideways, so it stays quiet unless it is the only band
+        const target = l > deg ? 0 : l === deg ? 1 : l === 1 ? 0.2 : 0.55;
+        state.gate[l] += (target - state.gate[l]) * ease;
+        energy += state.gate[l] * state.gate[l] * (2 * l + 1);
+    }
+    const norm = 1 / Math.sqrt(Math.max(energy / 5, 1e-3));
+    for (let i = 0; i < 24; i++) {
+        const g = state.gate[SH_BANDS[i]];
+        out[i] = g * norm * (0.7 * Math.sin(T * state.f1[i] + state.p1[i]) + 0.3 * Math.sin(T * state.f2[i] + state.p2[i]));
+    }
+}
+// ---------------------------------------------------------------- GLSL
+/** The shared uniforms, declared (the shell's own ShaderMaterial; a layered material gets them from the kit). */
+export const HSH_FIELD_DECL = /* glsl */ `
+  uniform float uHshW[24];
+  uniform float uHshAmplitude; uniform float uHshBound; uniform float uHshSize;
+  uniform vec3 uHshColor; uniform vec3 uHshRim; uniform float uHshFilm; uniform float uHshTint; uniform float uHshTime;
+  uniform float uHshMorph; uniform float uHshMode;
+  uniform sampler2D uHshSdf; uniform vec2 uHshSdfHalf; uniform float uHshDepth;
+  uniform sampler3D uHshSdf3; uniform vec3 uHshSdf3Min; uniform vec3 uHshSdf3Size; uniform mat4 uHshSdf3Inv; uniform mat4 uHshSdf3Mat;
+`;
+/**
+ * The field, for any shader (after the declarations): the harmonic polynomial, the
+ * thin film, and the target distance functions. Include once per stage.
+ */
+export const HSH_FIELD_FUNCS = /* glsl */ `
+
+  // Real spherical harmonics for l = 1..4, as polynomials in the unit vector,
+  // each scaled so its peak is about 1. The CPU animates the 24 weights.
+  float hshSh(vec3 n){
+    float x = n.x, y = n.y, z = n.z;
+    float x2 = x * x, y2 = y * y, z2 = z * z;
+    float s = 0.0;
+    s += uHshW[0] * y + uHshW[1] * z + uHshW[2] * x;
+    s += uHshW[3] * 2.0 * x * y + uHshW[4] * 2.0 * y * z + uHshW[5] * (1.5 * z2 - 0.5)
+       + uHshW[6] * 2.0 * x * z + uHshW[7] * (x2 - y2);
+    s += uHshW[8]  * y * (3.0 * x2 - y2)
+       + uHshW[9]  * 5.2 * x * y * z
+       + uHshW[10] * 0.8 * y * (5.0 * z2 - 1.0)
+       + uHshW[11] * 0.5 * z * (5.0 * z2 - 3.0)
+       + uHshW[12] * 0.8 * x * (5.0 * z2 - 1.0)
+       + uHshW[13] * 2.6 * z * (x2 - y2)
+       + uHshW[14] * x * (x2 - 3.0 * y2);
+    s += uHshW[15] * 4.0 * x * y * (x2 - y2)
+       + uHshW[16] * 3.0 * y * z * (3.0 * x2 - y2)
+       + uHshW[17] * 1.5 * x * y * (7.0 * z2 - 1.0)
+       + uHshW[18] * 0.95 * y * z * (7.0 * z2 - 3.0)
+       + uHshW[19] * 0.125 * (35.0 * z2 * z2 - 30.0 * z2 + 3.0)
+       + uHshW[20] * 0.95 * x * z * (7.0 * z2 - 3.0)
+       + uHshW[21] * 0.78 * (x2 - y2) * (7.0 * z2 - 1.0)
+       + uHshW[22] * 3.0 * x * z * (x2 - 3.0 * y2)
+       + uHshW[23] * (x2 * (x2 - 3.0 * y2) - y2 * (3.0 * x2 - y2));
+    return s;
+  }
+
+  // The resting shell: radius along direction n, in shell-local units.
+  float hshRadius(vec3 n, out float field){
+    field = hshSh(n);
+    return uHshBound * uHshSize * (1.0 + uHshAmplitude * field);
+  }
+
+  // Thin-film interference, as on a soap bubble: a film of index 1.33 and
+  // thickness d delays the inner reflection by 2*n*d*cos(theta_t). Each
+  // wavelength interferes on its own, which splits white light into bands.
+  vec3 hshFilm(float ndv, float field){
+    float cosT = sqrt(max(1.0 - (1.0 - ndv * ndv) / (1.33 * 1.33), 0.0));
+    float opd  = 2.0 * 1.33 * uHshFilm * (1.0 + 0.35 * field) * cosT;
+    vec3 film  = 0.5 + 0.5 * cos(6.28318530718 * opd / vec3(650.0, 532.0, 450.0));
+    float lum  = dot(film, vec3(0.299, 0.587, 0.114));
+    return mix(film, lum * uHshColor * 1.7 + film * 0.12, uHshTint);
+  }
+
+  // ── the target: signed distance in shell-local units (negative inside) ──
+  float hshSdf2(vec2 p){
+    vec2 uv = p / (2.0 * uHshSdfHalf) + 0.5;
+    vec2 c = clamp(uv, 0.0, 1.0);
+    return texture2D(uHshSdf, c).r + length((uv - c) * 2.0 * uHshSdfHalf);
+  }
+  float hshSdf(vec3 p){
+    if (uHshMode > 1.5) {
+      // an object's own field, baked in its local space
+      vec3 q = (uHshSdf3Inv * vec4(p, 1.0)).xyz;
+      vec3 uvw = (q - uHshSdf3Min) / uHshSdf3Size; vec3 c = clamp(uvw, 0.0, 1.0);
+      return texture(uHshSdf3, c).r + length((uvw - c) * uHshSdf3Size);
+    }
+    // text / shape: the 2D field extruded to ±depth
+    float d2 = hshSdf2(p.xy); float dz = abs(p.z) - uHshDepth;
+    vec2 w = max(vec2(d2, dz), 0.0);
+    return min(max(d2, dz), 0.0) + length(w);
+  }
+  vec3 hshSdfGrad(vec3 p){
+    float e = 0.012;
+    vec3 g = vec3(hshSdf(p + vec3(e, 0, 0)) - hshSdf(p - vec3(e, 0, 0)),
+                  hshSdf(p + vec3(0, e, 0)) - hshSdf(p - vec3(0, e, 0)),
+                  hshSdf(p + vec3(0, 0, e)) - hshSdf(p - vec3(0, 0, e)));
+    float l = length(g); return l > 1e-6 ? g / l : vec3(0.0, 0.0, 1.0);
+  }
+
+  // Signed distance from a shell-local point to the shell's CURRENT surface
+  // (the resting shell blended with the target by uHshMorph). 'field' is the
+  // harmonic value in that direction, for the film.
+  // Where a sphere vertex starts its trace: the resting shell point stretched to the
+  // target's extent, so a wide word or a long object gets vertices along its whole length
+  // instead of everything converging on the part nearest the centre.
+  vec3 hshTraceStart(vec3 p0){
+    float R0 = uHshBound * uHshSize;
+    if (uHshMode > 1.5) {
+      vec3 c = uHshSdf3Min + 0.5 * uHshSdf3Size;        // the target's centre, in its own space
+      vec3 h = uHshSdf3Size * 0.44;                       // half extents (the baked box is padded 12%)
+      vec3 ct = (uHshSdf3Inv * vec4(0.0, 0.0, 0.0, 1.0)).xyz;
+      vec3 qt = (uHshSdf3Inv * vec4(p0, 1.0)).xyz;
+      qt = c + (qt - ct) * (h / R0);
+      return (uHshSdf3Mat * vec4(qt, 1.0)).xyz;
+    }
+    return p0 * vec3(uHshSdfHalf / R0, max(uHshDepth, 0.05) / R0);
+  }
+
+  float hshDist(vec3 p, out float field){
+    float r = length(p); vec3 n = r > 1e-5 ? p / r : vec3(0.0, 1.0, 0.0);
+    float dS = r - hshRadius(n, field);
+    return uHshMode > 0.5 && uHshMorph > 0.0 ? mix(dS, hshSdf(p), uHshMorph) : dS;
+  }
+`;
+/** Declarations + functions: the whole field for a shader that declares nothing itself. */
+export const HSH_FIELD_GLSL = HSH_FIELD_DECL + HSH_FIELD_FUNCS;
+/** The shell's own material: the sphere displaced by the field, traced onto the target when it has one. */
+export const SHELL_VERT = /* glsl */ `
+  uniform float uBreath;
+  varying vec3  vNormal;
+  varying vec3  vViewDir;
+  varying float vField;
+  varying vec3  vLocal;
+  ${HSH_FIELD_GLSL}
+
+  vec3 shellPoint(vec3 n, out float f){ return n * hshRadius(n, f); }
+
+  void main(){
+    vec3 n = normalize(position);
+    float f, f1, f2;
+    vec3 p0 = shellPoint(n, f);
+
+    // normal from two nearby points on the displaced surface
+    vec3 up = abs(n.y) > 0.99 ? vec3(1.0, 0.0, 0.0) : vec3(0.0, 1.0, 0.0);
+    vec3 t1 = normalize(cross(n, up));
+    vec3 t2 = cross(n, t1);
+    vec3 p1 = shellPoint(normalize(n + t1 * 0.01), f1);
+    vec3 p2 = shellPoint(normalize(n + t2 * 0.01), f2);
+    vec3 nrm = normalize(cross(p1 - p0, p2 - p0));
+    if (dot(nrm, n) < 0.0) nrm = -nrm;
+
+    vec3 p = p0; vec3 N = nrm;
+    if (uHshMode > 0.5 && uHshMorph > 0.0) {
+      // trace the vertex onto the target surface along the field's gradient
+      vec3 q = hshTraceStart(p0);
+      for (int i = 0; i < 12; i++) { float d = hshSdf(q); q -= d * hshSdfGrad(q) * 0.85; }
+      vec3 g = hshSdfGrad(q);
+      // the harmonics keep breathing on the target, along its normal
+      q += g * uHshBound * uHshAmplitude * uBreath * f;
+      p = mix(p0, q, uHshMorph);
+      N = normalize(mix(nrm, g, uHshMorph));
+    }
+
+    vLocal = p;
+    vField = f;
+    vec4 mv = modelViewMatrix * vec4(p, 1.0);
+    vNormal = normalize(normalMatrix * N);
+    vViewDir = normalize(-mv.xyz);
+    gl_Position = projectionMatrix * mv;
+  }
+`;
+export const SHELL_FRAG = /* glsl */ `
+  uniform float uOpacity;
+  uniform float uIntensity;
+  uniform float uNodalLines;
+  uniform float uWeb;
+  varying vec3  vNormal;
+  varying vec3  vViewDir;
+  varying float vField;
+  varying vec3  vLocal;
+  ${HSH_FIELD_GLSL}
+
+  void main(){
+    vec3 N = normalize(vNormal);
+    vec3 V = normalize(vViewDir);
+    float ndv = abs(dot(N, V));
+
+    // the film is thicker where the harmonic pushes the shell out, so the colour bands follow the shape
+    vec3 film = hshFilm(ndv, vField);
+
+    float fres = pow(1.0 - ndv, 3.0);
+    vec3 col = uHshColor * 0.25 + film * (0.2 + 0.8 * fres);
+    col = mix(col, uHshRim, fres * 0.45);
+
+    // nodal lines: where the harmonic field crosses zero
+    float nd = abs(vField) / max(fwidth(vField), 1e-4);
+    float nodal = (1.0 - smoothstep(0.5, 1.5, nd)) * uNodalLines;
+    col += uHshRim * nodal * 1.5;
+
+    float a = (0.06 + 0.9 * fres + nodal * 0.8) * uOpacity;
+    // webbing between letters: pixels that are not on the target fade out as the morph completes
+    if (uHshMode > 0.5 && uHshMorph > 0.0) { float d = abs(hshSdf(vLocal)); a *= 1.0 - uHshMorph * smoothstep(uWeb, uWeb * 3.0, d); }
+    if (a < 0.003) discard;
+    gl_FragColor = vec4(col * uIntensity, a);
+  }
+`;
+/** A 1×1×1 texture so the sampler3D is always bound, target or not. */
+function emptySdf3() {
+    const t = new THREE.Data3DTexture(new Uint16Array([THREE.DataUtils.toHalfFloat(1)]), 1, 1, 1);
+    t.format = THREE.RedFormat;
+    t.type = THREE.HalfFloatType;
+    t.needsUpdate = true;
+    return t;
+}
+function emptySdf2() {
+    const t = new THREE.DataTexture(new Uint16Array([THREE.DataUtils.toHalfFloat(1)]), 1, 1, THREE.RedFormat, THREE.HalfFloatType);
+    t.needsUpdate = true;
+    return t;
+}
+/** Fresh uniform objects for one shell (the shell writes them every frame; effects read them). */
+export function createShellUniforms() {
+    return {
+        uHshW: { value: new Float32Array(24) },
+        uHshAmplitude: { value: 0.22 }, uHshBound: { value: 1 }, uHshSize: { value: 1.35 },
+        uHshColor: { value: new THREE.Color('#3a2a6b') }, uHshRim: { value: new THREE.Color('#bfe8ff') },
+        uHshFilm: { value: 380 }, uHshTint: { value: 0 }, uHshTime: { value: 0 },
+        uHshMorph: { value: 0 }, uHshMode: { value: 0 },
+        uHshSdf: { value: emptySdf2() }, uHshSdfHalf: { value: new THREE.Vector2(1, 1) }, uHshDepth: { value: 0.35 },
+        uHshSdf3: { value: emptySdf3() }, uHshSdf3Min: { value: new THREE.Vector3() }, uHshSdf3Size: { value: new THREE.Vector3(1, 1, 1) }, uHshSdf3Inv: { value: new THREE.Matrix4() }, uHshSdf3Mat: { value: new THREE.Matrix4() },
+    };
+}
+/** The keys an effect copies from a shell into its own uniforms (everything but the time, which it keeps). */
+export const HSH_SHARED_KEYS = [
+    'uHshW', 'uHshAmplitude', 'uHshBound', 'uHshSize', 'uHshColor', 'uHshRim', 'uHshFilm', 'uHshTint',
+    'uHshMorph', 'uHshMode', 'uHshSdf', 'uHshSdfHalf', 'uHshDepth', 'uHshSdf3', 'uHshSdf3Min', 'uHshSdf3Size', 'uHshSdf3Inv', 'uHshSdf3Mat',
+];
+/** Copy a shell's current values into another uniform set (objects are shared by reference, scalars by value). */
+export function copyShellUniforms(from, to) {
+    for (const k of HSH_SHARED_KEYS) {
+        const v = from[k].value;
+        if (typeof v === 'number')
+            to[k].value = v;
+        else
+            to[k].value = v; // Float32Array, Color, Vector, Matrix4, textures: the shell's own objects
+    }
+}
+const shells = new Set();
+export function registerShellField(f) { shells.add(f); }
+export function unregisterShellField(f) { shells.delete(f); }
+export const shellFields = () => shells;
+const _p = new THREE.Vector3();
+/** The shell whose centre is nearest a world point (what `inShell` reacts to), or null when the scene has none. */
+export function nearestShellField(worldPos) {
+    let best = null, bd = Infinity;
+    for (const s of shells) {
+        _p.setFromMatrixPosition(s.root.matrixWorld);
+        const d = _p.distanceToSquared(worldPos);
+        if (d < bd) {
+            bd = d;
+            best = s;
+        }
+    }
+    return best;
+}
+// ---------------------------------------------------------------- 2D distance fields (text, shapes)
+export const SHELL_SHAPES = [
+    'star', 'heart', 'ring', 'hexagon', 'triangle', 'cross',
+    'disc', 'square', 'diamond', 'pentagon', 'octagon', 'sparkle', 'hexstar', 'crescent', 'drop', 'bolt',
+    'arrow', 'cloud', 'flower', 'gear', 'shield', 'leaf', 'capsule', 'infinity', 'chevron', 'hourglass',
+    'clover', 'spade', 'sun', 'halfmoon',
+];
+/** CSS font families the `font` option maps to (the page's own fonts, with system fallbacks). */
+export const SHELL_FONTS = {
+    sans: '"Inter", "Inter Variable", system-ui, -apple-system, "Segoe UI", Arial, sans-serif',
+    display: '"Syne", "Syne Variable", "Montserrat", "Arial Black", Impact, sans-serif',
+    serif: '"Instrument Serif", "Playfair Display", Georgia, "Times New Roman", serif',
+    mono: '"DM Mono", ui-monospace, Menlo, Consolas, monospace',
+};
+const SDF_N = 256;
+// Felzenszwalb & Huttenlocher's exact euclidean distance transform, 1D pass.
+function edt1d(f, n, d, v, z) {
+    let k = 0;
+    v[0] = 0;
+    z[0] = -Infinity;
+    z[1] = Infinity;
+    for (let q = 1; q < n; q++) {
+        let s = ((f[q] + q * q) - (f[v[k]] + v[k] * v[k])) / (2 * q - 2 * v[k]);
+        while (s <= z[k]) {
+            k--;
+            s = ((f[q] + q * q) - (f[v[k]] + v[k] * v[k])) / (2 * q - 2 * v[k]);
+        }
+        k++;
+        v[k] = q;
+        z[k] = s;
+        z[k + 1] = Infinity;
+    }
+    k = 0;
+    for (let q = 0; q < n; q++) {
+        while (z[k + 1] < q)
+            k++;
+        d[q] = (q - v[k]) * (q - v[k]) + f[v[k]];
+    }
+}
+function edt2d(grid, w, h) {
+    const m = Math.max(w, h);
+    const f = new Float32Array(m), d = new Float32Array(m), v = new Int32Array(m), z = new Float32Array(m + 1);
+    for (let x = 0; x < w; x++) {
+        for (let y = 0; y < h; y++)
+            f[y] = grid[y * w + x];
+        edt1d(f, h, d, v, z);
+        for (let y = 0; y < h; y++)
+            grid[y * w + x] = d[y];
+    }
+    for (let y = 0; y < h; y++) {
+        for (let x = 0; x < w; x++)
+            f[x] = grid[y * w + x];
+        edt1d(f, w, d, v, z);
+        for (let x = 0; x < w; x++)
+            grid[y * w + x] = d[x];
+    }
+}
+/** A canvas (alpha = inside) → signed distance (shell units) over ±half, as a half-float texture. */
+function sdfFromCanvas(c, half) {
+    const img = c.getContext('2d').getImageData(0, 0, SDF_N, SDF_N).data;
+    const INF = 1e10, inside = new Float32Array(SDF_N * SDF_N), outside = new Float32Array(SDF_N * SDF_N);
+    for (let i = 0; i < SDF_N * SDF_N; i++) {
+        const on = img[i * 4 + 3] > 127;
+        inside[i] = on ? INF : 0;
+        outside[i] = on ? 0 : INF;
+    }
+    edt2d(inside, SDF_N, SDF_N);
+    edt2d(outside, SDF_N, SDF_N);
+    const unit = (2 * half) / SDF_N;
+    const data = new Uint16Array(SDF_N * SDF_N);
+    for (let y = 0; y < SDF_N; y++)
+        for (let x = 0; x < SDF_N; x++) {
+            const i = y * SDF_N + x, j = (SDF_N - 1 - y) * SDF_N + x; // canvas y runs down, texture v runs up
+            const d = (Math.sqrt(outside[j]) - Math.sqrt(inside[j])) * unit;
+            data[i] = THREE.DataUtils.toHalfFloat(Math.max(-8, Math.min(8, d)));
+        }
+    const tex = new THREE.DataTexture(data, SDF_N, SDF_N, THREE.RedFormat, THREE.HalfFloatType);
+    tex.minFilter = tex.magFilter = THREE.LinearFilter;
+    tex.needsUpdate = true;
+    return { tex, half };
+}
+function drawTarget(kind, text, fontFamily) {
+    const c = document.createElement('canvas');
+    c.width = c.height = SDF_N;
+    const g = c.getContext('2d');
+    g.clearRect(0, 0, SDF_N, SDF_N);
+    g.fillStyle = '#fff';
+    const cx = SDF_N / 2, cy = SDF_N / 2, R = SDF_N * 0.36;
+    const poly = (pts) => { g.beginPath(); pts.forEach((p, i) => (i ? g.lineTo(p[0], p[1]) : g.moveTo(p[0], p[1]))); g.closePath(); g.fill(); };
+    const circle = (x, y, r) => { g.beginPath(); g.arc(x, y, r, 0, Math.PI * 2); g.fill(); };
+    const ngon = (n, r, a0) => { const pts = []; for (let i = 0; i < n; i++) {
+        const a = a0 + (i * Math.PI * 2) / n;
+        pts.push([cx + r * Math.cos(a), cy + r * Math.sin(a)]);
+    } poly(pts); };
+    const starN = (n, r, inner, a0) => { const pts = []; for (let i = 0; i < n * 2; i++) {
+        const rr = i % 2 ? r * inner : r;
+        const a = a0 + (i * Math.PI) / n;
+        pts.push([cx + rr * Math.cos(a), cy + rr * Math.sin(a)]);
+    } poly(pts); };
+    /** Erase what `draw` fills (a hole or a bite). */
+    const cut = (draw) => { g.globalCompositeOperation = 'destination-out'; draw(); g.globalCompositeOperation = 'source-over'; };
+    switch (kind) {
+        case 'text': {
+            const t = (text || 'A').slice(0, 24);
+            let size = SDF_N * 0.5;
+            g.font = `800 ${size}px ${fontFamily}`;
+            const w = g.measureText(t).width;
+            if (w > SDF_N * 0.92) {
+                size *= (SDF_N * 0.92) / w;
+                g.font = `800 ${size}px ${fontFamily}`;
+            }
+            g.textAlign = 'center';
+            g.textBaseline = 'middle';
+            g.fillText(t, cx, cy + size * 0.04);
+            break;
+        }
+        case 'star': {
+            const pts = [];
+            for (let i = 0; i < 10; i++) {
+                const r = i % 2 ? R * 0.45 : R;
+                const a = -Math.PI / 2 + (i * Math.PI) / 5;
+                pts.push([cx + r * Math.cos(a), cy + r * Math.sin(a)]);
+            }
+            poly(pts);
+            break;
+        }
+        case 'heart': {
+            g.beginPath();
+            const s = R / 16;
+            g.moveTo(cx, cy + 14 * s);
+            g.bezierCurveTo(cx - 24 * s, cy - 4 * s, cx - 14 * s, cy - 18 * s, cx, cy - 8 * s);
+            g.bezierCurveTo(cx + 14 * s, cy - 18 * s, cx + 24 * s, cy - 4 * s, cx, cy + 14 * s);
+            g.fill();
+            break;
+        }
+        case 'ring':
+            g.beginPath();
+            g.arc(cx, cy, R, 0, Math.PI * 2);
+            g.arc(cx, cy, R * 0.55, 0, Math.PI * 2, true);
+            g.fill();
+            break;
+        case 'hexagon': {
+            const pts = [];
+            for (let i = 0; i < 6; i++) {
+                const a = (i * Math.PI) / 3;
+                pts.push([cx + R * Math.cos(a), cy + R * Math.sin(a)]);
+            }
+            poly(pts);
+            break;
+        }
+        case 'triangle':
+            poly([[cx, cy - R], [cx + R * 0.95, cy + R * 0.6], [cx - R * 0.95, cy + R * 0.6]]);
+            break;
+        case 'cross':
+            g.fillRect(cx - R * 0.22, cy - R, R * 0.44, 2 * R);
+            g.fillRect(cx - R, cy - R * 0.22, 2 * R, R * 0.44);
+            break;
+        case 'disc':
+            circle(cx, cy, R);
+            break;
+        case 'square':
+            g.fillRect(cx - R * 0.88, cy - R * 0.88, R * 1.76, R * 1.76);
+            break;
+        case 'diamond':
+            poly([[cx, cy - R], [cx + R * 0.7, cy], [cx, cy + R], [cx - R * 0.7, cy]]);
+            break;
+        case 'pentagon':
+            ngon(5, R, -Math.PI / 2);
+            break;
+        case 'octagon':
+            ngon(8, R, Math.PI / 8);
+            break;
+        case 'sparkle':
+            starN(4, R, 0.3, -Math.PI / 2);
+            break;
+        case 'hexstar':
+            starN(6, R, 0.58, -Math.PI / 2);
+            break;
+        case 'crescent':
+            circle(cx, cy, R);
+            cut(() => circle(cx + R * 0.5, cy - R * 0.12, R * 0.82));
+            break;
+        case 'drop': {
+            g.beginPath();
+            g.moveTo(cx, cy - R);
+            g.bezierCurveTo(cx + R * 0.95, cy + R * 0.05, cx + R * 0.7, cy + R, cx, cy + R);
+            g.bezierCurveTo(cx - R * 0.7, cy + R, cx - R * 0.95, cy + R * 0.05, cx, cy - R);
+            g.fill();
+            break;
+        }
+        case 'bolt':
+            poly([[cx + R * 0.25, cy - R], [cx - R * 0.55, cy + R * 0.12], [cx - R * 0.05, cy + R * 0.12], [cx - R * 0.3, cy + R], [cx + R * 0.55, cy - R * 0.18], [cx + R * 0.05, cy - R * 0.18]]);
+            break;
+        case 'arrow':
+            poly([[cx - R, cy - R * 0.3], [cx + R * 0.15, cy - R * 0.3], [cx + R * 0.15, cy - R * 0.75], [cx + R, cy], [cx + R * 0.15, cy + R * 0.75], [cx + R * 0.15, cy + R * 0.3], [cx - R, cy + R * 0.3]]);
+            break;
+        case 'cloud': {
+            circle(cx - R * 0.5, cy + R * 0.15, R * 0.42);
+            circle(cx - R * 0.1, cy - R * 0.2, R * 0.55);
+            circle(cx + R * 0.4, cy + R * 0.05, R * 0.48);
+            g.fillRect(cx - R * 0.5, cy + R * 0.15, R * 0.9, R * 0.42);
+            break;
+        }
+        case 'flower': {
+            for (let i = 0; i < 6; i++) {
+                const a = (i * Math.PI) / 3;
+                circle(cx + R * 0.58 * Math.cos(a), cy + R * 0.58 * Math.sin(a), R * 0.42);
+            }
+            circle(cx, cy, R * 0.4);
+            break;
+        }
+        case 'gear': {
+            const pts = [], teeth = 10;
+            for (let i = 0; i < teeth * 4; i++) {
+                const r = (i % 4) < 2 ? R : R * 0.78;
+                const a = (i * Math.PI * 2) / (teeth * 4);
+                pts.push([cx + r * Math.cos(a), cy + r * Math.sin(a)]);
+            }
+            poly(pts);
+            cut(() => circle(cx, cy, R * 0.3));
+            break;
+        }
+        case 'shield': {
+            g.beginPath();
+            g.moveTo(cx - R * 0.85, cy - R * 0.8);
+            g.lineTo(cx + R * 0.85, cy - R * 0.8);
+            g.lineTo(cx + R * 0.85, cy + R * 0.1);
+            g.quadraticCurveTo(cx + R * 0.85, cy + R * 0.75, cx, cy + R);
+            g.quadraticCurveTo(cx - R * 0.85, cy + R * 0.75, cx - R * 0.85, cy + R * 0.1);
+            g.closePath();
+            g.fill();
+            break;
+        }
+        case 'leaf': {
+            g.beginPath();
+            g.moveTo(cx - R * 0.9, cy + R * 0.9);
+            g.quadraticCurveTo(cx - R * 1.1, cy - R * 0.9, cx + R * 0.9, cy - R * 0.9);
+            g.quadraticCurveTo(cx + R * 1.1, cy + R * 0.9, cx - R * 0.9, cy + R * 0.9);
+            g.fill();
+            break;
+        }
+        case 'capsule': {
+            g.beginPath();
+            g.arc(cx - R * 0.55, cy, R * 0.45, Math.PI / 2, -Math.PI / 2);
+            g.arc(cx + R * 0.55, cy, R * 0.45, -Math.PI / 2, Math.PI / 2);
+            g.closePath();
+            g.fill();
+            break;
+        }
+        case 'infinity': {
+            const r = R * 0.5, k = R * 0.28;
+            for (const sx of [-1, 1]) {
+                g.beginPath();
+                g.arc(cx + sx * r, cy, r, 0, Math.PI * 2);
+                g.arc(cx + sx * r, cy, r - k, 0, Math.PI * 2, true);
+                g.fill();
+            }
+            break;
+        }
+        case 'chevron':
+            poly([[cx - R * 0.9, cy - R * 0.8], [cx - R * 0.3, cy - R * 0.8], [cx + R * 0.5, cy], [cx - R * 0.3, cy + R * 0.8], [cx - R * 0.9, cy + R * 0.8], [cx - R * 0.1, cy]]);
+            break;
+        case 'hourglass':
+            poly([[cx - R * 0.75, cy - R], [cx + R * 0.75, cy - R], [cx + R * 0.1, cy], [cx + R * 0.75, cy + R], [cx - R * 0.75, cy + R], [cx - R * 0.1, cy]]);
+            break;
+        case 'clover': {
+            for (let i = 0; i < 3; i++) {
+                const a = -Math.PI / 2 + (i * Math.PI * 2) / 3;
+                circle(cx + R * 0.45 * Math.cos(a), cy + R * 0.45 * Math.sin(a), R * 0.46);
+            }
+            g.fillRect(cx - R * 0.1, cy, R * 0.2, R);
+            break;
+        }
+        case 'spade': {
+            g.beginPath();
+            g.moveTo(cx, cy - R);
+            g.bezierCurveTo(cx + R * 0.9, cy - R * 0.1, cx + R * 0.9, cy + R * 0.45, cx + R * 0.15, cy + R * 0.3);
+            g.bezierCurveTo(cx + R * 0.1, cy + R * 0.7, cx + R * 0.35, cy + R, cx + R * 0.4, cy + R);
+            g.lineTo(cx - R * 0.4, cy + R);
+            g.bezierCurveTo(cx - R * 0.35, cy + R, cx - R * 0.1, cy + R * 0.7, cx - R * 0.15, cy + R * 0.3);
+            g.bezierCurveTo(cx - R * 0.9, cy + R * 0.45, cx - R * 0.9, cy - R * 0.1, cx, cy - R);
+            g.fill();
+            break;
+        }
+        case 'sun': {
+            circle(cx, cy, R * 0.5);
+            for (let i = 0; i < 8; i++) {
+                const a = (i * Math.PI) / 4;
+                poly([[cx + R * 0.62 * Math.cos(a - 0.14), cy + R * 0.62 * Math.sin(a - 0.14)], [cx + R * Math.cos(a), cy + R * Math.sin(a)], [cx + R * 0.62 * Math.cos(a + 0.14), cy + R * 0.62 * Math.sin(a + 0.14)]]);
+            }
+            break;
+        }
+        case 'halfmoon':
+            g.beginPath();
+            g.arc(cx, cy, R, -Math.PI / 2, Math.PI / 2);
+            g.closePath();
+            g.fill();
+            break;
+    }
+    return c;
+}
+/**
+ * The 2D field of a word or a shape, sized to the shell: `half` is the half-width it
+ * spans in shell-local units (the shell's resting radius, a little more).
+ * Text waits for the page font once (document.fonts), then draws.
+ */
+export async function bakeShapeSdf(kind, text, font, half) {
+    if (typeof document === 'undefined')
+        return null;
+    const family = SHELL_FONTS[font] ?? SHELL_FONTS.sans;
+    if (kind === 'text') {
+        try {
+            await document.fonts?.load?.(`800 40px ${family}`);
+        }
+        catch { /* the fallback face draws */ }
+    }
+    return sdfFromCanvas(drawTarget(kind, text, family), half);
+}
+const SDF3_N = 48;
+const sdf3Cache = new WeakMap();
+/** A key for "the same meshes, same geometry" — a model that lands later gets a new bake. */
+function geometryKey(root) {
+    const parts = [];
+    root.traverse((o) => { if (o.isMesh && o.geometry && !o.userData?.__opFxHelper)
+        parts.push(o.geometry.uuid + ':' + (o.geometry.attributes?.position?.count ?? 0)); });
+    return parts.join('|');
+}
+/**
+ * Every mesh of the object as one position-only, root-local geometry (what the bake
+ * needs — materials, uvs and normals are irrelevant). Helpers and hidden meshes are left out.
+ */
+function mergedPositions(root) {
+    root.updateWorldMatrix(true, true);
+    const rootInv = root.matrixWorld.clone().invert();
+    const m = new THREE.Matrix4(), v = new THREE.Vector3();
+    const chunks = [];
+    let total = 0;
+    root.traverse((o) => {
+        if (!o.isMesh || !o.visible || o.userData?.__opFxHelper)
+            return;
+        const pos = o.geometry?.attributes?.position;
+        if (!pos || pos.count < 3)
+            return;
+        const idx = o.geometry.index;
+        const n = idx ? idx.count : pos.count;
+        if (n < 3)
+            return;
+        m.multiplyMatrices(rootInv, o.matrixWorld);
+        const out = new Float32Array(n * 3);
+        for (let i = 0; i < n; i++) {
+            v.fromBufferAttribute(pos, idx ? idx.getX(i) : i).applyMatrix4(m);
+            out[i * 3] = v.x;
+            out[i * 3 + 1] = v.y;
+            out[i * 3 + 2] = v.z;
+        }
+        chunks.push(out);
+        total += n;
+    });
+    if (total < 3)
+        return null;
+    const all = new Float32Array(total * 3);
+    let at = 0;
+    for (const c of chunks) {
+        all.set(c, at);
+        at += c.length;
+    }
+    const g = new THREE.BufferGeometry();
+    g.setAttribute('position', new THREE.BufferAttribute(all, 3));
+    return g;
+}
+/**
+ * The object's signed distance field in its root-local space: all its meshes merged
+ * (position only, see mergedPositions), sampled on a 48³ grid with the BVH's
+ * closest-point query, sign from the hit face. Baked in slices so the page stays
+ * responsive; cached on the root until its geometry changes. ~100–300 ms for a
+ * typical model on a desktop CPU — do it at load (pre-bake), never on trigger.
+ */
+export async function bakeObjectSdf(root) {
+    const key = geometryKey(root);
+    if (!key) {
+        console.warn('[harmonicShell] target object has no meshes to bake', root.name || root.uuid);
+        return null;
+    }
+    const hit = sdf3Cache.get(root);
+    if (hit && hit.key === key)
+        return hit.sdf;
+    const t0 = performance.now();
+    const geometry = mergedPositions(root);
+    if (!geometry) {
+        console.warn('[harmonicShell] target object has no geometry to bake');
+        return null;
+    }
+    const bvh = new MeshBVH(geometry);
+    geometry.computeBoundingBox();
+    const bb = geometry.boundingBox.clone();
+    bb.expandByScalar(bb.getSize(new THREE.Vector3()).length() * 0.12);
+    const min = bb.min.clone(), size = bb.getSize(new THREE.Vector3());
+    // cells follow the shape: a wide flat word gets more across and fewer through, same budget
+    const mean = Math.cbrt(Math.max(size.x * size.y * size.z, 1e-9));
+    const res = (v) => Math.max(8, Math.min(160, Math.round((SDF3_N * v) / mean)));
+    const NX = res(size.x), NY = res(size.y), NZ = res(size.z);
+    const data = new Uint16Array(NX * NY * NZ);
+    const p = new THREE.Vector3(), tri = new THREE.Triangle(), n = new THREE.Vector3(), d = new THREE.Vector3();
+    const pos = geometry.attributes.position, idx = geometry.index;
+    const target = { point: new THREE.Vector3(), distance: 0, faceIndex: 0 };
+    for (let z = 0; z < NZ; z++) {
+        for (let y = 0; y < NY; y++)
+            for (let x = 0; x < NX; x++) {
+                p.set(min.x + (size.x * (x + 0.5)) / NX, min.y + (size.y * (y + 0.5)) / NY, min.z + (size.z * (z + 0.5)) / NZ);
+                bvh.closestPointToPoint(p, target);
+                const f = target.faceIndex * 3;
+                const i0 = idx ? idx.getX(f) : f, i1 = idx ? idx.getX(f + 1) : f + 1, i2 = idx ? idx.getX(f + 2) : f + 2;
+                tri.a.fromBufferAttribute(pos, i0);
+                tri.b.fromBufferAttribute(pos, i1);
+                tri.c.fromBufferAttribute(pos, i2);
+                tri.getNormal(n);
+                const sign = n.dot(d.copy(p).sub(target.point)) < 0 ? -1 : 1;
+                data[x + NX * (y + NY * z)] = THREE.DataUtils.toHalfFloat(sign * target.distance);
+            }
+        // a slice per task: the studio stays live while a big model bakes
+        if (z % 4 === 3)
+            await new Promise(r => setTimeout(r, 0));
+    }
+    geometry.dispose();
+    const tex = new THREE.Data3DTexture(data, NX, NY, NZ);
+    tex.format = THREE.RedFormat;
+    tex.type = THREE.HalfFloatType;
+    tex.minFilter = tex.magFilter = THREE.LinearFilter;
+    tex.unpackAlignment = 1;
+    tex.needsUpdate = true;
+    const sdf = { tex, min, size };
+    const old = sdf3Cache.get(root);
+    old?.sdf.tex.dispose();
+    sdf3Cache.set(root, { key, sdf });
+    console.info(`[harmonicShell] baked ${NX}×${NY}×${NZ} field of "${root.name || root.uuid}" in ${(performance.now() - t0).toFixed(0)} ms`);
+    return sdf;
+}