@naniteninja/trait-visual 1.0.4 → 1.0.7

package/lib/types/canvas-config.d.ts

@@ -0,0 +1,181 @@
+import type { INodeData } from './app.types';
+import type { ISimulationConfigs } from './app.types';
+/**
+ * Payload for a declarative command sent to the canvas.
+ * This is the discriminated union of all possible actions; `CanvasCommand` adds the `seq` field.
+ */
+export type CanvasCommandPayload = {
+    action: 'rotateLeft';
+} | {
+    action: 'rotateRight';
+} | {
+    action: 'panUp';
+} | {
+    action: 'panDown';
+} | {
+    action: 'panLeft';
+} | {
+    action: 'panRight';
+} | {
+    action: 'zoomIn';
+} | {
+    action: 'zoomOut';
+} | {
+    action: 'toggleCameraLock';
+} | {
+    action: 'addNode';
+} | {
+    action: 'removeNode';
+    nodeId: number;
+} | {
+    action: 'setCentral';
+    nodeId: number;
+} | {
+    action: 'setNodeColor';
+    nodeId: number;
+    color: string;
+} | {
+    action: 'updateAttribute';
+    nodeId: number;
+    attrIndex: number;
+    value: number;
+} | {
+    action: 'updatePreference';
+    nodeId: number;
+    prefIndex: number;
+    value: number;
+} | {
+    action: 'setTraitCount';
+    count: number;
+} | {
+    action: 'setNodeData';
+    nodeData: INodeData[];
+};
+/**
+ * Declarative command sent to the canvas via the `command` input.
+ * Bump `seq` each time to trigger Angular change detection, even for repeated identical actions.
+ */
+export type CanvasCommand = CanvasCommandPayload & {
+    seq: number;
+};
+/** Default values used when config or a property is missing. Single source of truth for canvas and sidenav display fallbacks. */
+export declare const TRAIT_VISUAL_CANVAS_DEFAULTS: {
+    readonly selectedPreset: "Maximum Diversity";
+    readonly galaxyParticleSize: 1.5;
+    readonly particleFieldCloudSize: 0.35;
+    readonly nodeSizeScale: 1.05;
+    readonly particleSizeScale: 1;
+    readonly particleDepth: 1.06;
+    readonly lightBlueParticleSizeScale: 1.5;
+    readonly lightBlueParticleDepth: 1.11;
+    readonly nodeHaloParticleSizeScale: 1.1;
+    readonly nodeHaloInfluenceScale: 1.55;
+    readonly particleMovementSmoothing: 1;
+    readonly glowIntensity: 0;
+    readonly interactionCap: 4;
+    readonly galaxyParticleCount: 8192;
+    readonly auraParticleCount: 60;
+    readonly sphereSegments: 16;
+    readonly pixelRatioCap: 1.5;
+    readonly defaultZoomLevel: 1.75;
+    readonly smbhAttraction: 3.7;
+    readonly simulationSpeed: 3.25;
+    readonly blackholeRepulsion: 1;
+    readonly pairwiseRepulsionMain: 20;
+    readonly pairwiseRepulsionSecondary: 55;
+    readonly pairwiseRepulsionMultiplier: 2.7;
+    readonly dissimilarityRepulsionExponent: 2.25;
+    readonly collisionDamping: 0.3;
+    readonly minDistanceWidths: 0.65;
+    readonly maxDistanceWidths: 5;
+};
+/** Configuration passed into TraitVisualCanvasComponent. All canvas behavior is driven by this. */
+export interface ITraitVisualCanvasConfig {
+    /** Node data for the cluster. If not provided, library default is used. */
+    nodeData?: INodeData[];
+    attributeWeights?: number[];
+    preferenceWeights?: number[];
+    simulation?: Partial<ISimulationConfigs>;
+    /** Background color (hex). */
+    backgroundColor?: string;
+    primaryColor?: string;
+    secondaryColor?: string;
+    defaultZoomLevel?: number;
+    /** Simulation/repulsion params (mirror of simulation.blackhole etc.). */
+    smbhAttraction?: number;
+    blackholeRepulsion?: number;
+    pairwiseRepulsionMain?: number;
+    pairwiseRepulsionSecondary?: number;
+    pairwiseRepulsionMultiplier?: number;
+    dissimilarityRepulsionExponent?: number;
+    /** Velocity retention after collision (0 = fully absorb, 1 = elastic bounce). Default 0.3. */
+    collisionDamping?: number;
+    minDistanceWidths?: number;
+    maxDistanceWidths?: number;
+    simulationSpeed?: number;
+    particleSizeScale?: number;
+    particleDepth?: number;
+    /** Light blue (central/SMBH) particle aura size scale; default 1. */
+    lightBlueParticleSizeScale?: number;
+    /** Light blue (central/SMBH) particle depth (0.3–1.05, 1 = surface). */
+    lightBlueParticleDepth?: number;
+    /** Galaxy/background particle field point size (shader uniform; default 2.6). */
+    galaxyParticleSize?: number;
+    /** Scale for entire particle field cloud (default 1, typical range 0.25–3). */
+    particleFieldCloudSize?: number;
+    /** Scale factor for all node spheres (BHs and SMBH); default 1, range typically 0.5–2. */
+    nodeSizeScale?: number;
+    /** Size scale for galaxy (field) particles when pulled onto nodes (halo); default 2, range 0.2–5. */
+    nodeHaloParticleSizeScale?: number;
+    /** Influence radius scale for node halo (how far from node the field particles are pulled); default 1, range 0.3–2. */
+    nodeHaloInfluenceScale?: number;
+    /** Particle movement smoothing (0.05–1): anchor lerp per frame; lower = smoother. Default 0.2. */
+    particleMovementSmoothing?: number;
+    /** Galaxy glow intensity (superScale for glow pass); 0 = off, 2 = default bloom. Range 0–5. */
+    glowIntensity?: number;
+    /** Max galaxy-particle interactions in shader loop; fewer = less GPU work. Range 1–30, default 8. */
+    interactionCap?: number;
+    /** Galaxy point cloud particle count; higher = richer field, more GPU cost. 8192 | 16384 | 32768. */
+    galaxyParticleCount?: number;
+    /** Particles per node aura; fewer = less GPU work per node. Range 20–400, default 200. */
+    auraParticleCount?: number;
+    /** Sphere geometry segments for node meshes; lower = cheaper. Range 8–48, default 24. */
+    sphereSegments?: number;
+    /** Device-pixel-ratio cap for the renderer; lower = smaller render target. Range 0.5–3, default 2. */
+    pixelRatioCap?: number;
+    /** Base URL for textures (scale-texture.png, color-tiles.png, ani-tiles.exr). */
+    assetsBaseUrl?: string;
+}
+/** GPU performance stats emitted by the canvas component for monitoring. */
+export interface IPerfStats {
+    /** Frames per second (averaged over emission interval). */
+    fps: number;
+    /** Last frame time in milliseconds. */
+    frameTimeMs: number;
+    /** Draw calls in the last frame. */
+    drawCalls: number;
+    /** Points rendered in the last frame. */
+    points: number;
+    /** Triangles rendered in the last frame. */
+    triangles: number;
+    /** Geometries currently in GPU memory. */
+    geometries: number;
+    /** Textures currently in GPU memory. */
+    textures: number;
+}
+/** Payload emitted on frameRendered for snapshot recording. */
+export interface ISnapshotPayload {
+    cluster: {
+        blackholes: Array<{
+            position: {
+                x: number;
+                y: number;
+                z: number;
+            };
+            userData: Record<string, unknown>;
+            isSupermassiveBlackhole: boolean;
+        }>;
+    } | null;
+    attributeWeights: number[];
+    simulationSpeed?: number;
+}

package/lib/types/node-info.type.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Plain-data representation of a node, emitted via component outputs.
+ * Consumers should use this instead of internal Blackhole/Cluster classes.
+ */
+export interface INodeInfo {
+    id: number;
+    name: string;
+    isSupermassiveBlackhole: boolean;
+    color: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    attributes: number[];
+    preferences: number[];
+}

package/lib/types/particle-field.types.d.ts

@@ -10,6 +10,8 @@ export interface IParticleFieldOptions {
     surfaceRadiusMin?: number;
     surfaceRadiusMax?: number;
     rimMinShellFactor?: number;
+    /** Anchor smoothing (0–1): lerp factor per frame toward node position; lower = smoother. Default 0.2. */
+    anchorSmooth?: number;
 }
 export interface IFlowParticle {
     type: 'topCurve' | 'bottomCurve' | 'orbit' | 'topCap' | 'bottomCap' | 'surface';

package/lib/utils/createShaderMaterial.d.ts

@@ -0,0 +1,8 @@
+import * as THREE from 'three';
+interface CreateMaterialOptions {
+    vertexShader: string;
+    fragmentShader: string;
+    uniforms: Record<string, THREE.IUniform>;
+}
+export declare function createShaderMaterial({ vertexShader, fragmentShader, uniforms }: CreateMaterialOptions): THREE.RawShaderMaterial;
+export {};

package/lib/utils/createUniforms.d.ts

@@ -0,0 +1,2 @@
+import * as THREE from 'three';
+export declare function createUniforms(): Record<string, THREE.IUniform<any>>;

package/lib/utils/debug-ingest.constants.d.ts

@@ -0,0 +1,2 @@
+/** Base URL for debug ingest when ?debug=1 is in the URL. Empty = no request (library default). */
+export declare const DEBUG_INGEST_URL = "";

package/lib/utils/debug-ingest.d.ts

@@ -0,0 +1,12 @@
+export interface IDebugIngestPayload {
+    hypothesisId: string;
+    location: string;
+    message: string;
+    data: Record<string, unknown>;
+    timestamp: number;
+}
+/**
+ * Sends a payload to the debug ingest endpoint when ?debug=1 is in the URL.
+ * Uses RxJS (no Promises). No-op when debug is not enabled.
+ */
+export declare function logDebugIngest(payload: IDebugIngestPayload, searchOverride?: string): void;

package/lib/utils/galaxyGeometryForPhase.d.ts

@@ -0,0 +1 @@
+export declare function getGalaxyGeometryForPhase(count: number, extent: number): Float32Array<ArrayBufferLike>;

package/lib/utils/window.util.d.ts

@@ -3,5 +3,5 @@
  * Use instead of (window as any)?.location?.search to satisfy strict typing.
  */
 export declare function getWindowLocationSearch(): string;
-/** True when URL has debug=1 (enables optional ingest logging). */
-export declare function isDebugIngestEnabled(): boolean;
+/** True when URL has debug=1 (enables optional ingest logging). @param searchOverride - for tests only; when set, used instead of window.location.search */
+export declare function isDebugIngestEnabled(searchOverride?: string): boolean;

package/package.json

@@ -1,37 +1,20 @@
 {
   "name": "@naniteninja/trait-visual",
-  "version": "1.0.4",
-  "description": "Angular library for visualizing trait-based relationships in 3D space using Three.js",
-  "keywords": [
-    "angular",
-    "three.js",
-    "visualization",
-    "3d",
-    "traits",
-    "pca",
-    "personality",
-    "test"
-  ],
-  "author": "naniteninja",
-  "license": "MIT",
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "restricted"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/naniteninja/trait-visual.git"
-  },
+  "version": "1.0.7",
+  "description": "Angular 3D trait visualization canvas (Three.js)",
   "peerDependencies": {
     "@angular/common": "^20.0.0",
     "@angular/core": "^20.0.0"
   },
   "dependencies": {
+    "tslib": "^2.3.0",
     "three": "^0.174.0",
-    "ml-pca": "^4.1.1",
-    "tslib": "^2.3.0"
+    "ml-pca": "^4.1.1"
   },
   "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
   "module": "fesm2022/naniteninja-trait-visual.mjs",
   "typings": "index.d.ts",
   "exports": {

package/public-api.d.ts

@@ -1,12 +1,10 @@
-export * from './lib/trait-visual.component';
-export * from './lib/config-sidenav/config-sidenav.component';
-export * from './lib/app.types';
-export { Cluster } from './lib/objects/Cluster';
+export { TraitVisualCanvasComponent } from './lib/trait-visual-canvas/trait-visual-canvas.component';
+export type { ITraitVisualCanvasConfig, ISnapshotPayload, IPerfStats, CanvasCommand, CanvasCommandPayload, } from './lib/types/canvas-config';
+export { TRAIT_VISUAL_CANVAS_DEFAULTS } from './lib/types/canvas-config';
+export type { INodeData, IHumanAttributes, IBlackholeUserData, ITraitVisualConfigState, ConfigChangePayload, IPresetConfig, ISimulationConfigs, } from './lib/types/app.types';
+export type { INodeInfo } from './lib/types/node-info.type';
+/** @deprecated Use INodeInfo for output event types instead of Blackhole instances. */
 export { Blackhole } from './lib/objects/Blackhole';
-export { StellarDustField } from './lib/services/stellar-dust-field';
-export type { DustMode } from './lib/services/stellar-dust-field';
-export { addNode, removeNode } from './lib/services/node-actions';
-export { BlackHoleParticleField } from './lib/services/black-hole-particle-field';
-export { handleRightClick } from './lib/utils/on-right-click.util';
-export { getWindowLocationSearch } from './lib/utils/window.util';
-export { dynamicCounts, updateCounts, attributeWeights, nodeData } from './lib/data/nodes.data';
+/** @deprecated Use INodeInfo for output event types instead of Cluster/Blackhole instances. */
+export { Cluster } from './lib/objects/Cluster';
+export { nodeData as defaultNodeData, attributeWeights } from './lib/data/nodes.data';

package/lib/config-sidenav/config-sidenav.component.d.ts

@@ -1,30 +0,0 @@
-import { EventEmitter } from '@angular/core';
-import type { ITraitVisualConfigState, ConfigChangePayload, INodeData } from '../app.types';
-import * as i0 from "@angular/core";
-export declare class ConfigSidenavComponent {
-    config: ITraitVisualConfigState;
-    open: boolean;
-    configChange: EventEmitter<ConfigChangePayload>;
-    /** Active tab: 'docs' shows documentation, 'configs' shows configuration UI. */
-    activeTab: 'docs' | 'configs';
-    setActiveTab(tab: 'docs' | 'configs'): void;
-    get centralNode(): INodeData | null;
-    get nonSupermassiveBlackholeNodes(): INodeData[];
-    traitCount(): number;
-    centralPrefsArray(): number[];
-    nodeAttrsArray(node: INodeData): number[];
-    onPresetChange(value: string): void;
-    onWeightChange(index: number, value: number): void;
-    onPrefWeightChange(index: number, value: number): void;
-    onSimulationSpeedChange(value: number): void;
-    onBlackholeRepulsionChange(value: number): void;
-    onTraitCountChange(count: number): void;
-    onCentralPreferenceChange(index: number, value: number): void;
-    onNodeAttributeChange(nodeId: number, attrIndex: number, value: number): void;
-    onAddNode(): void;
-    onRemoveNode(nodeId: number): void;
-    onShowContextMenuChange(value: boolean): void;
-    onDefaultZoomLevelChange(value: number): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<ConfigSidenavComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<ConfigSidenavComponent, "tv-config-sidenav", never, { "config": { "alias": "config"; "required": false; }; "open": { "alias": "open"; "required": false; }; }, { "configChange": "configChange"; }, never, ["[config-appearance]", "[config-simulation-extra]"], true, never>;
-}

package/lib/trait-visual.component.d.ts

@@ -1,85 +0,0 @@
-import { ElementRef, EventEmitter, OnInit, AfterViewInit, OnDestroy, Renderer2, NgZone, OnChanges, SimpleChanges } from '@angular/core';
-import * as THREE from 'three';
-import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
-import { INodeData, ISimulationConfigs } from './app.types';
-import { Cluster } from './objects/Cluster';
-import { Blackhole } from './objects/Blackhole';
-import * as i0 from "@angular/core";
-export declare class TraitVisualComponent implements OnInit, AfterViewInit, OnDestroy, OnChanges {
-    private renderer2;
-    private ngZone;
-    canvasRef: ElementRef;
-    nodeData: INodeData[];
-    attributeWeights: number[];
-    preferenceWeights: number[];
-    attributeCount?: number;
-    preferenceCount?: number;
-    simulationOptions?: Partial<ISimulationConfigs>;
-    /** When true, right-click on a node can show the context menu (when implemented). Default false. */
-    showContextMenu: boolean;
-    /** Default zoom level: multiplier on initial camera distance (1 = normal, > 1 = zoom out more). Default 1.25. */
-    defaultZoomLevel: number;
-    /** Emits when the user selects a blackhole (e.g. via right-click). Host app can use this for context menu or sidenav. */
-    blackholeSelected: EventEmitter<Blackhole | null>;
-    scene: THREE.Scene;
-    camera: THREE.PerspectiveCamera;
-    renderer: THREE.WebGLRenderer;
-    controls: OrbitControls;
-    raycaster: THREE.Raycaster;
-    mouse: THREE.Vector2;
-    cluster: Cluster;
-    selectedNode: Blackhole | null;
-    draggingNode: Blackhole | null;
-    dragPlane: THREE.Plane;
-    dragOffset: THREE.Vector3;
-    newNodeCounter: number;
-    isCameraLocked: boolean;
-    private nodeAuras;
-    private starFieldNear;
-    private starFieldFar;
-    private starTexture;
-    private dustField;
-    private readonly pointerPitchAxis;
-    private readonly pointerYawAxis;
-    private pointerPitchCurrent;
-    private pointerPitchTarget;
-    private pointerYawCurrent;
-    private pointerYawTarget;
-    private pointerYawAccumulated;
-    private readonly pointerOffset;
-    private readonly pointerPitchMax;
-    private readonly pointerYawMax;
-    private readonly pointerYawSpeed;
-    private readonly pointerPitchDamping;
-    private readonly pointerYawDamping;
-    /** Reused buffer for dust-field attractors (avoids per-frame allocations). */
-    private readonly _attractorsBuffer;
-    private readonly _centerFallback;
-    constructor(renderer2: Renderer2, ngZone: NgZone);
-    ngOnInit(): void;
-    ngOnChanges(changes: SimpleChanges): void;
-    /** Apply defaultZoomLevel to camera: same direction from target, scaled distance. */
-    private applyDefaultZoomLevel;
-    ngAfterViewInit(): void;
-    ngOnDestroy(): void;
-    currentSupermassiveBlackhole(): Blackhole | null;
-    nonSupermassiveBlackholes(): Blackhole[];
-    private syncNodeWeightGlobals;
-    private initScene;
-    private loadNodes;
-    private onWindowResize;
-    private onRightClick;
-    private onMouseMove;
-    private onDragStart;
-    private onDragMove;
-    private onDragEnd;
-    private onCanvasLeave;
-    private resetPointerPitch;
-    private updateCameraOrbitFromPointer;
-    private animate;
-    private ensureNodeAuras;
-    private createStarField;
-    private getStarTexture;
-    static ɵfac: i0.ɵɵFactoryDeclaration<TraitVisualComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<TraitVisualComponent, "tv-trait-visual", never, { "nodeData": { "alias": "nodeData"; "required": false; }; "attributeWeights": { "alias": "attributeWeights"; "required": false; }; "preferenceWeights": { "alias": "preferenceWeights"; "required": false; }; "attributeCount": { "alias": "attributeCount"; "required": false; }; "preferenceCount": { "alias": "preferenceCount"; "required": false; }; "simulationOptions": { "alias": "simulationOptions"; "required": false; }; "showContextMenu": { "alias": "showContextMenu"; "required": false; }; "defaultZoomLevel": { "alias": "defaultZoomLevel"; "required": false; }; }, { "blackholeSelected": "blackholeSelected"; }, never, never, true, never>;
-}

package/lib/utils/on-right-click.util.d.ts

@@ -1,4 +0,0 @@
-import * as THREE from 'three';
-import { Blackhole } from '../objects/Blackhole';
-import { ElementRef, Renderer2 } from '@angular/core';
-export declare function handleRightClick(event: MouseEvent, mouse: THREE.Vector2, camera: THREE.Camera, raycaster: THREE.Raycaster, cluster: THREE.Object3D, contextMenuRef: ElementRef, renderer2: Renderer2, setSelectedNode: (blackhole: Blackhole) => void, canvas?: HTMLCanvasElement | null, containerEl?: HTMLElement | null): void;