@naniteninja/trait-visual 1.0.3 → 1.0.4

package/fesm2022/naniteninja-trait-visual.mjs

@@ -1,21 +1,186 @@
+import * as i1 from '@angular/common';
 import { CommonModule } from '@angular/common';
 import * as i0 from '@angular/core';
-import { Input, ViewChild, Component } from '@angular/core';
+import { EventEmitter, Output, Input, ViewChild, Component } from '@angular/core';
+import * as i2 from '@angular/material/icon';
+import { MatIconModule } from '@angular/material/icon';
+import * as i3 from '@angular/material/button';
+import { MatButtonModule } from '@angular/material/button';
+import * as i4 from '@angular/material/tooltip';
+import { MatTooltipModule } from '@angular/material/tooltip';
 import * as THREE from 'three';
 import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
 import { PCA } from 'ml-pca';
+import * as i5 from '@angular/material/select';
+import { MatSelectModule } from '@angular/material/select';
+import { MatFormFieldModule } from '@angular/material/form-field';
 
-class Node extends THREE.Object3D {
+/**
+ * Safe access to window.location.search (e.g. for ?debug=1).
+ * Use instead of (window as any)?.location?.search to satisfy strict typing.
+ */
+function getWindowLocationSearch() {
+    if (typeof window === 'undefined')
+        return '';
+    return window.location?.search ?? '';
+}
+/** True when URL has debug=1 (enables optional ingest logging). */
+function isDebugIngestEnabled() {
+    const search = getWindowLocationSearch();
+    try {
+        return new URLSearchParams(search).get('debug') === '1';
+    }
+    catch {
+        return false;
+    }
+}
+
+// Dynamically resolve the PCA constructor for different build types
+const PCAClass = PCA.default ||
+    PCA.PCA ||
+    PCA;
+let dynamicCounts = {
+    attributes: 8,
+    preferences: 8
+};
+function updateCounts(attrCount, prefCount) {
+    dynamicCounts.attributes = attrCount;
+    dynamicCounts.preferences = prefCount;
+}
+/**
+ * Performs PCA on a list of attribute arrays to map them into 3D space.
+ * Returns:
+ *  - positions: normalized [x, y, z] tuples
+ *  - weights: per-attribute magnitude across PCA components
+ *  - pca: fitted model and maxAbs for projecting any vector to the same 3D space
+ */
+function computePCA3D(attributesList) {
+    const pca = new PCAClass(attributesList, { center: true, scale: true });
+    const reduced = pca.predict(attributesList, { nComponents: 3 }).to2DArray();
+    // --- Compute per-attribute weights ---
+    const loadings = pca.getLoadings().to2DArray();
+    const weights = loadings.map((arr) => Math.sqrt(arr[0] ** 2 + arr[1] ** 2 + arr[2] ** 2));
+    const maxAbs = Math.max(1e-6, ...reduced.flatMap((arr) => arr.map((v) => Math.abs(v))));
+    const positions = reduced.map((arr) => [
+        arr[0] / maxAbs,
+        arr[1] / maxAbs,
+        arr[2] / maxAbs
+    ]);
+    return { positions, weights, pca, maxAbs };
+}
+function generateAttributes(count, base = 0) {
+    const attrs = {};
+    for (let i = 0; i < count; i++)
+        attrs[`attr${i + 1}`] = (base + i * 20) % 101;
+    return attrs;
+}
+// Default node colors: SMBH black, BHs dark blue (#00001E)
+const defaultSMBHColor = '#000000';
+const defaultBHColor = '#00001E';
+const baseNodes = [
+    {
+        id: 1,
+        name: 'James',
+        initialPosition: [0, 0, 0],
+        isSupermassiveBlackhole: true,
+        color: defaultSMBHColor,
+        attributes: generateAttributes(dynamicCounts.attributes, 0),
+        preferences: generateAttributes(dynamicCounts.preferences, 100),
+    },
+    ...[...Array(10)].map((_, i) => {
+        const id = i + 2;
+        const names = ['John', 'Alice', 'Robert', 'Emma', 'Michael', 'Sarah', 'David', 'Lisa', 'Chris', 'Maria'];
+        return {
+            id,
+            name: names[i],
+            initialPosition: [0, 0, 0],
+            isSupermassiveBlackhole: false,
+            color: defaultBHColor,
+            attributes: generateAttributes(dynamicCounts.attributes, i * 10),
+            preferences: generateAttributes(dynamicCounts.preferences, 0),
+        };
+    }),
+];
+const attributesList = baseNodes.map((n) => Object.values(n.attributes));
+const { positions, pca, maxAbs } = computePCA3D(attributesList);
+const attrCount = attributesList[0]?.length ?? 8;
+/**
+ * Projects an attribute or preference vector into the same 3D PCA space used for layout.
+ * Use this to compare preference vs attribute in one dimension per trait, then in 3D.
+ */
+const pcaDim = attributesList[0]?.length ?? 8;
+function projectTo3D(vec) {
+    if (!vec || vec.length === 0)
+        return [0, 0, 0];
+    const row = [];
+    for (let i = 0; i < pcaDim; i++)
+        row.push(typeof vec[i] === 'number' ? vec[i] : 0);
+    const reduced = pca.predict([row], { nComponents: 3 }).to2DArray();
+    const arr = reduced[0];
+    return [
+        arr[0] / maxAbs,
+        arr[1] / maxAbs,
+        arr[2] / maxAbs
+    ];
+}
+const nodeData = baseNodes.map((node, i) => {
+    if (node.isSupermassiveBlackhole)
+        return { ...node, initialPosition: [0, 0, 0] };
+    const [x, y, z] = positions[i];
+    return {
+        ...node,
+        initialPosition: [x * 5, y * 5, z * 5],
+    };
+});
+const attributeWeights = Array.from({ length: attrCount }, () => 1);
+
+/**
+ * Debug frame counters for physics/snapshot logging. Kept in a module instead of
+ * (Blackhole as any) to satisfy strict typing. Only used when ?debug=1 ingest is enabled.
+ */
+let _physicsCallsThisFrame = 0;
+let _debugFrameCount = 0;
+function getPhysicsCallsThisFrame() {
+    return _physicsCallsThisFrame;
+}
+function setPhysicsCallsThisFrame(value) {
+    _physicsCallsThisFrame = value;
+}
+function incrementPhysicsCalls() {
+    _physicsCallsThisFrame += 1;
+    return _physicsCallsThisFrame;
+}
+function getDebugFrameCount() {
+    return _debugFrameCount;
+}
+function incrementDebugFrameCount() {
+    _debugFrameCount += 1;
+    return _debugFrameCount;
+}
+function resetPhysicsCalls() {
+    _physicsCallsThisFrame = 0;
+}
+
+class Blackhole extends THREE.Object3D {
     options;
     velocity;
-    isSun;
+    isSupermassiveBlackhole;
     attributes;
     preferences;
     preference = 0;
     mesh;
     swap = null;
+    nodeMaterial = null;
+    fixedY = 0;
     static attributeWeights = [];
     static preferenceWeights = [];
+    static toNumberArray(v) {
+        if (!v)
+            return [];
+        if (Array.isArray(v))
+            return v.slice();
+        return Object.values(v);
+    }
     static normalizeWeights(weights, len) {
         const list = Array.isArray(weights) ? weights.slice(0, len) : [];
         const extended = list.slice();
@@ -23,258 +188,502 @@ class Node extends THREE.Object3D {
             extended.push(1);
         return extended.map((w) => (Number.isFinite(w) && w >= 0 ? w : 0));
     }
-    sunBaseScale = 3;
-    halo;
-    coreSprite;
-    haloSprite;
-    baseSphereRadius = 0.05; // geometry radius
+    supermassiveBlackholeBaseScale = 1.4;
+    baseSphereRadius = 8; // geometry radius
     clock = new THREE.Clock();
+    /** Used by Cluster for deltaTime. */
+    getClockDelta() {
+        return this.clock.getDelta();
+    }
+    /** Reused force vectors per blackhole index (avoids N² allocations per frame). */
+    _forces = [];
+    _scratchD = new THREE.Vector3();
+    _scratchDir = new THREE.Vector3();
+    _scratchF = new THREE.Vector3();
     constructor(data, options) {
         super();
         this.options = options;
         this.position.fromArray(data.initialPosition);
+        this.position.y = 0;
         this.velocity = new THREE.Vector3(0, 0, 0);
         this.userData = { ...data };
-        this.isSun = data.isSun;
+        this.isSupermassiveBlackhole = data.isSupermassiveBlackhole;
         this.attributes = data.attributes
             ? [...Object.values(data.attributes)]
             : Array.from({ length: 10 }, () => Math.floor(Math.random() * 99));
         this.preferences = data.preferences
             ? [...Object.values(data.preferences)]
             : Array.from({ length: 10 }, () => Math.floor(Math.random() * 99));
-        // Create glowing core using additive Fresnel-like shader (center-bright)
         const geom = new THREE.SphereGeometry(this.baseSphereRadius, 48, 48);
-        const coreMat = makeCoreGlowMaterial(this.isSun ? new THREE.Color('#C300FF') : new THREE.Color('#FF3366'), this.isSun ? 0.9 : 0.7, 3.5, this.isSun ? 0.6 : 0.35 // base floor so planets stay red from all angles
-        );
-        this.mesh = new THREE.Mesh(geom, coreMat);
+        this.nodeMaterial = new THREE.MeshBasicMaterial({ color: 0x000000 });
+        this.mesh = new THREE.Mesh(geom, this.nodeMaterial);
         this.add(this.mesh);
-        // Soft additive rim glow (BackSide Fresnel)
-        const haloMat = makeRimGlowMaterial(this.isSun ? new THREE.Color('#C300FF') : new THREE.Color('#FF3366'), this.isSun ? 0.22 : 0.16, 0.2, 2.2);
-        this.halo = new THREE.Mesh(geom.clone(), haloMat);
-        this.halo.scale.setScalar(this.isSun ? 1.8 : 1.35);
-        this.add(this.halo);
-        // Camera-facing luminous core billboard to ensure visibility from all angles
-        this.coreSprite = this.createBillboardGlow(this.isSun ? new THREE.Color('#C300FF') : new THREE.Color('#FF3366'), this.isSun ? 0.35 : 0.25, // reduced to avoid washing out particles
-        this.isSun ? 1.4 : 1.05);
-        this.coreSprite.visible = false; // keep glow sprites hidden for clearer particles
-        this.add(this.coreSprite);
-        // Softer, larger halo billboard (always-on rim feel)
-        this.halo.visible = false; // keep mesh halo hidden
-        this.haloSprite = this.createBillboardGlow(this.isSun ? new THREE.Color('#C300FF') : new THREE.Color('#FF3366'), this.isSun ? 0.08 : 0.06, // much softer halo
-        this.isSun ? 2.2 : 1.6);
-        this.haloSprite.renderOrder = 18;
-        this.haloSprite.visible = false; // hide outer halo to ensure particles remain readable
-        this.add(this.haloSprite);
-    }
-    updatePhysics(nodes, central, deltaTime) {
-        if (!nodes || nodes.length === 0)
+    }
+    enforceFixedY() {
+        this.position.y = this.fixedY;
+    }
+    updatePhysics(blackholes, central, deltaTime) {
+        if (!blackholes || blackholes.length === 0)
             return;
-        const forces = nodes.map(() => new THREE.Vector3());
-        // --- Attraction: from each non-sun node to central (sun) ---
+        // #region agent log
+        incrementPhysicsCalls();
+        const blackholeIndices = central ? blackholes.map((b, idx) => idx).filter((idx) => blackholes[idx] !== central) : [];
+        const logFrame = getDebugFrameCount() % 60 === 0;
+        if (logFrame && isDebugIngestEnabled()) {
+            const aw = Blackhole.attributeWeights;
+            const sample = (aw?.length && aw.length > 0) ? [aw[0], aw[1], aw[2]] : [];
+            const weightSum = (aw?.length && aw.length > 0) ? aw.slice(0, 8).reduce((s, w) => s + (Number(w) || 0), 0) : 0;
+            fetch('http://127.0.0.1:7243/ingest/eb74700b-8e83-4a1d-a30e-6c89d056a897', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ hypothesisId: 'H5', location: 'Blackhole.ts:updatePhysics', message: 'attributeWeights static', data: { attributeWeightsLength: aw?.length ?? 0, sample, weightSum }, timestamp: Date.now() }) }).catch(() => { });
+        }
+        // #endregion
+        const forces = this._forces;
+        while (forces.length < blackholes.length) {
+            forces.push(new THREE.Vector3());
+        }
+        for (let i = 0; i < blackholes.length; i++) {
+            forces[i].set(0, 0, 0);
+        }
+        // Central: desired distance from PCA compatibility; min/max in SMBHW from options.
+        const supermassiveWidth = 2 * 8 * 1.4;
+        const minW = this.options.supermassiveBlackHole.minDistanceWidths ?? 0.25;
+        const maxW = this.options.supermassiveBlackHole.maxDistanceWidths ?? 7;
+        const viewableRadius = maxW * supermassiveWidth;
+        const minDistFromCentral = minW * supermassiveWidth;
+        // Per-BH preferred compatibility with central (BH attributes vs SMBH preferences). Used to reduce repulsion on same-trait BHs.
+        const compatWithCentral = [];
+        for (let k = 0; k < blackholes.length; k++) {
+            compatWithCentral[k] = 0;
+            if (central && blackholes[k] !== central) {
+                compatWithCentral[k] = blackholes[k].calculatePreferredCompatibility(central);
+            }
+        }
+        // Per-BH "neighbor repulsion pressure" (PCA: dissimilar neighbors repel); attenuates drift toward SMBH.
+        const neighborPressure = [];
+        for (let i = 0; i < blackholes.length; i++) {
+            neighborPressure[i] = 0;
+            const a = blackholes[i];
+            if (a === central)
+                continue;
+            for (let j = 0; j < blackholes.length; j++) {
+                if (j === i || blackholes[j] === central)
+                    continue;
+                const b = blackholes[j];
+                const dist = Math.max(1e-4, a.position.distanceTo(b.position));
+                const compat = a.calculateAttributeCompatibility(b);
+                neighborPressure[i] += (1 - compat) / (dist * 0.01 + 1);
+            }
+        }
         if (central) {
-            for (let i = 0; i < nodes.length; i++) {
-                const node = nodes[i];
-                if (node === central)
+            const d = this._scratchD;
+            for (let i = 0; i < blackholes.length; i++) {
+                const bh = blackholes[i];
+                if (bh === central)
+                    continue;
+                d.copy(central.position).sub(bh.position);
+                const distance = Math.sqrt(d.lengthSq() + 1e-4);
+                // Collision: prevent blackhole from passing through SMBH (position correction when overlapping).
+                const centralScale = central.mesh?.scale?.x ?? 1;
+                const centralRadius = central.baseSphereRadius * centralScale * 1;
+                const bhRadius = bh.baseSphereRadius * bh.mesh.scale.x * 1;
+                const minDistCentral = centralRadius + bhRadius;
+                if (distance < minDistCentral && distance > 1e-8) {
+                    const overlap = minDistCentral - distance;
+                    d.normalize();
+                    // Push blackhole away from central: d points bh→central, so use -d to move bh outward
+                    this._scratchF.copy(d).multiplyScalar(-overlap * 1.2);
+                    this._scratchF.z = 0;
+                    bh.position.add(this._scratchF);
+                    bh.position.y = 0;
+                    // Resolve velocity so blackhole is not moving toward central (stops bounce/jitter).
+                    const towardCentral = bh.velocity.dot(d);
+                    if (towardCentral > 0)
+                        bh.velocity.addScaledVector(d, -towardCentral);
+                    bh.velocity.y = 0;
+                    d.copy(central.position).sub(bh.position);
+                    d.y = 0;
+                }
+                const distanceAfterCollision = Math.sqrt(d.lengthSq() + 1e-4);
+                // PCA: single-trait-to-xyz via projectTo3D in calculatePreferredCompatibility; settle by attr vs SMBH prefs.
+                const compatibility = bh.calculatePreferredCompatibility(central);
+                const desiredWidths = minW + (1 - compatibility) * (maxW - minW);
+                const desiredDist = desiredWidths * supermassiveWidth;
+                const error = distanceAfterCollision - desiredDist;
+                const settlingStiffness = compatibility > 0.9 ? 0.85 : 0.14;
+                let settlingMag = settlingStiffness * error;
+                // Attenuate drift by neighbor repulsion only when BH is not very similar to SMBH; same-trait BHs (e.g. Alice) must settle close.
+                const pressure = neighborPressure[i] ?? 0;
+                const attenuation = compatibility > 0.9 ? 1 : (1 / (1 + 0.25 * pressure));
+                settlingMag *= attenuation;
+                const settlingCap = compatibility > 0.9 ? 9 : 2.5;
+                settlingMag = Math.max(-settlingCap, Math.min(settlingCap, settlingMag));
+                d.normalize();
+                this._scratchF.copy(d).multiplyScalar(settlingMag);
+                forces[i].add(this._scratchF);
+                const falloffDenom = Math.sqrt(distanceAfterCollision + 1) * 2.5 + 2;
+                let centralMag = (this.options.supermassiveBlackHole.attraction * compatibility * 3.0) / falloffDenom;
+                if (compatibility > 0.8)
+                    centralMag *= Math.min(1 + (compatibility - 0.8) * 1.5, 1.5);
+                if (compatibility > 0.9 && distanceAfterCollision > desiredDist * 1.2)
+                    centralMag *= 2.2;
+                d.copy(central.position).sub(bh.position).normalize().multiplyScalar(centralMag);
+                d.clampLength(0, compatibility > 0.9 ? 3.2 : 1.4);
+                forces[i].add(d);
+                if (distanceAfterCollision > viewableRadius) {
+                    const excess = distanceAfterCollision - viewableRadius;
+                    const boundaryMag = Math.min(excess * 0.45 * compatibility, 22);
+                    this._scratchF.copy(central.position).sub(bh.position).normalize().multiplyScalar(boundaryMag);
+                    forces[i].add(this._scratchF);
+                }
+            }
+        }
+        // #region agent log — per-BH preferredCompat and distance (to verify same-trait nodes e.g. Alice settle close)
+        if (logFrame && central && isDebugIngestEnabled()) {
+            const perBh = [];
+            for (let k = 0; k < blackholes.length; k++) {
+                const b = blackholes[k];
+                if (b === central)
                     continue;
-                const d = central.position.clone().sub(node.position);
-                const distanceSq = d.lengthSq() + 1e-4;
-                const compatibility = node.calculatePreferredCompatibility(central);
-                let force = d
-                    .normalize()
-                    .multiplyScalar((this.options.sun.attraction * compatibility * 2.0) /
-                    (distanceSq + 0.5));
-                // Clamp runaway attraction
-                force.clampLength(0, 0.08);
-                forces[i].add(force);
-            }
-        }
-        // ---Outer ↔ Outer interactions (blend of attraction and repulsion) ---
-        for (let i = 0; i < nodes.length; i++) {
-            const a = nodes[i];
+                const compat = b.calculatePreferredCompatibility(central);
+                const dw = minW + (1 - compat) * (maxW - minW);
+                const dist = central.position.distanceTo(b.position);
+                perBh.push({
+                    name: String(b.userData?.['name'] ?? ''),
+                    preferredCompat: compat,
+                    desiredWidths: dw,
+                    distFromCentral: dist,
+                    distInWidths: dist / supermassiveWidth,
+                });
+            }
+            if (perBh.length > 0) {
+                fetch('http://127.0.0.1:7243/ingest/eb74700b-8e83-4a1d-a30e-6c89d056a897', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ hypothesisId: 'compat', location: 'Blackhole.ts:perBhCompat', message: 'per-BH preferredCompat and distance', data: { frame: getDebugFrameCount(), viewableRadius, minW, maxW, perBh }, timestamp: Date.now() }) }).catch(() => { });
+            }
+        }
+        // #endregion
+        const dir = this._scratchDir;
+        const scratchF = this._scratchF;
+        for (let i = 0; i < blackholes.length; i++) {
+            const a = blackholes[i];
             if (a === central)
                 continue;
-            for (let j = i + 1; j < nodes.length; j++) {
-                const b = nodes[j];
+            for (let j = i + 1; j < blackholes.length; j++) {
+                const b = blackholes[j];
                 if (b === central)
                     continue;
-                const dir = b.position.clone().sub(a.position);
+                dir.copy(b.position).sub(a.position);
+                dir.y = 0;
                 const distSq = dir.lengthSq() + 1e-6;
                 const dist = Math.sqrt(distSq);
                 if (dist < 1e-8)
                     continue;
-                const similarity = a.calculateAttributeCompatibility(b);
-                const dissimilarity = 1 - similarity;
-                const radiusA = a.baseSphereRadius * a.mesh.scale.x;
-                const radiusB = b.baseSphereRadius * b.mesh.scale.x;
-                const minDist = (radiusA + radiusB) * 1;
+                const visualRadiusA = a.baseSphereRadius * a.mesh.scale.x * 1;
+                const visualRadiusB = b.baseSphereRadius * b.mesh.scale.x * 1;
+                const minDist = visualRadiusA + visualRadiusB;
+                const compatibility = a.calculateAttributeCompatibility(b);
+                // #region agent log (first blackhole-blackhole pair; index 0 is often central so (0,3) never ran)
+                if (logFrame && blackholeIndices.length >= 2 && i === blackholeIndices[0] && j === blackholeIndices[1] && isDebugIngestEnabled()) {
+                    fetch('http://127.0.0.1:7243/ingest/eb74700b-8e83-4a1d-a30e-6c89d056a897', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ hypothesisId: 'H4', location: 'Blackhole.ts:pairwise_first_pair', message: 'first blackhole-blackhole pair compat', data: { i, j, compatibility, dist, minDist, overlap: minDist - dist, similarity: compatibility, dissimilarity: 1 - compatibility, attrsA: a.attributes?.slice(0, 4), attrsB: b.attributes?.slice(0, 4) }, timestamp: Date.now() }) }).catch(() => { });
+                }
+                // #endregion
+                if (compatibility > 0.95) {
+                    const overlap = minDist - dist;
+                    if (overlap > 0) {
+                        dir.normalize();
+                        scratchF.copy(dir).multiplyScalar(overlap * 1.2);
+                        scratchF.z = 0;
+                        a.position.sub(scratchF);
+                        b.position.add(scratchF);
+                        a.position.y = 0;
+                        b.position.y = 0;
+                        // Resolve approach velocity to prevent bounce/jitter.
+                        const relVel = b.velocity.dot(dir) - a.velocity.dot(dir);
+                        if (relVel < 0) {
+                            const k = relVel / 2;
+                            a.velocity.addScaledVector(dir, k);
+                            b.velocity.addScaledVector(dir, -k);
+                            a.velocity.y = 0;
+                            b.velocity.y = 0;
+                        }
+                    }
+                    // No extra attraction when already very close — let separation dominate so they don’t pile up
+                    if (overlap > 0)
+                        continue; // already handled; skip dist < minDist to avoid double position/velocity correction
+                }
                 if (dist < minDist) {
-                    const repel = dir
-                        .normalize()
-                        .multiplyScalar(this.options.planet.repulsion / (distSq + 0.01));
-                    repel.clampLength(0, 0.25);
-                    forces[i].sub(repel);
-                    forces[j].add(repel);
+                    dir.normalize();
+                    const overlap = minDist - dist;
+                    // Position correction for all overlapping pairs so BHs cannot pass through each other (collision on for similar and dissimilar).
+                    const separatePush = Math.max(0.15, overlap * 1.2);
+                    scratchF.copy(dir).multiplyScalar(separatePush);
+                    scratchF.z = 0;
+                    a.position.sub(scratchF);
+                    b.position.add(scratchF);
+                    a.position.y = 0;
+                    b.position.y = 0;
+                    // Resolve approach velocity so they separate instead of bouncing every frame (stops jitter).
+                    const relVel = b.velocity.dot(dir) - a.velocity.dot(dir);
+                    if (relVel < 0) {
+                        const k = relVel / 2;
+                        a.velocity.addScaledVector(dir, k);
+                        b.velocity.addScaledVector(dir, -k);
+                        a.velocity.y = 0;
+                        b.velocity.y = 0;
+                    }
+                    // Also add force for extra separation
+                    const push = Math.max(0.15, overlap * 0.3);
+                    scratchF.copy(dir).multiplyScalar(-push);
+                    forces[i].add(scratchF);
+                    scratchF.copy(dir).multiplyScalar(push);
+                    forces[j].add(scratchF);
                     continue;
                 }
-                const attractMag = (30 * similarity * 3.0) / (distSq + 0.5);
-                const repelMag = 90 * dissimilarity / (distSq + 0.5);
+                const similarity = compatibility;
+                const dissimilarity = 1 - compatibility;
+                const exp = Math.min(4, Math.max(1, a.options.blackhole.dissimilarityRepulsionExponent ?? 2));
+                const dNorm = Math.pow(dissimilarity, exp);
+                // Attraction: reduced so similar nodes cluster but don’t collapse on top of each other
+                let attractMag = similarity >= 0.5
+                    ? (45 * similarity) / (dist + 8.0)
+                    : 0;
+                // Repulsion: stronger and longer range so dissimilar groups actually spread apart (gentler falloff)
+                const mult = a.options.blackhole.pairwiseRepulsionMultiplier ?? 1;
+                const repulsionBase = (a.options.blackhole.pairwiseRepulsionMain ?? 52) * mult;
+                let repelMag = repulsionBase * 2.5 * dNorm / (dist * 0.08 + 3);
+                if (similarity > 0.85) {
+                    attractMag *= 1.3;
+                    repelMag *= 0.25;
+                }
+                // dir = B - A: positive netMag = pull A toward B (attract), negative = push A away from B (repel)
                 const netMag = attractMag - repelMag;
                 if (Math.abs(netMag) < 1e-4)
                     continue;
-                const f = dir.normalize().multiplyScalar(netMag).clampLength(-0.9, 0.9);
-                forces[i].add(f);
-                forces[j].add(f.clone().multiplyScalar(-1));
+                // Strong repulsion (up to 10); mild attraction (cap 2) so similar stay near but not on top
+                dir.normalize().multiplyScalar(netMag).clampLength(-10, 2);
+                // Same-trait BHs (high compat with SMBH) receive much less pairwise repulsion so they can settle close to central
+                const scaleI = (compatWithCentral[i] > 0.9 && netMag < 0) ? 0.05 : 1;
+                const scaleJ = (compatWithCentral[j] > 0.9 && netMag < 0) ? 0.05 : 1;
+                // #region agent log
+                if (logFrame && blackholeIndices.length >= 2 && i === blackholeIndices[0] && j === blackholeIndices[1]) {
+                    const ax = dir.x;
+                    const ay = dir.y;
+                    const az = dir.z;
+                    fetch('http://127.0.0.1:7243/ingest/eb74700b-8e83-4a1d-a30e-6c89d056a897', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ hypothesisId: 'B', location: 'Blackhole.ts:pairwise', message: 'pair 0-1 force', data: { similarity, dissimilarity, attractMag, repelMag, netMag, forceOnI: { x: ax, y: ay, z: az }, dist }, timestamp: Date.now() }) }).catch(() => { });
+                }
+                // #endregion
+                scratchF.copy(dir).multiplyScalar(scaleI);
+                forces[i].add(scratchF);
+                scratchF.copy(dir).multiplyScalar(-scaleJ);
+                forces[j].add(scratchF);
             }
         }
-        // ---Extra Repulsion (outer nodes only) ---
-        for (let i = 0; i < nodes.length; i++) {
-            const a = nodes[i];
+        for (let i = 0; i < blackholes.length; i++) {
+            const a = blackholes[i];
             if (a === central)
                 continue;
-            for (let j = i + 1; j < nodes.length; j++) {
-                const b = nodes[j];
+            for (let j = i + 1; j < blackholes.length; j++) {
+                const b = blackholes[j];
                 if (b === central)
                     continue;
-                const dir = a.position.clone().sub(b.position);
+                dir.copy(a.position).sub(b.position);
                 const distSq = dir.lengthSq() + 1e-4;
+                const distSec = Math.sqrt(distSq);
                 const similarity = a.calculateAttributeCompatibility(b);
-                const mag = 20 * (1 - similarity) / (distSq + 0.5);
-                const f = dir.normalize().multiplyScalar(mag).clampLength(0, 0.9);
-                forces[i].add(f);
-                forces[j].add(f.clone().multiplyScalar(-1));
+                const d = 1 - similarity;
+                const exp = Math.min(4, Math.max(1, a.options.blackhole.dissimilarityRepulsionExponent ?? 2));
+                const dNorm = Math.pow(d, exp);
+                const multSec = a.options.blackhole.pairwiseRepulsionMultiplier ?? 1;
+                const secBase = (a.options.blackhole.pairwiseRepulsionSecondary ?? 42) * multSec;
+                const mag = secBase * 2 * dNorm / (distSec * 0.08 + 3);
+                // Cap per-pair repulsion at 6 so dissimilar groups spread out
+                dir.normalize().multiplyScalar(mag).clampLength(0, 6);
+                const secScaleI = compatWithCentral[i] > 0.9 ? 0.05 : 1;
+                const secScaleJ = compatWithCentral[j] > 0.9 ? 0.05 : 1;
+                scratchF.copy(dir).multiplyScalar(secScaleI);
+                forces[i].add(scratchF);
+                scratchF.copy(dir).multiplyScalar(-secScaleJ);
+                forces[j].add(scratchF);
             }
         }
-        // --- Apply forces → velocities → positions ---
-        for (let i = 0; i < nodes.length; i++) {
-            const node = nodes[i];
-            if (node == central)
+        // #region agent log
+        if (logFrame && blackholeIndices[0] !== undefined) {
+            const totalAccel = forces[blackholeIndices[0]]?.length?.() ?? 0;
+            fetch('http://127.0.0.1:7243/ingest/eb74700b-8e83-4a1d-a30e-6c89d056a897', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ hypothesisId: 'C', location: 'Blackhole.ts:beforeApply', message: 'total acceleration mag first blackhole', data: { totalAccelMag: totalAccel }, timestamp: Date.now() }) }).catch(() => { });
+        }
+        // #endregion
+        let didLogLocThisFrame = false;
+        for (let i = 0; i < blackholes.length; i++) {
+            const bh = blackholes[i];
+            if (bh == central)
                 continue;
-            if (!(node.velocity instanceof THREE.Vector3)) {
-                node.velocity = new THREE.Vector3(0, 0, 0);
+            if (!(bh.velocity instanceof THREE.Vector3)) {
+                bh.velocity = new THREE.Vector3(0, 0, 0);
             }
             const effectiveDt = Math.min(deltaTime, 0.95);
             const acceleration = forces[i];
-            // apply acceleration
-            node.velocity.addScaledVector(acceleration, effectiveDt);
-            // --- jitter suppression ---
-            // add a small deadzone to prevent micro-oscillation
-            if (node.velocity.lengthSq() < 1e-10) {
-                node.velocity.set(0, 0, 0);
+            bh.velocity.addScaledVector(acceleration, effectiveDt);
+            bh.velocity.y = 0;
+            // Light similarity boost so similar nodes still cluster, but don’t over-amplify (was 2.0, caused pile-up)
+            if (!bh.isSupermassiveBlackhole) {
+                let boost = 1.0;
+                for (let j = 0; j < blackholes.length; j++) {
+                    const other = blackholes[j];
+                    if (other === bh || other.isSupermassiveBlackhole)
+                        continue;
+                    const similarity = bh.calculateAttributeCompatibility(other);
+                    if (similarity > 0.85)
+                        boost += (similarity - 0.85) * 0.4;
+                }
+                boost = Math.min(boost, 1.25);
+                forces[i].multiplyScalar(boost);
+            }
+            if (bh.velocity.lengthSq() < 1e-10) {
+                bh.velocity.set(0, 0, 0);
                 continue;
             }
-            // soft low-pass filter to smooth small fluctuations
-            node.velocity.lerp(node.velocity.clone(), 0.95);
-            // damping
-            // const dampingFactor = 1 - 0.8 * 0.9;
-            const dampingFactor = 0.181;
-            node.velocity.multiplyScalar(dampingFactor);
-            // clamp to prevent small high-frequency shake
-            node.velocity.clampLength(0, 0.15);
-            // integrate motion
-            node.position.addScaledVector(node.velocity, effectiveDt);
-            // --- Multi-node jitter suppression (group stabilizer) ---
-            if (nodes.length > 2) {
+            bh.velocity.multiplyScalar(0.96);
+            bh.position.addScaledVector(bh.velocity, effectiveDt);
+            bh.position.y = 0;
+            // Clamp BH to viewport: no closer than minW SMBHW, no further than maxW SMBHW (e.g. 14 SMBHW diameter when max=7).
+            if (central && bh !== central) {
+                const distFromCentral = central.position.distanceTo(bh.position) + 1e-6;
+                const toBh = bh.position.clone().sub(central.position);
+                toBh.y = 0;
+                if (distFromCentral > 1e-6) {
+                    if (distFromCentral > viewableRadius) {
+                        toBh.normalize().multiplyScalar(viewableRadius);
+                        bh.position.copy(central.position).add(toBh);
+                        bh.position.y = 0;
+                        bh.velocity.multiplyScalar(0.82);
+                        // #region agent log
+                        if (logFrame && isDebugIngestEnabled()) {
+                            fetch('http://127.0.0.1:7243/ingest/eb74700b-8e83-4a1d-a30e-6c89d056a897', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ hypothesisId: 'viewport', location: 'Blackhole.ts:clampMax', message: 'BH clamped to max viewport radius', data: { bhIndex: i, distFromCentralBefore: distFromCentral, viewableRadius, distInWidths: distFromCentral / supermassiveWidth }, timestamp: Date.now() }) }).catch(() => { });
+                        }
+                        // #endregion
+                    }
+                    else if (distFromCentral < minDistFromCentral) {
+                        this._scratchD.copy(bh.position).sub(central.position).normalize();
+                        this._scratchF.copy(this._scratchD).multiplyScalar(minDistFromCentral);
+                        bh.position.copy(central.position).add(this._scratchF);
+                        bh.position.y = 0;
+                        const dot = bh.velocity.dot(this._scratchD);
+                        if (dot < 0)
+                            bh.velocity.addScaledVector(this._scratchD, -dot);
+                        // #region agent log
+                        if (logFrame && isDebugIngestEnabled()) {
+                            fetch('http://127.0.0.1:7243/ingest/eb74700b-8e83-4a1d-a30e-6c89d056a897', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ hypothesisId: 'viewport', location: 'Blackhole.ts:clampMin', message: 'BH clamped to min distance', data: { bhIndex: i, distFromCentralBefore: distFromCentral, minDistFromCentral, distInWidths: distFromCentral / supermassiveWidth }, timestamp: Date.now() }) }).catch(() => { });
+                        }
+                        // #endregion
+                    }
+                }
+            }
+            // Jitter reduction: when very slow and near equilibrium, zero velocity so nodes/particles don't jitter.
+            const speedSq = bh.velocity.lengthSq();
+            if (speedSq < 4e-4) {
+                bh.velocity.set(0, 0, 0);
+            }
+            else if (speedSq < 0.0025) {
+                bh.velocity.multiplyScalar(0.92);
+            }
+            // #region agent log — location over time: BH vs SMBH (first non-central BH every 60 frames)
+            if (logFrame && central && !didLogLocThisFrame && isDebugIngestEnabled()) {
+                didLogLocThisFrame = true;
+                const dFromCentral = central.position.distanceTo(bh.position);
+                const inView = dFromCentral <= viewableRadius && dFromCentral >= minDistFromCentral;
+                fetch('http://127.0.0.1:7243/ingest/eb74700b-8e83-4a1d-a30e-6c89d056a897', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ hypothesisId: 'loc', location: 'Blackhole.ts:locationOverTime', message: 'BH vs SMBH distance and viewport', data: { frame: getDebugFrameCount(), bhIndex: i, distFromCentral: dFromCentral, viewableRadius, minDistFromCentral, distInWidths: dFromCentral / supermassiveWidth, inViewableZone: inView, velocityMag: bh.velocity.length() }, timestamp: Date.now() }) }).catch(() => { });
+            }
+            // #endregion
+            if (blackholes.length > 2) {
                 let nearCount = 0;
-                for (let j = 0; j < nodes.length; j++) {
-                    if (j === i || nodes[j] === central)
+                for (let j = 0; j < blackholes.length; j++) {
+                    if (j === i || blackholes[j] === central)
                         continue;
-                    const d = node.position.distanceTo(nodes[j].position);
+                    const d = bh.position.distanceTo(blackholes[j].position);
                     if (d < 0.35)
-                        nearCount++; // consider nodes within a small neighborhood
+                        nearCount++;
                 }
-                // if surrounded by 2+ near neighbors and moving very slowly, freeze micro motion
-                if (nearCount >= 2 && node.velocity.lengthSq() < 1e-5) {
-                    node.velocity.multiplyScalar(0.1); // heavy dampening
-                    if (node.velocity.lengthSq() < 1e-10)
-                        node.velocity.set(0, 0, 0);
+                if (nearCount >= 2 && bh.velocity.lengthSq() < 1e-5) {
+                    bh.velocity.multiplyScalar(0.1);
+                    if (bh.velocity.lengthSq() < 1e-10)
+                        bh.velocity.set(0, 0, 0);
                 }
             }
         }
-        // --- Final stabilization: prevent overlap among similar clusters ---
-        const separationRadius = 0.12;
-        const stiffness = 0.1;
-        for (let i = 0; i < nodes.length; i++) {
-            const a = nodes[i];
+        // Enforce minimum separation so nodes stay visible and don’t stack
+        const separationRadius = 0.4;
+        const stiffness = 0.6;
+        for (let i = 0; i < blackholes.length; i++) {
+            const a = blackholes[i];
             if (a === central)
                 continue;
-            for (let j = i + 1; j < nodes.length; j++) {
-                const b = nodes[j];
+            for (let j = i + 1; j < blackholes.length; j++) {
+                const b = blackholes[j];
                 if (b === central)
                     continue;
-                const dir = a.position.clone().sub(b.position);
+                dir.copy(a.position).sub(b.position);
                 const dist = dir.length();
                 if (dist < separationRadius && dist > 0.01) {
-                    // very small corrective displacement only, not a new force
                     const overlap = separationRadius - dist;
-                    const correction = dir.normalize().multiplyScalar(overlap * stiffness);
-                    a.position.add(correction);
-                    b.position.sub(correction);
+                    scratchF.copy(dir).normalize().multiplyScalar(overlap * stiffness);
+                    a.position.add(scratchF);
+                    b.position.sub(scratchF);
                 }
             }
         }
-    }
-    setSun(state = !this.isSun, preference) {
-        this.isSun = state;
-        if (state) {
-            // Switch to neon purple core; keep sprites hidden for clarity
-            const core = this.mesh.material;
-            core.uniforms['glowColor'].value = new THREE.Color('#C300FF');
-            core.uniforms['opacity'].value = 0.9;
-            core.uniforms['base'].value = 0.6;
-            const halo = this.halo.material;
-            halo.uniforms['glowColor'].value = new THREE.Color('#C300FF');
-            halo.uniforms['opacity'].value = 0.22;
-            this.halo.scale.setScalar(1.8);
-            // Billboard core (hidden)
-            this.coreSprite.material.color =
-                new THREE.Color('#C300FF');
-            this.coreSprite.material.opacity = 0.35;
-            const dSun = this.baseSphereRadius * 2 * 1.8;
-            this.coreSprite.scale.set(dSun, dSun, 1);
-            // Billboard halo (hidden)
-            this.haloSprite.material.color =
-                new THREE.Color('#C300FF');
-            this.haloSprite.material.opacity = 0.08;
-            const dSunHalo = this.baseSphereRadius * 2 * 3.0;
-            this.haloSprite.scale.set(dSunHalo, dSunHalo, 1);
-        }
-        else {
-            // Switch to pink-red core; keep sprites hidden for clarity
-            const core = this.mesh.material;
-            core.uniforms['glowColor'].value = new THREE.Color('#FF3366');
-            core.uniforms['opacity'].value = 0.7;
-            core.uniforms['base'].value = 0.35;
-            const halo = this.halo.material;
-            halo.uniforms['glowColor'].value = new THREE.Color('#FF3366');
-            halo.uniforms['opacity'].value = 0.16;
-            this.halo.scale.setScalar(1.35);
-            // Billboard core (hidden)
-            this.coreSprite.material.color =
-                new THREE.Color('#FF3366');
-            this.coreSprite.material.opacity = 0.25;
-            const d = this.baseSphereRadius * 2 * 1.3;
-            this.coreSprite.scale.set(d, d, 1);
-            // Billboard halo (hidden)
-            this.haloSprite.material.color =
-                new THREE.Color('#FF3366');
-            this.haloSprite.material.opacity = 0.06;
-            const dHalo = this.baseSphereRadius * 2 * 2.0;
-            this.haloSprite.scale.set(dHalo, dHalo, 1);
+        // Same-trait BHs (compat with SMBH > 0.95): snap to min distance AFTER separation so they stay at 0.25 SMBHW
+        if (central) {
+            for (let i = 0; i < blackholes.length; i++) {
+                const bh = blackholes[i];
+                if (bh === central)
+                    continue;
+                if (compatWithCentral[i] <= 0.95)
+                    continue;
+                const distFromCentral = central.position.distanceTo(bh.position) + 1e-6;
+                if (distFromCentral <= minDistFromCentral * 1.05)
+                    continue;
+                this._scratchD.copy(bh.position).sub(central.position).normalize();
+                this._scratchF.copy(this._scratchD).multiplyScalar(minDistFromCentral);
+                bh.position.copy(central.position).add(this._scratchF);
+                bh.position.y = 0;
+                const radialVel = bh.velocity.dot(this._scratchD);
+                bh.velocity.addScaledVector(this._scratchD, -radialVel);
+                bh.velocity.y = 0;
+                if (logFrame && isDebugIngestEnabled()) {
+                    fetch('http://127.0.0.1:7243/ingest/eb74700b-8e83-4a1d-a30e-6c89d056a897', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ hypothesisId: 'snap', location: 'Blackhole.ts:snapAfterSep', data: { bhIndex: i, name: bh.userData?.['name'], distBefore: distFromCentral, distAfter: minDistFromCentral }, timestamp: Date.now() }) }).catch(() => { });
+                }
+            }
         }
+    }
+    setSupermassiveBlackhole(state = !this.isSupermassiveBlackhole, preference) {
+        this.isSupermassiveBlackhole = state;
         if (preference !== undefined) {
             this.preference = preference;
         }
     }
-    calculatePreferredCompatibility(sun) {
-        const sunPreferences = sun.preferences;
-        const planetAttributes = this.attributes;
-        const len = Math.min(sunPreferences.length, planetAttributes.length);
-        const weights = Node.normalizeWeights(Node.preferenceWeights, len);
+    /** Preferred compatibility via PCA: map preferences and attributes to 3D (each trait its own dimension, then PCA to 3D) and use distance. */
+    calculatePreferredCompatibility(supermassiveBlackhole) {
+        const prefVec = Blackhole.toNumberArray(supermassiveBlackhole.preferences);
+        const attrVec = Blackhole.toNumberArray(this.attributes);
+        if (prefVec.length === 0 || attrVec.length === 0)
+            return 0;
+        try {
+            const p = projectTo3D(prefVec);
+            const a = projectTo3D(attrVec);
+            const d = Math.sqrt((p[0] - a[0]) ** 2 + (p[1] - a[1]) ** 2 + (p[2] - a[2]) ** 2);
+            return 1 / (1 + d);
+        }
+        catch {
+            return this.fallbackPreferredCompatibility(supermassiveBlackhole);
+        }
+    }
+    fallbackPreferredCompatibility(supermassiveBlackhole) {
+        const centralPreferences = Blackhole.toNumberArray(supermassiveBlackhole.preferences);
+        const blackholeAttributes = Blackhole.toNumberArray(this.attributes);
+        const len = Math.min(centralPreferences.length, blackholeAttributes.length);
+        const weights = Blackhole.normalizeWeights(Blackhole.preferenceWeights, len);
         let diffSum = 0;
         let weightSum = 0;
         for (let i = 0; i < len; i++) {
             const w = weights[i];
-            diffSum += w * Math.abs(sunPreferences[i] - planetAttributes[i]);
+            diffSum += w * Math.abs(centralPreferences[i] - blackholeAttributes[i]);
             weightSum += w;
         }
         const maxDiff = Math.max(1e-6, weightSum * 100);
@@ -284,7 +693,7 @@ class Node extends THREE.Object3D {
         const attributesA = this.attributes;
         const attributesB = other.attributes;
         const len = Math.min(attributesA.length, attributesB.length);
-        const weights = Node.normalizeWeights(Node.attributeWeights, len);
+        const weights = Blackhole.normalizeWeights(Blackhole.attributeWeights, len);
         let diffSum = 0;
         let weightSum = 0;
         for (let i = 0; i < len; i++) {
@@ -295,62 +704,42 @@ class Node extends THREE.Object3D {
         const maxDiff = Math.max(1e-6, weightSum * 100);
         return 1 - diffSum / maxDiff;
     }
-    update(nodes, cursorPosition, scene, camera) {
+    update(blackholes, cursorPosition, scene, camera) {
         if (this.swap) {
             this.handleSwapAnimation();
             return;
         }
-        // Sun: keep steady size and glow (disable pulsation)
-        if (this.isSun) {
-            const targetScale = this.sunBaseScale;
+        // Apply group color from userData when set (e.g. Diverse Groups preset or context menu). Applies to all BHs (planets and SMBH) so opacity knob fades the sphere and reveals particles behind it.
+        if (this.userData?.['color'] && this.nodeMaterial && 'color' in this.nodeMaterial) {
+            const colorStr = String(this.userData['color']).trim();
+            const mat = this.nodeMaterial;
+            if (colorStr.length === 9 && colorStr.startsWith('#') && /^#[0-9a-fA-F]{8}$/.test(colorStr)) {
+                const rgbHex = colorStr.slice(1, 7);
+                const alphaHex = colorStr.slice(7, 9);
+                mat.color.set('#' + rgbHex);
+                mat.opacity = parseInt(alphaHex, 16) / 255;
+                mat.transparent = mat.opacity < 1;
+                mat.depthWrite = mat.opacity >= 1; // transparent sphere must not write depth so it doesn't occlude particles/background
+            }
+            else {
+                mat.color.set(colorStr);
+                mat.opacity = 1;
+                mat.transparent = false;
+                mat.depthWrite = true;
+            }
+            // Draw sphere after particles (renderOrder 0) so the BH is the visible layer that fades; opacity then shows particles behind it
+            this.mesh.renderOrder = 1;
+        }
+        if (this.isSupermassiveBlackhole) {
+            const targetScale = this.supermassiveBlackholeBaseScale;
             this.mesh.scale.lerp(new THREE.Vector3(targetScale, targetScale, targetScale), 0.2);
-            const core = this.mesh.material;
-            core.uniforms['opacity'].value = 0.75;
-            const haloMat = this.halo.material;
-            haloMat.uniforms['opacity'].value = 0.14;
-            const haloScale = 1.8;
-            this.halo.scale.lerp(new THREE.Vector3(haloScale, haloScale, haloScale), 0.2);
-            // Sprites remain hidden/steady
             return;
         }
-        let totalForce = new THREE.Vector3();
-        const sun = nodes.find((n) => n.isSun) ?? null;
-        if (sun) {
-            totalForce.add(this.calculateSunForce(sun));
-            // Update planet glow based on compatibility with sun
-            const compat = this.calculatePreferredCompatibility(sun); // 0..1
-            const core = this.mesh.material;
-            core.uniforms['opacity'].value = 0.55 + compat * 0.4; // brighter core with compatibility
-            // Planet additive halo tightly around mesh
-            const haloMat = this.halo.material;
-            const baseOpacity = 0.12 + compat * 0.25; // 0.12..0.37
-            let proximityBoost = 0;
-            if (cursorPosition) {
-                const d = this.position.distanceTo(cursorPosition);
-                proximityBoost = Math.max(0, 1 - d / 1.5) * 0.04; // very subtle
-            }
-            haloMat.uniforms['opacity'].value = Math.min(0.5, baseOpacity + proximityBoost);
-            this.mesh.scale.set(1.9, 1.9, 1.9);
-            const s = 1.35 * (1 + compat * 0.15);
-            this.halo.scale.lerp(new THREE.Vector3(s, s, s), 0.25);
-            // Billboard tuning for planets
-            const coreMat = this.coreSprite.material;
-            coreMat.opacity = 0.45 + compat * 0.35 + proximityBoost * 0.2;
-            const d2 = this.baseSphereRadius * 2 * (1.3 + compat * 0.2) * this.mesh.scale.x;
-            this.coreSprite.scale.lerp(new THREE.Vector3(d2, d2, 1), 0.2);
-            const haloMatS = this.haloSprite.material;
-            haloMatS.opacity = 0.16 + compat * 0.18 + proximityBoost * 0.1;
-            const d2h = this.baseSphereRadius * 2 * (2.0 + compat * 0.5) * this.mesh.scale.x;
-            this.haloSprite.scale.lerp(new THREE.Vector3(d2h, d2h, 1), 0.2);
-        }
-        totalForce.add(this.calculatePlanetRepulsion(nodes));
-        totalForce.add(this.calculatePlanetAttraction(nodes));
-        totalForce.multiplyScalar(this.options.velocityDamping);
-        const deltaTime = this.clock.getDelta();
-        this.updatePhysics(nodes, sun, deltaTime);
-        this.applyForces(totalForce);
-    }
-    // (Sprite-based glow removed in favor of additive core + halo meshes)
+        // Blackholes: motion is integrated only in updatePhysics() (central + pairwise attract/repel).
+        // Skipping applyForces here so the central "spring" in calculateSupermassiveBlackHoleForce
+        // doesn't run again and pull everyone back to center, which was overpowering dissimilar repulsion.
+        return;
+    }
     createBillboardGlow(color, opacity, diameterMultiplier) {
         const size = 128;
         const canvas = document.createElement('canvas');
@@ -381,32 +770,32 @@ class Node extends THREE.Object3D {
         sprite.renderOrder = 20;
         return sprite;
     }
-    calculateSunForce(sun) {
+    calculateSupermassiveBlackHoleForce(supermassiveBlackhole) {
         let force = new THREE.Vector3();
-        const compatibility = this.calculatePreferredCompatibility(sun);
-        const desiredDistance = 0.25 + (1 - compatibility) * 4.0;
-        const currentDistance = sun.position.distanceTo(this.position);
+        const compatibility = this.calculatePreferredCompatibility(supermassiveBlackhole);
+        const desiredDistance = 0.15 + (1 - compatibility) * 200.0;
+        const currentDistance = supermassiveBlackhole.position.distanceTo(this.position);
         const error = currentDistance - desiredDistance;
-        const directionToSun = new THREE.Vector3()
-            .subVectors(sun.position, this.position)
+        const directionToCentral = new THREE.Vector3()
+            .subVectors(supermassiveBlackhole.position, this.position)
             .normalize();
         if (currentDistance < desiredDistance) {
-            const repulsionForce = -this.options.sun.repulsion *
+            const repulsionForce = -this.options.supermassiveBlackHole.repulsion *
                 (desiredDistance - currentDistance) *
                 compatibility;
-            force.add(directionToSun.multiplyScalar(repulsionForce));
+            force.add(directionToCentral.multiplyScalar(repulsionForce));
         }
         else {
-            const attractionForce = 2 * this.options.sun.attraction * error * compatibility + 0.001;
-            force.add(directionToSun.multiplyScalar(attractionForce));
+            const attractionForce = 2 * this.options.supermassiveBlackHole.attraction * error * compatibility + 0.001;
+            force.add(directionToCentral.multiplyScalar(attractionForce));
         }
         return force;
     }
-    calculatePlanetAttraction(nodes) {
+    calculateBlackholeAttraction(blackholes) {
         let attractionForce = new THREE.Vector3();
         const attractionConstant = 0.001;
-        nodes.forEach((other) => {
-            if (other !== this && !other.isSun) {
+        blackholes.forEach((other) => {
+            if (other !== this && !other.isSupermassiveBlackhole) {
                 const compatibility = this.calculateAttributeCompatibility(other);
                 const forceMagnitude = attractionConstant * compatibility - 0.001;
                 const attractionDirection = new THREE.Vector3()
@@ -417,17 +806,20 @@ class Node extends THREE.Object3D {
         });
         return attractionForce;
     }
-    calculatePlanetRepulsion(nodes) {
+    calculateBlackholeRepulsion(blackholes) {
         let repulsionForce = new THREE.Vector3();
-        nodes.forEach((other) => {
-            if (other !== this && !other.isSun) {
+        blackholes.forEach((other) => {
+            if (other !== this && !other.isSupermassiveBlackhole) {
                 const distance = this.position.distanceTo(other.position);
-                if (distance < this.options.planet.repulsionInitializationThreshold) {
+                if (distance < this.options.blackhole.repulsionInitializationThreshold) {
                     const compatibility = this.calculateAttributeCompatibility(other);
-                    const repulsion = this.options.planet.repulsion *
-                        (this.options.planet.repulsionInitializationThreshold -
+                    const d = 1 - compatibility;
+                    const exp = Math.min(4, Math.max(1, this.options.blackhole.dissimilarityRepulsionExponent ?? 2));
+                    const dNorm = Math.pow(d, exp);
+                    const repulsion = this.options.blackhole.repulsion *
+                        (this.options.blackhole.repulsionInitializationThreshold -
                             distance) *
-                        (1 - compatibility) +
+                        dNorm +
                         0.001;
                     const repulsionDirection = new THREE.Vector3()
                         .subVectors(this.position, other.position)
@@ -486,7 +878,6 @@ function makeCoreGlowMaterial(color, opacity = 0.8, power = 3.5, base = 0.1) {
     varying vec3 vWorldPosition;
     void main() {
       vec3 viewDir = normalize(cameraPosition - vWorldPosition);
-      // Center-bright with a base floor so sides never go black
       float ndv = clamp(dot(vNormal, viewDir), 0.0, 1.0);
       float intensity = base + (1.0 - base) * pow(ndv, p);
       gl_FragColor = vec4(glowColor * intensity, intensity * opacity);
@@ -542,46 +933,145 @@ function makeRimGlowMaterial(color, opacity = 0.2, c = 0.2, power = 2.2) {
         side: THREE.BackSide,
     });
 }
-Node.prototype.makeCoreGlowMaterial = makeCoreGlowMaterial;
-Node.prototype.makeRimGlowMaterial = makeRimGlowMaterial;
+Blackhole.prototype.makeCoreGlowMaterial = makeCoreGlowMaterial;
+Blackhole.prototype.makeRimGlowMaterial = makeRimGlowMaterial;
 
 class Cluster extends THREE.Object3D {
     options;
-    nodes;
+    blackholes;
+    _lastLogDist = [];
     constructor(nodeData, options) {
         super();
         this.options = {
-            sun: {
-                attraction: 1,
+            supermassiveBlackHole: {
+                attraction: 1.4,
                 repulsion: 1,
                 repulsionInitializationThreshold: 0.4,
+                minDistanceWidths: 0.25,
+                maxDistanceWidths: 7,
             },
-            planet: {
+            blackhole: {
                 attraction: 1,
                 repulsion: 1,
-                repulsionInitializationThreshold: 0.2,
+                repulsionInitializationThreshold: 30.2,
+                pairwiseRepulsionMain: 52,
+                pairwiseRepulsionSecondary: 42,
+                pairwiseRepulsionMultiplier: 1,
+                dissimilarityRepulsionExponent: 2,
             },
-            maxVelocity: 0.02,
-            velocityDamping: 0.8,
+            maxVelocity: 1.0,
+            velocityDamping: 0.85,
             minAttributeValue: 0,
             minPreferenceValue: 0,
             maxAttributeValue: 100,
             maxPreferenceValue: 100,
+            simulationSpeed: 3.25,
             ...options,
         };
-        this.nodes = [];
+        this.blackholes = [];
         this.setUp(nodeData);
     }
     setUp(nodeData) {
         nodeData.forEach((data) => {
-            const node = new Node(data, this.options);
-            this.nodes.push(node);
-            this.add(node);
+            const blackhole = new Blackhole(data, this.options);
+            this.blackholes.push(blackhole);
+            this.add(blackhole);
         });
     }
     update(cursorPosition, scene, camera) {
-        this.nodes.forEach((node) => node.update(this.nodes, cursorPosition, scene, camera));
-        // Bound the position within (-8, -8, -8) and (8, 8, 8)
+        // #region agent log
+        setPhysicsCallsThisFrame(0);
+        const frame = incrementDebugFrameCount();
+        const central = this.blackholes.find((b) => b.isSupermassiveBlackhole);
+        const firstBlackhole = this.blackholes.find((b) => !b.isSupermassiveBlackhole);
+        if (frame % 60 === 0 && isDebugIngestEnabled()) {
+            const opts = this.options;
+            const sbh = opts.supermassiveBlackHole;
+            const bhOpts = opts.blackhole;
+            fetch('http://127.0.0.1:7243/ingest/eb74700b-8e83-4a1d-a30e-6c89d056a897', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ hypothesisId: 'H1_H2', location: 'Cluster.ts:update', message: 'options and updatePhysics gate', data: { frame, hasCentral: !!central, hasFirstBlackhole: !!firstBlackhole, sbhAttraction: sbh?.attraction, sbhRepulsion: sbh?.repulsion, blackholeRepulsion: bhOpts?.repulsion, pairwiseRepulsionMain: bhOpts?.pairwiseRepulsionMain, pairwiseRepulsionSecondary: bhOpts?.pairwiseRepulsionSecondary, optionsRefSameAsFirstBlackhole: firstBlackhole ? firstBlackhole.options === opts : null }, timestamp: Date.now() }) }).catch(() => { });
+        }
+        // #endregion
+        if (firstBlackhole && central) {
+            const rawDt = firstBlackhole.getClockDelta();
+            const speed = this.options.simulationSpeed ?? 1;
+            const deltaTime = rawDt * Math.max(0.1, Math.min(10, speed));
+            firstBlackhole.updatePhysics(this.blackholes, central, deltaTime);
+        }
+        this.blackholes.forEach((bh) => bh.update(this.blackholes, cursorPosition, scene, camera));
+        // #region agent log
+        const nonCentralBlackholes = this.blackholes.filter((b) => !b.isSupermassiveBlackhole);
+        if (central && nonCentralBlackholes.length > 0 && getDebugFrameCount() % 60 === 0 && isDebugIngestEnabled()) {
+            const supermassiveWidth = 2 * 8 * 1.4;
+            const minW = this.options.supermassiveBlackHole.minDistanceWidths ?? 0.25;
+            const maxW = this.options.supermassiveBlackHole.maxDistanceWidths ?? 7;
+            const viewableRadius = maxW * supermassiveWidth;
+            const centralPrefs = Array.isArray(central.preferences) ? [...central.preferences] : [];
+            while (this._lastLogDist.length < nonCentralBlackholes.length)
+                this._lastLogDist.push(0);
+            const positionsRel = nonCentralBlackholes.map((p, idx) => {
+                const relX = p.position.x - central.position.x;
+                const relY = p.position.y - central.position.y;
+                const relZ = p.position.z - central.position.z;
+                const dist = Math.sqrt(relX * relX + relY * relY + relZ * relZ);
+                const distPrev = this._lastLogDist[idx] ?? dist;
+                const distDelta = dist - distPrev;
+                this._lastLogDist[idx] = dist;
+                const inViewableZone = dist <= viewableRadius;
+                const preferredCompat = p.calculatePreferredCompatibility(central);
+                const desiredWidths = minW + (1 - preferredCompat) * (maxW - minW);
+                const desiredDist = desiredWidths * supermassiveWidth;
+                const velocityMag = p.velocity?.length?.() ?? 0;
+                const attrs = Array.isArray(p.attributes) ? [...p.attributes] : [];
+                return { idx, relX, relY, relZ, dist, distPrev, distDelta, distInWidths: dist / supermassiveWidth, velocityMag, preferredCompat, desiredDist, desiredWidths, inViewableZone, attributes: attrs };
+            });
+            const outsideCount = positionsRel.filter((r) => !r.inViewableZone).length;
+            const maxDist = Math.max(...positionsRel.map((r) => r.dist));
+            const avgAbsDistDelta = positionsRel.reduce((s, r) => s + Math.abs(r.distDelta), 0) / positionsRel.length;
+            let minDistDissimilar = Infinity;
+            for (let i = 0; i < nonCentralBlackholes.length; i++) {
+                for (let j = i + 1; j < nonCentralBlackholes.length; j++) {
+                    const sim = nonCentralBlackholes[i].calculateAttributeCompatibility(nonCentralBlackholes[j]);
+                    if (sim < 0.6) {
+                        const d = nonCentralBlackholes[i].position.distanceTo(nonCentralBlackholes[j].position);
+                        if (d < minDistDissimilar)
+                            minDistDissimilar = d;
+                    }
+                }
+            }
+            if (minDistDissimilar === Infinity)
+                minDistDissimilar = 0;
+            const pairwiseMult = this.options.blackhole.pairwiseRepulsionMultiplier ?? 1;
+            fetch('http://127.0.0.1:7243/ingest/eb74700b-8e83-4a1d-a30e-6c89d056a897', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ hypothesisId: 'pos', location: 'Cluster.ts:update', message: 'position over time: dist, distDelta, velocity, desiredDist, compat', data: { frame: getDebugFrameCount(), viewableRadius, supermassiveWidth, minDistanceWidths: minW, maxDistanceWidths: maxW, pairwiseRepulsionMultiplier: pairwiseMult, minDistBetweenDissimilar: minDistDissimilar, minDistDissimilarInWidths: minDistDissimilar / supermassiveWidth, centralPreferences: centralPrefs, positionsRel, outsideCount, maxDist, avgAbsDistDelta, centralPos: { x: central.position.x, y: central.position.y, z: central.position.z } }, timestamp: Date.now() }) }).catch(() => { });
+        }
+        if (nonCentralBlackholes.length >= 9 && getDebugFrameCount() % 60 === 0 && isDebugIngestEnabled()) {
+            const positions = nonCentralBlackholes.map((p) => ({ x: p.position.x, z: p.position.z }));
+            const groupA = [0, 1, 2], groupB = [3, 4, 5], groupC = [6, 7, 8, 9];
+            const avgDist = (indices) => {
+                let sum = 0, n = 0;
+                for (let i = 0; i < indices.length; i++)
+                    for (let j = i + 1; j < indices.length; j++) {
+                        sum += nonCentralBlackholes[indices[i]].position.distanceTo(nonCentralBlackholes[indices[j]].position);
+                        n++;
+                    }
+                return n ? sum / n : 0;
+            };
+            const avgBetween = (g1, g2) => {
+                let sum = 0, n = 0;
+                for (const i of g1)
+                    for (const j of g2) {
+                        sum += nonCentralBlackholes[i].position.distanceTo(nonCentralBlackholes[j].position);
+                        n++;
+                    }
+                return n ? sum / n : 0;
+            };
+            const withinA = avgDist(groupA), withinB = avgDist(groupB), withinC = avgDist(groupC);
+            const betweenAB = avgBetween(groupA, groupB), betweenAC = avgBetween(groupA, groupC), betweenBC = avgBetween(groupB, groupC);
+            fetch('http://127.0.0.1:7243/ingest/eb74700b-8e83-4a1d-a30e-6c89d056a897', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ hypothesisId: 'D', location: 'Cluster.ts:update', message: 'positions and group distances', data: { frame: getDebugFrameCount(), positions, withinA, withinB, withinC, betweenAB, betweenAC, betweenBC, physicsCalls: getPhysicsCallsThisFrame() }, timestamp: Date.now() }) }).catch(() => { });
+        }
+        if (getPhysicsCallsThisFrame() > 0 && getDebugFrameCount() % 60 === 0 && isDebugIngestEnabled()) {
+            fetch('http://127.0.0.1:7243/ingest/eb74700b-8e83-4a1d-a30e-6c89d056a897', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ hypothesisId: 'A', location: 'Cluster.ts:update', message: 'physics calls per frame', data: { physicsCallsThisFrame: getPhysicsCallsThisFrame(), blackholeCount: this.blackholes.length }, timestamp: Date.now() }) }).catch(() => { });
+        }
+        // #endregion
         const BOUND = 8;
         this.position.x = THREE.MathUtils.clamp(this.position.x, -BOUND, BOUND);
         this.position.y = THREE.MathUtils.clamp(this.position.y, -BOUND, BOUND);
@@ -601,11 +1091,11 @@ class BlackHoleParticleField {
     FIELD_RADIUS_FACTOR = 0.9; // relative scale
     NEON_PURPLE = new THREE.Color(0xc300ff);
     PINK_RED = new THREE.Color(0xff3366);
-    palette = 'planet';
+    palette = 'blackhole';
     // Use even surface distribution (no view alignment by default)
     useSurface = true;
     seedCounter = 0; // Fibonacci seed index
-    speedScale = 1; // instance speed scaler (planets slower)
+    speedScale = 1; // instance speed scaler (blackholes slower)
     // Animation params (slower, smoother orbits)
     MIN_SPEED = 0.4; // radians/sec
     MAX_SPEED = 1.2;
@@ -644,6 +1134,12 @@ class BlackHoleParticleField {
     flowSpeedScale = 1.0;
     prevTargetAnchor = new THREE.Vector3(); // for anchor-delta velocity
     worldUp = new THREE.Vector3(0, 1, 0);
+    // Particle size and depth (tunable via options and setters)
+    particleSizeMax = 1.8;
+    particleSizeScale = 1.0;
+    surfaceRadiusMin = 1.0;
+    surfaceRadiusMax = 1.01;
+    rimMinShellFactor = 0.7;
     constructor(scene, opts) {
         this.scene = scene;
         if (opts?.coreRadius && Number.isFinite(opts.coreRadius)) {
@@ -661,9 +1157,24 @@ class BlackHoleParticleField {
         if (opts?.speedScale && Number.isFinite(opts.speedScale)) {
             this.speedScale = Math.max(0.05, opts.speedScale);
         }
+        if (opts?.particleSizeMax != null && Number.isFinite(opts.particleSizeMax)) {
+            this.particleSizeMax = Math.max(0.5, opts.particleSizeMax);
+        }
+        if (opts?.particleSizeScale != null && Number.isFinite(opts.particleSizeScale)) {
+            this.particleSizeScale = Math.max(0.2, Math.min(3, opts.particleSizeScale));
+        }
+        if (opts?.surfaceRadiusMin != null && Number.isFinite(opts.surfaceRadiusMin)) {
+            this.surfaceRadiusMin = opts.surfaceRadiusMin;
+        }
+        if (opts?.surfaceRadiusMax != null && Number.isFinite(opts.surfaceRadiusMax)) {
+            this.surfaceRadiusMax = opts.surfaceRadiusMax;
+        }
+        if (opts?.rimMinShellFactor != null && Number.isFinite(opts.rimMinShellFactor)) {
+            this.rimMinShellFactor = THREE.MathUtils.clamp(opts.rimMinShellFactor, 0.5, 1.05);
+        }
         // Enable debug via query param ?debugBands=1
         try {
-            const search = window?.location?.search ?? '';
+            const search = getWindowLocationSearch();
             this.debugBands = /(?:^|[?&])debugBands=1(?:&|$)/.test(search);
         }
         catch { }
@@ -904,7 +1415,7 @@ class BlackHoleParticleField {
         this.setDebugBands(!this.debugBands);
         return this.debugBands;
     }
-    // Switch palette at runtime (e.g., when a node becomes or ceases to be the sun)
+    // Switch palette at runtime (e.g., when a node becomes or ceases to be the supermassive black hole)
     setPalette(newPalette) {
         if (this.palette === newPalette)
             return;
@@ -913,7 +1424,7 @@ class BlackHoleParticleField {
             return;
         const geom = this.particleSystem.geometry;
         const colorsAttr = geom.getAttribute('color');
-        const base = this.palette === 'sun' ? this.NEON_PURPLE : this.PINK_RED;
+        const base = this.palette === 'supermassiveBlackhole' ? this.NEON_PURPLE : this.PINK_RED;
         for (let i = 0; i < this.particles.length; i++) {
             const jitter = THREE.MathUtils.lerp(0.9, 1.1, Math.random());
             const c = base.clone().multiplyScalar(jitter);
@@ -929,6 +1440,30 @@ class BlackHoleParticleField {
         }
         colorsAttr.needsUpdate = true;
     }
+    /** Set global particle size scale (affects shader uniform). */
+    setParticleSizeScale(value) {
+        const v = Math.max(0.2, Math.min(3, value));
+        if (this.particleSizeScale === v)
+            return;
+        this.particleSizeScale = v;
+        if (this.particleSystem) {
+            const mat = this.particleSystem.material;
+            const u = mat.uniforms?.['uSizeScale'];
+            if (u)
+                u.value = v;
+        }
+    }
+    /** Set how far rim particles can go inside the node (0.7 = 30% inside, 1 = on surface). */
+    setRimMinShellFactor(value) {
+        this.rimMinShellFactor = THREE.MathUtils.clamp(value, 0.5, 1.05);
+    }
+    /** Set surface shell radius range (factors of coreRadius). */
+    setSurfaceRadiusMin(value) {
+        this.surfaceRadiusMin = value;
+    }
+    setSurfaceRadiusMax(value) {
+        this.surfaceRadiusMax = value;
+    }
     dispose() {
         if (this.particleSystem) {
             this.scene.remove(this.particleSystem);
@@ -954,6 +1489,14 @@ class BlackHoleParticleField {
             this.bandCounts[p.type]++;
         }
     }
+    /** Base size: mostly 0.8–1.8, ~12% chance of small 0.4–0.7, clamped by particleSizeMax. */
+    nextParticleSize() {
+        const smallChance = 0.12;
+        const base = Math.random() < smallChance
+            ? THREE.MathUtils.lerp(0.4, 0.7, Math.random())
+            : 0.8 + Math.random() * 1.0;
+        return Math.min(base, this.particleSizeMax);
+    }
     createNewParticle() {
         // New mode: evenly spread particles around the surface using per-particle orbit planes
         if (this.useSurface) {
@@ -985,7 +1528,7 @@ class BlackHoleParticleField {
             const radialJitterAmp = this.coreRadius * 0.002; // very subtle breathing
             const radialJitterFreq = 0.2 + Math.random() * 0.3;
             // Color from palette with small jitter
-            const base = this.palette === 'sun' ? this.NEON_PURPLE : this.PINK_RED;
+            const base = this.palette === 'supermassiveBlackhole' ? this.NEON_PURPLE : this.PINK_RED;
             const cjit = THREE.MathUtils.lerp(0.9, 1.1, Math.random());
             const color = base.clone().multiplyScalar(cjit);
             color.r = Math.min(1, Math.max(0, color.r));
@@ -1002,7 +1545,7 @@ class BlackHoleParticleField {
                 angularSpeed,
                 radialJitterAmp,
                 radialJitterFreq,
-                size: 0.8 + Math.random() * 1.4,
+                size: this.nextParticleSize(),
                 color,
                 opacity: 0.85,
                 lifetime: this.MIN_LIFETIME +
@@ -1143,8 +1686,8 @@ class BlackHoleParticleField {
         const radialJitterAmp = this.coreRadius *
             (type === 'topCap' || type === 'bottomCap' ? 0.012 : this.SHIMMER_FRAC);
         const radialJitterFreq = 0.3 + Math.random() * 0.5; // Hz (gentle)
-        // Color selection based on palette: sun = purple family, planet = pink-red
-        const base = this.palette === 'sun' ? this.NEON_PURPLE : this.PINK_RED;
+        // Color selection based on palette: supermassiveBlackhole = purple family, blackhole = pink-red
+        const base = this.palette === 'supermassiveBlackhole' ? this.NEON_PURPLE : this.PINK_RED;
         // subtle per-particle variation within same family (lighten/darken slightly)
         const jitter = THREE.MathUtils.lerp(0.9, 1.1, Math.random());
         const color = base.clone().multiplyScalar(jitter);
@@ -1176,7 +1719,7 @@ class BlackHoleParticleField {
             angularSpeed,
             radialJitterAmp,
             radialJitterFreq,
-            size: 0.8 + Math.random() * 1.4, // smaller discs (0.8..2.2)
+            size: this.nextParticleSize(),
             color,
             opacity: 0.85,
             lifetime: this.MIN_LIFETIME +
@@ -1246,62 +1789,62 @@ class BlackHoleParticleField {
         geometry.getAttribute('position').needsUpdate = true;
         geometry.getAttribute('color').needsUpdate = true;
         // Custom bubble shader for perfect circular bubbles with dramatic lighting
-        const vertexShader = `
-      attribute float size;
-      attribute float opacity;
-      varying vec3 vColor;
-      varying float vOpacity;
-      varying float vSize;
-
-      void main() {
-        vColor = color;
-        vOpacity = opacity;
-        vSize = size;
-
-        vec4 mvPosition = modelViewMatrix * vec4(position, 1.0);
-
-        // Smaller bokeh-style circles
-        gl_PointSize = size * 4.0;
-
-        gl_Position = projectionMatrix * mvPosition;
-      }
+        const vertexShader = `
+      uniform float uSizeScale;
+      attribute float size;
+      attribute float opacity;
+      varying vec3 vColor;
+      varying float vOpacity;
+      varying float vSize;
+
+      void main() {
+        vColor = color;
+        vOpacity = opacity;
+        vSize = size;
+
+        vec4 mvPosition = modelViewMatrix * vec4(position, 1.0);
+
+        gl_PointSize = size * 4.0 * uSizeScale;
+
+        gl_Position = projectionMatrix * mvPosition;
+      }
     `;
-        const fragmentShader = `
-      varying vec3 vColor;
-      varying float vOpacity;
-      varying float vSize;
-
-      void main() {
-        // Create circular bubble coordinate system
-        vec2 center = gl_PointCoord - 0.5;
-        float distance = length(center);
-
-        // Perfect circular mask - discard pixels outside circle
-        if (distance > 0.5) discard;
-
-        // Dramatic bubble lighting effects
-        float rimDistance = distance * 2.0; // 0.0 at center, 1.0 at edge
-
-        // Bright center fading to edge (soap bubble effect)
-        float centerGlow = 1.0 - smoothstep(0.0, 0.35, rimDistance);
-
-        // Rim lighting - bright edges
-        float rimGlow = smoothstep(0.65, 1.0, rimDistance) * 2.0;
-
-        // Glass-like inner reflection
-        float bubble = smoothstep(0.85, 0.25, rimDistance);
-
-        // Combine lighting effects
-        float totalGlow = centerGlow * 0.7 + rimGlow * 1.6 + bubble * 0.7;
-
-        // Final bubble color with dramatic lighting
-        vec3 finalColor = vColor * totalGlow * 1.9;
-
-        // Smooth alpha falloff for glass-like appearance
-        float alpha = (1.0 - smoothstep(0.35, 0.52, distance)) * vOpacity;
-
-        gl_FragColor = vec4(finalColor, alpha);
-      }
+        const fragmentShader = `
+      varying vec3 vColor;
+      varying float vOpacity;
+      varying float vSize;
+
+      void main() {
+        // Create circular bubble coordinate system
+        vec2 center = gl_PointCoord - 0.5;
+        float distance = length(center);
+
+        // Perfect circular mask - discard pixels outside circle
+        if (distance > 0.5) discard;
+
+        // Dramatic bubble lighting effects
+        float rimDistance = distance * 2.0; // 0.0 at center, 1.0 at edge
+
+        // Bright center fading to edge (soap bubble effect)
+        float centerGlow = 1.0 - smoothstep(0.0, 0.35, rimDistance);
+
+        // Rim lighting - bright edges
+        float rimGlow = smoothstep(0.65, 1.0, rimDistance) * 2.0;
+
+        // Glass-like inner reflection
+        float bubble = smoothstep(0.85, 0.25, rimDistance);
+
+        // Combine lighting effects
+        float totalGlow = centerGlow * 0.7 + rimGlow * 1.6 + bubble * 0.7;
+
+        // Final bubble color with dramatic lighting
+        vec3 finalColor = vColor * totalGlow * 1.9;
+
+        // Smooth alpha falloff for glass-like appearance
+        float alpha = (1.0 - smoothstep(0.35, 0.52, distance)) * vOpacity;
+
+        gl_FragColor = vec4(finalColor, alpha);
+      }
     `;
         const material = new THREE.ShaderMaterial({
             vertexShader,
@@ -1310,6 +1853,9 @@ class BlackHoleParticleField {
             blending: THREE.AdditiveBlending,
             depthWrite: false,
             vertexColors: true,
+            uniforms: {
+                uSizeScale: { value: this.particleSizeScale },
+            },
         });
         this.particleSystem = new THREE.Points(geometry, material);
         this.particleSystem.frustumCulled = false;
@@ -1337,9 +1883,9 @@ class BlackHoleParticleField {
                     Math.sin(age * 2 * Math.PI * (p.wiggleFreqUp || 0.3) + (p.wigglePhase || 0));
                 out.add(p.axis.clone().multiplyScalar(axWiggle));
             }
-            // Hard clamp to tight shell near exact surface
-            const minR = this.coreRadius * 1.0;
-            const maxR = this.coreRadius * 1.01;
+            // Hard clamp to tight shell (tunable via surfaceRadiusMin/Max)
+            const minR = this.coreRadius * this.surfaceRadiusMin;
+            const maxR = this.coreRadius * this.surfaceRadiusMax;
             const len = out.length();
             if (len < minR)
                 out.setLength(minR);
@@ -1380,9 +1926,9 @@ class BlackHoleParticleField {
         // Layer subtle extras
         out.add(up.clone().multiplyScalar(p.upBias + upWiggle + arcUp));
         out.add(forward.clone().multiplyScalar(p.depthBias + depthWiggle + arcDepth));
-        // Different penetration limits for different particle types
+        // Different penetration limits for different particle types (rim tunable via rimMinShellFactor)
         const minShell = p.type === 'topCurve' || p.type === 'bottomCurve'
-            ? this.coreRadius * 0.7 // Rim particles: 30% inside surface
+            ? this.coreRadius * this.rimMinShellFactor
             : this.coreRadius * 1.0; // Cap particles: stay at surface level
         const len = out.length();
         if (len < minShell) {
@@ -1431,6 +1977,13 @@ class TraitVisualComponent {
     preferenceWeights = [];
     attributeCount;
     preferenceCount;
+    simulationOptions;
+    /** When true, right-click on a node can show the context menu (when implemented). Default false. */
+    showContextMenu = false;
+    /** Default zoom level: multiplier on initial camera distance (1 = normal, > 1 = zoom out more). Default 1.25. */
+    defaultZoomLevel = 1.25;
+    /** Emits when the user selects a blackhole (e.g. via right-click). Host app can use this for context menu or sidenav. */
+    blackholeSelected = new EventEmitter();
     // Three.js scene properties
     scene;
     camera;
@@ -1444,7 +1997,7 @@ class TraitVisualComponent {
     dragPlane = new THREE.Plane();
     dragOffset = new THREE.Vector3();
     newNodeCounter = 1;
-    isCameraLocked = false;
+    isCameraLocked = true;
     // Private properties
     nodeAuras = new Map();
     starFieldNear;
@@ -1464,6 +2017,9 @@ class TraitVisualComponent {
     pointerYawSpeed = THREE.MathUtils.degToRad(0.15);
     pointerPitchDamping = 4;
     pointerYawDamping = 4;
+    /** Reused buffer for dust-field attractors (avoids per-frame allocations). */
+    _attractorsBuffer = [];
+    _centerFallback = new THREE.Vector3(0, 0, 0);
     constructor(renderer2, ngZone) {
         this.renderer2 = renderer2;
         this.ngZone = ngZone;
@@ -1482,8 +2038,9 @@ class TraitVisualComponent {
         }
     }
     ngOnChanges(changes) {
-        if (changes['nodeData'] && !changes['nodeData'].firstChange && this.scene) {
-            // Reload nodes when nodeData changes
+        const nodeDataChange = changes['nodeData'] && !changes['nodeData'].firstChange && this.scene;
+        const simulationOptionsChange = changes['simulationOptions'] && !changes['simulationOptions'].firstChange && this.scene;
+        if (nodeDataChange || simulationOptionsChange) {
             if (this.cluster) {
                 this.scene.remove(this.cluster);
                 this.nodeAuras.forEach((a) => a.dispose());
@@ -1497,6 +2054,22 @@ class TraitVisualComponent {
         if ((changes['attributeWeights'] || changes['preferenceWeights']) && !changes['attributeWeights']?.firstChange && !changes['preferenceWeights']?.firstChange) {
             this.syncNodeWeightGlobals();
         }
+        if (changes['defaultZoomLevel'] && !changes['defaultZoomLevel'].firstChange && this.camera && this.controls) {
+            this.applyDefaultZoomLevel();
+        }
+    }
+    /** Apply defaultZoomLevel to camera: same direction from target, scaled distance. */
+    applyDefaultZoomLevel() {
+        const L = Math.max(0.5, Math.min(2.5, this.defaultZoomLevel));
+        const target = this.controls.target;
+        const offset = this.camera.position.clone().sub(target);
+        const currentDist = offset.length();
+        if (currentDist < 1e-6)
+            return;
+        const baseDist = Math.hypot(500, 10);
+        const newDist = baseDist * L;
+        offset.normalize().multiplyScalar(newDist);
+        this.camera.position.copy(target).add(offset);
     }
     ngAfterViewInit() {
         this.animate();
@@ -1518,29 +2091,33 @@ class TraitVisualComponent {
         this.nodeAuras.clear();
         this.dustField?.dispose();
     }
-    currentCentral() {
+    currentSupermassiveBlackhole() {
         if (!this.cluster)
             return null;
-        return this.cluster.nodes.find((node) => node.isSun) || null;
+        return this.cluster.blackholes.find((bh) => bh.isSupermassiveBlackhole) || null;
     }
-    nonSuns() {
+    nonSupermassiveBlackholes() {
         if (!this.cluster)
             return [];
-        return this.cluster.nodes.filter((node) => !node.isSun);
+        return this.cluster.blackholes.filter((bh) => !bh.isSupermassiveBlackhole);
     }
     syncNodeWeightGlobals() {
         if (this.attributeWeights.length > 0) {
-            Node.attributeWeights = this.attributeWeights.slice();
+            Blackhole.attributeWeights = this.attributeWeights.slice();
         }
         if (this.preferenceWeights.length > 0) {
-            Node.preferenceWeights = this.preferenceWeights.slice();
+            Blackhole.preferenceWeights = this.preferenceWeights.slice();
         }
     }
     initScene() {
         this.scene = new THREE.Scene();
-        this.camera = new THREE.PerspectiveCamera(55, window.innerWidth / window.innerHeight, 0.1, 1000);
+        const container = this.canvasRef.nativeElement.parentElement;
+        const width = container?.clientWidth || window.innerWidth;
+        const height = container?.clientHeight || window.innerHeight;
+        this.camera = new THREE.PerspectiveCamera(55, width / height, 0.1, 1000);
         this.camera.up.set(0, 1, 0);
-        this.camera.position.set(0, 0, 60);
+        const L = Math.max(0.5, Math.min(2.5, this.defaultZoomLevel));
+        this.camera.position.set(0, 500 * L, 10 * L);
         const initialTilt = THREE.MathUtils.degToRad(-45);
         this.camera.position.applyAxisAngle(new THREE.Vector3(1, 0, 0), -initialTilt);
         this.camera.lookAt(0, 0, 0);
@@ -1550,10 +2127,11 @@ class TraitVisualComponent {
             alpha: true,
         });
         this.renderer.setClearColor(0x000000, 0);
-        this.renderer.setSize(window.innerWidth, window.innerHeight);
+        this.renderer.setSize(width, height);
         this.controls = new OrbitControls(this.camera, this.renderer.domElement);
         this.controls.target.set(0, 0, 0);
         this.controls.enableDamping = true;
+        this.controls.enabled = false;
         this.controls.enableRotate = true;
         this.controls.screenSpacePanning = true;
         this.controls.enablePan = true;
@@ -1583,17 +2161,17 @@ class TraitVisualComponent {
     loadNodes() {
         if (this.nodeData.length === 0)
             return;
-        this.cluster = new Cluster(this.nodeData);
+        this.cluster = new Cluster(this.nodeData, this.simulationOptions);
         this.scene.add(this.cluster);
-        const initialCentral = this.cluster.nodes.find((node) => node.isSun) || this.cluster.nodes[0];
-        initialCentral.setSun(true, 5);
+        const initialCentral = this.cluster.blackholes.find((bh) => bh.isSupermassiveBlackhole) || this.cluster.blackholes[0];
+        initialCentral.setSupermassiveBlackhole(true, 5);
         initialCentral.mesh.scale.set(3, 3, 3);
         this.ensureNodeAuras();
-        const sun = this.currentCentral();
-        if (sun) {
-            const geom = sun.mesh.geometry;
+        const supermassiveBlackhole = this.currentSupermassiveBlackhole();
+        if (supermassiveBlackhole) {
+            const geom = supermassiveBlackhole.mesh.geometry;
             const bs = geom.boundingSphere ?? new THREE.Sphere(new THREE.Vector3(), 0.05);
-            const coreRadius = (bs.radius || 0.05) * sun.mesh.scale.x;
+            const coreRadius = (bs.radius || 0.05) * supermassiveBlackhole.mesh.scale.x;
             let dustOuter = 18.0;
             let dustThickness = 0.0;
             let dustMidCount = 160000;
@@ -1604,7 +2182,7 @@ class TraitVisualComponent {
             let dustMode = 'disk';
             let searchParams;
             try {
-                const rawSearch = window?.location?.search ?? '';
+                const rawSearch = getWindowLocationSearch();
                 searchParams = new URLSearchParams(rawSearch);
             }
             catch {
@@ -1633,9 +2211,12 @@ class TraitVisualComponent {
         }
     }
     onWindowResize() {
-        this.camera.aspect = window.innerWidth / window.innerHeight;
+        const container = this.canvasRef.nativeElement.parentElement;
+        const width = container?.clientWidth || window.innerWidth;
+        const height = container?.clientHeight || window.innerHeight;
+        this.camera.aspect = width / height;
         this.camera.updateProjectionMatrix();
-        this.renderer.setSize(window.innerWidth, window.innerHeight);
+        this.renderer.setSize(width, height);
         this.dustField?.setViewportHeight(window.innerHeight);
     }
     onRightClick(event) {
@@ -1645,6 +2226,7 @@ class TraitVisualComponent {
         const intersects = this.raycaster.intersectObjects(this.cluster?.children || [], true);
         if (intersects.length > 0) {
             this.selectedNode = intersects[0].object.parent;
+            this.blackholeSelected.emit(this.selectedNode);
         }
     }
     onMouseMove(event) {
@@ -1773,14 +2355,14 @@ class TraitVisualComponent {
                 if (this.cluster)
                     this.cluster.update(undefined, this.scene, this.camera);
                 if (this.cluster) {
-                    for (const node of this.cluster.nodes) {
-                        const aura = this.nodeAuras.get(node);
+                    for (const bh of this.cluster.blackholes) {
+                        const aura = this.nodeAuras.get(bh);
                         if (aura) {
-                            const geom = node.mesh.geometry;
+                            const geom = bh.mesh.geometry;
                             const bs = geom.boundingSphere ??
                                 new THREE.Sphere(new THREE.Vector3(), 0.05);
-                            const newCoreRadius = (bs.radius || 0.05) * node.mesh.scale.x;
-                            const ud = node.userData;
+                            const newCoreRadius = (bs.radius || 0.05) * bh.mesh.scale.x;
+                            const ud = bh.userData;
                             const prevCoreRadius = ud._auraCoreRadius;
                             const needsResize = !prevCoreRadius ||
                                 Math.abs(newCoreRadius - prevCoreRadius) / prevCoreRadius >
@@ -1794,22 +2376,32 @@ class TraitVisualComponent {
                                 }
                                 ud._auraCoreRadius = newCoreRadius;
                             }
-                            aura.update(node.position, node.velocity, deltaTime, this.camera);
+                            aura.update(bh.position, bh.velocity, deltaTime, this.camera);
                         }
                     }
                 }
-                const center = this.currentCentral()?.position ?? new THREE.Vector3();
+                const center = this.currentSupermassiveBlackhole()?.position ?? this._centerFallback;
                 if (this.dustField && this.cluster) {
-                    const atts = this.cluster.nodes
-                        .filter((n) => !n.isSun)
-                        .map((n) => {
+                    const blackholes = this.cluster.blackholes;
+                    const buf = this._attractorsBuffer;
+                    const maxAttractors = 24;
+                    while (buf.length < maxAttractors) {
+                        buf.push({ position: new THREE.Vector3(), radius: 0 });
+                    }
+                    let k = 0;
+                    for (let i = 0; i < blackholes.length && k < maxAttractors; i++) {
+                        const n = blackholes[i];
+                        if (n.isSupermassiveBlackhole)
+                            continue;
                         const geom = n.mesh.geometry;
                         const bs = geom.boundingSphere ??
                             new THREE.Sphere(new THREE.Vector3(), 0.05);
                         const radius = (bs.radius || 0.05) * n.mesh.scale.x;
-                        return { position: n.position.clone(), radius };
-                    });
-                    this.dustField.setAttractorsWorld(atts);
+                        buf[k].position.copy(n.position);
+                        buf[k].radius = radius;
+                        k++;
+                    }
+                    this.dustField.setAttractorsWorld(buf, k);
                 }
                 this.dustField?.update(deltaTime, center);
                 if (this.starFieldNear && this.starFieldFar) {
@@ -1824,20 +2416,20 @@ class TraitVisualComponent {
     ensureNodeAuras() {
         if (!this.cluster)
             return;
-        for (const node of this.cluster.nodes) {
-            if (!this.nodeAuras.has(node)) {
-                const geom = node.mesh.geometry;
+        for (const bh of this.cluster.blackholes) {
+            if (!this.nodeAuras.has(bh)) {
+                const geom = bh.mesh.geometry;
                 const bs = geom.boundingSphere ?? new THREE.Sphere(new THREE.Vector3(), 0.05);
-                const coreRadius = (bs.radius || 0.05) * node.mesh.scale.x;
-                const particleCount = node.isSun ? 900 : 200; // Increased from 600 to 900 for supermassive black hole effect
+                const coreRadius = (bs.radius || 0.05) * bh.mesh.scale.x;
+                const particleCount = bh.isSupermassiveBlackhole ? 900 : 200;
                 const aura = new BlackHoleParticleField(this.scene, {
                     coreRadius,
                     particleCount,
-                    palette: node.isSun ? 'sun' : 'planet',
+                    palette: bh.isSupermassiveBlackhole ? 'supermassiveBlackhole' : 'blackhole',
                     distribution: 'surface',
                     speedScale: 0.3,
                 });
-                this.nodeAuras.set(node, aura);
+                this.nodeAuras.set(bh, aura);
                 const occGeom = new THREE.SphereGeometry(coreRadius * 0.99, 24, 24);
                 const occMat = new THREE.MeshBasicMaterial({
                     color: 0x000000,
@@ -1846,9 +2438,10 @@ class TraitVisualComponent {
                 occMat.colorWrite = false;
                 const occluder = new THREE.Mesh(occGeom, occMat);
                 occluder.renderOrder = -0.5;
-                node.add(occluder);
-                node.userData._auraCoreRadius = coreRadius;
-                node.userData._occluder = occluder;
+                bh.add(occluder);
+                const ud = bh.userData;
+                ud._auraCoreRadius = coreRadius;
+                ud._occluder = occluder;
             }
         }
     }
@@ -1912,12 +2505,12 @@ class TraitVisualComponent {
         this.starTexture = texture;
         return texture;
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.11", ngImport: i0, type: TraitVisualComponent, deps: [{ token: i0.Renderer2 }, { token: i0.NgZone }], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "20.3.11", type: TraitVisualComponent, isStandalone: true, selector: "tv-trait-visual", inputs: { nodeData: "nodeData", attributeWeights: "attributeWeights", preferenceWeights: "preferenceWeights", attributeCount: "attributeCount", preferenceCount: "preferenceCount" }, viewQueries: [{ propertyName: "canvasRef", first: true, predicate: ["rendererCanvas"], descendants: true, static: true }], usesOnChanges: true, ngImport: i0, template: "<div class=\"app-wrapper\">\n  <canvas #rendererCanvas></canvas>\n</div>\n\n", styles: [".app-wrapper{display:flex;width:100vw;position:relative;height:100vh;background:#000}canvas{display:flex;width:100vw;height:100vh;overflow:hidden;position:relative;z-index:1;background:transparent!important}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }] });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.17", ngImport: i0, type: TraitVisualComponent, deps: [{ token: i0.Renderer2 }, { token: i0.NgZone }], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "19.2.17", type: TraitVisualComponent, isStandalone: true, selector: "tv-trait-visual", inputs: { nodeData: "nodeData", attributeWeights: "attributeWeights", preferenceWeights: "preferenceWeights", attributeCount: "attributeCount", preferenceCount: "preferenceCount", simulationOptions: "simulationOptions", showContextMenu: "showContextMenu", defaultZoomLevel: "defaultZoomLevel" }, outputs: { blackholeSelected: "blackholeSelected" }, viewQueries: [{ propertyName: "canvasRef", first: true, predicate: ["rendererCanvas"], descendants: true, static: true }], usesOnChanges: true, ngImport: i0, template: "<div class=\"app-wrapper\">\r\n  <canvas #rendererCanvas></canvas>\r\n</div>\r\n\r\n", styles: [":host .app-wrapper{display:flex;width:100vw;position:relative;height:100vh;background:transparent}:host canvas{display:flex;width:100vw;height:100vh;overflow:hidden;position:relative;z-index:1;background:transparent}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "ngmodule", type: MatIconModule }, { kind: "ngmodule", type: MatButtonModule }, { kind: "ngmodule", type: MatTooltipModule }] });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.11", ngImport: i0, type: TraitVisualComponent, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.17", ngImport: i0, type: TraitVisualComponent, decorators: [{
             type: Component,
-            args: [{ selector: 'tv-trait-visual', standalone: true, imports: [CommonModule], template: "<div class=\"app-wrapper\">\n  <canvas #rendererCanvas></canvas>\n</div>\n\n", styles: [".app-wrapper{display:flex;width:100vw;position:relative;height:100vh;background:#000}canvas{display:flex;width:100vw;height:100vh;overflow:hidden;position:relative;z-index:1;background:transparent!important}\n"] }]
+            args: [{ selector: 'tv-trait-visual', standalone: true, imports: [CommonModule, MatIconModule, MatButtonModule, MatTooltipModule], template: "<div class=\"app-wrapper\">\r\n  <canvas #rendererCanvas></canvas>\r\n</div>\r\n\r\n", styles: [":host .app-wrapper{display:flex;width:100vw;position:relative;height:100vh;background:transparent}:host canvas{display:flex;width:100vw;height:100vh;overflow:hidden;position:relative;z-index:1;background:transparent}\n"] }]
         }], ctorParameters: () => [{ type: i0.Renderer2 }, { type: i0.NgZone }], propDecorators: { canvasRef: [{
                 type: ViewChild,
                 args: ['rendererCanvas', { static: true }]
@@ -1931,84 +2524,2592 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.11", ngImpo
                 type: Input
             }], preferenceCount: [{
                 type: Input
+            }], simulationOptions: [{
+                type: Input
+            }], showContextMenu: [{
+                type: Input
+            }], defaultZoomLevel: [{
+                type: Input
+            }], blackholeSelected: [{
+                type: Output
             }] } });
 
-// Dynamically resolve the PCA constructor for different build types
-const PCAClass = PCA.default || PCA.PCA || PCA;
-let dynamicCounts = {
-    attributes: 8,
-    preferences: 8
-};
-function updateCounts(attrCount, prefCount) {
-    dynamicCounts.attributes = attrCount;
-    dynamicCounts.preferences = prefCount;
+/** Ordered keys for attributes/preferences (attr1, attr2, ...). */
+function orderedKeys(record) {
+    const keys = Object.keys(record || {});
+    return keys.sort((a, b) => {
+        const numA = parseInt(a.replace(/\D/g, ''), 10) || 0;
+        const numB = parseInt(b.replace(/\D/g, ''), 10) || 0;
+        return numA - numB;
+    });
 }
-/**
- * Performs PCA on a list of attribute arrays to map them into 3D space.
- * Returns:
- *  - positions: normalized [x, y, z] tuples
- *  - weights: per-attribute magnitude across PCA components
- */
-function computePCA3D(attributesList) {
-    const pca = new PCAClass(attributesList, { center: true, scale: true });
-    const reduced = pca.predict(attributesList, { nComponents: 3 }).to2DArray();
-    // --- Compute per-attribute weights ---
-    const loadings = pca.getLoadings().to2DArray();
-    const weights = loadings.map((arr) => Math.sqrt(arr[0] ** 2 + arr[1] ** 2 + arr[2] ** 2));
-    const maxAbs = Math.max(...reduced.flatMap((arr) => arr.map((v) => Math.abs(v))));
-    const positions = reduced.map((arr) => [
-        arr[0] / maxAbs,
-        arr[1] / maxAbs,
-        arr[2] / maxAbs
-    ]);
-    return { positions, weights };
+function toValuesArray(record) {
+    return orderedKeys(record).map((k) => record[k] ?? 0);
 }
-function generateAttributes(count, base = 0) {
-    const attrs = {};
-    for (let i = 0; i < count; i++)
-        attrs[`attr${i + 1}`] = (base + i * 20) % 101;
-    return attrs;
+class ConfigSidenavComponent {
+    config;
+    open = true;
+    configChange = new EventEmitter();
+    /** Active tab: 'docs' shows documentation, 'configs' shows configuration UI. */
+    activeTab = 'configs';
+    setActiveTab(tab) {
+        this.activeTab = tab;
+    }
+    get centralNode() {
+        return this.config?.nodeData?.find((n) => n.isSupermassiveBlackhole) ?? null;
+    }
+    get nonSupermassiveBlackholeNodes() {
+        return this.config?.nodeData?.filter((n) => !n.isSupermassiveBlackhole) ?? [];
+    }
+    traitCount() {
+        const central = this.centralNode;
+        if (central?.preferences)
+            return orderedKeys(central.preferences).length;
+        const first = this.nonSupermassiveBlackholeNodes[0];
+        if (first?.attributes)
+            return orderedKeys(first.attributes).length;
+        return 5;
+    }
+    centralPrefsArray() {
+        const central = this.centralNode;
+        return central ? toValuesArray(central.preferences) : [];
+    }
+    nodeAttrsArray(node) {
+        return toValuesArray(node.attributes ?? {});
+    }
+    onPresetChange(value) {
+        this.configChange.emit({ type: 'preset', selectedPreset: value });
+    }
+    onWeightChange(index, value) {
+        const next = [...(this.config.attributeWeights ?? [])];
+        while (next.length <= index)
+            next.push(1);
+        next[index] = value;
+        this.configChange.emit({ type: 'weights', attributeWeights: next });
+    }
+    onPrefWeightChange(index, value) {
+        const next = [...(this.config.preferenceWeights ?? [])];
+        while (next.length <= index)
+            next.push(1);
+        next[index] = value;
+        this.configChange.emit({ type: 'weights', preferenceWeights: next });
+    }
+    onSimulationSpeedChange(value) {
+        this.configChange.emit({
+            type: 'simulation',
+            simulation: { ...this.config.simulation, simulationSpeed: value },
+        });
+    }
+    onBlackholeRepulsionChange(value) {
+        this.configChange.emit({
+            type: 'simulation',
+            simulation: {
+                ...this.config.simulation,
+                blackhole: { ...this.config.simulation?.blackhole, repulsion: value },
+            },
+        });
+    }
+    onTraitCountChange(count) {
+        const c = Math.max(1, Math.min(20, Number(count) || this.traitCount()));
+        this.configChange.emit({ type: 'setTraitCount', count: c });
+    }
+    onCentralPreferenceChange(index, value) {
+        this.configChange.emit({ type: 'centralPreferenceChange', index, value });
+    }
+    onNodeAttributeChange(nodeId, attrIndex, value) {
+        this.configChange.emit({ type: 'nodeAttributeChange', nodeId, attrIndex, value });
+    }
+    onAddNode() {
+        this.configChange.emit({ type: 'addNode' });
+    }
+    onRemoveNode(nodeId) {
+        this.configChange.emit({ type: 'removeNode', nodeId });
+    }
+    onShowContextMenuChange(value) {
+        this.configChange.emit({ type: 'showContextMenu', value });
+    }
+    onDefaultZoomLevelChange(value) {
+        const v = Math.max(0.5, Math.min(2.5, Number(value)));
+        this.configChange.emit({ type: 'defaultZoomLevel', value: v });
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.17", ngImport: i0, type: ConfigSidenavComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "19.2.17", type: ConfigSidenavComponent, isStandalone: true, selector: "tv-config-sidenav", inputs: { config: "config", open: "open" }, outputs: { configChange: "configChange" }, ngImport: i0, template: "<aside class=\"sidebar scrollable-minimal\" [class.closed]=\"!open\">\r\n  <div class=\"sidenav-tabs\">\r\n    <button\r\n      type=\"button\"\r\n      class=\"sidenav-tab\"\r\n      [class.active]=\"activeTab === 'docs'\"\r\n      (click)=\"setActiveTab('docs')\"\r\n      i18n\r\n    >\r\n      Docs\r\n    </button>\r\n    <button\r\n      type=\"button\"\r\n      class=\"sidenav-tab\"\r\n      [class.active]=\"activeTab === 'configs'\"\r\n      (click)=\"setActiveTab('configs')\"\r\n      i18n\r\n    >\r\n      Configs\r\n    </button>\r\n  </div>\r\n\r\n  <div class=\"sidenav-tab-content\">\r\n    @if (activeTab === 'docs') {\r\n      <div class=\"docs-panel\">\r\n        <h3 i18n>Inputs &amp; Outputs</h3>\r\n        <p class=\"docs-lead\">tv-trait-visual component API:</p>\r\n        <p class=\"docs-label\">Inputs</p>\r\n        <ul class=\"docs-list\">\r\n          <li><code>nodeData: INodeData[]</code> (required) \u2013 Array of node data to visualize.</li>\r\n          <li><code>attributeWeights?: number[]</code> \u2013 Weights for attribute calculations.</li>\r\n          <li><code>preferenceWeights?: number[]</code> \u2013 Weights for preference calculations.</li>\r\n          <li><code>attributeCount?: number</code> \u2013 Number of attributes per node (optional).</li>\r\n          <li><code>preferenceCount?: number</code> \u2013 Number of preferences per node (optional).</li>\r\n          <li><code>simulationOptions?: Partial&lt;ISimulationConfigs&gt;</code> \u2013 Simulation options (optional).</li>\r\n          <li><code>showContextMenu?: boolean</code> \u2013 When true, right-click on a node can show the context menu. Default false.</li>\r\n          <li><code>defaultZoomLevel?: number</code> \u2013 Multiplier on initial camera distance (1 = normal, &gt; 1 = zoom out more). Default 1.25.</li>\r\n        </ul>\r\n        <p class=\"docs-label\">Outputs</p>\r\n        <ul class=\"docs-list\">\r\n          <li><code>blackholeSelected: Blackhole | null</code> \u2013 Emitted when the user selects a blackhole (e.g. right-click).</li>\r\n        </ul>\r\n        <p class=\"docs-label\">Usage</p>\r\n        <pre class=\"docs-code\"><code>&lt;tv-trait-visual\r\n  [nodeData]=\"nodeData\"\r\n  [attributeWeights]=\"attributeWeights\"\r\n  [preferenceWeights]=\"preferenceWeights\"\r\n  [showContextMenu]=\"showContextMenu\"\r\n  [defaultZoomLevel]=\"defaultZoomLevel\"\r\n&gt;&lt;/tv-trait-visual&gt;</code></pre>\r\n\r\n        <h3 i18n>Quick Start</h3>\r\n        <p class=\"docs-label\">1. Import the component</p>\r\n        <pre class=\"docs-code\"><code>import &#123; TraitVisualComponent &#125; from '&#64;naniteninja/trait-visual';\r\n\r\n&#64;Component(&#123;\r\n  selector: 'app-my-component',\r\n  standalone: true,\r\n  imports: [TraitVisualComponent],\r\n  template: `\r\n    &lt;tv-trait-visual\r\n      [nodeData]=\"myNodeData\"\r\n      [attributeWeights]=\"myAttributeWeights\"\r\n      [preferenceWeights]=\"myPreferenceWeights\"\r\n      [showContextMenu]=\"false\"\r\n      [defaultZoomLevel]=\"1.25\"\r\n    &gt;&lt;/tv-trait-visual&gt;\r\n  `\r\n&#125;)\r\nexport class MyComponent &#123; &#125;</code></pre>\r\n        <p class=\"docs-label\">2. Prepare your data</p>\r\n        <pre class=\"docs-code\"><code>import &#123; INodeData &#125; from '&#64;naniteninja/trait-visual';\r\n\r\nconst myNodeData: INodeData[] = [\r\n  &#123;\r\n    id: 1,\r\n    name: 'Central Node',\r\n    initialPosition: [0, 0, 0],\r\n    isSupermassiveBlackhole: true,\r\n    color: '#C300FF',\r\n    attributes: &#123; attr1: 50, attr2: 75, attr3: 25 &#125;,\r\n    preferences: &#123; attr1: 100, attr2: 80, attr3: 60 &#125;\r\n  &#125;,\r\n  &#123;\r\n    id: 2,\r\n    name: 'Node 1',\r\n    initialPosition: [5, 0, 0],\r\n    isSupermassiveBlackhole: false,\r\n    color: '#FF3366',\r\n    attributes: &#123; attr1: 0, attr2: 50, attr3: 100 &#125;,\r\n    preferences: &#123; attr1: 0, attr2: 0, attr3: 0 &#125;\r\n  &#125;\r\n];\r\n\r\nconst myAttributeWeights = [1.0, 1.2, 0.8];\r\nconst myPreferenceWeights = [1.0, 1.0, 1.0];</code></pre>\r\n      </div>\r\n    }\r\n\r\n    @if (activeTab === 'configs') {\r\n      <div class=\"configs-panel\">\r\n        <div class=\"sidebar-section\" style=\"margin-top: 40px;\">\r\n          <h3 i18n>Configuration Preset</h3>\r\n          <mat-form-field appearance=\"outline\" style=\"width: 100%;\">\r\n            <mat-label i18n>Select Preset</mat-label>\r\n            <mat-select [value]=\"config.selectedPreset\" (selectionChange)=\"onPresetChange($event.value)\">\r\n              <mat-option value=\"custom\" i18n>Custom (Manual)</mat-option>\r\n              @for (preset of config.availablePresets; track preset.name) {\r\n                <mat-option [value]=\"preset.name\">{{ preset.name }}</mat-option>\r\n              }\r\n            </mat-select>\r\n          </mat-form-field>\r\n        </div>\r\n\r\n        <div class=\"sidebar-section\" style=\"margin-top: 24px;\">\r\n          <h3 i18n>Options</h3>\r\n          <label class=\"context-menu-checkbox\">\r\n            <input\r\n              type=\"checkbox\"\r\n              [checked]=\"config.showContextMenu ?? false\"\r\n              (change)=\"onShowContextMenuChange($any($event.target).checked)\"\r\n            />\r\n            <span i18n>Show context menu</span>\r\n          </label>\r\n          <p class=\"sidebar-hint\" i18n>When on, right-click a node to open its menu (set as central, remove, color).</p>\r\n          <ul class=\"weights-list\" style=\"margin-top: 12px;\">\r\n            <li>\r\n              <label>\r\n                <span i18n>Default zoom (1 = normal, higher = zoom out more)</span>\r\n                <input\r\n                  type=\"range\"\r\n                  min=\"0.5\"\r\n                  max=\"2.5\"\r\n                  step=\"0.05\"\r\n                  [value]=\"config.defaultZoomLevel ?? 1.25\"\r\n                  (input)=\"onDefaultZoomLevelChange($any($event.target).valueAsNumber)\"\r\n                />\r\n                <span>{{ (config.defaultZoomLevel ?? 1.25) | number:'1.2-2' }}</span>\r\n              </label>\r\n            </li>\r\n          </ul>\r\n        </div>\r\n\r\n        <ng-content select=\"[config-appearance]\"></ng-content>\r\n\r\n        <div class=\"sidebar-section\" style=\"margin-top: 40px;\">\r\n          <h3 i18n>Attribute Weights</h3>\r\n          <ul class=\"weights-list\">\r\n            @for (w of config.attributeWeights; track $index; let i = $index) {\r\n              <li>\r\n                <label>\r\n                  Attr {{ i + 1 }}:\r\n                  <input\r\n                    type=\"number\"\r\n                    min=\"0\"\r\n                    step=\"0.01\"\r\n                    [value]=\"w\"\r\n                    (input)=\"onWeightChange(i, $any($event.target).valueAsNumber)\"\r\n                  />\r\n                  <span>{{ w | number:'1.2-2' }}</span>\r\n                </label>\r\n              </li>\r\n            }\r\n          </ul>\r\n        </div>\r\n        <div class=\"sidebar-section\" style=\"margin-top: 20px;\">\r\n          <h3 i18n>Preference Weights</h3>\r\n          <ul class=\"weights-list\">\r\n            @for (w of config.preferenceWeights; track $index; let i = $index) {\r\n              <li>\r\n                <label>\r\n                  Pref {{ i + 1 }}:\r\n                  <input\r\n                    type=\"number\"\r\n                    min=\"0\"\r\n                    step=\"0.01\"\r\n                    [value]=\"w\"\r\n                    (input)=\"onPrefWeightChange(i, $any($event.target).valueAsNumber)\"\r\n                  />\r\n                  <span>{{ w | number:'1.2-2' }}</span>\r\n                </label>\r\n              </li>\r\n            }\r\n          </ul>\r\n        </div>\r\n\r\n        @if (config.simulation != null) {\r\n          <div class=\"sidebar-section\" style=\"margin-top: 40px;\">\r\n            <h3 i18n>Dissimilarity Repulsion</h3>\r\n            <ul class=\"weights-list\">\r\n              <li>\r\n                <label>\r\n                  Blackhole repulsion:\r\n                  <input\r\n                    type=\"range\"\r\n                    min=\"0.2\"\r\n                    max=\"3\"\r\n                    step=\"0.1\"\r\n                    [value]=\"config.simulation.blackhole?.repulsion ?? 1\"\r\n                    (input)=\"onBlackholeRepulsionChange($any($event.target).valueAsNumber)\"\r\n                  />\r\n                  <span>{{ (config.simulation.blackhole?.repulsion ?? 1) | number:'1.1-1' }}</span>\r\n                </label>\r\n              </li>\r\n              <li>\r\n                <label>\r\n                  Simulation speed:\r\n                  <input\r\n                    type=\"range\"\r\n                    min=\"0.25\"\r\n                    max=\"4\"\r\n                    step=\"0.25\"\r\n                    [value]=\"config.simulation.simulationSpeed ?? 1\"\r\n                    (input)=\"onSimulationSpeedChange($any($event.target).valueAsNumber)\"\r\n                  />\r\n                  <span>{{ (config.simulation.simulationSpeed ?? 1) | number:'1.2-2' }}\u00D7</span>\r\n                </label>\r\n              </li>\r\n            </ul>\r\n          </div>\r\n        }\r\n\r\n        <ng-content select=\"[config-simulation-extra]\"></ng-content>\r\n\r\n        <div class=\"sidebar-section\" style=\"margin-top: 40px;\">\r\n          <div class=\"blackhole-head\">\r\n            <h3 style=\"margin: 0;\" i18n>Supermassive Black Hole Preferences</h3>\r\n            <button mat-icon-button i18n-matTooltip=\"Tooltip for add blackhole button\" matTooltip=\"Add Blackhole\" (click)=\"onAddNode()\">\r\n              <mat-icon>add</mat-icon>\r\n            </button>\r\n          </div>\r\n          <div class=\"attribute-list\" style=\"margin-bottom: 8px;\">\r\n            <label>\r\n              Trait Count:\r\n              <input\r\n                type=\"number\"\r\n                min=\"1\"\r\n                max=\"20\"\r\n                [value]=\"traitCount()\"\r\n                (change)=\"onTraitCountChange($any($event.target).valueAsNumber)\"\r\n              />\r\n            </label>\r\n          </div>\r\n          @if (centralNode) {\r\n            @for (pref of centralPrefsArray(); track $index; let i = $index) {\r\n              <div class=\"attribute-list\">\r\n                <label>\r\n                  Preference {{ i + 1 }}:\r\n                  <input\r\n                    type=\"number\"\r\n                    min=\"0\"\r\n                    max=\"100\"\r\n                    [value]=\"pref\"\r\n                    (input)=\"onCentralPreferenceChange(i, $any($event.target).valueAsNumber)\"\r\n                  />\r\n                  <span>{{ pref }}</span>\r\n                </label>\r\n              </div>\r\n            }\r\n          }\r\n        </div>\r\n\r\n        <div class=\"sidebar-section\" style=\"margin-top: 40px;\">\r\n          <h3 i18n>Blackhole Attributes</h3>\r\n          @for (node of nonSupermassiveBlackholeNodes; track node.id) {\r\n            <div class=\"blackhole-block\">\r\n              <div class=\"blackhole-head\">\r\n                <div class=\"blackhole-name\">{{ node.name }}</div>\r\n                <button mat-icon-button i18n-matTooltip=\"Tooltip for remove blackhole button\" matTooltip=\"Remove Blackhole\" (click)=\"onRemoveNode(node.id)\">\r\n                  <mat-icon>delete</mat-icon>\r\n                </button>\r\n              </div>\r\n              @for (attr of nodeAttrsArray(node); track $index; let j = $index) {\r\n                <div class=\"attribute-list\">\r\n                  <label>\r\n                    Attr {{ j + 1 }}:\r\n                    <input\r\n                      type=\"number\"\r\n                      min=\"0\"\r\n                      max=\"100\"\r\n                      [value]=\"attr\"\r\n                      (input)=\"onNodeAttributeChange(node.id, j, $any($event.target).valueAsNumber)\"\r\n                    />\r\n                    <span>{{ attr }}</span>\r\n                  </label>\r\n                </div>\r\n              }\r\n            </div>\r\n          }\r\n        </div>\r\n      </div>\r\n    }\r\n  </div>\r\n</aside>\r\n", styles: [".sidebar{position:absolute;top:0;left:0;height:100vh;width:320px;overflow-y:auto;padding:16px 16px 24px;background:#1a0f18;box-shadow:4px 0 12px #0006;z-index:100;transition:transform .2s ease}.sidebar.closed{transform:translate(-100%)}.sidebar h3{margin:8px 0 12px;color:#f6c;font-weight:600}.sidebar .blackhole-name{margin:12px 0 6px;color:#c300ff;font-weight:500}.sidebar .attribute-list label{display:flex;align-items:center;justify-content:space-between;gap:8px}.sidebar input[type=range]{flex:1;margin:0 8px}.sidebar input[type=number]{width:72px;margin:0 8px;padding:6px 8px;border-radius:8px;border:none;background:#231321;color:#f6c;box-shadow:inset 2px 2px 5px #0006,inset -2px -2px 5px #c300ff26}.blackhole-head{display:flex;align-items:center;justify-content:space-between}.blackhole-block{margin-bottom:12px;padding-bottom:8px;border-bottom:1px solid rgba(255,255,255,.08)}.weights-list{list-style:none;padding:0;margin:0}.weights-list li{margin-bottom:8px}.weights-list label{display:flex;align-items:center;gap:8px}.context-menu-checkbox{display:flex;align-items:center;gap:8px;cursor:pointer;margin-bottom:4px}.context-menu-checkbox input[type=checkbox]{width:18px;height:18px}.sidebar-hint{margin:0 0 12px;font-size:12px;color:#ff66ccd9}.sidenav-tabs{display:flex;flex-direction:row;gap:0;margin-bottom:12px;border-bottom:1px solid rgba(255,255,255,.12)}.sidenav-tab{flex:1;padding:10px 16px;border:none;border-bottom:3px solid transparent;background:transparent;color:#f6cc;font-size:14px;font-weight:500;cursor:pointer;transition:color .2s ease,border-color .2s ease}.sidenav-tab:hover{color:#f6c}.sidenav-tab.active{color:#f6c;border-bottom-color:#c300ff}.docs-panel h3{margin:16px 0 10px;color:#f6c;font-weight:600}.docs-panel h3:first-child{margin-top:0}.docs-lead{margin:0 0 8px;font-size:13px;color:#ffffffe6}.docs-label{margin:12px 0 6px;font-size:12px;font-weight:600;color:#c300ff}.docs-list{margin:0 0 12px;padding-left:20px;font-size:13px;color:#ffffffe6;line-height:1.5}.docs-list li{margin-bottom:4px}.docs-list code{font-family:ui-monospace,monospace;font-size:12px;color:#f6c;background:#231321cc;padding:2px 6px;border-radius:4px}.docs-code{margin:8px 0 16px;padding:12px;overflow-x:auto;font-family:ui-monospace,monospace;font-size:11px;line-height:1.4;color:#f6c;background:#231321;border-radius:8px;border:1px solid rgba(195,0,255,.25);box-shadow:inset 2px 2px 6px #0000004d}.docs-code code{padding:0;background:none;color:inherit}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "pipe", type: i1.DecimalPipe, name: "number" }, { kind: "ngmodule", type: MatIconModule }, { kind: "component", type: i2.MatIcon, selector: "mat-icon", inputs: ["color", "inline", "svgIcon", "fontSet", "fontIcon"], exportAs: ["matIcon"] }, { kind: "ngmodule", type: MatButtonModule }, { kind: "component", type: i3.MatIconButton, selector: "button[mat-icon-button]", exportAs: ["matButton"] }, { kind: "ngmodule", type: MatTooltipModule }, { kind: "directive", type: i4.MatTooltip, selector: "[matTooltip]", inputs: ["matTooltipPosition", "matTooltipPositionAtOrigin", "matTooltipDisabled", "matTooltipShowDelay", "matTooltipHideDelay", "matTooltipTouchGestures", "matTooltip", "matTooltipClass"], exportAs: ["matTooltip"] }, { kind: "ngmodule", type: MatSelectModule }, { kind: "component", type: i5.MatFormField, selector: "mat-form-field", inputs: ["hideRequiredMarker", "color", "floatLabel", "appearance", "subscriptSizing", "hintLabel"], exportAs: ["matFormField"] }, { kind: "directive", type: i5.MatLabel, selector: "mat-label" }, { kind: "component", type: i5.MatSelect, selector: "mat-select", inputs: ["aria-describedby", "panelClass", "disabled", "disableRipple", "tabIndex", "hideSingleSelectionIndicator", "placeholder", "required", "multiple", "disableOptionCentering", "compareWith", "value", "aria-label", "aria-labelledby", "errorStateMatcher", "typeaheadDebounceInterval", "sortComparator", "id", "panelWidth", "canSelectNullableOptions"], outputs: ["openedChange", "opened", "closed", "selectionChange", "valueChange"], exportAs: ["matSelect"] }, { kind: "component", type: i5.MatOption, selector: "mat-option", inputs: ["value", "id", "disabled"], outputs: ["onSelectionChange"], exportAs: ["matOption"] }, { kind: "ngmodule", type: MatFormFieldModule }] });
 }
-const colors = ['#C300FF', '#FF3366'];
-const baseNodes = [
-    {
-        id: 1,
-        name: 'James',
-        initialPosition: [0, 0, 0],
-        isSun: true,
-        color: '#C300FF',
-        attributes: generateAttributes(dynamicCounts.attributes, 0),
-        preferences: generateAttributes(dynamicCounts.preferences, 100),
-    },
-    ...[...Array(10)].map((_, i) => {
-        const id = i + 2;
-        const names = ['John', 'Alice', 'Robert', 'Emma', 'Michael', 'Sarah', 'David', 'Lisa', 'Chris', 'Maria'];
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.17", ngImport: i0, type: ConfigSidenavComponent, decorators: [{
+            type: Component,
+            args: [{ selector: 'tv-config-sidenav', standalone: true, imports: [
+                        CommonModule,
+                        MatIconModule,
+                        MatButtonModule,
+                        MatTooltipModule,
+                        MatSelectModule,
+                        MatFormFieldModule,
+                    ], template: "<aside class=\"sidebar scrollable-minimal\" [class.closed]=\"!open\">\r\n  <div class=\"sidenav-tabs\">\r\n    <button\r\n      type=\"button\"\r\n      class=\"sidenav-tab\"\r\n      [class.active]=\"activeTab === 'docs'\"\r\n      (click)=\"setActiveTab('docs')\"\r\n      i18n\r\n    >\r\n      Docs\r\n    </button>\r\n    <button\r\n      type=\"button\"\r\n      class=\"sidenav-tab\"\r\n      [class.active]=\"activeTab === 'configs'\"\r\n      (click)=\"setActiveTab('configs')\"\r\n      i18n\r\n    >\r\n      Configs\r\n    </button>\r\n  </div>\r\n\r\n  <div class=\"sidenav-tab-content\">\r\n    @if (activeTab === 'docs') {\r\n      <div class=\"docs-panel\">\r\n        <h3 i18n>Inputs &amp; Outputs</h3>\r\n        <p class=\"docs-lead\">tv-trait-visual component API:</p>\r\n        <p class=\"docs-label\">Inputs</p>\r\n        <ul class=\"docs-list\">\r\n          <li><code>nodeData: INodeData[]</code> (required) \u2013 Array of node data to visualize.</li>\r\n          <li><code>attributeWeights?: number[]</code> \u2013 Weights for attribute calculations.</li>\r\n          <li><code>preferenceWeights?: number[]</code> \u2013 Weights for preference calculations.</li>\r\n          <li><code>attributeCount?: number</code> \u2013 Number of attributes per node (optional).</li>\r\n          <li><code>preferenceCount?: number</code> \u2013 Number of preferences per node (optional).</li>\r\n          <li><code>simulationOptions?: Partial&lt;ISimulationConfigs&gt;</code> \u2013 Simulation options (optional).</li>\r\n          <li><code>showContextMenu?: boolean</code> \u2013 When true, right-click on a node can show the context menu. Default false.</li>\r\n          <li><code>defaultZoomLevel?: number</code> \u2013 Multiplier on initial camera distance (1 = normal, &gt; 1 = zoom out more). Default 1.25.</li>\r\n        </ul>\r\n        <p class=\"docs-label\">Outputs</p>\r\n        <ul class=\"docs-list\">\r\n          <li><code>blackholeSelected: Blackhole | null</code> \u2013 Emitted when the user selects a blackhole (e.g. right-click).</li>\r\n        </ul>\r\n        <p class=\"docs-label\">Usage</p>\r\n        <pre class=\"docs-code\"><code>&lt;tv-trait-visual\r\n  [nodeData]=\"nodeData\"\r\n  [attributeWeights]=\"attributeWeights\"\r\n  [preferenceWeights]=\"preferenceWeights\"\r\n  [showContextMenu]=\"showContextMenu\"\r\n  [defaultZoomLevel]=\"defaultZoomLevel\"\r\n&gt;&lt;/tv-trait-visual&gt;</code></pre>\r\n\r\n        <h3 i18n>Quick Start</h3>\r\n        <p class=\"docs-label\">1. Import the component</p>\r\n        <pre class=\"docs-code\"><code>import &#123; TraitVisualComponent &#125; from '&#64;naniteninja/trait-visual';\r\n\r\n&#64;Component(&#123;\r\n  selector: 'app-my-component',\r\n  standalone: true,\r\n  imports: [TraitVisualComponent],\r\n  template: `\r\n    &lt;tv-trait-visual\r\n      [nodeData]=\"myNodeData\"\r\n      [attributeWeights]=\"myAttributeWeights\"\r\n      [preferenceWeights]=\"myPreferenceWeights\"\r\n      [showContextMenu]=\"false\"\r\n      [defaultZoomLevel]=\"1.25\"\r\n    &gt;&lt;/tv-trait-visual&gt;\r\n  `\r\n&#125;)\r\nexport class MyComponent &#123; &#125;</code></pre>\r\n        <p class=\"docs-label\">2. Prepare your data</p>\r\n        <pre class=\"docs-code\"><code>import &#123; INodeData &#125; from '&#64;naniteninja/trait-visual';\r\n\r\nconst myNodeData: INodeData[] = [\r\n  &#123;\r\n    id: 1,\r\n    name: 'Central Node',\r\n    initialPosition: [0, 0, 0],\r\n    isSupermassiveBlackhole: true,\r\n    color: '#C300FF',\r\n    attributes: &#123; attr1: 50, attr2: 75, attr3: 25 &#125;,\r\n    preferences: &#123; attr1: 100, attr2: 80, attr3: 60 &#125;\r\n  &#125;,\r\n  &#123;\r\n    id: 2,\r\n    name: 'Node 1',\r\n    initialPosition: [5, 0, 0],\r\n    isSupermassiveBlackhole: false,\r\n    color: '#FF3366',\r\n    attributes: &#123; attr1: 0, attr2: 50, attr3: 100 &#125;,\r\n    preferences: &#123; attr1: 0, attr2: 0, attr3: 0 &#125;\r\n  &#125;\r\n];\r\n\r\nconst myAttributeWeights = [1.0, 1.2, 0.8];\r\nconst myPreferenceWeights = [1.0, 1.0, 1.0];</code></pre>\r\n      </div>\r\n    }\r\n\r\n    @if (activeTab === 'configs') {\r\n      <div class=\"configs-panel\">\r\n        <div class=\"sidebar-section\" style=\"margin-top: 40px;\">\r\n          <h3 i18n>Configuration Preset</h3>\r\n          <mat-form-field appearance=\"outline\" style=\"width: 100%;\">\r\n            <mat-label i18n>Select Preset</mat-label>\r\n            <mat-select [value]=\"config.selectedPreset\" (selectionChange)=\"onPresetChange($event.value)\">\r\n              <mat-option value=\"custom\" i18n>Custom (Manual)</mat-option>\r\n              @for (preset of config.availablePresets; track preset.name) {\r\n                <mat-option [value]=\"preset.name\">{{ preset.name }}</mat-option>\r\n              }\r\n            </mat-select>\r\n          </mat-form-field>\r\n        </div>\r\n\r\n        <div class=\"sidebar-section\" style=\"margin-top: 24px;\">\r\n          <h3 i18n>Options</h3>\r\n          <label class=\"context-menu-checkbox\">\r\n            <input\r\n              type=\"checkbox\"\r\n              [checked]=\"config.showContextMenu ?? false\"\r\n              (change)=\"onShowContextMenuChange($any($event.target).checked)\"\r\n            />\r\n            <span i18n>Show context menu</span>\r\n          </label>\r\n          <p class=\"sidebar-hint\" i18n>When on, right-click a node to open its menu (set as central, remove, color).</p>\r\n          <ul class=\"weights-list\" style=\"margin-top: 12px;\">\r\n            <li>\r\n              <label>\r\n                <span i18n>Default zoom (1 = normal, higher = zoom out more)</span>\r\n                <input\r\n                  type=\"range\"\r\n                  min=\"0.5\"\r\n                  max=\"2.5\"\r\n                  step=\"0.05\"\r\n                  [value]=\"config.defaultZoomLevel ?? 1.25\"\r\n                  (input)=\"onDefaultZoomLevelChange($any($event.target).valueAsNumber)\"\r\n                />\r\n                <span>{{ (config.defaultZoomLevel ?? 1.25) | number:'1.2-2' }}</span>\r\n              </label>\r\n            </li>\r\n          </ul>\r\n        </div>\r\n\r\n        <ng-content select=\"[config-appearance]\"></ng-content>\r\n\r\n        <div class=\"sidebar-section\" style=\"margin-top: 40px;\">\r\n          <h3 i18n>Attribute Weights</h3>\r\n          <ul class=\"weights-list\">\r\n            @for (w of config.attributeWeights; track $index; let i = $index) {\r\n              <li>\r\n                <label>\r\n                  Attr {{ i + 1 }}:\r\n                  <input\r\n                    type=\"number\"\r\n                    min=\"0\"\r\n                    step=\"0.01\"\r\n                    [value]=\"w\"\r\n                    (input)=\"onWeightChange(i, $any($event.target).valueAsNumber)\"\r\n                  />\r\n                  <span>{{ w | number:'1.2-2' }}</span>\r\n                </label>\r\n              </li>\r\n            }\r\n          </ul>\r\n        </div>\r\n        <div class=\"sidebar-section\" style=\"margin-top: 20px;\">\r\n          <h3 i18n>Preference Weights</h3>\r\n          <ul class=\"weights-list\">\r\n            @for (w of config.preferenceWeights; track $index; let i = $index) {\r\n              <li>\r\n                <label>\r\n                  Pref {{ i + 1 }}:\r\n                  <input\r\n                    type=\"number\"\r\n                    min=\"0\"\r\n                    step=\"0.01\"\r\n                    [value]=\"w\"\r\n                    (input)=\"onPrefWeightChange(i, $any($event.target).valueAsNumber)\"\r\n                  />\r\n                  <span>{{ w | number:'1.2-2' }}</span>\r\n                </label>\r\n              </li>\r\n            }\r\n          </ul>\r\n        </div>\r\n\r\n        @if (config.simulation != null) {\r\n          <div class=\"sidebar-section\" style=\"margin-top: 40px;\">\r\n            <h3 i18n>Dissimilarity Repulsion</h3>\r\n            <ul class=\"weights-list\">\r\n              <li>\r\n                <label>\r\n                  Blackhole repulsion:\r\n                  <input\r\n                    type=\"range\"\r\n                    min=\"0.2\"\r\n                    max=\"3\"\r\n                    step=\"0.1\"\r\n                    [value]=\"config.simulation.blackhole?.repulsion ?? 1\"\r\n                    (input)=\"onBlackholeRepulsionChange($any($event.target).valueAsNumber)\"\r\n                  />\r\n                  <span>{{ (config.simulation.blackhole?.repulsion ?? 1) | number:'1.1-1' }}</span>\r\n                </label>\r\n              </li>\r\n              <li>\r\n                <label>\r\n                  Simulation speed:\r\n                  <input\r\n                    type=\"range\"\r\n                    min=\"0.25\"\r\n                    max=\"4\"\r\n                    step=\"0.25\"\r\n                    [value]=\"config.simulation.simulationSpeed ?? 1\"\r\n                    (input)=\"onSimulationSpeedChange($any($event.target).valueAsNumber)\"\r\n                  />\r\n                  <span>{{ (config.simulation.simulationSpeed ?? 1) | number:'1.2-2' }}\u00D7</span>\r\n                </label>\r\n              </li>\r\n            </ul>\r\n          </div>\r\n        }\r\n\r\n        <ng-content select=\"[config-simulation-extra]\"></ng-content>\r\n\r\n        <div class=\"sidebar-section\" style=\"margin-top: 40px;\">\r\n          <div class=\"blackhole-head\">\r\n            <h3 style=\"margin: 0;\" i18n>Supermassive Black Hole Preferences</h3>\r\n            <button mat-icon-button i18n-matTooltip=\"Tooltip for add blackhole button\" matTooltip=\"Add Blackhole\" (click)=\"onAddNode()\">\r\n              <mat-icon>add</mat-icon>\r\n            </button>\r\n          </div>\r\n          <div class=\"attribute-list\" style=\"margin-bottom: 8px;\">\r\n            <label>\r\n              Trait Count:\r\n              <input\r\n                type=\"number\"\r\n                min=\"1\"\r\n                max=\"20\"\r\n                [value]=\"traitCount()\"\r\n                (change)=\"onTraitCountChange($any($event.target).valueAsNumber)\"\r\n              />\r\n            </label>\r\n          </div>\r\n          @if (centralNode) {\r\n            @for (pref of centralPrefsArray(); track $index; let i = $index) {\r\n              <div class=\"attribute-list\">\r\n                <label>\r\n                  Preference {{ i + 1 }}:\r\n                  <input\r\n                    type=\"number\"\r\n                    min=\"0\"\r\n                    max=\"100\"\r\n                    [value]=\"pref\"\r\n                    (input)=\"onCentralPreferenceChange(i, $any($event.target).valueAsNumber)\"\r\n                  />\r\n                  <span>{{ pref }}</span>\r\n                </label>\r\n              </div>\r\n            }\r\n          }\r\n        </div>\r\n\r\n        <div class=\"sidebar-section\" style=\"margin-top: 40px;\">\r\n          <h3 i18n>Blackhole Attributes</h3>\r\n          @for (node of nonSupermassiveBlackholeNodes; track node.id) {\r\n            <div class=\"blackhole-block\">\r\n              <div class=\"blackhole-head\">\r\n                <div class=\"blackhole-name\">{{ node.name }}</div>\r\n                <button mat-icon-button i18n-matTooltip=\"Tooltip for remove blackhole button\" matTooltip=\"Remove Blackhole\" (click)=\"onRemoveNode(node.id)\">\r\n                  <mat-icon>delete</mat-icon>\r\n                </button>\r\n              </div>\r\n              @for (attr of nodeAttrsArray(node); track $index; let j = $index) {\r\n                <div class=\"attribute-list\">\r\n                  <label>\r\n                    Attr {{ j + 1 }}:\r\n                    <input\r\n                      type=\"number\"\r\n                      min=\"0\"\r\n                      max=\"100\"\r\n                      [value]=\"attr\"\r\n                      (input)=\"onNodeAttributeChange(node.id, j, $any($event.target).valueAsNumber)\"\r\n                    />\r\n                    <span>{{ attr }}</span>\r\n                  </label>\r\n                </div>\r\n              }\r\n            </div>\r\n          }\r\n        </div>\r\n      </div>\r\n    }\r\n  </div>\r\n</aside>\r\n", styles: [".sidebar{position:absolute;top:0;left:0;height:100vh;width:320px;overflow-y:auto;padding:16px 16px 24px;background:#1a0f18;box-shadow:4px 0 12px #0006;z-index:100;transition:transform .2s ease}.sidebar.closed{transform:translate(-100%)}.sidebar h3{margin:8px 0 12px;color:#f6c;font-weight:600}.sidebar .blackhole-name{margin:12px 0 6px;color:#c300ff;font-weight:500}.sidebar .attribute-list label{display:flex;align-items:center;justify-content:space-between;gap:8px}.sidebar input[type=range]{flex:1;margin:0 8px}.sidebar input[type=number]{width:72px;margin:0 8px;padding:6px 8px;border-radius:8px;border:none;background:#231321;color:#f6c;box-shadow:inset 2px 2px 5px #0006,inset -2px -2px 5px #c300ff26}.blackhole-head{display:flex;align-items:center;justify-content:space-between}.blackhole-block{margin-bottom:12px;padding-bottom:8px;border-bottom:1px solid rgba(255,255,255,.08)}.weights-list{list-style:none;padding:0;margin:0}.weights-list li{margin-bottom:8px}.weights-list label{display:flex;align-items:center;gap:8px}.context-menu-checkbox{display:flex;align-items:center;gap:8px;cursor:pointer;margin-bottom:4px}.context-menu-checkbox input[type=checkbox]{width:18px;height:18px}.sidebar-hint{margin:0 0 12px;font-size:12px;color:#ff66ccd9}.sidenav-tabs{display:flex;flex-direction:row;gap:0;margin-bottom:12px;border-bottom:1px solid rgba(255,255,255,.12)}.sidenav-tab{flex:1;padding:10px 16px;border:none;border-bottom:3px solid transparent;background:transparent;color:#f6cc;font-size:14px;font-weight:500;cursor:pointer;transition:color .2s ease,border-color .2s ease}.sidenav-tab:hover{color:#f6c}.sidenav-tab.active{color:#f6c;border-bottom-color:#c300ff}.docs-panel h3{margin:16px 0 10px;color:#f6c;font-weight:600}.docs-panel h3:first-child{margin-top:0}.docs-lead{margin:0 0 8px;font-size:13px;color:#ffffffe6}.docs-label{margin:12px 0 6px;font-size:12px;font-weight:600;color:#c300ff}.docs-list{margin:0 0 12px;padding-left:20px;font-size:13px;color:#ffffffe6;line-height:1.5}.docs-list li{margin-bottom:4px}.docs-list code{font-family:ui-monospace,monospace;font-size:12px;color:#f6c;background:#231321cc;padding:2px 6px;border-radius:4px}.docs-code{margin:8px 0 16px;padding:12px;overflow-x:auto;font-family:ui-monospace,monospace;font-size:11px;line-height:1.4;color:#f6c;background:#231321;border-radius:8px;border:1px solid rgba(195,0,255,.25);box-shadow:inset 2px 2px 6px #0000004d}.docs-code code{padding:0;background:none;color:inherit}\n"] }]
+        }], propDecorators: { config: [{
+                type: Input
+            }], open: [{
+                type: Input
+            }], configChange: [{
+                type: Output
+            }] } });
+
+/**
+ * StellarDustField
+ *
+ * A true 3D, GPU‑animated particle disk that orbits a given center (the supermassive black hole).
+ * It uses two draw calls: a dense mid/far bed of tiny points and a sparse
+ * foreground bokeh cohort of large, soft discs. Motion is computed fully on
+ * the GPU (vertex shader) from per‑particle attributes; the CPU only updates
+ * a few uniforms per frame.
+ */
+class StellarDustField {
+    scene;
+    group; // positioned at the supermassive black hole; orientable disk
+    points = null;
+    // Node-attractor uniforms (shared across cohorts)
+    MAX_ATTRACTORS = 24;
+    MAX_PALETTE_STOPS = 12;
+    // We store world-space attractors from the app; convert to local each update
+    attractorWorldPos = [];
+    attractorWorldRad = [];
+    attractorLocalPos = []; // derived each frame
+    attractorRadius = []; // derived each frame (same values)
+    // Tunables for near-capture + stick approximation
+    nearRadiusFactor = 8.0; // moderate capture zone relative to node radius
+    // Phase 2: relative epsilon per node
+    stickEpsRel = 0.12; // 12% of node radius
+    stickEpsMin = 0.004; // world-units floor
+    stickEpsMax = 0.02; // world-units cap
+    attractStrength = 1.0; // strong pull to surface
+    tangentialBias = 0.22; // slide, tapered near surface in shader
+    debugDustTouch = false;
+    lastDustLogMs = 0;
+    // Phase 0: feature flag (disabled by default)
+    useAttract = false;
+    debugLogPalette = false;
+    debugLogBands = true;
+    debugEdgeMix = 0.3;
+    // Debug: center brightness controls (off by default)
+    debugDimLights = false;
+    whitenScale = 1.0; // scales white mixes (rim/core highlights)
+    alphaScale = 1.0; // global alpha scale to reduce additive blowout
+    // Palette controls (phase 1)
+    paletteStops = [];
+    paletteHueBiasScale = 0.65;
+    paletteBackgroundLift = 0.08;
+    paletteCoreIntensity = 1.45;
+    paletteUniformColors = [];
+    paletteUniformStops = new Float32Array(this.MAX_PALETTE_STOPS);
+    paletteUniformIntensities = new Float32Array(this.MAX_PALETTE_STOPS);
+    paletteUniformCount = 0;
+    // Disk/halo composition + arm shaping (disk mode)
+    diskFraction = 0.62; // keep majority of particles in the thin disk
+    diskBokehFraction = 0.7;
+    haloRadiusMultiplier = 1.35; // extend halo slightly beyond outer radius
+    armCount = 5;
+    armPopulation = 0.68; // % of disk particles influenced by spiral arms
+    armSpread = 0.42; // radians of jitter around each arm center
+    armTwist = 4.6; // radians of twist across radius (log spiral feel)
+    haloArmPopulation = 0.45;
+    haloArmSpread = 0.75;
+    haloArmTwist = 3.2;
+    // Spherical mode parameters
+    dustMode = 'disk';
+    sphereJitter = 0.22; // controls local noise amplitude in sphere mode
+    static DEFAULT_PALETTE = {
+        stops: [
+            { at: 0.0, color: '#f8fdff', intensity: 1.3 },
+            { at: 0.12, color: '#67dbff', intensity: 1.05 },
+            { at: 0.24, color: '#1c4cff', intensity: 0.92 },
+            { at: 0.36, color: '#2c35f4', intensity: 0.9 },
+            { at: 0.5, color: '#4321f2', intensity: 0.92 },
+            { at: 0.64, color: '#6d23fa', intensity: 0.95 },
+            { at: 0.76, color: '#a22eff', intensity: 0.96 },
+            { at: 0.88, color: '#d641ff', intensity: 0.9 },
+            { at: 1.0, color: '#ff63d9', intensity: 0.82 },
+        ],
+        hueBiasScale: 0.78,
+        backgroundLift: 0.062,
+        coreIntensity: 1.3,
+    };
+    opts = {
+        innerRadius: 0.1,
+        outerRadius: 6.0,
+        thickness: 0.0,
+        countMidFar: 24000,
+        countBokeh: 1400,
+        minAngularVel: 0.05,
+        maxAngularVel: 0.18,
+        noiseStrength: 0.06,
+        colorInner: new THREE.Color('#f3fbff'),
+        colorMid: new THREE.Color('#2f7aff'),
+        colorOuter: new THREE.Color('#ff5dd6'),
+        renderOrder: 0,
+    };
+    time = 0;
+    viewportHeight = 800; // for size attenuation approx
+    constructor(scene, options) {
+        this.scene = scene;
+        this.group = new THREE.Group();
+        this.scene.add(this.group);
+        this.applyPalette(StellarDustField.DEFAULT_PALETTE);
+        if (options)
+            this.applyOptions(options);
+        else
+            this.syncLegacyColorsFromPalette();
+        // Optional flags via query string (fail-safe)
+        try {
+            const search = getWindowLocationSearch();
+            // Attraction disabled by default; enable only when ?dustAttract=1
+            this.useAttract = /(?:^|[?&])dustAttract=1(?:&|$)/.test(search);
+            this.debugDustTouch = /(?:^|[?&])debugDust=(1|2)(?:&|$)/.test(search);
+            // Optional tuning overrides
+            const mNear = /(?:^|[?&])dustNear=([0-9.]+)(?:&|$)/.exec(search);
+            if (mNear)
+                this.nearRadiusFactor = Math.max(1, parseFloat(mNear[1]));
+            const mRel = /(?:^|[?&])dustEpsRel=([0-9.]+)(?:&|$)/.exec(search);
+            if (mRel)
+                this.stickEpsRel = Math.max(0.001, parseFloat(mRel[1]));
+            const mEpsMin = /(?:^|[?&])dustEpsMin=([0-9.]+)(?:&|$)/.exec(search);
+            if (mEpsMin) {
+                this.stickEpsMin = Math.max(0, parseFloat(mEpsMin[1]));
+                // Keep invariant so clamping honours the override even without dustEpsMax.
+                if (this.stickEpsMin > this.stickEpsMax) {
+                    this.stickEpsMax = this.stickEpsMin;
+                }
+            }
+            const mEpsMax = /(?:^|[?&])dustEpsMax=([0-9.]+)(?:&|$)/.exec(search);
+            if (mEpsMax)
+                this.stickEpsMax = Math.max(this.stickEpsMin, parseFloat(mEpsMax[1]));
+            const modeMatch = /(?:^|[?&])dustMode=(sphere|disk)(?:&|$)/.exec(search);
+            if (modeMatch)
+                this.dustMode =
+                    modeMatch[1] === 'sphere' ? 'disk' : modeMatch[1];
+            const mJitter = /(?:^|[?&])dustJitter=([0-9.]+)(?:&|$)/.exec(search);
+            if (mJitter)
+                this.sphereJitter = Math.max(0, parseFloat(mJitter[1]));
+            this.debugLogPalette = /(?:^|[?&])dustPaletteLog=1(?:&|$)/.test(search);
+            const mBandLog = /(?:^|[?&])dustBandLog=(0|1)(?:&|$)/.exec(search);
+            if (mBandLog) {
+                this.debugLogBands = mBandLog[1] !== '0';
+            }
+            const mEdgeDebug = /(?:^|[?&])dustEdge(?:Debug)?=([0-9.]+)(?:&|$)/.exec(search);
+            if (mEdgeDebug) {
+                const mix = parseFloat(mEdgeDebug[1]);
+                if (Number.isFinite(mix)) {
+                    this.debugEdgeMix = THREE.MathUtils.clamp(mix, 0, 1);
+                }
+            }
+            // Brightness reduction toggles
+            // Enable dimming with ?dustDim=1 (aliases: dustReduceLight=1, dustDimLights=1)
+            this.debugDimLights =
+                /(?:^|[?&])dustDim=1(?:&|$)/.test(search) ||
+                    /(?:^|[?&])dustReduceLight=1(?:&|$)/.test(search) ||
+                    /(?:^|[?&])dustDimLights=1(?:&|$)/.test(search);
+            // Optional explicit scales
+            const mWhiten = /(?:^|[?&])dustWhitenScale=([0-9.]+)(?:&|$)/.exec(search);
+            const mAlpha = /(?:^|[?&])dustAlphaScale=([0-9.]+)(?:&|$)/.exec(search);
+            if (mWhiten) {
+                const v = parseFloat(mWhiten[1]);
+                if (Number.isFinite(v))
+                    this.whitenScale = THREE.MathUtils.clamp(v, 0, 2);
+            }
+            if (mAlpha) {
+                const v = parseFloat(mAlpha[1]);
+                if (Number.isFinite(v))
+                    this.alphaScale = THREE.MathUtils.clamp(v, 0, 2);
+            }
+            if (this.debugDimLights) {
+                // Conservative defaults if not explicitly set
+                if (!mWhiten)
+                    this.whitenScale = 0.35;
+                if (!mAlpha)
+                    this.alphaScale = 0.75;
+            }
+            // (Removed optional cyan-band and blending debug toggles)
+        }
+        catch { }
+        this.build();
+        if (this.debugLogPalette) {
+            this.logPaletteRamp();
+        }
+    }
+    // Public: Set overall dust brightness (scales particle alpha)
+    setBrightnessScale(scale) {
+        const v = THREE.MathUtils.clamp(scale, 0, 3);
+        if (Math.abs(v - this.alphaScale) < 1e-6)
+            return;
+        this.alphaScale = v;
+        this.updatePaletteUniformsOnMaterials();
+    }
+    // Public: Set strength of white rim/core mixes
+    setWhitenScale(scale) {
+        const v = THREE.MathUtils.clamp(scale, 0, 3);
+        if (Math.abs(v - this.whitenScale) < 1e-6)
+            return;
+        this.whitenScale = v;
+        this.updatePaletteUniformsOnMaterials();
+    }
+    // Public: Simple 0..1 brightness control
+    // 0 => fully dim, 1 => current maximum
+    setBrightness(value01) {
+        const v = THREE.MathUtils.clamp(value01, 0, 1);
+        // Scale overall alpha directly
+        this.alphaScale = v;
+        // Tie white highlight strength to the same factor so we don’t wash out
+        this.whitenScale = v;
+        this.updatePaletteUniformsOnMaterials();
+    }
+    // (Removed setCoreCyanScale helper)
+    // Public API --------------------------------------------------------------
+    applyOptions(o) {
+        if (!o)
+            return;
+        const { palette, colorInner, colorMid, colorOuter, ...rest } = o;
+        Object.assign(this.opts, rest);
+        if (colorInner !== undefined)
+            this.opts.colorInner.set(colorInner);
+        if (colorMid !== undefined)
+            this.opts.colorMid.set(colorMid);
+        if (colorOuter !== undefined)
+            this.opts.colorOuter.set(colorOuter);
+        if (palette) {
+            this.applyPalette(palette);
+        }
+        else if (colorInner !== undefined ||
+            colorMid !== undefined ||
+            colorOuter !== undefined) {
+            this.applyPalette(this.buildPaletteFromLegacyColors());
+        }
+        else {
+            this.syncLegacyColorsFromPalette();
+        }
+    }
+    setMode(mode) {
+        const resolved = mode === 'sphere' ? 'disk' : mode;
+        if (resolved === this.dustMode)
+            return;
+        this.dustMode = resolved;
+        if (this.points)
+            this.build();
+    }
+    setSphereParameters(params) {
+        let changed = false;
+        if (params.jitter !== undefined) {
+            const next = Math.max(0, params.jitter);
+            if (Math.abs(next - this.sphereJitter) > 1e-5) {
+                this.sphereJitter = next;
+                changed = true;
+            }
+        }
+        if (changed && this.points)
+            this.build();
+    }
+    setDiskNormal(normal) {
+        const n = normal.clone().normalize();
+        // rotate local +Y to n
+        const from = new THREE.Vector3(0, 0, 1);
+        const q = new THREE.Quaternion().setFromUnitVectors(from, n);
+        this.group.quaternion.copy(q);
+    }
+    setViewportHeight(h) {
+        this.viewportHeight = Math.max(1, Math.floor(h));
+        const cohorts = ['disk', 'diskBokeh', 'halo', 'haloBokeh'];
+        for (const c of cohorts) {
+            const pts = this.points?.[c];
+            if (!pts)
+                continue;
+            const mat = pts.material;
+            if (mat?.uniforms?.['uViewportH'] !== undefined) {
+                mat.uniforms['uViewportH'].value = this.viewportHeight;
+                mat.needsUpdate = true;
+            }
+        }
+    }
+    buildPaletteFromLegacyColors() {
+        const legacyStops = [
+            { at: 0.0, color: this.opts.colorInner, intensity: 1.35 },
+            { at: 0.5, color: this.opts.colorMid, intensity: 1.0 },
+            { at: 1.0, color: this.opts.colorOuter, intensity: 0.9 },
+        ];
         return {
-            id,
-            name: names[i],
-            initialPosition: [0, 0, 0],
-            isSun: false,
-            color: colors[i % 2],
-            attributes: generateAttributes(dynamicCounts.attributes, i * 10),
-            preferences: generateAttributes(dynamicCounts.preferences, 0),
+            stops: legacyStops,
+            hueBiasScale: this.paletteHueBiasScale,
+            backgroundLift: this.paletteBackgroundLift,
+            coreIntensity: this.paletteCoreIntensity,
         };
-    }),
-];
-const attributesList = baseNodes.map((n) => Object.values(n.attributes));
-const { positions, weights } = computePCA3D(attributesList);
-const nodeData = baseNodes.map((node, i) => {
-    if (node.isSun)
-        return { ...node, initialPosition: [0, 0, 0] };
-    const [x, y, z] = positions[i];
-    return {
-        ...node,
-        initialPosition: [x * 5, y * 5, z * 5],
+    }
+    applyPalette(palette) {
+        const source = palette && palette.stops?.length
+            ? {
+                stops: palette.stops,
+                hueBiasScale: palette.hueBiasScale ??
+                    StellarDustField.DEFAULT_PALETTE.hueBiasScale,
+                backgroundLift: palette.backgroundLift ??
+                    StellarDustField.DEFAULT_PALETTE.backgroundLift,
+                coreIntensity: palette.coreIntensity ??
+                    StellarDustField.DEFAULT_PALETTE.coreIntensity,
+            }
+            : StellarDustField.DEFAULT_PALETTE;
+        const sorted = [...source.stops]
+            .map((stop) => ({
+            at: THREE.MathUtils.clamp(stop.at, 0, 1),
+            color: new THREE.Color(stop.color),
+            intensity: stop.intensity !== undefined ? stop.intensity : 1.0,
+        }))
+            .sort((a, b) => a.at - b.at);
+        if (sorted.length === 0) {
+            sorted.push({
+                at: 0,
+                color: new THREE.Color('#ffffff'),
+                intensity: 1.0,
+            });
+        }
+        if (sorted[0].at > 0) {
+            const first = sorted[0];
+            sorted.unshift({ ...first, at: 0 });
+        }
+        if (sorted[sorted.length - 1].at < 1) {
+            const last = sorted[sorted.length - 1];
+            sorted.push({ ...last, at: 1 });
+        }
+        this.paletteStops = sorted.slice(0, this.MAX_PALETTE_STOPS);
+        this.paletteHueBiasScale =
+            palette?.hueBiasScale ?? StellarDustField.DEFAULT_PALETTE.hueBiasScale;
+        this.paletteBackgroundLift =
+            palette?.backgroundLift ??
+                StellarDustField.DEFAULT_PALETTE.backgroundLift;
+        this.paletteCoreIntensity =
+            palette?.coreIntensity ?? StellarDustField.DEFAULT_PALETTE.coreIntensity;
+        this.refreshPaletteUniformData();
+        this.updatePaletteUniformsOnMaterials();
+        this.syncLegacyColorsFromPalette();
+        if (this.debugLogPalette) {
+            this.logPaletteRamp();
+        }
+    }
+    syncLegacyColorsFromPalette() {
+        if (!this.paletteStops.length)
+            return;
+        const first = this.paletteStops[0];
+        const middle = this.paletteStops[Math.floor(this.paletteStops.length / 2)];
+        const last = this.paletteStops[this.paletteStops.length - 1];
+        this.opts.colorInner.set(first.color);
+        this.opts.colorMid.set(middle.color);
+        this.opts.colorOuter.set(last.color);
+    }
+    updatePaletteUniformsOnMaterials() {
+        if (!this.points)
+            return;
+        const cohorts = ['disk', 'diskBokeh', 'halo', 'haloBokeh'];
+        for (const c of cohorts) {
+            const pts = this.points[c];
+            if (!pts)
+                continue;
+            const mat = pts.material;
+            const uniforms = mat?.uniforms;
+            if (!uniforms)
+                continue;
+            if (uniforms['uPaletteCount'] !== undefined) {
+                uniforms['uPaletteCount'].value = this.paletteUniformCount;
+            }
+            if (uniforms['uPaletteStops']?.value instanceof Float32Array) {
+                uniforms['uPaletteStops'].value.set(this.paletteUniformStops);
+            }
+            if (uniforms['uPaletteIntensities']?.value instanceof Float32Array) {
+                uniforms['uPaletteIntensities'].value.set(this.paletteUniformIntensities);
+            }
+            if (uniforms['uPaletteColors']) {
+                uniforms['uPaletteColors'].value = this.paletteUniformColors;
+            }
+            if (uniforms['uHueBiasScale'] !== undefined) {
+                uniforms['uHueBiasScale'].value = this.paletteHueBiasScale;
+            }
+            if (uniforms['uBackgroundLift'] !== undefined) {
+                const bg = this.debugDimLights
+                    ? this.paletteBackgroundLift * 0.25
+                    : this.paletteBackgroundLift;
+                uniforms['uBackgroundLift'].value = bg;
+            }
+            if (uniforms['uCoreIntensity'] !== undefined) {
+                const core = this.debugDimLights
+                    ? this.paletteCoreIntensity * 0.8
+                    : this.paletteCoreIntensity;
+                uniforms['uCoreIntensity'].value = core;
+            }
+            if (uniforms['uEdgeDebugMix'] !== undefined) {
+                uniforms['uEdgeDebugMix'].value = this.debugEdgeMix;
+            }
+            if (uniforms['uWhitenScale'] !== undefined) {
+                uniforms['uWhitenScale'].value = this.whitenScale;
+            }
+            if (uniforms['uAlphaScale'] !== undefined) {
+                uniforms['uAlphaScale'].value = this.alphaScale;
+            }
+            mat.needsUpdate = true;
+        }
+    }
+    samplePaletteAt(radialT) {
+        const clamped = THREE.MathUtils.clamp(radialT, 0, 1);
+        if (!this.paletteStops.length) {
+            return { color: new THREE.Color(1, 1, 1), intensity: 1 };
+        }
+        let prev = this.paletteStops[0];
+        if (clamped <= prev.at) {
+            return { color: prev.color.clone(), intensity: prev.intensity };
+        }
+        for (let i = 1; i < this.paletteStops.length; i++) {
+            const curr = this.paletteStops[i];
+            if (clamped <= curr.at + 1e-6) {
+                const span = Math.max(1e-5, curr.at - prev.at);
+                const t = (clamped - prev.at) / span;
+                const color = prev.color.clone().lerp(curr.color, t);
+                const intensity = THREE.MathUtils.lerp(prev.intensity, curr.intensity, t);
+                return { color, intensity };
+            }
+            prev = curr;
+        }
+        return {
+            color: prev.color.clone(),
+            intensity: prev.intensity,
+        };
+    }
+    colorToHexString(color) {
+        const safe = new THREE.Color(THREE.MathUtils.clamp(color.r, 0, 1), THREE.MathUtils.clamp(color.g, 0, 1), THREE.MathUtils.clamp(color.b, 0, 1));
+        return `#${safe.getHexString().toUpperCase()}`;
+    }
+    logPaletteRamp(samples = 8) {
+        const step = Math.max(1, samples);
+        const rows = [];
+        for (let i = 0; i < step; i++) {
+            const t = step === 1 ? 0 : i / (step - 1);
+            const { color, intensity } = this.samplePaletteAt(t);
+            rows.push({
+                radial: parseFloat(t.toFixed(2)),
+                color: this.colorToHexString(color),
+                intensity: parseFloat(intensity.toFixed(2)),
+            });
+        }
+        // eslint-disable-next-line no-console
+        console.table(rows);
+    }
+    logDiskBandStats(kind, total, stats) {
+        if (!total)
+            return;
+        const rows = stats.map((band) => {
+            const share = band.count / total;
+            const avgT = band.count ? band.sumT / band.count : 0;
+            const alphaAvg = band.count ? band.alphaSum / band.count : 0;
+            const voidRate = band.count ? band.voidHits / band.count : 0;
+            const innerAvg = band.count ? band.innerSum / band.count : 0;
+            const outerAvg = band.count ? band.outerSum / band.count : 0;
+            const minT = band.count
+                ? parseFloat(band.minT.toFixed(3))
+                : '–';
+            const maxT = band.count
+                ? parseFloat(band.maxT.toFixed(3))
+                : '–';
+            const radiusMin = band.count
+                ? parseFloat(band.radiusMin.toFixed(3))
+                : '–';
+            const radiusMax = band.count
+                ? parseFloat(band.radiusMax.toFixed(3))
+                : '–';
+            const innerAvgFmt = band.count
+                ? parseFloat(innerAvg.toFixed(2))
+                : '–';
+            const outerAvgFmt = band.count
+                ? parseFloat(outerAvg.toFixed(2))
+                : '–';
+            const innerMin = band.count
+                ? parseFloat(band.innerMin.toFixed(2))
+                : '–';
+            const innerMax = band.count
+                ? parseFloat(band.innerMax.toFixed(2))
+                : '–';
+            const outerMin = band.count
+                ? parseFloat(band.outerMin.toFixed(2))
+                : '–';
+            const outerMax = band.count
+                ? parseFloat(band.outerMax.toFixed(2))
+                : '–';
+            return {
+                cohort: kind,
+                band: band.id,
+                share: parseFloat(share.toFixed(3)),
+                avgT: parseFloat(avgT.toFixed(3)),
+                minT,
+                maxT,
+                radiusMin,
+                radiusMax,
+                innerAvg: innerAvgFmt,
+                outerAvg: outerAvgFmt,
+                innerMin,
+                innerMax,
+                outerMin,
+                outerMax,
+                alphaAvg: parseFloat(alphaAvg.toFixed(3)),
+                voidRate: parseFloat(voidRate.toFixed(3)),
+                count: band.count,
+            };
+        });
+        // eslint-disable-next-line no-console
+        console.table(rows);
+    }
+    refreshPaletteUniformData() {
+        if (!this.paletteUniformColors.length) {
+            this.paletteUniformColors = Array.from({ length: this.MAX_PALETTE_STOPS }, () => new THREE.Vector3());
+        }
+        if (this.paletteUniformStops.length !== this.MAX_PALETTE_STOPS) {
+            this.paletteUniformStops = new Float32Array(this.MAX_PALETTE_STOPS);
+        }
+        if (this.paletteUniformIntensities.length !== this.MAX_PALETTE_STOPS) {
+            this.paletteUniformIntensities = new Float32Array(this.MAX_PALETTE_STOPS);
+        }
+        const count = Math.min(this.MAX_PALETTE_STOPS, this.paletteStops.length);
+        for (let i = 0; i < count; i++) {
+            const stop = this.paletteStops[i];
+            const colorVec = this.paletteUniformColors[i] ?? new THREE.Vector3(stop.color.r, stop.color.g, stop.color.b);
+            colorVec.set(stop.color.r, stop.color.g, stop.color.b);
+            this.paletteUniformColors[i] = colorVec;
+            this.paletteUniformStops[i] = stop.at;
+            this.paletteUniformIntensities[i] = stop.intensity;
+        }
+        for (let i = count; i < this.MAX_PALETTE_STOPS; i++) {
+            const fallbackColor = count > 0 ? this.paletteStops[count - 1].color : new THREE.Color(0, 0, 0);
+            const colorVec = this.paletteUniformColors[i] ??
+                new THREE.Vector3(fallbackColor.r, fallbackColor.g, fallbackColor.b);
+            colorVec.set(fallbackColor.r, fallbackColor.g, fallbackColor.b);
+            this.paletteUniformColors[i] = colorVec;
+            this.paletteUniformStops[i] = 1.0;
+            this.paletteUniformIntensities[i] = 1.0;
+        }
+        this.paletteUniformCount = count;
+    }
+    update(dt, center) {
+        this.time += Math.max(0, dt);
+        this.group.position.copy(center);
+        // Slow global precession to avoid a static read (rotate around local Y)
+        this.group.rotateZ(dt * 0.02);
+        const cohorts = ['disk', 'diskBokeh', 'halo', 'haloBokeh'];
+        for (const c of cohorts) {
+            const pts = this.points?.[c];
+            if (!pts)
+                continue;
+            const mat = pts.material;
+            if (mat?.uniforms?.['uTime'] !== undefined) {
+                mat.uniforms['uTime'].value = this.time;
+            }
+            if (mat?.uniforms?.['uMode'] !== undefined) {
+                mat.uniforms['uMode'].value = this.dustMode === 'sphere' ? 1 : 0;
+            }
+            if (mat?.uniforms?.['uSphereJitter'] !== undefined) {
+                mat.uniforms['uSphereJitter'].value = this.sphereJitter;
+            }
+            if (mat?.uniforms?.['uEdgeDebugMix'] !== undefined) {
+                mat.uniforms['uEdgeDebugMix'].value = this.debugEdgeMix;
+            }
+            // Only drive attraction uniforms when the feature flag is enabled
+            if (this.useAttract) {
+                this.syncAttractorUniforms(mat);
+                if (mat?.uniforms?.['uUseAttract'] !== undefined) {
+                    mat.uniforms['uUseAttract'].value = 1.0;
+                }
+            }
+            else if (mat?.uniforms?.['uUseAttract'] !== undefined) {
+                mat.uniforms['uUseAttract'].value = 0.0;
+            }
+        }
+        // Lightweight contact sampling for logs (once/sec)
+        if (this.debugDustTouch)
+            this.sampleAndLogContacts();
+    }
+    dispose() {
+        if (this.points) {
+            const cohorts = ['disk', 'diskBokeh', 'halo', 'haloBokeh'];
+            for (const c of cohorts) {
+                const pts = this.points[c];
+                if (!pts)
+                    continue;
+                this.group.remove(pts);
+                pts.geometry.dispose();
+                pts.material.dispose();
+            }
+        }
+        this.scene.remove(this.group);
+        this.points = null;
+    }
+    // --- Attractors API -----------------------------------------------------
+    /**
+     * Provide world-space node centers and radii; internally converted to
+     * dust-local coordinates and pushed to shader uniforms.
+     * @param usedCount If set, only the first usedCount entries of attractors are read (allows reusing a buffer).
+     */
+    setAttractorsWorld(attractors, usedCount) {
+        // Store world-space list; conversion to local happens inside update()
+        const len = usedCount !== undefined ? usedCount : attractors.length;
+        const n = Math.min(this.MAX_ATTRACTORS, len);
+        if (this.attractorWorldPos.length !== this.MAX_ATTRACTORS) {
+            this.attractorWorldPos = Array.from({ length: this.MAX_ATTRACTORS }, () => new THREE.Vector3());
+            this.attractorWorldRad = new Array(this.MAX_ATTRACTORS).fill(0);
+            this.attractorLocalPos = Array.from({ length: this.MAX_ATTRACTORS }, () => new THREE.Vector3());
+            this.attractorRadius = new Array(this.MAX_ATTRACTORS).fill(0);
+        }
+        for (let i = 0; i < n; i++) {
+            this.attractorWorldPos[i].copy(attractors[i].position);
+            this.attractorWorldRad[i] = attractors[i].radius;
+        }
+        for (let i = n; i < this.MAX_ATTRACTORS; i++) {
+            this.attractorWorldPos[i].set(9999, 9999, 9999);
+            this.attractorWorldRad[i] = 0;
+        }
+    }
+    // Phase 0: small helper to toggle attraction at runtime (optional)
+    setAttractEnabled(enabled) {
+        this.useAttract = !!enabled;
+    }
+    // Build ------------------------------------------------------------------
+    build() {
+        // Clean previous
+        if (this.points)
+            this.dispose();
+        this.scene.add(this.group);
+        const totalMid = Math.max(0, this.opts.countMidFar || 0);
+        const totalBokeh = Math.max(0, this.opts.countBokeh || 0);
+        this.points = {};
+        if (this.dustMode === 'sphere') {
+            console.warn('[StellarDustField] sphere mode disabled in 2D view; falling back to disk.');
+            this.dustMode = 'disk';
+        }
+        const disk = this.makeCohort('disk', totalMid);
+        const diskBokeh = this.makeCohort('diskBokeh', totalBokeh);
+        if (disk)
+            this.points.disk = disk;
+        if (diskBokeh)
+            this.points.diskBokeh = diskBokeh;
+    }
+    makeCohort(kind, count) {
+        const isBokeh = kind === 'diskBokeh' || kind === 'haloBokeh';
+        const isHalo = kind === 'halo' || kind === 'haloBokeh';
+        if (count <= 0)
+            return null;
+        const g = new THREE.BufferGeometry();
+        // We compute motion entirely from attributes; base positions are not used
+        const base = new Float32Array(count * 3); // kept at 0s
+        const aRadius = new Float32Array(count);
+        const aTheta0 = new Float32Array(count);
+        const aOmega = new Float32Array(count);
+        const aLayer = new Float32Array(count);
+        const aSize = new Float32Array(count);
+        const aIntensity = new Float32Array(count);
+        const aHue = new Float32Array(count);
+        const aSeed = new Float32Array(count);
+        const aAnchor = new Float32Array(count * 3);
+        const aU = new Float32Array(count * 3); // per-particle plane U (for halo or disk default)
+        const aV = new Float32Array(count * 3); // per-particle plane V
+        const aIsHalo = new Float32Array(count);
+        const aBandIndex = new Float32Array(count); // which band this particle belongs to
+        const aEdgeParams = new Float32Array(count * 4);
+        const inner = this.opts.innerRadius;
+        const outer = this.opts.outerRadius;
+        const halfThickness = Math.max(0, this.opts.thickness);
+        const twoPi = Math.PI * 2;
+        const diskBand = Math.max(outer - inner, 1e-5);
+        const haloOuter = outer * this.haloRadiusMultiplier;
+        const haloBand = Math.max(haloOuter - inner, 1e-5);
+        const wrapAngle = (theta) => {
+            const twopi = twoPi;
+            theta %= twopi;
+            return theta < 0 ? theta + twopi : theta;
+        };
+        const diskBands = [
+            {
+                id: 'core-void',
+                start: 0,
+                end: 0.07,
+                z: 0.52,
+                curve: 3.1,
+                weight: 0.18,
+                colorIntensity: 0.4,
+                bias: 0.05,
+                rim: {
+                    thicknessScale: 0.55,
+                    thicknessMin: 0.08,
+                    sigma: 0.01,
+                    inner: {
+                        amplitude: 0.25,
+                        frequency: 2.6,
+                        octaves: 3,
+                        lacunarity: 2.2,
+                        gain: 0.55,
+                        warpAmplitude: 0.3,
+                        warpFrequency: 0.9,
+                    },
+                    outer: {
+                        amplitude: 0.32,
+                        frequency: 3.0,
+                        octaves: 3,
+                        lacunarity: 2.1,
+                        gain: 0.58,
+                        warpAmplitude: 0.28,
+                        warpFrequency: 1.1,
+                    },
+                },
+                radialPockets: [
+                    { center: 0.06, width: 0.02, depth: 0.8, feather: 0.6 },
+                ],
+                angularPockets: [
+                    { angle: Math.PI * 0.55, width: 0.38, depth: 0.4, feather: 0.85 },
+                ],
+                alphaFloor: 0.04,
+            },
+            {
+                id: 'inner-rim',
+                start: 0.05,
+                end: 0.28,
+                z: 0.28,
+                curve: 0.9,
+                weight: 1.6,
+                colorIntensity: 1.32,
+                bias: 0.22,
+                rim: {
+                    thicknessScale: 0.82,
+                    thicknessMin: 0.18,
+                    sigma: 0.018,
+                    inner: {
+                        amplitude: 0.85,
+                        frequency: 3.6,
+                        octaves: 4,
+                        lacunarity: 2.05,
+                        gain: 0.52,
+                        warpAmplitude: 0.48,
+                        warpFrequency: 1.25,
+                    },
+                    outer: {
+                        amplitude: 1.15,
+                        frequency: 3.9,
+                        octaves: 4,
+                        lacunarity: 2.2,
+                        gain: 0.55,
+                        warpAmplitude: 0.52,
+                        warpFrequency: 1.42,
+                    },
+                },
+                radialPockets: [
+                    { center: 0.16, width: 0.026, depth: 0.42, feather: 0.9 },
+                ],
+                angularPockets: [
+                    { angle: -Math.PI * 0.12, width: 0.34, depth: 0.34, feather: 0.9 },
+                    { angle: Math.PI * 0.62, width: 0.28, depth: 0.28, feather: 1.0 },
+                ],
+                alphaNoise: 0.1,
+                alphaFloor: 0.32,
+            },
+            {
+                id: 'mid-shelf',
+                start: 0.24,
+                end: 0.6,
+                z: 0.02,
+                curve: 1.05,
+                weight: 1.42,
+                colorIntensity: 1.78,
+                bias: 0.08,
+                rim: {
+                    thicknessScale: 0.95,
+                    thicknessMin: 0.16,
+                    sigma: 0.024,
+                    inner: {
+                        amplitude: 0.95,
+                        frequency: 2.8,
+                        octaves: 4,
+                        lacunarity: 2.18,
+                        gain: 0.6,
+                        warpAmplitude: 0.54,
+                        warpFrequency: 1.05,
+                    },
+                    outer: {
+                        amplitude: 1.4,
+                        frequency: 3.4,
+                        octaves: 4,
+                        lacunarity: 2.25,
+                        gain: 0.58,
+                        warpAmplitude: 0.62,
+                        warpFrequency: 1.32,
+                    },
+                },
+                radialPockets: [
+                    { center: 0.42, width: 0.03, depth: 0.28, feather: 1.0 },
+                    { center: 0.55, width: 0.04, depth: 0.22, feather: 1.1 },
+                ],
+                angularPockets: [
+                    { angle: Math.PI * 1.18, width: 0.38, depth: 0.36, feather: 0.8 },
+                    { angle: Math.PI * 0.28, width: 0.3, depth: 0.32, feather: 1.0 },
+                    { angle: -Math.PI * 0.2, width: 0.26, depth: 0.36, feather: 1.1 },
+                ],
+                alphaNoise: 0.18,
+                alphaFloor: 0.18,
+            },
+            {
+                id: 'outer-rim',
+                start: 0.56,
+                end: 0.9,
+                z: -0.18,
+                curve: 1.2,
+                weight: 1.05,
+                colorIntensity: 1.95,
+                bias: 0.05,
+                rim: {
+                    thicknessScale: 1.08,
+                    thicknessMin: 0.18,
+                    sigma: 0.026,
+                    inner: {
+                        amplitude: 1.05,
+                        frequency: 2.6,
+                        octaves: 4,
+                        lacunarity: 2.15,
+                        gain: 0.62,
+                        warpAmplitude: 0.68,
+                        warpFrequency: 1.08,
+                    },
+                    outer: {
+                        amplitude: 1.55,
+                        frequency: 3.1,
+                        octaves: 4,
+                        lacunarity: 2.32,
+                        gain: 0.6,
+                        warpAmplitude: 0.74,
+                        warpFrequency: 1.24,
+                    },
+                },
+                radialPockets: [
+                    { center: 0.7, width: 0.045, depth: 0.35, feather: 0.95 },
+                    { center: 0.82, width: 0.05, depth: 0.28, feather: 1.05 },
+                ],
+                angularPockets: [
+                    { angle: Math.PI * 0.64, width: 0.4, depth: 0.34, feather: 0.95 },
+                    { angle: -Math.PI * 0.52, width: 0.48, depth: 0.28, feather: 1.15 },
+                ],
+                alphaNoise: 0.2,
+                alphaFloor: 0.14,
+            },
+            {
+                id: 'outer-halo',
+                start: 0.82,
+                end: 1.0,
+                z: -0.62,
+                curve: 1.65,
+                weight: 0.75,
+                colorIntensity: 2.92,
+                angularPockets: [
+                    { angle: Math.PI * 0.58, width: 0.45, depth: 0.36, feather: 1.05 },
+                    { angle: -Math.PI * 0.05, width: 0.32, depth: 0.32, feather: 1.15 },
+                    { angle: Math.PI * 1.1, width: 0.88, depth: 0.26, feather: 1.2 },
+                ],
+                radialPockets: [
+                    { center: 0.88, width: 0.05, depth: 0.38, feather: 0.8 },
+                    { center: 0.96, width: 0.04, depth: 0.35, feather: 0.9 },
+                ],
+                alphaNoise: 0.22,
+                rim: {
+                    thicknessScale: 1.15,
+                    thicknessMin: 0.12,
+                    sigma: 0.032,
+                    inner: {
+                        amplitude: 1.2,
+                        frequency: 2.4,
+                        octaves: 4,
+                        lacunarity: 2.1,
+                        gain: 0.6,
+                        warpAmplitude: 0.72,
+                        warpFrequency: 0.95,
+                    },
+                    outer: {
+                        amplitude: 1.8,
+                        frequency: 2.9,
+                        octaves: 4,
+                        lacunarity: 2.28,
+                        gain: 0.62,
+                        warpAmplitude: 0.78,
+                        warpFrequency: 1.12,
+                    },
+                },
+            },
+        ];
+        const diskWeightTotal = diskBands.reduce((sum, band) => sum + band.weight, 0);
+        const diskWeightSafe = diskWeightTotal > 0 ? diskWeightTotal : diskBands.length;
+        const defaultRimResolution = 720;
+        const bandProfiles = diskBands.map((band, bandIndex) => {
+            const baseSpan = Math.max(band.end - band.start, 1e-4);
+            const rim = band.rim ??
+                {
+                    thicknessScale: 1.0,
+                    thicknessMin: 0.2,
+                    sigma: baseSpan * 0.2,
+                    inner: {
+                        amplitude: 0.65,
+                        frequency: 3.2,
+                        octaves: 4,
+                        lacunarity: 2.05,
+                        gain: 0.58,
+                        warpAmplitude: 0.45,
+                        warpFrequency: 1.05,
+                    },
+                    outer: {
+                        amplitude: 0.95,
+                        frequency: 3.6,
+                        octaves: 4,
+                        lacunarity: 2.18,
+                        gain: 0.58,
+                        warpAmplitude: 0.5,
+                        warpFrequency: 1.2,
+                    },
+                    resolution: defaultRimResolution,
+                };
+            const resolution = Math.max(64, Math.floor(rim.resolution ?? defaultRimResolution));
+            const innerSamples = new Float32Array(resolution);
+            const outerSamples = new Float32Array(resolution);
+            const midSamples = new Float32Array(resolution);
+            const halfSamples = new Float32Array(resolution);
+            const baseCenter = (band.start + band.end) * 0.5;
+            const baseHalfThickness = Math.max(baseSpan * 0.5, 1e-4) *
+                THREE.MathUtils.clamp(rim.thicknessScale ?? 1, 0.2, 3.0);
+            const minThickness = Math.max(baseSpan * THREE.MathUtils.clamp(rim.thicknessMin ?? 0.18, 0.02, 0.9), 1e-4);
+            const sigma = rim.sigma !== undefined
+                ? Math.max(rim.sigma, 1e-4)
+                : Math.max(baseSpan * 0.18, 0.01);
+            let minInner = Number.POSITIVE_INFINITY;
+            let maxOuter = Number.NEGATIVE_INFINITY;
+            for (let s = 0; s < resolution; s++) {
+                const theta = (s / resolution) * twoPi;
+                const innerNoise = this.samplePeriodicFbm(theta, rim.inner, bandIndex, 137 + bandIndex * 19);
+                const outerNoise = this.samplePeriodicFbm(theta, rim.outer, bandIndex, 211 + bandIndex * 23);
+                let inner = baseCenter -
+                    baseHalfThickness +
+                    innerNoise * baseHalfThickness;
+                let outer = baseCenter +
+                    baseHalfThickness +
+                    outerNoise * baseHalfThickness;
+                if (!isFinite(inner))
+                    inner = baseCenter - baseHalfThickness;
+                if (!isFinite(outer))
+                    outer = baseCenter + baseHalfThickness;
+                let thickness = outer - inner;
+                if (thickness < minThickness) {
+                    const correction = (minThickness - thickness) * 0.5;
+                    inner -= correction;
+                    outer += correction;
+                    thickness = outer - inner;
+                }
+                const clampMin = Math.max(0, band.start - baseSpan * 0.4);
+                const clampMax = Math.min(1, band.end + baseSpan * 0.6);
+                inner = THREE.MathUtils.clamp(inner, clampMin, clampMax);
+                outer = THREE.MathUtils.clamp(outer, clampMin, clampMax);
+                if (outer <= inner) {
+                    outer = inner + Math.max(minThickness, 1e-4);
+                }
+                innerSamples[s] = inner;
+                outerSamples[s] = outer;
+                const mid = (inner + outer) * 0.5;
+                const half = Math.max((outer - inner) * 0.5, minThickness * 0.5);
+                midSamples[s] = mid;
+                halfSamples[s] = half;
+                minInner = Math.min(minInner, inner);
+                maxOuter = Math.max(maxOuter, outer);
+            }
+            return {
+                inner: innerSamples,
+                outer: outerSamples,
+                mid: midSamples,
+                halfThickness: halfSamples,
+                sigma,
+                resolution,
+                step: twoPi / resolution,
+                minInner,
+                maxOuter,
+            };
+        });
+        let globalMinInnerRatio = Number.POSITIVE_INFINITY;
+        let globalMaxOuterRatio = Number.NEGATIVE_INFINITY;
+        for (const profile of bandProfiles) {
+            if (!profile)
+                continue;
+            if (isFinite(profile.minInner)) {
+                globalMinInnerRatio = Math.min(globalMinInnerRatio, profile.minInner);
+            }
+            if (isFinite(profile.maxOuter)) {
+                globalMaxOuterRatio = Math.max(globalMaxOuterRatio, profile.maxOuter);
+            }
+        }
+        if (!isFinite(globalMinInnerRatio)) {
+            globalMinInnerRatio = diskBands.length ? diskBands[0].start : 0;
+        }
+        if (!isFinite(globalMaxOuterRatio) || globalMaxOuterRatio <= 0) {
+            globalMaxOuterRatio = diskBands.length ? diskBands[diskBands.length - 1].end : 1;
+        }
+        const diskInnerEnvelope = inner + diskBand * globalMinInnerRatio;
+        const diskOuterEnvelope = inner + diskBand * globalMaxOuterRatio;
+        const selectDiskBandIndex = (idx) => {
+            let pick = rand(idx, 0) * diskWeightSafe;
+            for (let b = 0; b < diskBands.length; b++) {
+                pick -= diskBands[b].weight;
+                if (pick <= 0)
+                    return b;
+            }
+            return diskBands.length - 1;
+        };
+        const sampleGaussian = (idxSeed, salt) => {
+            const u1 = Math.max(1e-6, rand(idxSeed, 700 + salt));
+            const u2 = Math.max(1e-6, rand(idxSeed, 701 + salt));
+            const mag = Math.sqrt(-2 * Math.log(u1));
+            const angle = twoPi * u2;
+            return mag * Math.cos(angle);
+        };
+        const lerpProfile = (arr, samplePos, resolution) => {
+            if (!resolution)
+                return arr[0] ?? 0;
+            const wrapped = ((samplePos % resolution) + resolution) % resolution;
+            const idx0 = Math.floor(wrapped);
+            const idx1 = (idx0 + 1) % resolution;
+            const frac = wrapped - idx0;
+            const v0 = arr[idx0] ?? arr[0] ?? 0;
+            const v1 = arr[idx1] ?? v0;
+            return v0 + (v1 - v0) * frac;
+        };
+        const fetchRimSample = (bandIndex, theta) => {
+            const profile = bandProfiles[bandIndex];
+            if (!profile) {
+                const band = diskBands[bandIndex];
+                const start = band?.start ?? 0;
+                const end = band?.end ?? 1;
+                const mid = (start + end) * 0.5;
+                const half = Math.max((end - start) * 0.5, 1e-4);
+                return {
+                    innerRatio: mid - half,
+                    outerRatio: mid + half,
+                    midRatio: mid,
+                    halfRatio: half,
+                    sigmaRatio: Math.max(half * 0.35, 1e-4),
+                };
+            }
+            const norm = wrapAngle(theta) / twoPi;
+            const samplePos = norm * profile.resolution;
+            const innerRatio = lerpProfile(profile.inner, samplePos, profile.resolution);
+            const outerRatio = lerpProfile(profile.outer, samplePos, profile.resolution);
+            const midRatio = lerpProfile(profile.mid, samplePos, profile.resolution);
+            const halfRatio = lerpProfile(profile.halfThickness, samplePos, profile.resolution);
+            return {
+                innerRatio,
+                outerRatio,
+                midRatio,
+                halfRatio,
+                sigmaRatio: profile.sigma,
+            };
+        };
+        const resolveBandShell = (bandIndex, theta) => {
+            const rim = fetchRimSample(bandIndex, theta);
+            const sigmaRadius = Math.max(rim.sigmaRatio * diskBand, 1e-4);
+            const halfRadius = Math.max(rim.halfRatio * diskBand, sigmaRadius * 1.6);
+            const innerRadius = inner + diskBand * rim.innerRatio;
+            const outerRadius = inner + diskBand * rim.outerRatio;
+            const midRadius = inner + diskBand * rim.midRatio;
+            const span = Math.max(outerRadius - innerRadius, 1e-4);
+            const innerSoft = Math.max(sigmaRadius * 1.65, span * 0.48, diskBand * 0.022);
+            const outerSoft = Math.max(sigmaRadius * 1.5, span * 0.44, diskBand * 0.028);
+            const innerBleed = Math.max(innerSoft * 1.35, diskBand * 0.05);
+            const outerBleed = Math.max(outerSoft * 1.35, diskBand * 0.055);
+            const supportInner = Math.max(inner + diskBand * 0.0005, innerRadius - innerBleed);
+            const supportOuter = Math.min(haloOuter * 1.08, outerRadius + outerBleed);
+            return {
+                sigmaRadius,
+                halfRadius,
+                innerRadius,
+                outerRadius,
+                midRadius,
+                innerSoft,
+                outerSoft,
+                supportInner,
+                supportOuter,
+            };
+        };
+        const applySpiralArms = (baseTheta, radialTForArm, idxSeed, isHaloParticle) => {
+            let theta = baseTheta;
+            if (!isHaloParticle) {
+                if (this.armCount > 0 && rand(idxSeed, 23) < this.armPopulation) {
+                    const armIdx = Math.floor(rand(idxSeed, 24) * this.armCount);
+                    const armBase = (armIdx / this.armCount) * twoPi;
+                    const twist = radialTForArm * this.armTwist;
+                    const jitter = (rand(idxSeed, 25) - 0.5) * this.armSpread;
+                    const armTheta = armBase + twist + jitter;
+                    theta = wrapAngle(THREE.MathUtils.lerp(theta, armTheta, 0.65));
+                }
+            }
+            else {
+                if (this.armCount > 0 && rand(idxSeed, 26) < this.haloArmPopulation) {
+                    const armIdx = Math.floor(rand(idxSeed, 27) * this.armCount);
+                    const haloTwist = THREE.MathUtils.clamp(radialTForArm, 0, 1) * this.haloArmTwist;
+                    const jitter = (rand(idxSeed, 28) - 0.5) * this.haloArmSpread;
+                    const armTheta = (armIdx / this.armCount) * twoPi + haloTwist + jitter;
+                    theta = wrapAngle(THREE.MathUtils.lerp(theta, armTheta, 0.55));
+                }
+            }
+            return theta;
+        };
+        const goldenAngle = Math.PI * (3 - Math.sqrt(5));
+        const kindSalt = kind === 'disk'
+            ? 11
+            : kind === 'diskBokeh'
+                ? 37
+                : kind === 'halo'
+                    ? 73
+                    : 109;
+        const rand = (idx, salt = 0) => this.hashFloat(idx + 1, kindSalt + salt);
+        const evaluateRadialMask = (ratio, band) => {
+            if (!band.radialPockets?.length)
+                return 1.0;
+            let mask = 1.0;
+            for (let p = 0; p < band.radialPockets.length; p++) {
+                const pocket = band.radialPockets[p];
+                const width = Math.max(1e-4, pocket.width);
+                const center = THREE.MathUtils.clamp(pocket.center, band.start + width * 0.35, band.end - width * 0.35);
+                const dist = Math.abs(ratio - center) / (width * 1.1);
+                const feather = pocket.feather ?? 1.0;
+                const falloff = Math.exp(-Math.pow(dist, feather * 1.2) * 2.4);
+                const depth = THREE.MathUtils.clamp(pocket.depth, 0, 1);
+                mask = Math.min(mask, 1 - falloff * depth);
+            }
+            return THREE.MathUtils.clamp(mask, 0.05, 1.0);
+        };
+        const shortestAngularDistance = (a, b) => {
+            let diff = a - b;
+            diff = ((diff + Math.PI) % (Math.PI * 2)) - Math.PI;
+            return Math.abs(diff);
+        };
+        const applyAngularPockets = (theta, radialT, band, idxSeed) => {
+            if (!band.angularPockets?.length)
+                return 1.0;
+            let alpha = 1.0;
+            const bandSpan = Math.max(band.end - band.start, 1e-4);
+            for (let p = 0; p < band.angularPockets.length; p++) {
+                const pocket = band.angularPockets[p];
+                const width = Math.max(1e-4, pocket.width);
+                const feather = pocket.feather ?? 1.0;
+                const depth = THREE.MathUtils.clamp(pocket.depth, 0, 1);
+                const swirl = (radialT - band.start) / bandSpan +
+                    (rand(idxSeed, 500 + p) - 0.5) * 0.2;
+                const offset = swirl * 0.9;
+                const target = pocket.angle + offset;
+                const dist = shortestAngularDistance(theta, target);
+                if (dist > width)
+                    continue;
+                const norm = dist / width;
+                const falloff = 1 - Math.pow(norm, feather * 1.25);
+                const noise = (rand(idxSeed, 520 + p) - 0.5) * 0.12;
+                const influence = THREE.MathUtils.clamp(falloff + noise, 0, 1);
+                alpha = Math.min(alpha, 1 - influence * depth);
+            }
+            return THREE.MathUtils.clamp(alpha, 0, 1);
+        };
+        const sampleDiskLayer = (idx, bandIndex, radialT) => {
+            if (halfThickness <= 1e-5)
+                return 0;
+            const clampedIndex = THREE.MathUtils.clamp(bandIndex, 0, diskBands.length - 1);
+            const band = diskBands[clampedIndex];
+            const baseLayer = THREE.MathUtils.clamp(band.z, -1, 1) * halfThickness;
+            const jitter = (rand(idx, 2) - 0.5) * halfThickness * 0.35 * (0.6 + radialT * 0.8);
+            return THREE.MathUtils.clamp(baseLayer + jitter, -halfThickness, halfThickness);
+        };
+        const haloInnerBase = Math.max(inner + diskBand * 0.55, diskOuterEnvelope - diskBand * 0.08);
+        const haloOuterBase = haloOuter;
+        const haloWidth = Math.max(haloOuterBase - haloInnerBase, 1e-4);
+        const haloInnerSoft = Math.max(haloWidth * 0.28, diskBand * 0.05);
+        const haloOuterSoft = Math.max(haloWidth * 0.36, diskBand * 0.08);
+        const haloSupportInner = Math.max(inner + diskBand * 0.35, haloInnerBase - haloInnerSoft * 1.35);
+        const haloSupportOuter = Math.min(haloOuter * 1.35, haloOuterBase + haloOuterSoft * 1.35);
+        const haloSpan = Math.max(haloOuterBase - haloInnerBase, 1e-5);
+        const sampleHaloRadius = (idx) => {
+            const roll = rand(idx, 3);
+            let radius;
+            if (roll < 0.4) {
+                const sub = Math.pow(rand(idx, 4), 0.82);
+                radius = THREE.MathUtils.lerp(haloSupportInner, haloInnerBase + haloInnerSoft * 1.05, sub);
+            }
+            else if (roll < 0.88) {
+                const sub = Math.pow(rand(idx, 5), 1.18);
+                radius = THREE.MathUtils.lerp(haloInnerBase, haloOuterBase, sub);
+            }
+            else {
+                const sub = Math.pow(rand(idx, 6), 0.58);
+                radius = THREE.MathUtils.lerp(haloOuterBase, haloSupportOuter, sub);
+            }
+            const radialT = THREE.MathUtils.clamp((radius - haloInnerBase) / haloSpan, 0, 1);
+            return { radius: THREE.MathUtils.clamp(radius, haloSupportInner, haloSupportOuter), radialT };
+        };
+        const anchorVec = new THREE.Vector3();
+        const dirVec = new THREE.Vector3();
+        const axisVec = new THREE.Vector3();
+        const fallbackVec = new THREE.Vector3();
+        const uVec = new THREE.Vector3();
+        const vVec = new THREE.Vector3();
+        const tmpVec = new THREE.Vector3();
+        const tmpVec2 = new THREE.Vector3();
+        const sphereMode = this.dustMode === 'sphere';
+        const collectBandStats = this.debugLogBands && kind === 'disk';
+        const bandStats = collectBandStats
+            ? diskBands.map((band) => ({
+                id: band.id,
+                count: 0,
+                minT: Number.POSITIVE_INFINITY,
+                maxT: Number.NEGATIVE_INFINITY,
+                sumT: 0,
+                alphaSum: 0,
+                voidHits: 0,
+                innerSum: 0,
+                outerSum: 0,
+                radiusMin: Number.POSITIVE_INFINITY,
+                radiusMax: Number.NEGATIVE_INFINITY,
+                innerMin: Number.POSITIVE_INFINITY,
+                innerMax: Number.NEGATIVE_INFINITY,
+                outerMin: Number.POSITIVE_INFINITY,
+                outerMax: Number.NEGATIVE_INFINITY,
+            }))
+            : null;
+        for (let i = 0; i < count; i++) {
+            if (sphereMode) {
+                const clampedInner = Math.max(0, inner);
+                const safeOuter = Math.max(clampedInner + 1e-3, outer);
+                const span = Math.max(safeOuter - clampedInner, 1e-5);
+                const coreOffset = Math.max(span * 0.015, 0.01);
+                const startRadius = Math.min(clampedInner + coreOffset, safeOuter);
+                const startC = Math.pow(startRadius, 3);
+                const endRadius = clampedInner + span * 0.5; // trim outer population to ~50% of span
+                const endC = Math.pow(Math.min(endRadius, safeOuter), 3);
+                const radius = Math.cbrt(startC + rand(i, 7) * Math.max(endC - startC, 1e-6));
+                const radialT = THREE.MathUtils.clamp((radius - inner) / Math.max(outer - inner, 1e-5), 0, 1);
+                const v = (i + 0.5) / Math.max(1, count);
+                const phiBase = Math.acos(1 - 2 * v);
+                const phiJitter = (rand(i, 8) - 0.5) * 0.12;
+                const thetaBase = wrapAngle(i * goldenAngle);
+                const thetaJitter = (rand(i, 9) - 0.5) * 0.25;
+                const lon = wrapAngle(thetaBase + thetaJitter);
+                const phi = THREE.MathUtils.clamp(phiBase + phiJitter, 0, Math.PI);
+                dirVec.set(Math.sin(phi) * Math.cos(lon), Math.cos(phi), Math.sin(phi) * Math.sin(lon));
+                anchorVec.copy(dirVec).multiplyScalar(radius);
+                axisVec.copy(anchorVec);
+                if (axisVec.lengthSq() < 1e-8)
+                    axisVec.set(0, 1, 0);
+                axisVec.normalize();
+                fallbackVec.set(0, 1, 0);
+                if (Math.abs(axisVec.dot(fallbackVec)) > 0.9)
+                    fallbackVec.set(1, 0, 0);
+                uVec.crossVectors(axisVec, fallbackVec).normalize();
+                if (!isFinite(uVec.x) || !isFinite(uVec.y) || !isFinite(uVec.z)) {
+                    uVec.set(-axisVec.y, axisVec.x, 0).normalize();
+                    if (uVec.lengthSq() < 1e-6)
+                        uVec.set(1, 0, 0);
+                }
+                vVec.crossVectors(axisVec, uVec).normalize();
+                const w = THREE.MathUtils.lerp(this.opts.minAngularVel, this.opts.maxAngularVel, rand(i, 10));
+                aRadius[i] = radius;
+                aTheta0[i] = wrapAngle(thetaBase + thetaJitter);
+                aOmega[i] = w * 0.35 * (rand(i, 11) < 0.5 ? -1 : 1);
+                aLayer[i] = 0;
+                if (isBokeh) {
+                    aSize[i] = THREE.MathUtils.lerp(14, 30, rand(i, 12));
+                    aIntensity[i] = THREE.MathUtils.lerp(0.4, 0.62, rand(i, 13));
+                }
+                else {
+                    const rPick = rand(i, 14);
+                    if (rPick < 0.7)
+                        aSize[i] = THREE.MathUtils.lerp(1.2, 2.6, rand(i, 15));
+                    else if (rPick < 0.95)
+                        aSize[i] = THREE.MathUtils.lerp(2.6, 5.1, rand(i, 16));
+                    else
+                        aSize[i] = THREE.MathUtils.lerp(5.2, 8.0, rand(i, 17));
+                    aIntensity[i] = THREE.MathUtils.lerp(0.45, 1.1, rand(i, 18));
+                }
+                const radialForIntensity = isHalo
+                    ? THREE.MathUtils.clamp((radius - inner) / haloBand, 0, 1)
+                    : radialT;
+                aIntensity[i] *= THREE.MathUtils.lerp(1.08, 0.9, radialT);
+                const magentaBias = THREE.MathUtils.lerp(1.0, 1.45, radialForIntensity);
+                aIntensity[i] *= magentaBias;
+                const hueBase = THREE.MathUtils.lerp(-0.05, 0.12, rand(i, 19));
+                const hueRadialBias = THREE.MathUtils.lerp(-0.02, 0.08, radialT);
+                aHue[i] = hueBase + hueRadialBias * 0.3;
+                aSeed[i] = rand(i, 20) * 1000.0;
+                aAnchor[i * 3 + 0] = anchorVec.x;
+                aAnchor[i * 3 + 1] = anchorVec.y;
+                aAnchor[i * 3 + 2] = anchorVec.z;
+                aU[i * 3 + 0] = uVec.x;
+                aU[i * 3 + 1] = uVec.y;
+                aU[i * 3 + 2] = uVec.z;
+                aV[i * 3 + 0] = vVec.x;
+                aV[i * 3 + 1] = vVec.y;
+                aV[i * 3 + 2] = vVec.z;
+                aIsHalo[i] = 1;
+                continue;
+            }
+            let radius = 0;
+            let radialT = 0;
+            let theta = 0;
+            let bandIndex = -1;
+            let bandTransparency = 1.0;
+            let innerDist = 0;
+            let outerDist = 0;
+            let innerSoft = 1;
+            let outerSoft = 1;
+            if (isHalo) {
+                const sample = sampleHaloRadius(i);
+                radius = sample.radius;
+                radialT = sample.radialT;
+                const baseTheta = wrapAngle(i * goldenAngle);
+                const angleJitter = (rand(i, 22) - 0.5) * this.haloArmSpread * 0.35;
+                theta = applySpiralArms(wrapAngle(baseTheta + angleJitter), radialT, i, true);
+                innerDist = radius - haloInnerBase;
+                outerDist = haloOuterBase - radius;
+                innerSoft = haloInnerSoft;
+                outerSoft = haloOuterSoft;
+                const innerNorm = THREE.MathUtils.clamp(innerDist / Math.max(1e-4, innerSoft), -4, 4);
+                const outerNorm = THREE.MathUtils.clamp(outerDist / Math.max(1e-4, outerSoft), -4, 4);
+                const haloBody = THREE.MathUtils.smoothstep(innerNorm, -1.4, 0.25) *
+                    THREE.MathUtils.smoothstep(outerNorm, -1.6, 0.3);
+                const haloShell = 1.0 - THREE.MathUtils.smoothstep(Math.min(innerNorm, outerNorm), 0.1, 1.4);
+                const haloFringe = THREE.MathUtils.smoothstep(Math.max(innerNorm, outerNorm), -2.2, 0.8);
+                bandTransparency = THREE.MathUtils.clamp(haloBody * 0.85 + haloShell * 0.55 + haloFringe * 0.28, 0.26, 1.28);
+                aLayer[i] = 0;
+                aBandIndex[i] = -1;
+            }
+            else {
+                bandIndex = selectDiskBandIndex(i);
+                const bandData = diskBands[bandIndex];
+                const baseTheta = wrapAngle(i * goldenAngle);
+                const jitterMag = THREE.MathUtils.lerp(0.16, 0.48, bandData.end);
+                const jitter = (rand(i, 22) - 0.5) * jitterMag;
+                let workingTheta = wrapAngle(baseTheta + jitter);
+                const gaussian = sampleGaussian(i, 30 + bandIndex * 7);
+                const jitterScalar = rand(i, 602 + bandIndex) - 0.5;
+                const sampleFromShell = (shellData, salt) => {
+                    const spread = shellData.halfRadius * 0.52;
+                    const wobble = (rand(i, 608 + salt) - 0.5) *
+                        (shellData.innerSoft + shellData.outerSoft) *
+                        0.25;
+                    const candidate = shellData.midRadius +
+                        gaussian * shellData.sigmaRadius +
+                        jitterScalar * spread +
+                        wobble;
+                    return THREE.MathUtils.clamp(candidate, shellData.supportInner, shellData.supportOuter);
+                };
+                const sampleUniformTail = (shellData, salt) => {
+                    const tailMin = Math.max(shellData.supportInner, shellData.innerRadius - shellData.innerSoft * 1.6);
+                    const tailMax = Math.min(shellData.supportOuter, shellData.outerRadius + shellData.outerSoft * 1.65);
+                    const span = tailMax - tailMin;
+                    if (span <= 1e-5) {
+                        return sampleFromShell(shellData, salt + 11);
+                    }
+                    const wobble = (rand(i, 702 + salt) - 0.5) *
+                        (shellData.innerSoft + shellData.outerSoft) *
+                        0.2;
+                    const t = rand(i, 701 + salt);
+                    const candidate = tailMin + span * t;
+                    return THREE.MathUtils.clamp(candidate + wobble, shellData.supportInner, shellData.supportOuter);
+                };
+                const bridgeToNeighbor = (dir, primary, salt) => {
+                    const neighborIndex = bandIndex + dir;
+                    if (neighborIndex < 0 || neighborIndex >= diskBands.length) {
+                        return null;
+                    }
+                    const neighborShell = resolveBandShell(neighborIndex, workingTheta);
+                    const start = dir < 0
+                        ? Math.min(neighborShell.outerRadius, primary.innerRadius)
+                        : Math.min(primary.outerRadius, neighborShell.innerRadius);
+                    const end = dir < 0
+                        ? Math.max(neighborShell.outerRadius, primary.innerRadius)
+                        : Math.max(primary.outerRadius, neighborShell.innerRadius);
+                    const span = end - start;
+                    if (span <= 1e-4)
+                        return null;
+                    const softness = primary.sigmaRadius + neighborShell.sigmaRadius;
+                    const blendT = Math.pow(rand(i, 720 + salt), 0.88);
+                    const base = start + span * blendT;
+                    const jitter = (rand(i, 721 + salt) - 0.5) * softness * 0.35;
+                    const supportMin = Math.min(primary.supportInner, neighborShell.supportInner);
+                    const supportMax = Math.max(primary.supportOuter, neighborShell.supportOuter);
+                    return THREE.MathUtils.clamp(base + jitter, supportMin, supportMax);
+                };
+                let shell = resolveBandShell(bandIndex, workingTheta);
+                radius = sampleFromShell(shell, bandIndex * 17 + 5);
+                radialT = THREE.MathUtils.clamp((radius - inner) / diskBand, 0, 1);
+                workingTheta = applySpiralArms(workingTheta, radialT, i, false);
+                shell = resolveBandShell(bandIndex, workingTheta);
+                radius = sampleFromShell(shell, bandIndex * 31 + 9);
+                radialT = THREE.MathUtils.clamp((radius - inner) / diskBand, 0, 1);
+                theta = workingTheta;
+                const mixRoll = rand(i, 618 + bandIndex);
+                if (mixRoll < 0.22) {
+                    const tail = sampleUniformTail(shell, bandIndex * 41 + 3);
+                    radius = THREE.MathUtils.lerp(radius, tail, 0.6);
+                    radialT = THREE.MathUtils.clamp((radius - inner) / diskBand, 0, 1);
+                }
+                else if (mixRoll < 0.48) {
+                    const dir = mixRoll < 0.35 ? -1 : 1;
+                    const bridged = bridgeToNeighbor(dir, shell, bandIndex * 53 + (dir < 0 ? 7 : 13));
+                    if (bridged !== null) {
+                        radius = THREE.MathUtils.lerp(radius, bridged, 0.7);
+                        radialT = THREE.MathUtils.clamp((radius - inner) / diskBand, 0, 1);
+                    }
+                }
+                else if (mixRoll < 0.62) {
+                    const dir = mixRoll < 0.55 ? -1 : 1;
+                    const neighborIndex = bandIndex + dir;
+                    if (neighborIndex >= 0 && neighborIndex < diskBands.length) {
+                        const neighborShell = resolveBandShell(neighborIndex, workingTheta);
+                        const neighborRadius = sampleFromShell(neighborShell, bandIndex * 61 + (dir < 0 ? 9 : 17));
+                        const supportMin = Math.min(shell.supportInner, neighborShell.supportInner);
+                        const supportMax = Math.max(shell.supportOuter, neighborShell.supportOuter);
+                        const blend = THREE.MathUtils.clamp(rand(i, 623 + bandIndex), 0.25, 0.75);
+                        const mixed = THREE.MathUtils.lerp(radius, neighborRadius, blend);
+                        radius = THREE.MathUtils.clamp(mixed, supportMin, supportMax);
+                        radialT = THREE.MathUtils.clamp((radius - inner) / diskBand, 0, 1);
+                    }
+                }
+                innerDist = radius - shell.innerRadius;
+                outerDist = shell.outerRadius - radius;
+                innerSoft = shell.innerSoft;
+                outerSoft = shell.outerSoft;
+                const innerNorm = THREE.MathUtils.clamp(innerDist / Math.max(1e-4, innerSoft), -4, 4);
+                const outerNorm = THREE.MathUtils.clamp(outerDist / Math.max(1e-4, outerSoft), -4, 4);
+                const bandBody = THREE.MathUtils.smoothstep(innerNorm, -1.5, 0.35) *
+                    THREE.MathUtils.smoothstep(outerNorm, -1.4, 0.32);
+                const rimShell = 1.0 -
+                    THREE.MathUtils.smoothstep(Math.min(innerNorm, outerNorm), 0.25, 1.6);
+                const baselineGlow = THREE.MathUtils.smoothstep(Math.max(innerNorm, outerNorm), -2.6, 0.9);
+                bandTransparency = THREE.MathUtils.clamp(bandBody * 0.9 + rimShell * 0.52 + baselineGlow * 0.24, bandData.alphaFloor ?? 0.16, 1.45);
+                const innerFiller = THREE.MathUtils.smoothstep(innerNorm, -2.15, 0.45);
+                const outerFiller = THREE.MathUtils.smoothstep(outerNorm, -2.25, 0.42);
+                const filler = Math.max(innerFiller, outerFiller);
+                bandTransparency = Math.max(bandTransparency, filler * 0.22);
+                const radialMask = evaluateRadialMask(radialT, bandData);
+                const angularMask = applyAngularPockets(theta, radialT, bandData, i);
+                bandTransparency *= radialMask * angularMask;
+                const maskFloor = Math.max(filler * 0.14, (bandData.alphaFloor ?? 0) * 0.6);
+                bandTransparency = Math.max(bandTransparency, maskFloor);
+                bandTransparency = THREE.MathUtils.clamp(bandTransparency, 0.1, 1.45);
+                if (bandData.alphaNoise && bandData.alphaNoise > 0) {
+                    const noise = THREE.MathUtils.lerp(1 - bandData.alphaNoise, 1 + bandData.alphaNoise, rand(i, 560 + bandIndex));
+                    bandTransparency *= THREE.MathUtils.clamp(noise, 0.15, 1.25);
+                }
+                if (bandData.alphaFloor !== undefined) {
+                    bandTransparency = Math.max(bandData.alphaFloor, bandTransparency);
+                }
+                if (bandData.id === 'core-void') {
+                    bandTransparency = Math.min(bandTransparency, 0.2);
+                }
+                else if (bandData.id === 'outer-halo') {
+                    bandTransparency *= 0.82;
+                }
+                bandTransparency = THREE.MathUtils.clamp(bandTransparency, 0, 1.5);
+                aLayer[i] = sampleDiskLayer(i, bandIndex, radialT);
+                aBandIndex[i] = bandIndex;
+                if (bandStats) {
+                    const stat = bandStats[bandIndex];
+                    stat.count++;
+                    stat.sumT += radialT;
+                    stat.minT = Math.min(stat.minT, radialT);
+                    stat.maxT = Math.max(stat.maxT, radialT);
+                    stat.alphaSum += bandTransparency;
+                    if (bandTransparency < 0.35)
+                        stat.voidHits++;
+                    stat.innerSum += innerNorm;
+                    stat.outerSum += outerNorm;
+                    stat.radiusMin = Math.min(stat.radiusMin, radius);
+                    stat.radiusMax = Math.max(stat.radiusMax, radius);
+                    stat.innerMin = Math.min(stat.innerMin, innerNorm);
+                    stat.innerMax = Math.max(stat.innerMax, innerNorm);
+                    stat.outerMin = Math.min(stat.outerMin, outerNorm);
+                    stat.outerMax = Math.max(stat.outerMax, outerNorm);
+                }
+            }
+            aEdgeParams[i * 4 + 0] = innerDist;
+            aEdgeParams[i * 4 + 1] = outerDist;
+            aEdgeParams[i * 4 + 2] = innerSoft;
+            aEdgeParams[i * 4 + 3] = outerSoft;
+            const w = THREE.MathUtils.lerp(this.opts.minAngularVel, this.opts.maxAngularVel, rand(i, 29));
+            const direction = rand(i, 30) < 0.5 ? -1 : 1;
+            aOmega[i] = (isBokeh ? w * 0.6 : w) * direction;
+            aTheta0[i] = theta;
+            const radialForIntensity = isHalo
+                ? THREE.MathUtils.clamp((radius - haloInnerBase) / haloSpan, 0, 1)
+                : radialT;
+            const magentaBias = THREE.MathUtils.lerp(1.0, 1.35, radialForIntensity);
+            if (isBokeh) {
+                aSize[i] = THREE.MathUtils.lerp(12, 26, rand(i, 31));
+                aIntensity[i] = THREE.MathUtils.lerp(0.32, 0.58, rand(i, 32));
+            }
+            else {
+                const r = rand(i, 33);
+                if (rand(i, 40) < 0.15 && !isHalo) {
+                    // 15% chance of bright cluster particles
+                    aSize[i] = THREE.MathUtils.lerp(3.5, 6.2, rand(i, 41));
+                    aIntensity[i] = THREE.MathUtils.lerp(0.8, 1.3, rand(i, 42));
+                }
+                else if (r < 0.68) {
+                    aSize[i] = THREE.MathUtils.lerp(1.0, 2.3, rand(i, 34));
+                    aIntensity[i] = THREE.MathUtils.lerp(0.4, 1.05, rand(i, 37));
+                }
+                else if (r < 0.94) {
+                    aSize[i] = THREE.MathUtils.lerp(2.3, 4.6, rand(i, 35));
+                    aIntensity[i] = THREE.MathUtils.lerp(0.4, 1.05, rand(i, 37));
+                }
+                else {
+                    aSize[i] = THREE.MathUtils.lerp(4.8, 7.4, rand(i, 36));
+                    aIntensity[i] = THREE.MathUtils.lerp(0.4, 1.05, rand(i, 37));
+                }
+            }
+            // Apply per-band color intensity multiplier and transparency gradient
+            if (!isHalo) {
+                const band = diskBands[bandIndex];
+                const bandAlpha = Math.max(0, bandTransparency);
+                const posInBand = THREE.MathUtils.clamp((radialT - band.start) /
+                    Math.max(1e-5, band.end - band.start), 0, 1);
+                const coreBoost = band.id === 'inner-rim'
+                    ? THREE.MathUtils.lerp(1.6, 1.05, Math.pow(posInBand, 1.4))
+                    : radialT < 0.22
+                        ? THREE.MathUtils.lerp(1.55, 1.0, radialT / 0.22)
+                        : 1.0;
+                const densityLift = band.id === 'mid-shelf'
+                    ? THREE.MathUtils.lerp(1.0, 1.22, rand(i, 47))
+                    : band.id === 'outer-rim'
+                        ? THREE.MathUtils.lerp(0.9, 1.08, rand(i, 470))
+                        : band.id === 'outer-halo'
+                            ? THREE.MathUtils.lerp(0.88, 1.02, rand(i, 471))
+                            : 1.0;
+                const intensityVariation = THREE.MathUtils.lerp(0.88, 1.32, rand(i, 46));
+                const bokehComp = isBokeh ? 0.9 : 1.0;
+                aIntensity[i] *=
+                    band.colorIntensity *
+                        bandAlpha *
+                        coreBoost *
+                        densityLift *
+                        intensityVariation *
+                        magentaBias *
+                        bokehComp;
+            }
+            else {
+                const rimBoost = Math.max(0.65, bandTransparency);
+                const haloInnerNorm = THREE.MathUtils.clamp(innerDist / Math.max(1e-4, innerSoft), -3, 3);
+                const haloOuterNorm = THREE.MathUtils.clamp(outerDist / Math.max(1e-4, outerSoft), -3, 3);
+                const contourMix = THREE.MathUtils.smoothstep(haloInnerNorm, -1.1, 0.5) *
+                    THREE.MathUtils.smoothstep(haloOuterNorm, -1.1, 0.55);
+                const bandContour = THREE.MathUtils.clamp(contourMix, 0.2, 1.2);
+                aIntensity[i] *= THREE.MathUtils.lerp(1.25, 0.82, radialForIntensity);
+                aIntensity[i] *= rimBoost * bandContour;
+            }
+            aRadius[i] = radius;
+            // Organic color mixing: blue/purple/magenta dominant with cyan accents
+            // Distribute colors: majority blue/magenta, less cyan
+            const colorRoll = rand(i, 38);
+            let hueBase = 0.0;
+            if (colorRoll < 0.4) {
+                // 40% deep blue to purple
+                hueBase = THREE.MathUtils.lerp(0.05, 0.2, rand(i, 49));
+            }
+            else if (colorRoll < 0.75) {
+                // 35% magenta to purple
+                hueBase = THREE.MathUtils.lerp(0.2, 0.4, rand(i, 50));
+            }
+            else {
+                // 25% cyan to blue
+                hueBase = THREE.MathUtils.lerp(-0.1, 0.05, rand(i, 51));
+            }
+            // Create color regions using spatial patterns
+            const spatialCluster1 = Math.sin(theta * 2.3 + radialForIntensity * 4.5) * 0.1;
+            const spatialCluster2 = Math.cos(theta * 5.1 - radialForIntensity * 3.2) * 0.08;
+            // Subtle radial gradient: don't force too much cyan in inner
+            const hueRadialBias = THREE.MathUtils.lerp(0.0, // inner: mixed colors
+            0.15, // outer: slightly more magenta
+            Math.pow(radialForIntensity, 1.2));
+            const magentaPull = THREE.MathUtils.lerp(-0.4, 0.45, radialForIntensity);
+            const bandIndexNormalized = diskBands.length > 1
+                ? THREE.MathUtils.clamp(bandIndex, 0, diskBands.length - 1) /
+                    (diskBands.length - 1)
+                : 0;
+            const bandBias = THREE.MathUtils.lerp(-0.18, 0.25, bandIndexNormalized);
+            aHue[i] = hueBase * 0.25 + magentaPull + bandBias + spatialCluster1 + spatialCluster2;
+            aSeed[i] = rand(i, 39) * 1000.0;
+            if (isHalo) {
+                axisVec
+                    .set(rand(i, 40) * 2 - 1, rand(i, 41) * 2 - 1, rand(i, 42) * 2 - 1)
+                    .normalize();
+                if (!isFinite(axisVec.x))
+                    axisVec.set(0, 1, 0);
+                const ref = Math.abs(axisVec.y) > 0.9 ? tmpVec.set(1, 0, 0) : tmpVec.set(0, 1, 0);
+                uVec.crossVectors(ref, axisVec).normalize();
+                vVec.crossVectors(axisVec, uVec).normalize();
+                tmpVec.copy(uVec).multiplyScalar(Math.cos(theta) * radius);
+                tmpVec2.copy(vVec).multiplyScalar(Math.sin(theta) * radius);
+                anchorVec.copy(tmpVec.add(tmpVec2));
+                aIsHalo[i] = 1;
+            }
+            else {
+                uVec.set(1, 0, 0);
+                vVec.set(0, 1, 0);
+                anchorVec.set(radius * Math.cos(theta), radius * Math.sin(theta), 0);
+                aIsHalo[i] = 0;
+            }
+            aAnchor[i * 3 + 0] = anchorVec.x;
+            aAnchor[i * 3 + 1] = anchorVec.y;
+            aAnchor[i * 3 + 2] = anchorVec.z;
+            aU[i * 3 + 0] = uVec.x;
+            aU[i * 3 + 1] = uVec.y;
+            aU[i * 3 + 2] = uVec.z;
+            aV[i * 3 + 0] = vVec.x;
+            aV[i * 3 + 1] = vVec.y;
+            aV[i * 3 + 2] = vVec.z;
+        }
+        g.setAttribute('position', new THREE.BufferAttribute(base, 3));
+        g.setAttribute('aRadius', new THREE.BufferAttribute(aRadius, 1));
+        g.setAttribute('aTheta0', new THREE.BufferAttribute(aTheta0, 1));
+        g.setAttribute('aOmega', new THREE.BufferAttribute(aOmega, 1));
+        g.setAttribute('aLayer', new THREE.BufferAttribute(aLayer, 1));
+        g.setAttribute('aSize', new THREE.BufferAttribute(aSize, 1));
+        g.setAttribute('aIntensity', new THREE.BufferAttribute(aIntensity, 1));
+        g.setAttribute('aHue', new THREE.BufferAttribute(aHue, 1));
+        g.setAttribute('aSeed', new THREE.BufferAttribute(aSeed, 1));
+        g.setAttribute('aAnchor', new THREE.BufferAttribute(aAnchor, 3));
+        g.setAttribute('aU', new THREE.BufferAttribute(aU, 3));
+        g.setAttribute('aV', new THREE.BufferAttribute(aV, 3));
+        g.setAttribute('aIsHalo', new THREE.BufferAttribute(aIsHalo, 1));
+        g.setAttribute('aBandIndex', new THREE.BufferAttribute(aBandIndex, 1));
+        g.setAttribute('aEdgeParams', new THREE.BufferAttribute(aEdgeParams, 4));
+        if (collectBandStats && bandStats) {
+            const loggedTotal = bandStats.reduce((sum, band) => sum + band.count, 0);
+            this.logDiskBandStats(kind, loggedTotal || count, bandStats);
+        }
+        const mat = this.makeMaterial(isBokeh);
+        const pts = new THREE.Points(g, mat);
+        pts.renderOrder = this.opts.renderOrder;
+        pts.frustumCulled = false;
+        this.group.add(pts);
+        return pts;
+    }
+    makeMaterial(isBokeh) {
+        this.refreshPaletteUniformData();
+        const uniforms = {
+            uTime: { value: 0 },
+            uViewportH: { value: this.viewportHeight },
+            uInner: { value: this.opts.innerRadius },
+            uOuter: { value: this.opts.outerRadius },
+            uHalfThickness: { value: this.opts.thickness },
+            uNoise: { value: this.opts.noiseStrength },
+            uColorInner: { value: new THREE.Color(this.opts.colorInner) },
+            uColorMid: { value: new THREE.Color(this.opts.colorMid) },
+            uColorOuter: { value: new THREE.Color(this.opts.colorOuter) },
+            uPaletteCount: { value: this.paletteUniformCount },
+            uPaletteStops: { value: this.paletteUniformStops },
+            uPaletteIntensities: { value: this.paletteUniformIntensities },
+            uPaletteColors: { value: this.paletteUniformColors },
+            uHueBiasScale: { value: this.paletteHueBiasScale },
+            uBackgroundLift: {
+                value: this.debugDimLights
+                    ? this.paletteBackgroundLift * 0.25
+                    : this.paletteBackgroundLift,
+            },
+            uCoreIntensity: {
+                value: this.debugDimLights
+                    ? this.paletteCoreIntensity * 0.8
+                    : this.paletteCoreIntensity,
+            },
+            uEdgeDebugMix: { value: this.debugEdgeMix },
+            uSoftness: { value: isBokeh ? 2.6 : 3.6 },
+            uSizeScale: { value: (isBokeh ? 1.0 : 1.2) * 5.0 },
+            uMode: { value: this.dustMode === 'sphere' ? 1 : 0 },
+            uSphereJitter: { value: this.sphereJitter },
+            // Brightness control uniforms
+            uWhitenScale: { value: this.whitenScale },
+            uAlphaScale: { value: this.alphaScale },
+            // Attractor uniforms
+            uUseAttract: { value: 0.0 },
+            uAttractorCount: { value: 0 },
+            uAttractorPos: {
+                // array of vec3 in dust local space
+                value: Array.from({ length: this.MAX_ATTRACTORS }, () => new THREE.Vector3(9999, 9999, 9999)),
+            },
+            uAttractorRad: {
+                value: new Array(this.MAX_ATTRACTORS).fill(0),
+            },
+            uNearFactor: { value: this.nearRadiusFactor },
+            uStickEpsRel: { value: this.stickEpsRel },
+            uStickEpsMin: { value: this.stickEpsMin },
+            uStickEpsMax: { value: this.stickEpsMax },
+            uAttractStrength: { value: this.attractStrength },
+            uTangentialBias: { value: this.tangentialBias },
+        };
+        const vertex = `
+      uniform float uTime;
+      uniform float uInner;
+      uniform float uOuter;
+      uniform float uHalfThickness;
+      uniform float uNoise;
+      uniform float uViewportH;
+      uniform float uSizeScale;
+      uniform int uMode;
+      uniform float uSphereJitter;
+      uniform float uAlphaScale;
+      // Attractor uniforms
+      const int MAX_ATTRACTORS = ${24};
+      uniform float uUseAttract; // 0 = off, 1 = on
+      uniform int uAttractorCount;
+      uniform vec3 uAttractorPos[MAX_ATTRACTORS];
+      uniform float uAttractorRad[MAX_ATTRACTORS];
+      uniform float uNearFactor;
+      uniform float uStickEpsRel;
+      uniform float uStickEpsMin;
+      uniform float uStickEpsMax;
+      uniform float uAttractStrength;
+      uniform float uTangentialBias;
+
+      attribute float aRadius;   // base orbit radius
+      attribute float aTheta0;   // initial angle
+      attribute float aOmega;    // angular velocity (rad/s)
+      attribute float aLayer;    // vertical offset across disk thickness (disk only)
+      attribute float aSize;     // pixel size (base)
+      attribute float aIntensity;// brightness multiplier
+      attribute float aHue;      // slight hue bias [-~0.06..+~0.08]
+      attribute float aSeed;     // noise seed
+      attribute vec3 aAnchor;    // base anchor (sphere mode or cached local)
+      attribute vec3 aU;         // plane basis U (halo or disk default)
+      attribute vec3 aV;         // plane basis V
+      attribute float aIsHalo;   // 1 = halo, 0 = disk
+      attribute vec4 aEdgeParams;
+
+      varying float vAlpha;
+      varying float vRadialT;
+      varying float vHueBias;
+      varying vec4 vEdgeParams;
+
+      // Smooth value noise (cheap 1D) to avoid jitter/vibrate
+      float hash(float n){ return fract(sin(n)*43758.5453123); }
+      float vnoise1(float x){
+        float i = floor(x);
+        float f = fract(x);
+        float a = hash(i);
+        float b = hash(i + 1.0);
+        float s = f*f*(3.0-2.0*f); // smoothstep
+        return mix(a, b, s);
+      }
+
+      void main(){
+        float t = aTheta0 + aOmega * uTime;
+
+        float r = aRadius;
+        vec3 local;
+        if (uMode == 1) {
+          vec3 anchor = aAnchor;
+          float baseR = length(anchor);
+          vec3 axis = baseR > 1e-5 ? normalize(anchor) : vec3(0.0, 1.0, 0.0);
+          vec3 u = normalize(aU);
+          vec3 v = normalize(aV);
+          float spin = aOmega * uTime * 0.4;
+          float cs = cos(spin);
+          float sn = sin(spin);
+          vec3 su = u * cs + v * sn;
+          vec3 sv = -u * sn + v * cs;
+          vec3 n = normalize(cross(su, sv));
+          float jitter = uSphereJitter;
+          float j1 = (vnoise1(aSeed*1.41 + uTime*0.11) - 0.5) * jitter;
+          float j2 = (vnoise1(aSeed*2.17 + uTime*0.09) - 0.5) * jitter;
+          float j3 = (vnoise1(aSeed*3.07 + uTime*0.07) - 0.5) * jitter;
+          float breathe = (vnoise1(aSeed*4.19 + uTime*0.045) - 0.5) * jitter;
+          local = anchor
+            + su * (j1 * baseR * 0.45)
+            + sv * (j2 * baseR * 0.45)
+            + n * (j3 * baseR * 0.35)
+            + axis * (breathe * baseR * 0.18);
+          float radialDen = max(0.0001, (uOuter - uInner));
+          vRadialT = clamp((baseR - uInner) / radialDen, 0.0, 1.0);
+        } else if (aIsHalo > 0.5) {
+          // Halo: orbit in per‑particle plane (aU, aV) with tiny precession
+          float prec = mix(0.01, 0.03, fract(aSeed*0.317)) * uTime;
+          float cp = cos(prec), sp = sin(prec);
+          vec3 u = aU * cp + aV * sp;
+          vec3 v = -aU * sp + aV * cp;
+          vec3 n = normalize(cross(u, v));
+
+          local = r * (cos(t) * u + sin(t) * v);
+
+          // Smooth 3D drift: in-plane + along normal
+          float j1 = vnoise1(aSeed*1.37 + t*0.09) - 0.5;
+          float j2 = vnoise1(aSeed*2.11 + t*0.07) - 0.5;
+          float j3 = vnoise1(aSeed*3.03 + uTime*0.06) - 0.5;
+          local += (u * j1 + v * j2) * uNoise * r * 0.08;
+          local += n * j3 * uNoise * 0.18;
+        } else {
+          // Disk: flattened local XY plane (treating Z as zero for 2D look)
+          local = vec3(r * cos(t), r * sin(t), 0.0);
+          float jx = vnoise1(aSeed*1.37 + t*0.09) - 0.5;
+          float jy = vnoise1(aSeed*2.11 + t*0.07) - 0.5;
+          local.x += jx * uNoise * r * 0.15;
+          local.y += jy * uNoise * r * 0.15;
+        }
+
+        float radialDen = max(0.0001, (uOuter - uInner));
+        float radialNorm = clamp((r - uInner) / radialDen, 0.0, 1.0);
+        if (uMode != 1) {
+          // Radial ratio for color gradient (disk/halo paths)
+          vRadialT = radialNorm;
+        } else {
+          // Preserve sphere-provided value but keep it clamped
+          vRadialT = clamp(vRadialT, 0.0, 1.0);
+          radialNorm = vRadialT;
+        }
+        float hueBoost = mix(0.22, 1.0, pow(radialNorm, 0.85));
+        vHueBias = aHue * hueBoost;
+        vAlpha = aIntensity * uAlphaScale;
+        vEdgeParams = aEdgeParams;
+        // --- Node attractor warping (object local space) ---
+        if (uUseAttract > 0.5) {
+          // Plane normal in dust local space is +Z (group rotates the whole object)
+          vec3 n = vec3(0.0, 0.0, 1.0);
+          // Iterate all active attractors, apply strongest influence (nearest)
+          float bestS = 0.0;
+          vec3 bestTarget = local;
+          for (int i = 0; i < MAX_ATTRACTORS; i++) {
+            if (i >= uAttractorCount) break;
+            vec3 aPos = uAttractorPos[i];
+            float aR = uAttractorRad[i];
+            // distance in local space
+            vec3 d = aPos - local;
+            float dist = length(d);
+            float nearR = max(0.0001, aR * uNearFactor);
+            float eps = clamp(aR * uStickEpsRel, uStickEpsMin, uStickEpsMax);
+            float stickR = max(0.0001, aR + eps);
+            if (dist < nearR) {
+              // Project vector onto plane around node
+              vec3 toP = local - aPos;
+              vec3 tang = toP - n * dot(toP, n);
+              float tl = length(tang);
+              // If degenerate, pick a small tangent perpendicular to n
+              if (tl < 1e-5) {
+                vec3 fallback = normalize(cross(n, vec3(1.0, 0.0, 0.0)));
+                if (length(fallback) < 1e-3) fallback = normalize(cross(n, vec3(0.0, 0.0, 1.0)));
+                tang = fallback * stickR;
+                tl = length(tang);
+              }
+              vec3 tangN = tang / max(1e-5, tl);
+            // Influence grows from nearR → stickR
+            float s = clamp((nearR - dist) / max(1e-6, (nearR - stickR)), 0.0, 1.0);
+            // Quadratic ease for smoother capture
+            s = s * s * (3.0 - 2.0 * s);
+            // Add tangential bias that tapers near the surface (avoid donut ring)
+            vec3 tangOrtho = normalize(cross(n, tangN));
+            float slide = uTangentialBias * (1.0 - s);
+            vec3 target = aPos + tangN * stickR + tangOrtho * (slide * stickR * 0.05);
+              if (s > bestS) {
+                bestS = s;
+                bestTarget = target;
+              }
+            }
+          }
+          // Blend toward the strongest attractor target, with snap when very close
+          if (bestS > 0.0) {
+            float t = clamp(uAttractStrength * bestS + 0.6, 0.0, 1.0);
+            if (bestS > 0.9) {
+              local = bestTarget;
+            } else {
+              local = mix(local, bestTarget, t);
+            }
+          }
+        }
+
+        if (uMode != 1) {
+          local.z = clamp(local.z, -uHalfThickness, uHalfThickness);
+        }
+
+        vec4 mv = modelViewMatrix * vec4(local, 1.0);
+        gl_Position = projectionMatrix * mv;
+
+        float att = uViewportH * 0.5 / max(1.0, -mv.z);
+        float depthScale = mix(1.3, 0.7, clamp(vRadialT, 0.0, 1.0));
+        gl_PointSize = aSize * uSizeScale * att * depthScale * 0.0035; // tuned factor
+      }
+    `;
+        const fragment = `
+      precision highp float;
+      uniform vec3 uColorInner;
+      uniform vec3 uColorMid;
+      uniform vec3 uColorOuter;
+      uniform float uSoftness; // gaussian falloff strength
+      uniform int uMode;
+      const int MAX_PALETTE_STOPS = ${this.MAX_PALETTE_STOPS};
+      uniform int uPaletteCount;
+      uniform float uPaletteStops[MAX_PALETTE_STOPS];
+      uniform float uPaletteIntensities[MAX_PALETTE_STOPS];
+      uniform vec3 uPaletteColors[MAX_PALETTE_STOPS];
+      uniform float uHueBiasScale;
+      uniform float uBackgroundLift;
+      uniform float uCoreIntensity;
+      uniform float uEdgeDebugMix;
+      uniform float uWhitenScale;
+
+      varying float vAlpha;
+      varying float vRadialT;
+      varying float vHueBias;
+      varying vec4 vEdgeParams;
+
+      vec3 samplePalette(float t, out float intensity){
+        float clamped = clamp(t, 0.0, 1.0);
+        if (uPaletteCount <= 0){
+          intensity = 1.0;
+          return vec3(1.0);
+        }
+        float prevStop = uPaletteStops[0];
+        vec3 prevColor = uPaletteColors[0];
+        float prevIntensity = uPaletteIntensities[0];
+        if (clamped <= prevStop){
+          intensity = prevIntensity;
+          return prevColor;
+        }
+        for (int i = 1; i < MAX_PALETTE_STOPS; i++){
+          if (i >= uPaletteCount) break;
+          float stop = uPaletteStops[i];
+          vec3 color = uPaletteColors[i];
+          float inten = uPaletteIntensities[i];
+          if (clamped <= stop + 1e-5){
+            float span = max(1e-4, stop - prevStop);
+            float localT = (clamped - prevStop) / span;
+            intensity = mix(prevIntensity, inten, localT);
+            return mix(prevColor, color, localT);
+          }
+          prevStop = stop;
+          prevColor = color;
+          prevIntensity = inten;
+        }
+        intensity = prevIntensity;
+        return prevColor;
+      }
+
+      vec3 resolveColor(float radialT, float hueBias, out float paletteIntensity){
+        float baseIntensity;
+        vec3 baseColor = samplePalette(radialT, baseIntensity);
+        float biasMag = mix(0.05, 0.32, pow(radialT, 1.4));
+        float offsetT = clamp(radialT + hueBias * biasMag, 0.0, 1.0);
+        float accentIntensity;
+        vec3 accentColor = samplePalette(offsetT, accentIntensity);
+        float mixAmt = clamp(abs(hueBias) * uHueBiasScale * mix(0.8, 1.25, radialT), 0.0, 1.0);
+        paletteIntensity = mix(baseIntensity, accentIntensity, mixAmt);
+        vec3 color = mix(baseColor, accentColor, mixAmt);
+        return color;
+      }
+
+      vec3 applyCoreBoost(vec3 color, float radialT){
+        float boost = mix(uCoreIntensity, 1.0, smoothstep(0.18, 0.5, radialT));
+        return clamp(color * boost, 0.0, 1.2);
+      }
+
+      void main(){
+        vec2 uv = gl_PointCoord * 2.0 - 1.0;
+        float r2 = dot(uv, uv);
+        if (r2 > 1.0) discard;
+
+        float falloff = exp(-r2 * uSoftness);
+        float alpha = falloff * vAlpha;
+        vec3 color;
+
+        if (uMode == 1) {
+          float mixT = clamp(vRadialT, 0.0, 1.0);
+          float modeIntensity;
+          color = samplePalette(mixT, modeIntensity);
+          alpha *= mix(1.2, 0.6, mixT);
+        } else {
+          float radialT = clamp(vRadialT, 0.0, 1.0);
+          float edgeFade = smoothstep(1.0, 0.45, sqrt(r2));
+          float radialFade = mix(1.15, 0.38, pow(radialT, 1.4));
+          alpha *= edgeFade * radialFade;
+
+          float paletteIntensity;
+          color = resolveColor(radialT, vHueBias, paletteIntensity);
+          float floorMix = smoothstep(0.05, 0.65, paletteIntensity);
+          color = mix(vec3(uBackgroundLift), color, floorMix);
+          color = applyCoreBoost(color, radialT);
+
+          vec2 edgeDist = vEdgeParams.xy;
+          vec2 edgeSoft = max(vec2(1e-4), vEdgeParams.zw);
+          vec2 norm = clamp(edgeDist / edgeSoft, vec2(-4.0), vec2(4.0));
+          float body = smoothstep(-1.35, 0.2, norm.x) * smoothstep(-1.38, 0.32, norm.y);
+          float shell = 1.0 - smoothstep(0.18, 1.55, min(norm.x, norm.y));
+          float innerGlow = smoothstep(-2.3, 0.6, norm.x);
+          float outerGlow = smoothstep(-2.4, 0.8, norm.y);
+          float baseline = max(innerGlow * 0.18, outerGlow * 0.28);
+          float rimAmount = clamp(shell * mix(0.5, 1.0, body), 0.0, 1.0);
+          float bodyScale = mix(0.68, 1.35, body);
+          float rimScale = mix(0.92, 1.16, rimAmount);
+          float outerBias = mix(1.02, 0.88, smoothstep(-0.35, 0.8, norm.y));
+          alpha *= bodyScale;
+          alpha *= rimScale;
+          alpha *= outerBias;
+          float ambient = max(baseline, body * 0.32);
+          float alphaFloor = ambient * mix(0.45, 1.0, clamp(vAlpha, 0.0, 1.0));
+          alpha = max(alpha, alphaFloor);
+          alpha = max(alpha, rimAmount * vAlpha * 0.24);
+          color = mix(color, vec3(0.92, 0.98, 1.12), rimAmount * 0.22 * uWhitenScale);
+
+          if (uEdgeDebugMix > 0.0) {
+            vec3 dbg = vec3(
+              clamp(norm.x * 0.25 + 0.5, 0.0, 1.0),
+              clamp(norm.y * 0.25 + 0.5, 0.0, 1.0),
+              clamp((norm.x - norm.y) * 0.25 + 0.5, 0.0, 1.0)
+            );
+            color = mix(color, dbg, clamp(uEdgeDebugMix, 0.0, 1.0));
+          }
+
+          if (radialT < 0.22) {
+            float coreBright = smoothstep(0.22, 0.0, radialT);
+            color = mix(color, vec3(0.94, 0.97, 1.0), coreBright * 0.45 * uWhitenScale);
+            alpha *= mix(1.0, uCoreIntensity, coreBright * 0.35);
+          }
+        }
+        gl_FragColor = vec4(clamp(color, 0.0, 1.0), alpha);
+      }
+    `;
+        return new THREE.ShaderMaterial({
+            uniforms,
+            vertexShader: vertex,
+            fragmentShader: fragment,
+            transparent: true,
+            blending: THREE.AdditiveBlending,
+            depthWrite: false,
+            depthTest: true,
+        });
+    }
+    valueNoise2D(x, y, saltPrimary, saltSecondary) {
+        const fade = (t) => t * t * (3 - 2 * t);
+        const xi = Math.floor(x);
+        const yi = Math.floor(y);
+        const xf = x - xi;
+        const yf = y - yi;
+        const hashCorner = (ix, iy, saltOffset) => {
+            const sx = ix | 0;
+            const sy = iy | 0;
+            let key = Math.imul(sx, 374761393) ^ Math.imul(sy, 668265263);
+            key ^= saltOffset * 1597334677;
+            return this.hashFloat(key, saltPrimary + saltSecondary + saltOffset * 31);
+        };
+        const v00 = hashCorner(xi, yi, 0);
+        const v10 = hashCorner(xi + 1, yi, 1);
+        const v01 = hashCorner(xi, yi + 1, 2);
+        const v11 = hashCorner(xi + 1, yi + 1, 3);
+        const u = fade(xf);
+        const v = fade(yf);
+        const lerp = THREE.MathUtils.lerp;
+        const x0 = lerp(v00, v10, u);
+        const x1 = lerp(v01, v11, u);
+        return lerp(x0, x1, v);
+    }
+    samplePeriodicFbm(theta, params, bandIndex, salt) {
+        const octaves = Math.max(1, Math.floor(params.octaves ?? 4));
+        const lacunarity = params.lacunarity ?? 2.0;
+        const gain = params.gain ?? 0.5;
+        const baseFrequency = Math.max(0.05, params.frequency);
+        const warpAmplitude = params.warpAmplitude ?? 0;
+        const warpFrequency = params.warpFrequency ?? Math.max(0.05, baseFrequency * 0.45);
+        const warpOctaves = Math.max(1, Math.floor(params.warpOctaves ?? 2));
+        const baseX = Math.cos(theta);
+        const baseY = Math.sin(theta);
+        let warpX = 0;
+        let warpY = 0;
+        if (warpAmplitude > 1e-4) {
+            let wAmp = 1;
+            let wTotal = 0;
+            let wSumX = 0;
+            let wSumY = 0;
+            for (let o = 0; o < warpOctaves; o++) {
+                const wf = warpFrequency * Math.pow(1.8, o);
+                const nx = baseX * wf + bandIndex * 1.137 + salt * 0.017;
+                const ny = baseY * wf + bandIndex * 1.931 + salt * 0.029;
+                const noiseX = this.valueNoise2D(nx + 19.1, ny + 4.73, salt + o * 37, 97) * 2 - 1;
+                const noiseY = this.valueNoise2D(nx - 3.44, ny + 11.82, salt + o * 41, 151) * 2 - 1;
+                wSumX += noiseX * wAmp;
+                wSumY += noiseY * wAmp;
+                wTotal += wAmp;
+                wAmp *= 0.55;
+            }
+            if (wTotal > 0) {
+                warpX = (wSumX / wTotal) * warpAmplitude;
+                warpY = (wSumY / wTotal) * warpAmplitude;
+            }
+        }
+        let sum = 0;
+        let amplitude = 1;
+        let totalAmplitude = 0;
+        for (let o = 0; o < octaves; o++) {
+            const freq = baseFrequency * Math.pow(lacunarity, o);
+            const nx = baseX * freq + warpX;
+            const ny = baseY * freq + warpY;
+            const n = this.valueNoise2D(nx + bandIndex * 9.713 + salt * 0.13 + o * 13.37, ny + bandIndex * 7.291 + salt * 0.19 + o * 17.53, salt + o * 59, 211 + bandIndex * 13) *
+                2 -
+                1;
+            sum += n * amplitude;
+            totalAmplitude += amplitude;
+            amplitude *= gain;
+        }
+        if (totalAmplitude <= 1e-6)
+            return 0;
+        return THREE.MathUtils.clamp(sum / totalAmplitude, -1, 1) * (params.amplitude ?? 1);
+    }
+    // Debug: sample a small subset of particles across cohorts and log near/stick counts
+    sampleAndLogContacts() {
+        const now = performance.now();
+        if (now - this.lastDustLogMs < 1000)
+            return;
+        this.lastDustLogMs = now;
+        const cohorts = ['disk', 'diskBokeh', 'halo', 'haloBokeh'];
+        let sample = 0;
+        let nearHits = 0;
+        let stickHits = 0;
+        const perAttractorNear = new Array(this.MAX_ATTRACTORS).fill(0);
+        const perAttractorStick = new Array(this.MAX_ATTRACTORS).fill(0);
+        const perAttractorSumR = new Array(this.MAX_ATTRACTORS).fill(0);
+        const perAttractorSumAbsDelta = new Array(this.MAX_ATTRACTORS).fill(0);
+        // Build local copies of attractors
+        const nAttr = Math.min(this.MAX_ATTRACTORS, this.attractorLocalPos.length);
+        const apos = this.attractorLocalPos.slice(0, nAttr);
+        const arad = this.attractorRadius.slice(0, nAttr);
+        const MAX_SAMPLE = 400; // keep it light
+        for (const c of cohorts) {
+            const pts = this.points?.[c];
+            if (!pts)
+                continue;
+            const g = pts.geometry;
+            const aRadius = g.getAttribute('aRadius');
+            const aTheta0 = g.getAttribute('aTheta0');
+            const aOmega = g.getAttribute('aOmega');
+            const aLayer = g.getAttribute('aLayer');
+            const aU = g.getAttribute('aU');
+            const aV = g.getAttribute('aV');
+            const aIsHalo = g.getAttribute('aIsHalo');
+            const count = aRadius?.count ?? 0;
+            if (!count)
+                continue;
+            const step = Math.max(1, Math.floor(count / Math.max(1, Math.floor(MAX_SAMPLE / cohorts.length))));
+            for (let i = 0; i < count && sample < MAX_SAMPLE; i += step) {
+                const r = aRadius.getX(i);
+                const t = aTheta0.getX(i) + aOmega.getX(i) * this.time;
+                let local;
+                if ((aIsHalo.getX(i) || 0) > 0.5) {
+                    // halo
+                    const u = new THREE.Vector3(aU.getX(i), aU.getY(i), aU.getZ(i));
+                    const v = new THREE.Vector3(aV.getX(i), aV.getY(i), aV.getZ(i));
+                    local = u
+                        .multiplyScalar(Math.cos(t) * r)
+                        .add(v.multiplyScalar(Math.sin(t) * r));
+                }
+                else {
+                    const y = aLayer ? aLayer.getX(i) : 0;
+                    local = new THREE.Vector3(Math.cos(t) * r, y, Math.sin(t) * r);
+                }
+                // Check against attractors (mirror shader warp when enabled)
+                let usedK = -1;
+                let usedNearR = 0;
+                let usedStickR = 0;
+                let posAfter = local;
+                // Find strongest influence
+                let bestS = 0;
+                let bestK = -1;
+                let bestNearR = 0;
+                let bestStickR = 0;
+                let bestTarget = null;
+                for (let k = 0; k < nAttr; k++) {
+                    const aPos = apos[k];
+                    const aR = arad[k];
+                    const d = local.distanceTo(aPos);
+                    const nearR = aR * this.nearRadiusFactor;
+                    const eps = Math.min(this.stickEpsMax, Math.max(this.stickEpsMin, aR * this.stickEpsRel));
+                    const stickR = aR + eps;
+                    if (d < nearR) {
+                        // plane projection and target (same as shader)
+                        const n = new THREE.Vector3(0, 1, 0);
+                        const toP = local.clone().sub(aPos);
+                        let tang = toP.clone().sub(n.clone().multiplyScalar(toP.dot(n)));
+                        let tl = tang.length();
+                        if (tl < 1e-5) {
+                            const fallback = new THREE.Vector3(0, 1, 0)
+                                .cross(new THREE.Vector3(1, 0, 0))
+                                .normalize();
+                            tang = fallback.clone().multiplyScalar(stickR);
+                            tl = tang.length();
+                        }
+                        const tangN = tang.clone().multiplyScalar(1 / Math.max(1e-5, tl));
+                        const tangOrtho = new THREE.Vector3()
+                            .crossVectors(n, tangN)
+                            .normalize();
+                        // Tapered slide mirrors shader
+                        const slide = this.tangentialBias *
+                            (1 - (nearR - d) / Math.max(1e-6, nearR - stickR)); // approx
+                        const target = aPos
+                            .clone()
+                            .add(tangN.clone().multiplyScalar(stickR))
+                            .add(tangOrtho
+                            .clone()
+                            .multiplyScalar(Math.max(0, slide) * stickR * 0.05));
+                        let s = (nearR - d) / Math.max(1e-6, nearR - stickR);
+                        s = Math.max(0, Math.min(1, s));
+                        s = s * s * (3 - 2 * s);
+                        if (s > bestS) {
+                            bestS = s;
+                            bestK = k;
+                            bestNearR = nearR;
+                            bestStickR = stickR;
+                            bestTarget = target;
+                        }
+                    }
+                }
+                if (this.useAttract && bestS > 0 && bestTarget) {
+                    let tBlend = Math.max(0, Math.min(1, this.attractStrength * bestS + 0.6));
+                    // Snap when close to stick band (mirror shader approx)
+                    const distBest = local.clone().sub(bestTarget).length();
+                    if (distBest <= 1.2 * Math.abs(bestStickR)) {
+                        posAfter = bestTarget.clone();
+                    }
+                    else {
+                        posAfter = local.clone().lerp(bestTarget, tBlend);
+                    }
+                    usedK = bestK;
+                    usedNearR = bestNearR;
+                    usedStickR = bestStickR;
+                }
+                else if (bestK >= 0) {
+                    // Attraction off: measure pre-warp distance using bestK
+                    usedK = bestK;
+                    usedNearR = bestNearR;
+                    usedStickR = bestStickR;
+                }
+                if (usedK >= 0) {
+                    const d2 = posAfter.distanceTo(apos[usedK]);
+                    if (d2 < usedNearR) {
+                        nearHits++;
+                        perAttractorNear[usedK]++;
+                        perAttractorSumR[usedK] += d2;
+                        perAttractorSumAbsDelta[usedK] += Math.abs(d2 - usedStickR);
+                        if (d2 < usedStickR) {
+                            stickHits++;
+                            perAttractorStick[usedK]++;
+                        }
+                    }
+                }
+                sample++;
+            }
+        }
+        // Always print once/second for analysis (low volume)
+        console.info('[DustAttract] near:', nearHits, 'stick-ish:', stickHits, 'sample:', sample, '| config:', {
+            useAttract: this.useAttract,
+            nearFactor: this.nearRadiusFactor,
+            epsRel: this.stickEpsRel,
+            epsMin: this.stickEpsMin,
+            epsMax: this.stickEpsMax,
+            attractStrength: this.attractStrength,
+            tangentialBias: this.tangentialBias,
+        });
+        try {
+            const search = getWindowLocationSearch();
+            const verbose = /(?:^|[?&])debugDust=2(?:&|$)/.test(search);
+            if (verbose && nAttr > 0) {
+                const rows = [];
+                for (let i = 0; i < nAttr; i++) {
+                    const n = perAttractorNear[i];
+                    const s = perAttractorStick[i];
+                    if (n === 0 && s === 0)
+                        continue;
+                    const aR = arad[i];
+                    const stickR = aR +
+                        Math.min(this.stickEpsMax, Math.max(this.stickEpsMin, aR * this.stickEpsRel));
+                    const avgR = n > 0 ? perAttractorSumR[i] / n : 0;
+                    const avgDelta = n > 0 ? perAttractorSumAbsDelta[i] / n : 0;
+                    rows.push({ idx: i, n, s, avgR, avgDelta, aR, stickR });
+                }
+                rows.sort((a, b) => b.n - a.n);
+                const top = rows
+                    .slice(0, 6)
+                    .map((p) => `#${p.idx} aR:${p.aR.toFixed(3)} stickR:${p.stickR.toFixed(3)} avgR:${p.avgR.toFixed(3)} avg|d-stickR|:${p.avgDelta.toFixed(3)} near:${p.n} stick:${p.s}`);
+                if (top.length)
+                    console.info('[DustAttract] per-node (top6):', top.join(' | '));
+            }
+        }
+        catch { }
+    }
+    hashFloat(index, salt = 0) {
+        let x = Math.imul(index | 0, 0x6d2b79f5);
+        x ^= Math.imul((salt | 0) ^ 0x9e3779b9, 0x1b873593);
+        x ^= x >>> 16;
+        x = Math.imul(x, 0x85ebca6b);
+        x ^= x >>> 13;
+        x = Math.imul(x, 0xc2b2ae35);
+        x ^= x >>> 16;
+        return (x >>> 0) / 4294967296;
+    }
+    syncAttractorUniforms(mat) {
+        // Guard: ensure our shader uniforms exist (HMR/alternate materials)
+        if (!mat?.uniforms)
+            return;
+        if (mat.uniforms['uAttractorCount'] === undefined)
+            return;
+        // Recompute local-space positions using the CURRENT group transform
+        const n = this.attractorWorldPos.length
+            ? Math.min(this.MAX_ATTRACTORS, this.attractorWorldPos.length)
+            : 0;
+        for (let i = 0; i < n; i++) {
+            const lp = this.group.worldToLocal(this.attractorWorldPos[i].clone());
+            this.attractorLocalPos[i].copy(lp);
+            this.attractorRadius[i] = this.attractorWorldRad[i];
+        }
+        for (let i = n; i < this.MAX_ATTRACTORS; i++) {
+            this.attractorLocalPos[i].set(9999, 9999, 9999);
+            this.attractorRadius[i] = 0;
+        }
+        mat.uniforms['uAttractorCount'].value = n;
+        const arr = mat.uniforms['uAttractorPos'].value;
+        for (let i = 0; i < this.MAX_ATTRACTORS; i++)
+            arr[i].copy(this.attractorLocalPos[i] || new THREE.Vector3(9999, 9999, 9999));
+        const rarr = mat.uniforms['uAttractorRad'].value;
+        for (let i = 0; i < this.MAX_ATTRACTORS; i++)
+            rarr[i] = this.attractorRadius[i] || 0;
+        if (mat.uniforms['uNearFactor'] !== undefined)
+            mat.uniforms['uNearFactor'].value = this.nearRadiusFactor;
+        if (mat.uniforms['uStickEpsRel'] !== undefined)
+            mat.uniforms['uStickEpsRel'].value = this.stickEpsRel;
+        if (mat.uniforms['uStickEpsMin'] !== undefined)
+            mat.uniforms['uStickEpsMin'].value = this.stickEpsMin;
+        if (mat.uniforms['uStickEpsMax'] !== undefined)
+            mat.uniforms['uStickEpsMax'].value = this.stickEpsMax;
+        if (mat.uniforms['uAttractStrength'] !== undefined)
+            mat.uniforms['uAttractStrength'].value = this.attractStrength;
+        if (mat.uniforms['uTangentialBias'] !== undefined)
+            mat.uniforms['uTangentialBias'].value = this.tangentialBias;
+    }
+}
+
+let useBlue = true;
+function generateThemeColor() {
+    const color = useBlue ? '#60a5fa' : '#c084fc'; // Tailwind blue-400 / purple-400
+    useBlue = !useBlue; // alternate next time
+    return color;
+}
+function addNode(cluster, newNodeCounter) {
+    const newId = Date.now();
+    const newName = `New-Node-[${newNodeCounter}]`;
+    const randomPosition = [
+        (Math.random() - 0.5) * 400,
+        (Math.random() - 0.5) * 10,
+        (Math.random() - 0.5) * 400,
+    ];
+    // Determine trait count based on current cluster configuration (central preferences length)
+    const central = cluster.blackholes.find((n) => n.isSupermassiveBlackhole) || null;
+    const traitCount = central
+        ? (Array.isArray(central.preferences) ? central.preferences.length : 5)
+        : 5;
+    function randomAttributes(count = traitCount) {
+        const attrs = {};
+        for (let i = 0; i < count; i++) {
+            attrs[`attr${i + 1}`] = Math.floor(Math.random() * 100);
+        }
+        return attrs;
+    }
+    function randomPreferences(count = traitCount) {
+        const prefs = {};
+        for (let i = 0; i < count; i++) {
+            prefs[`attr${i + 1}`] = Math.floor(Math.random() * 100);
+        }
+        return prefs;
+    }
+    const newNodeData = {
+        id: newId,
+        name: newName,
+        color: '#00001E', // default BH color; matches presets (except Diverse Groups / Match Group A)
+        isSupermassiveBlackhole: false,
+        initialPosition: randomPosition,
+        attributes: randomAttributes(),
+        preferences: randomPreferences(),
     };
-});
-const attributeWeights = weights;
+    const newBlackhole = new Blackhole(newNodeData, cluster.options);
+    cluster.blackholes.push(newBlackhole);
+    cluster.add(newBlackhole);
+    return newNodeCounter + 1;
+}
+function removeNode(cluster, selectedBlackhole, hiddenBlackholes, contextMenuElement) {
+    if (!selectedBlackhole || selectedBlackhole.isSupermassiveBlackhole)
+        return;
+    cluster.remove(selectedBlackhole);
+    const index = cluster.blackholes.indexOf(selectedBlackhole);
+    if (index > -1) {
+        cluster.blackholes.splice(index, 1);
+    }
+    hiddenBlackholes.push(selectedBlackhole);
+    contextMenuElement.style.display = 'none';
+}
+
+function handleRightClick(event, mouse, camera, raycaster, cluster, contextMenuRef, renderer2, setSelectedNode, canvas, containerEl) {
+    event.preventDefault();
+    if (canvas) {
+        const rect = canvas.getBoundingClientRect();
+        mouse.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
+        mouse.y = -((event.clientY - rect.top) / rect.height) * 2 + 1;
+    }
+    else {
+        mouse.x = (event.clientX / window.innerWidth) * 2 - 1;
+        mouse.y = -(event.clientY / window.innerHeight) * 2 + 1;
+    }
+    raycaster.setFromCamera(mouse, camera);
+    const intersects = raycaster.intersectObjects(cluster.children, true);
+    if (intersects.length > 0) {
+        const selected = intersects[0].object.parent;
+        setSelectedNode(selected);
+        const nodeName = selected.userData['name'] || 'Blackhole';
+        const menuElement = contextMenuRef.nativeElement;
+        menuElement.style.display = 'block';
+        menuElement.style.left = `${event.clientX}px`;
+        menuElement.style.top = `${event.clientY}px`;
+        menuElement.querySelector('#contextNodeName').textContent = nodeName;
+        if (containerEl) {
+            const menuRect = menuElement.getBoundingClientRect();
+            const containerRect = containerEl.getBoundingClientRect();
+            const menuWidth = menuRect.width;
+            const menuHeight = menuRect.height;
+            let left = event.clientX;
+            let top = event.clientY;
+            if (top + menuHeight > containerRect.bottom) {
+                top = containerRect.bottom - menuHeight;
+            }
+            if (left < containerRect.left) {
+                left = containerRect.left;
+            }
+            if (left + menuWidth > containerRect.right) {
+                left = containerRect.right - menuWidth;
+            }
+            menuElement.style.left = `${left}px`;
+            menuElement.style.top = `${top}px`;
+        }
+        renderer2.listen('document', 'click', (ev) => {
+            if (menuElement.contains(ev.target))
+                return;
+            menuElement.style.display = 'none';
+        });
+    }
+}
 
 /*
  * Public API Surface of trait-visual
+ *
+ * Canvas component (tv-trait-visual) API for host app / sidenav integration:
+ *
+ * Inputs:
+ *   nodeData: INodeData[]        - Data for each blackhole (required to render).
+ *   attributeWeights: number[]   - Weights for outer blackhole attributes.
+ *   preferenceWeights: number[]  - Weights for supermassive blackhole preferences.
+ *   attributeCount?: number     - Optional override for attribute count.
+ *   preferenceCount?: number    - Optional override for preference count.
+ *
+ * Outputs:
+ *   blackholeSelected: Blackhole | null - Emitted when the user selects a blackhole (e.g. right-click).
+ *   Host app can bind to this for context menu or sidenav (e.g. show details, remove, edit).
  */
 // Main component
 
@@ -2016,5 +5117,5 @@ const attributeWeights = weights;
  * Generated bundle index. Do not edit.
  */
 
-export { TraitVisualComponent, attributeWeights, dynamicCounts, nodeData, updateCounts };
+export { BlackHoleParticleField, Blackhole, Cluster, ConfigSidenavComponent, StellarDustField, TraitVisualComponent, addNode, attributeWeights, dynamicCounts, getWindowLocationSearch, handleRightClick, nodeData, removeNode, updateCounts };
 //# sourceMappingURL=naniteninja-trait-visual.mjs.map