@gratiaos/presence-kernel 1.1.0

package/dist/usePhaseSpatialSound.js

@@ -0,0 +1,206 @@
+import { useEffect, useRef } from 'react';
+import { phase$, peers$, pulse$ } from './index';
+import { DEFAULT_SOUND_PROFILE, PHASE_SOUND_PROFILE } from './phase-sound-profile';
+const LISTEN_EVENTS = ['pointerdown', 'keydown', 'touchstart'];
+const BASE_GAIN = 0.14;
+const filterFrequency = (type) => {
+    switch (type) {
+        case 'lowpass':
+            return 720;
+        case 'bandpass':
+            return 1500;
+        case 'highpass':
+            return 2600;
+        case 'notch':
+            return 1800;
+        default:
+            return 1200;
+    }
+};
+const hashCode = (input) => Array.from(input).reduce((acc, char, index) => acc + char.charCodeAt(0) * (index + 1), 0);
+// Cache per peer so we only compute hash + derived pan/detune once per id.
+// Peer IDs are stable for a session; memory footprint is minimal.
+const peerMetricsCache = new Map();
+const getPeerMetrics = (peerId) => {
+    let cached = peerMetricsCache.get(peerId);
+    if (cached)
+        return cached;
+    const hash = hashCode(peerId);
+    const pan = Math.max(-0.85, Math.min(0.85, Math.sin(hash)));
+    const semitone = (hash % 9) - 4; // discrete integral offset in [-4,4]
+    // Micro‑detune per peer:
+    //   Divide by 24 → range ≈ [-0.1667, +0.1667] semitones (± ~16.7 cents ≈ one sixth of a semitone).
+    //   This is a subtle colorization — previously commented as "quarter‑tone" which would be ~50 cents; kept subtle.
+    const detune = semitone / 24;
+    cached = { hash, pan, detune };
+    peerMetricsCache.set(peerId, cached);
+    return cached;
+};
+const gainForPeer = (pan) => {
+    const centerBoost = 1 - Math.min(Math.abs(pan), 0.85) * 0.45;
+    return 0.028 + centerBoost * 0.018;
+};
+const mergePeers = (ids, selfId) => {
+    const cleaned = ids.filter(Boolean);
+    const unique = Array.from(new Set(cleaned));
+    if (selfId && !unique.includes(selfId))
+        unique.unshift(selfId);
+    return unique;
+};
+export function usePhaseSpatialSound(selfId, enabled = true) {
+    const ctxRef = useRef(null);
+    const masterRef = useRef(null);
+    const readyRef = useRef(false);
+    const pendingRef = useRef([]);
+    const peersRef = useRef(mergePeers(peers$.value, selfId));
+    const profileRef = useRef(DEFAULT_SOUND_PROFILE);
+    useEffect(() => {
+        if (!enabled)
+            return; // gated; cleanup occurs when toggling from enabled→false
+        if (typeof window === 'undefined')
+            return;
+        const win = window;
+        const ensureMaster = () => {
+            const ctx = ctxRef.current;
+            if (!ctx)
+                return false;
+            if (!masterRef.current) {
+                const master = ctx.createGain();
+                master.gain.value = BASE_GAIN;
+                master.connect(ctx.destination);
+                masterRef.current = master;
+            }
+            return true;
+        };
+        const flushPending = () => {
+            if (!readyRef.current || !ensureMaster())
+                return;
+            const queue = pendingRef.current.splice(0, pendingRef.current.length);
+            queue.forEach((fn) => fn());
+        };
+        const ensureContext = (allowResume) => {
+            var _a;
+            const AudioCtx = (_a = win.AudioContext) !== null && _a !== void 0 ? _a : win.webkitAudioContext;
+            if (!AudioCtx)
+                return false;
+            try {
+                if (!ctxRef.current) {
+                    ctxRef.current = new AudioCtx();
+                }
+            }
+            catch {
+                return false;
+            }
+            const ctx = ctxRef.current;
+            if (!ctx)
+                return false;
+            if (ctx.state === 'suspended') {
+                if (!allowResume)
+                    return false;
+                void ctx
+                    .resume()
+                    .then(() => {
+                    readyRef.current = true;
+                    ensureMaster();
+                    flushPending();
+                })
+                    .catch(() => {
+                    /* still locked */
+                });
+                return false;
+            }
+            readyRef.current = true;
+            ensureMaster();
+            flushPending();
+            return true;
+        };
+        const queuePlayback = (fn) => {
+            if (!readyRef.current && !ensureContext(false)) {
+                pendingRef.current.push(fn);
+                return;
+            }
+            readyRef.current = true;
+            if (!ensureMaster()) {
+                pendingRef.current.push(fn);
+                return;
+            }
+            fn();
+        };
+        const unlock = () => {
+            if (ensureContext(true)) {
+                readyRef.current = true;
+                LISTEN_EVENTS.forEach((event) => win.removeEventListener(event, unlock));
+            }
+        };
+        LISTEN_EVENTS.forEach((event) => win.addEventListener(event, unlock, { passive: true }));
+        ensureContext(false);
+        const playPeerTone = (peerId, profile, index) => {
+            const base = profile.root;
+            const { detune, pan: rawPan } = getPeerMetrics(peerId);
+            const frequency = base * Math.pow(2, detune);
+            const pan = peerId === selfId ? 0 : rawPan;
+            const gainAmount = gainForPeer(pan);
+            const delay = index * 0.045;
+            queuePlayback(() => {
+                const ctx = ctxRef.current;
+                const master = masterRef.current;
+                if (!ctx || !master)
+                    return;
+                const start = ctx.currentTime + delay;
+                const osc = ctx.createOscillator();
+                const filter = ctx.createBiquadFilter();
+                const panner = ctx.createStereoPanner();
+                const gain = ctx.createGain();
+                osc.type = 'sine';
+                osc.frequency.setValueAtTime(frequency, start);
+                filter.type = profile.filter;
+                filter.frequency.setValueAtTime(filterFrequency(profile.filter), start);
+                panner.pan.setValueAtTime(pan, start);
+                gain.gain.setValueAtTime(gainAmount, start);
+                gain.gain.exponentialRampToValueAtTime(0.001, start + 0.24);
+                osc.connect(filter);
+                filter.connect(panner);
+                panner.connect(gain);
+                gain.connect(master);
+                osc.start(start);
+                osc.stop(start + 0.26);
+            });
+        };
+        const pulsePeers = (profile) => {
+            const peers = peersRef.current.length ? [...peersRef.current] : selfId ? [selfId] : [];
+            peers.forEach((peerId, index) => playPeerTone(peerId, profile, index));
+        };
+        const phaseSub = phase$.subscribe((phase) => {
+            var _a;
+            const profile = (_a = PHASE_SOUND_PROFILE[phase]) !== null && _a !== void 0 ? _a : DEFAULT_SOUND_PROFILE;
+            profileRef.current = profile;
+        });
+        const peersSub = peers$.subscribe((ids) => {
+            peersRef.current = mergePeers(ids, selfId);
+        });
+        let firstPulse = true;
+        const pulseSub = pulse$.subscribe(() => {
+            if (firstPulse) {
+                firstPulse = false;
+                return;
+            }
+            pulsePeers(profileRef.current);
+        });
+        return () => {
+            phaseSub();
+            peersSub();
+            pulseSub();
+            LISTEN_EVENTS.forEach((event) => win.removeEventListener(event, unlock));
+            pendingRef.current = [];
+            readyRef.current = false;
+            masterRef.current = null;
+            if (ctxRef.current) {
+                void ctxRef.current.close().catch(() => {
+                    /* ignore */
+                });
+                ctxRef.current = null;
+            }
+        };
+    }, [selfId, enabled]);
+}
+//# sourceMappingURL=usePhaseSpatialSound.js.map

package/dist/usePhaseSpatialSound.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePhaseSpatialSound.js","sourceRoot":"","sources":["../src/usePhaseSpatialSound.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@gratiaos/presence-kernel",
+  "version": "1.1.0",
+  "funding": "https://github.com/sponsors/GratiaOS",
+  "type": "module",
+  "license": "AGPL-3.0-only",
+  "description": "Shared presence kernel signals for Gratia OS surfaces.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GratiaOS/garden-core.git",
+    "directory": "packages/presence-kernel"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "./src/heartbeat.css",
+    "./src/constellation-hud.css"
+  ],
+  "peerDependencies": {
+    "react": "^18 || ^19"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rimraf dist"
+  },
+  "dependencies": {
+    "@gratiaos/signal": "workspace:*"
+  },
+  "keywords": [
+    "presence",
+    "signals",
+    "realtime",
+    "kernel",
+    "gratia",
+    "garden",
+    "a11y"
+  ],
+  "devDependencies": {
+    "react": "^19.2.0",
+    "@types/react": "^19.2.2",
+    "typescript": "^5.9.2",
+    "rimraf": "^6.0.1"
+  }
+}

package/src/ConstellationHUD.tsx

@@ -0,0 +1,136 @@
+import React, { useEffect, useMemo, useRef, useState, type CSSProperties } from 'react';
+import { phase$, peers$, pulse$, type Phase } from './index';
+import './constellation-hud.css';
+import { useConstellationAudio } from './useConstellationAudio';
+
+const BASE_RADIUS = 42;
+const RING_GAP = 18;
+const RING_CAPACITY = 10;
+
+const hueFromId = (id: string, index: number) => {
+  const sum = Array.from(id).reduce((acc, char) => acc + char.charCodeAt(0), 0);
+  return (sum + index * 37) % 360;
+};
+
+/**
+ * ConstellationHUD — visual + optional audio pulse for presence peers.
+ *
+ * Audio duplication guard: previously both `usePhaseSpatialSound` and `usePhaseSound`
+ * were invoked unconditionally, causing layered playback on each pulse. We now gate
+ * invocation with `soundMode`:
+ *  • 'spatial' (default) → spatial panning + micro-detune per peer.
+ *  • 'phase'            → single phase tone without spatial layering.
+ *  • 'both'             → preserves legacy behavior (two overlapping systems).
+ *  • 'none'             → suppress audio entirely (visual only).
+ */
+/**
+ * @param soundMode Controls audio playback mode:
+ *  - 'spatial': spatial panning + micro-detune per peer (default)
+ *  - 'phase': single phase tone without spatial layering
+ *  - 'both': legacy behavior with spatial + phase layers stacked
+ *  - 'none': silence all audio, leaving visuals only
+ */
+// Unified audio hook (replaces wrapper components). Underlying hooks are gated
+// via enabled flags; we avoid extra component indirection while keeping Rules of Hooks.
+
+export const ConstellationHUD: React.FC<{ selfId?: string; soundMode?: 'spatial' | 'phase' | 'both' | 'none' }> = ({
+  selfId,
+  soundMode = 'spatial',
+}) => {
+  const [phase, setPhase] = useState<Phase>(phase$.value);
+  const [peerIds, setPeerIds] = useState<string[]>(() => [...peers$.value]);
+  const [pulseActive, setPulseActive] = useState(false);
+  const pulseTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Render audio wrappers conditionally (hooks live inside wrapper components).
+
+  useEffect(() => {
+    const stopPhase = phase$.subscribe((nextPhase) => setPhase(nextPhase));
+    const stopPeers = peers$.subscribe((ids) => setPeerIds(ids));
+
+    return () => {
+      stopPhase();
+      stopPeers();
+      if (pulseTimeoutRef.current) {
+        window.clearTimeout(pulseTimeoutRef.current);
+        pulseTimeoutRef.current = null;
+      }
+    };
+  }, []);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    let first = true;
+    const stop = pulse$.subscribe(() => {
+      if (first) {
+        first = false;
+        return;
+      }
+      setPulseActive(true);
+      if (pulseTimeoutRef.current) {
+        window.clearTimeout(pulseTimeoutRef.current);
+      }
+      pulseTimeoutRef.current = window.setTimeout(() => {
+        setPulseActive(false);
+        pulseTimeoutRef.current = null;
+      }, 520);
+    });
+    return () => {
+      stop();
+      if (pulseTimeoutRef.current) {
+        window.clearTimeout(pulseTimeoutRef.current);
+        pulseTimeoutRef.current = null;
+      }
+    };
+  }, []);
+
+  const peers = useMemo(() => {
+    const sanitized = peerIds
+      .map((id) => id.trim())
+      .filter(Boolean)
+      .sort((a, b) => a.localeCompare(b));
+
+    const rings: string[][] = [];
+    sanitized.forEach((id, index) => {
+      const ringIndex = Math.floor(index / RING_CAPACITY);
+      if (!rings[ringIndex]) rings[ringIndex] = [];
+      rings[ringIndex].push(id);
+    });
+
+    return rings.flatMap((ringPeers, ringIndex) => {
+      const radius = BASE_RADIUS + ringIndex * RING_GAP;
+      const slice = 360 / Math.max(ringPeers.length, 1);
+      return ringPeers.map((id, indexInRing) => {
+        const angle = slice * indexInRing;
+        return {
+          id,
+          transform: `translate(-50%, -50%) rotate(${angle}deg) translateX(${radius}px)`,
+          hue: hueFromId(id, ringIndex + indexInRing),
+          label: id,
+        };
+      });
+    });
+  }, [peerIds]);
+
+  // Invoke unified audio hook (stable call order).
+  useConstellationAudio(soundMode, selfId);
+
+  return (
+    <div className="constellation-hud" data-count={peers.length} data-empty={peers.length === 0 || undefined}>
+      <div className={`peer-core ${pulseActive ? 'pulsing' : ''}`} style={{ background: `var(--color-${phase})` }} title={`local • ${phase}`} />
+      {peers.map((peer) => (
+        <div
+          key={peer.id}
+          className={`peer-dot ${pulseActive ? 'pulsing' : ''}`}
+          style={
+            {
+              background: `hsl(${peer.hue}, 65%, 60%)`,
+              '--orbit-transform': peer.transform,
+            } as CSSProperties & { ['--orbit-transform']: string }
+          }
+          title={peer.label}
+        />
+      ))}
+    </div>
+  );
+};

package/src/Heartbeat.tsx

@@ -0,0 +1,178 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { phase$, mood$, peers$, pulse$, type Phase, type Mood } from './index';
+import './heartbeat.css';
+
+const DEFAULT_COLOR = '#ffffff';
+
+function resolveColor(color: string): [number, number, number] {
+  if (typeof document === 'undefined') return [255, 255, 255];
+  const element = document.createElement('span');
+  element.style.color = color;
+  document.body.appendChild(element);
+  const computed = getComputedStyle(element).color;
+  document.body.removeChild(element);
+  const match = computed.match(/\d+/g)?.map(Number);
+  if (!match || match.length < 3) return [255, 255, 255];
+  return [match[0] ?? 255, match[1] ?? 255, match[2] ?? 255];
+}
+
+function rgbToHsl(r: number, g: number, b: number) {
+  r /= 255;
+  g /= 255;
+  b /= 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  let h = 0;
+  let s = 0;
+  const l = (max + min) / 2;
+
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    switch (max) {
+      case r:
+        h = (g - b) / d + (g < b ? 6 : 0);
+        break;
+      case g:
+        h = (b - r) / d + 2;
+        break;
+      default:
+        h = (r - g) / d + 4;
+        break;
+    }
+    h *= 60;
+  }
+
+  return { h, s: s * 100, l: l * 100 };
+}
+
+function amplitudeForMood(mood: Mood) {
+  if (mood === 'celebratory') return 4;
+  if (mood === 'presence') return 3;
+  if (mood === 'focused') return 2.5;
+  if (mood === 'soft') return 1.8;
+  return 1.5;
+}
+
+export const Heartbeat: React.FC = () => {
+  const [phase, setPhase] = useState<Phase>(phase$.value);
+  const [mood, setMood] = useState<Mood>(mood$.value);
+  const [peerWaves, setPeerWaves] = useState<string[]>(peers$.value);
+  const [pulseActive, setPulseActive] = useState(false);
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const pulseTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    const stopPhase = phase$.subscribe(setPhase);
+    const stopMood = mood$.subscribe(setMood);
+    const stopPeers = peers$.subscribe(setPeerWaves);
+
+    return () => {
+      stopPhase();
+      stopMood();
+      stopPeers();
+    };
+  }, []);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    let first = true;
+    const stop = pulse$.subscribe(() => {
+      if (first) {
+        first = false;
+        return;
+      }
+      setPulseActive(true);
+      if (pulseTimeoutRef.current) {
+        window.clearTimeout(pulseTimeoutRef.current);
+      }
+      pulseTimeoutRef.current = window.setTimeout(() => {
+        setPulseActive(false);
+        pulseTimeoutRef.current = null;
+      }, 520);
+    });
+    return () => {
+      stop();
+      if (pulseTimeoutRef.current) {
+        window.clearTimeout(pulseTimeoutRef.current);
+        pulseTimeoutRef.current = null;
+      }
+    };
+  }, []);
+
+  useEffect(() => {
+    if (typeof window === 'undefined' || typeof document === 'undefined') return;
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return;
+
+    let t = 0;
+    let frame: number;
+
+    const draw = () => {
+      const { width, height } = canvas;
+      ctx.clearRect(0, 0, width, height);
+
+      const computed = getComputedStyle(document.documentElement);
+      const strokeValue = computed.getPropertyValue(`--color-${phase}`).trim() || DEFAULT_COLOR;
+      const [r, g, b] = resolveColor(strokeValue);
+      const { h: baseHue, s: baseSat, l: baseLight } = rgbToHsl(r, g, b);
+      const mainColor = `hsl(${baseHue}, ${baseSat}%, ${baseLight}%)`;
+
+      const drawWave = (color: string, amplitude: number, phaseOffset = 0, opacity = 1) => {
+        ctx.save();
+        ctx.globalAlpha = opacity;
+        ctx.strokeStyle = color;
+        ctx.lineWidth = 1.5;
+        ctx.beginPath();
+        for (let x = 0; x < width; x++) {
+          const y = height / 2 + Math.sin((x + t + phaseOffset) * 0.06) * amplitude;
+          if (x === 0) ctx.moveTo(x, y);
+          else ctx.lineTo(x, y);
+        }
+        ctx.stroke();
+        ctx.restore();
+      };
+
+      drawWave(mainColor, 5 + amplitudeForMood(mood));
+
+      const hueDrift = (offset: number) => (Date.now() / 1000 / 8 + offset) % 360;
+
+      peerWaves.forEach((peerId, index) => {
+        const baseOffset = Array.from(peerId).reduce((sum, char) => sum + char.charCodeAt(0), 0) + index * 45;
+        const peerHue = (baseOffset + hueDrift(index)) % 360;
+        const peerColor = `hsl(${peerHue}, ${Math.min(baseSat + 10, 90)}%, ${Math.min(baseLight + 5, 70)}%)`;
+        drawWave(peerColor, 3 + amplitudeForMood(mood) * 0.6, index * 20, 0.4);
+      });
+
+      t += 2;
+      frame = requestAnimationFrame(draw);
+    };
+
+    draw();
+    return () => cancelAnimationFrame(frame);
+  }, [phase, mood, peerWaves]);
+
+  const color = `var(--color-${phase}, var(--color-${mood}, var(--color-accent)))`;
+  const scale = pulseActive ? 1.2 : 1;
+
+  return (
+    <div className={`heartbeat-wrapper ${pulseActive ? 'pulse-on' : ''}`} style={{ color }} title={`phase: ${phase}, mood: ${mood}`}>
+      <div
+        className="heartbeat"
+        style={{
+          width: '16px',
+          height: '16px',
+          backgroundColor: color,
+          transform: `scale(${scale})`,
+          transition: 'transform 0.3s ease, background 0.6s ease',
+          boxShadow: `0 0 12px ${color}`,
+        }}
+      />
+      <span className="heartbeat-ring" style={{ borderColor: color }} />
+      <span className="heartbeat-ring echo" style={{ borderColor: color }} />
+      <canvas ref={canvasRef} width={80} height={16} className="heartbeat-wave" />
+    </div>
+  );
+};

package/src/constellation-hud.css

@@ -0,0 +1,101 @@
+.constellation-hud {
+  position: fixed;
+  bottom: 2rem;
+  right: 2rem;
+  width: 124px;
+  height: 124px;
+  border-radius: 50%;
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  pointer-events: none;
+  opacity: 0.9;
+  backdrop-filter: blur(18px) saturate(115%);
+  animation: constellation-spin 60s linear infinite;
+  z-index: 95;
+}
+
+.constellation-hud::after {
+  content: '';
+  position: absolute;
+  inset: 10%;
+  border-radius: 50%;
+  background: radial-gradient(closest-side, rgba(255, 255, 255, 0.12), transparent);
+}
+
+.constellation-hud[data-empty='true'] {
+  opacity: 0.6;
+}
+
+.peer-core {
+  width: 14px;
+  height: 14px;
+  border-radius: 9999px;
+  box-shadow: 0 0 14px currentColor;
+}
+
+.peer-core.pulsing {
+  animation: phase-core-pulse 0.8s ease-out;
+}
+
+.peer-dot {
+  --orbit-transform: translate(-50%, -50%);
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 8px;
+  height: 8px;
+  border-radius: 9999px;
+  transform: var(--orbit-transform);
+  box-shadow: 0 0 8px currentColor;
+  opacity: 0.75;
+  transition: opacity 0.45s ease, transform 0.45s ease;
+}
+
+.peer-dot.pulsing {
+  animation: phase-dot-pulse 0.8s ease-out;
+}
+
+.constellation-hud:hover .peer-dot {
+  opacity: 1;
+}
+
+@keyframes constellation-spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@keyframes phase-core-pulse {
+  0% {
+    transform: scale(1);
+    box-shadow: 0 0 12px currentColor;
+  }
+  40% {
+    transform: scale(1.35);
+    box-shadow: 0 0 20px currentColor;
+  }
+  100% {
+    transform: scale(1);
+    box-shadow: 0 0 12px currentColor;
+  }
+}
+
+@keyframes phase-dot-pulse {
+  0% {
+    transform: var(--orbit-transform);
+    box-shadow: 0 0 8px currentColor;
+  }
+  40% {
+    transform: var(--orbit-transform) scale(1.25);
+    box-shadow: 0 0 16px currentColor;
+  }
+  100% {
+    transform: var(--orbit-transform);
+    box-shadow: 0 0 8px currentColor;
+  }
+}