@backbay/glia 0.2.0-alpha.1

package/dist/primitives/three/QuantumField/FieldBus.js

@@ -0,0 +1,278 @@
+/**
+ * Quantum Field Canvas - Signal Bus
+ *
+ * A lightweight external store for DOM → Field event communication.
+ * Uses the useSyncExternalStore pattern for React 18+ integration.
+ */
+import { DEFAULT_FIELD_CONFIG } from "./types";
+// -----------------------------------------------------------------------------
+// Initial State
+// -----------------------------------------------------------------------------
+function createInitialState() {
+    return {
+        impulses: [],
+        anchors: new Map(),
+        hover: {
+            active: false,
+            uv: { x: 0, y: 0 },
+            intent: "probe",
+            velocity: { x: 0, y: 0 },
+            sourceId: null,
+            lastTs: 0,
+        },
+        frame: 0,
+        pendingEvents: [],
+    };
+}
+// -----------------------------------------------------------------------------
+// Bus Factory
+// -----------------------------------------------------------------------------
+export function createFieldBus(initialConfig = {}) {
+    let state = createInitialState();
+    let config = { ...DEFAULT_FIELD_CONFIG, ...initialConfig };
+    const listeners = new Set();
+    // Notify all listeners
+    const notify = () => {
+        listeners.forEach((listener) => listener(state));
+    };
+    // Process hover event - queue for UV computation
+    const handleHover = (event) => {
+        // Queue for UV computation in FieldLayer
+        state = {
+            ...state,
+            pendingEvents: [
+                ...state.pendingEvents.filter((e) => e.kind !== "hover"), // Only keep one hover pending
+                {
+                    kind: "hover",
+                    id: event.id,
+                    clientX: event.clientX,
+                    clientY: event.clientY,
+                    intent: event.intent,
+                    ts: event.ts,
+                },
+            ],
+        };
+    };
+    // Apply hover with computed UV
+    const applyHover = (event, uv) => {
+        const prevHover = state.hover;
+        // Compute velocity from previous position
+        const dt = event.ts - prevHover.lastTs;
+        const velocity = dt > 0 && prevHover.active
+            ? {
+                x: (uv.x - prevHover.uv.x) / dt,
+                y: (uv.y - prevHover.uv.y) / dt,
+            }
+            : { x: 0, y: 0 };
+        state = {
+            ...state,
+            hover: {
+                active: true,
+                uv,
+                intent: event.intent || "probe",
+                velocity,
+                lastTs: event.ts,
+                sourceId: event.id,
+            },
+        };
+    };
+    // Process hover leave event
+    const handleHoverLeave = () => {
+        state = {
+            ...state,
+            hover: {
+                ...state.hover,
+                active: false,
+                sourceId: null,
+            },
+        };
+    };
+    // Process burst event - queue for UV computation
+    const handleBurst = (event) => {
+        state = {
+            ...state,
+            pendingEvents: [
+                ...state.pendingEvents,
+                {
+                    kind: "burst",
+                    id: event.id,
+                    clientX: event.clientX,
+                    clientY: event.clientY,
+                    amplitude: event.amplitude,
+                    radius: event.radius,
+                    ts: event.ts,
+                },
+            ],
+        };
+    };
+    // Apply burst with computed UV
+    const applyBurst = (event, uv) => {
+        const impulse = {
+            uv,
+            startTs: event.ts,
+            amplitude: event.amplitude || 0.8,
+            radius: event.radius || 0.1,
+        };
+        // Add impulse, capping at max
+        const newImpulses = [...state.impulses, impulse].slice(-config.maxImpulses);
+        state = {
+            ...state,
+            impulses: newImpulses,
+        };
+    };
+    // Process latch event - queue for UV computation (except removes)
+    const handleLatch = (event) => {
+        // Removes don't need UV computation
+        if (event.mode === "remove") {
+            const newAnchors = new Map(state.anchors);
+            newAnchors.delete(event.anchorId);
+            state = { ...state, anchors: newAnchors };
+            return;
+        }
+        // Toggle that removes also doesn't need UV
+        if (event.mode === "toggle" && state.anchors.has(event.anchorId)) {
+            const newAnchors = new Map(state.anchors);
+            newAnchors.delete(event.anchorId);
+            state = { ...state, anchors: newAnchors };
+            return;
+        }
+        // Queue for UV computation
+        state = {
+            ...state,
+            pendingEvents: [
+                ...state.pendingEvents,
+                {
+                    kind: "latch",
+                    id: event.id,
+                    clientX: event.clientX,
+                    clientY: event.clientY,
+                    anchorId: event.anchorId,
+                    mode: event.mode,
+                    strength: event.strength,
+                    ts: event.ts,
+                },
+            ],
+        };
+    };
+    // Apply latch with computed UV
+    const applyLatch = (event, uv) => {
+        const newAnchors = new Map(state.anchors);
+        newAnchors.set(event.anchorId, {
+            id: event.anchorId,
+            sourceId: event.id,
+            uv,
+            strength: event.strength || 1,
+            createdTs: event.ts,
+        });
+        // Cap anchors
+        if (newAnchors.size > config.maxAnchors) {
+            const entries = Array.from(newAnchors.entries());
+            const trimmed = entries.slice(-config.maxAnchors);
+            newAnchors.clear();
+            trimmed.forEach(([k, v]) => newAnchors.set(k, v));
+        }
+        state = {
+            ...state,
+            anchors: newAnchors,
+        };
+    };
+    return {
+        emit(event) {
+            switch (event.kind) {
+                case "hover":
+                    handleHover(event);
+                    break;
+                case "hover-leave":
+                    handleHoverLeave();
+                    break;
+                case "burst":
+                    handleBurst(event);
+                    break;
+                case "latch":
+                    handleLatch(event);
+                    break;
+            }
+            notify();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        getSnapshot() {
+            return state;
+        },
+        getServerSnapshot() {
+            return createInitialState();
+        },
+        setConfig(newConfig) {
+            config = { ...config, ...newConfig };
+        },
+        getConfig() {
+            return config;
+        },
+        tick(_deltaMs, currentTs) {
+            // Decay impulses
+            const decayThreshold = config.impulseDecayMs;
+            const activeImpulses = state.impulses.filter((imp) => currentTs - imp.startTs < decayThreshold);
+            // Only update if something changed
+            if (activeImpulses.length !== state.impulses.length) {
+                state = {
+                    ...state,
+                    impulses: activeImpulses,
+                    frame: state.frame + 1,
+                };
+                notify();
+            }
+            else {
+                state = {
+                    ...state,
+                    frame: state.frame + 1,
+                };
+            }
+        },
+        clear() {
+            state = createInitialState();
+            notify();
+        },
+        processPendingWithUv(computeUv) {
+            const pending = state.pendingEvents;
+            if (pending.length === 0)
+                return;
+            // Process all pending events
+            for (const event of pending) {
+                const uv = computeUv(event.clientX, event.clientY);
+                if (!uv)
+                    continue;
+                switch (event.kind) {
+                    case "hover":
+                        applyHover(event, uv);
+                        break;
+                    case "burst":
+                        applyBurst(event, uv);
+                        break;
+                    case "latch":
+                        applyLatch(event, uv);
+                        break;
+                }
+            }
+            // Clear pending events
+            state = {
+                ...state,
+                pendingEvents: [],
+            };
+            notify();
+        },
+    };
+}
+// -----------------------------------------------------------------------------
+// Singleton instance (for simple usage)
+// -----------------------------------------------------------------------------
+let globalBus = null;
+export function getGlobalFieldBus() {
+    if (!globalBus) {
+        globalBus = createFieldBus();
+    }
+    return globalBus;
+}

package/dist/primitives/three/QuantumField/FieldLayer.d.ts

@@ -0,0 +1,22 @@
+import type { FieldConfig } from "./types";
+export interface FieldLayerProps {
+    /** Custom configuration overrides */
+    config?: Partial<FieldConfig>;
+    /** Custom class for the wrapper */
+    className?: string;
+    /** Whether to pin to viewport (fixed) or fill parent (absolute) */
+    pinToViewport?: boolean;
+    /** Z-index for the canvas wrapper */
+    zIndex?: number;
+    /** Camera FOV */
+    fov?: number;
+    /** Camera Z position */
+    cameraZ?: number;
+}
+export declare function FieldLayer({ config: configOverrides, className, pinToViewport, zIndex, fov, cameraZ, }: FieldLayerProps): import("react/jsx-runtime").JSX.Element;
+export interface StandaloneFieldLayerProps extends FieldLayerProps {
+    /** Initial bus configuration */
+    busConfig?: Partial<FieldConfig>;
+}
+export declare function StandaloneFieldLayer({ busConfig, ...props }: StandaloneFieldLayerProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=FieldLayer.d.ts.map

package/dist/primitives/three/QuantumField/FieldLayer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldLayer.d.ts","sourceRoot":"","sources":["../../../../src/primitives/three/QuantumField/FieldLayer.tsx"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,WAAW,EAAqB,MAAM,SAAS,CAAC;AA6T9D,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9B,mCAAmC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,UAAU,CAAC,EACzB,MAAM,EAAE,eAAe,EACvB,SAAS,EACT,aAAoB,EACpB,MAAW,EACX,GAAQ,EACR,OAAY,GACb,EAAE,eAAe,2CAgDjB;AAMD,MAAM,WAAW,yBAA0B,SAAQ,eAAe;IAChE,gCAAgC;IAChC,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;CAClC;AAED,wBAAgB,oBAAoB,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,yBAAyB,2CAatF"}

package/dist/primitives/three/QuantumField/FieldLayer.js

@@ -0,0 +1,307 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Quantum Field Canvas - Field Layer Component
+ *
+ * The main R3F canvas component that renders the reactive field substrate.
+ * Supports multiple visual styles: constellation (A), pcb (B), water (C).
+ */
+import { Canvas, useFrame, useThree } from "@react-three/fiber";
+import { Suspense, useCallback, useEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+import { ConstellationField } from "./ConstellationField";
+import { createFieldBus } from "./FieldBus";
+import { clientToNdc } from "./domMapping";
+import { FieldProvider, useFieldBus } from "./FieldProvider";
+import { PcbField } from "./PcbField";
+import { DEFAULT_FIELD_CONFIG } from "./types";
+import { WaterField } from "./WaterField";
+// -----------------------------------------------------------------------------
+// Debug Shader Material
+// -----------------------------------------------------------------------------
+const DEBUG_VERTEX_SHADER = /* glsl */ `
+varying vec2 vUv;
+
+void main() {
+  vUv = uv;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}
+`;
+const DEBUG_FRAGMENT_SHADER = /* glsl */ `
+uniform float uTime;
+uniform vec4 uHover; // xy = uv, z = intent (0=probe, 1=etch), w = active
+uniform vec4 uImpulses[24]; // xy = uv, z = radius, w = amp
+uniform float uImpulsesAge[24]; // normalized age (0-1, 1 = expired)
+uniform int uImpulseCount;
+uniform vec4 uAnchors[8]; // xy = uv, z = strength, w = phase
+uniform int uAnchorCount;
+
+varying vec2 vUv;
+
+// Subtle grid pattern
+float grid(vec2 uv, float spacing) {
+  vec2 g = abs(fract(uv * spacing - 0.5) - 0.5) / fwidth(uv * spacing);
+  return 1.0 - min(min(g.x, g.y), 1.0);
+}
+
+// Smooth circle
+float circle(vec2 uv, vec2 center, float radius, float softness) {
+  float d = length(uv - center);
+  return 1.0 - smoothstep(radius - softness, radius + softness, d);
+}
+
+// Ring shape
+float ring(vec2 uv, vec2 center, float radius, float thickness, float softness) {
+  float d = length(uv - center);
+  float inner = smoothstep(radius - thickness - softness, radius - thickness, d);
+  float outer = 1.0 - smoothstep(radius, radius + softness, d);
+  return inner * outer;
+}
+
+void main() {
+  vec2 uv = vUv;
+  
+  // Base: very subtle dark with faint grid
+  vec3 baseColor = vec3(0.02, 0.03, 0.05);
+  float gridVal = grid(uv, 20.0) * 0.03;
+  vec3 color = baseColor + vec3(gridVal);
+  
+  // Hover probe effect
+  if (uHover.w > 0.5) {
+    vec2 hoverUv = uHover.xy;
+    float probeRadius = 0.08;
+    float intensity = uHover.z > 0.5 ? 0.4 : 0.25; // etch vs probe
+    
+    float probe = circle(uv, hoverUv, probeRadius, 0.02);
+    vec3 probeColor = uHover.z > 0.5 
+      ? vec3(0.9, 0.2, 0.5) // magenta for etch
+      : vec3(0.1, 0.8, 0.9); // cyan for probe
+    
+    color += probeColor * probe * intensity;
+    
+    // Add subtle crackle near probe
+    float crackle = fract(sin(dot(uv * 100.0 + uTime * 5.0, vec2(12.9898, 78.233))) * 43758.5453);
+    float crackleZone = circle(uv, hoverUv, probeRadius * 1.5, 0.05);
+    color += vec3(0.1, 0.6, 0.7) * crackle * crackleZone * 0.1;
+  }
+  
+  // Impulse rings (bursts)
+  for (int i = 0; i < 24; i++) {
+    if (i >= uImpulseCount) break;
+    
+    vec4 imp = uImpulses[i];
+    float age = uImpulsesAge[i];
+    
+    if (age >= 1.0) continue;
+    
+    vec2 impUv = imp.xy;
+    float baseRadius = imp.z;
+    float amp = imp.w;
+    
+    // Expanding ring
+    float expandedRadius = baseRadius + age * 0.3;
+    float thickness = 0.01 + (1.0 - age) * 0.02;
+    float ringVal = ring(uv, impUv, expandedRadius, thickness, 0.005);
+    
+    // Fade out with age
+    float fade = (1.0 - age) * amp;
+    
+    // Interference pattern
+    float interference = sin((length(uv - impUv) - uTime * 0.5) * 60.0) * 0.5 + 0.5;
+    
+    vec3 ringColor = mix(
+      vec3(0.2, 0.9, 1.0), // cyan
+      vec3(1.0, 0.3, 0.6), // magenta
+      interference
+    );
+    
+    color += ringColor * ringVal * fade;
+  }
+  
+  // Anchors (persistent glowing nodes)
+  for (int i = 0; i < 8; i++) {
+    if (i >= uAnchorCount) break;
+    
+    vec4 anchor = uAnchors[i];
+    vec2 anchorUv = anchor.xy;
+    float strength = anchor.z;
+    float phase = anchor.w;
+    
+    // Pulsing glow
+    float pulse = 0.7 + 0.3 * sin(uTime * 3.0 + phase);
+    float anchorGlow = circle(uv, anchorUv, 0.03, 0.02) * strength * pulse;
+    
+    // Tether-like radial streak
+    vec2 toAnchor = anchorUv - uv;
+    float dist = length(toAnchor);
+    float angle = atan(toAnchor.y, toAnchor.x);
+    float streak = smoothstep(0.1, 0.0, dist) * (0.5 + 0.5 * sin(angle * 8.0 + uTime * 2.0));
+    
+    color += vec3(0.3, 0.9, 0.4) * anchorGlow; // emerald
+    color += vec3(0.2, 0.6, 0.3) * streak * 0.1 * strength;
+  }
+  
+  gl_FragColor = vec4(color, 1.0);
+}
+`;
+// Reusable raycast objects
+const _raycaster = new THREE.Raycaster();
+const _ndcVec = new THREE.Vector2();
+const _intersections = [];
+function FieldPlane({ bus, config }) {
+    const { camera, size, gl } = useThree();
+    const meshRef = useRef(null);
+    // Local refs for state (avoid re-renders)
+    const stateRef = useRef(bus.getSnapshot());
+    // Subscribe to bus updates
+    useEffect(() => {
+        const unsub = bus.subscribe((state) => {
+            stateRef.current = state;
+        });
+        return unsub;
+    }, [bus]);
+    // UV computation via raycast
+    const computeUv = useCallback((clientX, clientY) => {
+        if (!meshRef.current)
+            return null;
+        // Get canvas bounds
+        const canvas = gl.domElement;
+        const rect = canvas.getBoundingClientRect();
+        // Convert client coords to NDC relative to canvas
+        const ndc = clientToNdc(clientX - rect.left, clientY - rect.top, {
+            width: rect.width,
+            height: rect.height,
+        });
+        _ndcVec.set(ndc.x, ndc.y);
+        _raycaster.setFromCamera(_ndcVec, camera);
+        _intersections.length = 0;
+        meshRef.current.raycast(_raycaster, _intersections);
+        if (_intersections.length > 0 && _intersections[0].uv) {
+            return {
+                x: _intersections[0].uv.x,
+                y: _intersections[0].uv.y,
+            };
+        }
+        return null;
+    }, [camera, gl.domElement]);
+    // Create uniforms
+    const uniforms = useMemo(() => ({
+        uTime: { value: 0 },
+        uHover: { value: new THREE.Vector4(0.5, 0.5, 0, 0) },
+        uImpulses: {
+            value: Array(24)
+                .fill(null)
+                .map(() => new THREE.Vector4(0, 0, 0, 0)),
+        },
+        uImpulsesAge: { value: new Float32Array(24) },
+        uImpulseCount: { value: 0 },
+        uAnchors: {
+            value: Array(8)
+                .fill(null)
+                .map(() => new THREE.Vector4(0, 0, 0, 0)),
+        },
+        uAnchorCount: { value: 0 },
+    }), []);
+    // Create shader material
+    const material = useMemo(() => {
+        return new THREE.ShaderMaterial({
+            vertexShader: DEBUG_VERTEX_SHADER,
+            fragmentShader: DEBUG_FRAGMENT_SHADER,
+            uniforms,
+            transparent: true,
+        });
+    }, [uniforms]);
+    // Calculate plane size based on camera
+    const planeSize = useMemo(() => {
+        if (camera instanceof THREE.PerspectiveCamera) {
+            const distance = camera.position.z;
+            const vFov = (camera.fov * Math.PI) / 180;
+            const height = 2 * Math.tan(vFov / 2) * distance;
+            const width = height * (size.width / size.height);
+            return { width: width * 1.2, height: height * 1.2 };
+        }
+        return { width: 20, height: 15 };
+    }, [camera, size]);
+    // Animation frame
+    useFrame((state, delta) => {
+        if (!meshRef.current)
+            return;
+        const currentTs = Date.now();
+        const currentState = stateRef.current;
+        // Process pending events with raycast UV computation
+        bus.processPendingWithUv(computeUv);
+        // Tick the bus
+        bus.tick(delta * 1000, currentTs);
+        // Update time
+        material.uniforms.uTime.value = state.clock.elapsedTime;
+        // Update hover uniform
+        if (currentState.hover.active) {
+            // Convert last known client position to UV via raycast
+            const hover = currentState.hover;
+            material.uniforms.uHover.value.set(hover.uv.x, hover.uv.y, hover.intent === "etch" ? 1 : 0, 1);
+        }
+        else {
+            material.uniforms.uHover.value.w = 0;
+        }
+        // Update impulses
+        const impulses = currentState.impulses;
+        material.uniforms.uImpulseCount.value = impulses.length;
+        for (let i = 0; i < 24; i++) {
+            if (i < impulses.length) {
+                const imp = impulses[i];
+                const age = Math.min(1, (currentTs - imp.startTs) / config.impulseDecayMs);
+                material.uniforms.uImpulses.value[i].set(imp.uv.x, imp.uv.y, imp.radius, imp.amplitude);
+                material.uniforms.uImpulsesAge.value[i] = age;
+            }
+            else {
+                material.uniforms.uImpulsesAge.value[i] = 1;
+            }
+        }
+        // Update anchors
+        const anchors = Array.from(currentState.anchors.values());
+        material.uniforms.uAnchorCount.value = anchors.length;
+        for (let i = 0; i < 8; i++) {
+            if (i < anchors.length) {
+                const anchor = anchors[i];
+                const phase = (currentTs - anchor.createdTs) * 0.001;
+                material.uniforms.uAnchors.value[i].set(anchor.uv.x, anchor.uv.y, anchor.strength, phase);
+            }
+        }
+    });
+    // Dispose material on unmount
+    useEffect(() => {
+        return () => {
+            material.dispose();
+        };
+    }, [material]);
+    return (_jsx("mesh", { ref: meshRef, position: [0, 0, 0], material: material, children: _jsx("planeGeometry", { args: [planeSize.width, planeSize.height] }) }));
+}
+export function FieldLayer({ config: configOverrides, className, pinToViewport = true, zIndex = -1, fov = 50, cameraZ = 10, }) {
+    const bus = useFieldBus();
+    const canvasRef = useRef(null);
+    const wrapperRef = useRef(null);
+    // Merge config
+    const config = useMemo(() => ({ ...DEFAULT_FIELD_CONFIG, ...configOverrides }), [configOverrides]);
+    // Update bus config when it changes
+    useEffect(() => {
+        bus.setConfig(config);
+    }, [bus, config]);
+    const wrapperStyle = {
+        position: pinToViewport ? "fixed" : "absolute",
+        inset: 0,
+        zIndex,
+        pointerEvents: "none",
+        overflow: "hidden",
+    };
+    return (_jsx("div", { ref: wrapperRef, className: className, style: wrapperStyle, "data-field-layer": true, children: _jsx(Canvas, { ref: canvasRef, camera: { position: [0, 0, cameraZ], fov }, dpr: config.dpr, gl: { antialias: true, alpha: true }, style: { background: "transparent" }, children: _jsx(Suspense, { fallback: null, children: config.style === "constellation" ? (_jsx(ConstellationField, { bus: bus, config: config })) : config.style === "pcb" ? (_jsx(PcbField, { bus: bus, config: config })) : config.style === "water" ? (_jsx(WaterField, { bus: bus, config: config })) : (
+                // Fallback to debug plane
+                _jsx(FieldPlane, { bus: bus, config: config })) }) }) }));
+}
+export function StandaloneFieldLayer({ busConfig, ...props }) {
+    const busRef = useRef(null);
+    // Create bus once
+    if (!busRef.current) {
+        busRef.current = createFieldBus(busConfig);
+    }
+    return (_jsx(FieldProvider, { bus: busRef.current, children: _jsx(FieldLayer, { ...props }) }));
+}

package/dist/primitives/three/QuantumField/FieldProvider.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Quantum Field Canvas - Provider & Hooks
+ *
+ * Provides the FieldBus context and helper hooks for DOM components.
+ */
+import React from "react";
+import type { FieldBus } from "./FieldBus";
+import type { FieldConfig, FieldRuntimeState } from "./types";
+export interface FieldProviderProps {
+    children: React.ReactNode;
+    /** Initial configuration */
+    config?: Partial<FieldConfig>;
+    /** Optional external bus instance (for sharing across providers) */
+    bus?: FieldBus;
+}
+export declare function FieldProvider({ children, config, bus: externalBus }: FieldProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Get the field bus instance
+ */
+export declare function useFieldBus(): FieldBus;
+/**
+ * Subscribe to field state changes
+ * Uses useSyncExternalStore for optimal React 18+ integration
+ */
+export declare function useFieldState(): FieldRuntimeState;
+/**
+ * Get field configuration
+ */
+export declare function useFieldConfig(): FieldConfig;
+export interface UseFieldSurfaceOptions {
+    /** Unique identifier for this surface */
+    id: string;
+    /** Enable hover/probe signals */
+    enableHover?: boolean;
+    /** Enable click/burst signals */
+    enableBurst?: boolean;
+    /** Enable selection/latch signals */
+    enableLatch?: boolean;
+    /** Default burst amplitude */
+    burstAmplitude?: number;
+    /** Default burst radius */
+    burstRadius?: number;
+    /** Default latch strength */
+    latchStrength?: number;
+    /** Custom anchor ID (defaults to surface id) */
+    anchorId?: string;
+}
+export interface UseFieldSurfaceReturn {
+    /** Attach to element's onMouseEnter */
+    onMouseEnter: (e: React.MouseEvent) => void;
+    /** Attach to element's onMouseMove */
+    onMouseMove: (e: React.MouseEvent) => void;
+    /** Attach to element's onMouseLeave */
+    onMouseLeave: (e: React.MouseEvent) => void;
+    /** Attach to element's onClick */
+    onClick: (e: React.MouseEvent) => void;
+    /** Manually emit hover event */
+    emitHover: (clientX: number, clientY: number, intent?: "probe" | "etch") => void;
+    /** Manually emit burst event */
+    emitBurst: (clientX: number, clientY: number) => void;
+    /** Manually emit latch event */
+    emitLatch: (clientX: number, clientY: number, mode?: "add" | "remove" | "toggle") => void;
+    /** Clear latch */
+    clearLatch: () => void;
+}
+/**
+ * Hook to instrument a DOM surface for field signals
+ */
+export declare function useFieldSurface(options: UseFieldSurfaceOptions): UseFieldSurfaceReturn;
+/**
+ * Hook that returns field surface handlers if inside a FieldProvider,
+ * otherwise returns no-op handlers. Safe to use anywhere.
+ */
+export declare function useFieldSurfaceOptional(options: UseFieldSurfaceOptions): UseFieldSurfaceReturn;
+//# sourceMappingURL=FieldProvider.d.ts.map

package/dist/primitives/three/QuantumField/FieldProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldProvider.d.ts","sourceRoot":"","sources":["../../../../src/primitives/three/QuantumField/FieldProvider.tsx"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,KAON,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAgB9D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,4BAA4B;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9B,oEAAoE;IACpE,GAAG,CAAC,EAAE,QAAQ,CAAC;CAChB;AAED,wBAAgB,aAAa,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,EAAE,kBAAkB,2CAgBvF;AAMD;;GAEG;AACH,wBAAgB,WAAW,IAAI,QAAQ,CAMtC;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,iBAAiB,CAGjD;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAG5C;AAMD,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,iCAAiC;IACjC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iCAAiC;IACjC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,qCAAqC;IACrC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8BAA8B;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2BAA2B;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6BAA6B;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,uCAAuC;IACvC,YAAY,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC5C,sCAAsC;IACtC,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC3C,uCAAuC;IACvC,YAAY,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC5C,kCAAkC;IAClC,OAAO,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IACvC,gCAAgC;IAChC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,KAAK,IAAI,CAAC;IACjF,gCAAgC;IAChC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACtD,gCAAgC;IAChC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,KAAK,IAAI,CAAC;IAC1F,kBAAkB;IAClB,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CA0JtF;AAiBD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAkJ9F"}