@gratiaos/presence-kernel 1.1.0

package/src/heartbeat.css

@@ -0,0 +1,75 @@
+.heartbeat-wrapper {
+  position: fixed;
+  bottom: 0.75rem;
+  left: 0.75rem;
+  z-index: 90;
+}
+
+.heartbeat {
+  position: relative;
+  border-radius: 9999px;
+  cursor: pointer;
+}
+
+.heartbeat-ring,
+.heartbeat-ring.echo {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+  transform: translate(-50%, -50%) scale(1);
+  pointer-events: none;
+  opacity: 0;
+  border: 2px solid currentColor;
+}
+
+.heartbeat-wrapper:hover .heartbeat-ring {
+  animation: ring-breath 1.8s ease-out infinite;
+  opacity: 0.7;
+}
+
+.heartbeat-wrapper:hover .heartbeat-ring.echo {
+  animation: ring-breath 1.8s ease-out infinite;
+  animation-delay: 0.9s;
+  opacity: 0.5;
+}
+
+.pulse-on .heartbeat-ring {
+  animation: ring-breath 1.8s ease-out;
+  opacity: 0.6;
+}
+
+.pulse-on .heartbeat-ring.echo {
+  animation: ring-breath 1.8s ease-out;
+  animation-delay: 0.9s;
+  opacity: 0.4;
+}
+
+.heartbeat-wave {
+  position: absolute;
+  left: 24px;
+  bottom: 0;
+  opacity: 0.65;
+  filter: drop-shadow(0 0 4px currentColor);
+  transition: opacity 0.45s ease;
+}
+
+.heartbeat-wrapper:hover .heartbeat-wave {
+  opacity: 1;
+}
+
+@keyframes ring-breath {
+  0% {
+    transform: translate(-50%, -50%) scale(1);
+    opacity: 0.8;
+  }
+  70% {
+    transform: translate(-50%, -50%) scale(2.6);
+    opacity: 0;
+  }
+  100% {
+    opacity: 0;
+  }
+}

package/src/index.ts

@@ -0,0 +1,177 @@
+export type Phase = 'companion' | 'presence' | 'archive' | (string & {});
+export type Mood = 'soft' | 'presence' | 'focused' | 'celebratory' | (string & {});
+
+export type PresenceSnapshot = Readonly<{
+  t: number;
+  phase: Phase;
+  mood: Mood;
+  peers: number;
+  whisper?: string;
+  meta?: Record<string, unknown>;
+}>;
+
+export type KernelEvent =
+  | { type: 'tick'; snap: PresenceSnapshot }
+  | { type: 'phase:set'; phase: Phase; snap: PresenceSnapshot }
+  | { type: 'mood:set'; mood: Mood; snap: PresenceSnapshot }
+  | { type: 'whisper'; message: string; snap: PresenceSnapshot }
+  | { type: 'peer:up'; id: string; snap: PresenceSnapshot }
+  | { type: 'peer:down'; id: string; snap: PresenceSnapshot };
+
+export type Unsubscribe = () => void;
+
+export interface PresenceAdapter {
+  init?(kernel: PresenceKernel): void;
+  onTick?(snap: PresenceSnapshot): void;
+  emit?(evt: KernelEvent): void;
+  dispose?(): void;
+}
+
+export type KernelPlugin = (kernel: PresenceKernel) => void;
+
+import { createSignal, type Signal, type SignalListener } from '@gratiaos/signal';
+// Signals are now sourced from @gratiaos/signal (shared micro observable).
+
+export const phase$ = createSignal<Phase>('presence');
+export const mood$ = createSignal<Mood>('soft'); // phase can be vivid while mood stays gentle by default
+export const peers$ = createSignal<string[]>([]);
+export const pulse$ = createSignal<number>(0);
+
+export const setPhase = (phase: Phase) => phase$.set(phase);
+export const setMood = (mood: Mood) => mood$.set(mood);
+
+export class PresenceKernel {
+  private phase: Phase = 'presence';
+  private mood: Mood = 'soft';
+  private peers = new Map<string, number>();
+  private whisperMsg = '';
+  private listeners = new Set<(event: KernelEvent) => void>();
+  private adapters = new Set<PresenceAdapter>();
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private readonly intervalMs: number;
+  private readonly now: () => number;
+
+  private syncPeers() {
+    peers$.set(Array.from(this.peers.keys()));
+  }
+
+  constructor(intervalMs: number = 1000, now: () => number = () => Date.now()) {
+    this.intervalMs = intervalMs;
+    this.now = now;
+  }
+
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => this.tick(), this.intervalMs);
+    for (const adapter of this.adapters) adapter.init?.(this);
+    this.tick();
+  }
+
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    for (const adapter of this.adapters) adapter.dispose?.();
+  }
+
+  setPhase(next: Phase) {
+    if (this.phase === next) return;
+    this.phase = next;
+    setPhase(next);
+    this.publish({ type: 'phase:set', phase: next, snap: this.snapshot });
+  }
+
+  setMood(next: Mood) {
+    if (this.mood === next) return;
+    this.mood = next;
+    setMood(next);
+    this.publish({ type: 'mood:set', mood: next, snap: this.snapshot });
+  }
+
+  whisper(message: string) {
+    this.whisperMsg = message;
+    this.publish({ type: 'whisper', message, snap: this.snapshot });
+  }
+
+  upsertPeer(id: string) {
+    const isNew = !this.peers.has(id);
+    this.peers.set(id, this.now());
+    if (isNew) this.syncPeers();
+    this.publish({ type: 'peer:up', id, snap: this.snapshot });
+  }
+
+  dropPeer(id: string) {
+    const existed = this.peers.delete(id);
+    if (!existed) return;
+    this.syncPeers();
+    this.publish({ type: 'peer:down', id, snap: this.snapshot });
+  }
+
+  activePeerCount(staleMs = 15_000) {
+    const now = this.now();
+    let changed = false;
+    for (const [id, seen] of Array.from(this.peers)) {
+      if (now - seen > staleMs) {
+        this.peers.delete(id);
+        changed = true;
+        this.publish({ type: 'peer:down', id, snap: this.snapshot });
+      }
+    }
+    if (changed) this.syncPeers();
+    return this.peers.size;
+  }
+
+  use(adapter: PresenceAdapter): this {
+    this.adapters.add(adapter);
+    if (this.timer) adapter.init?.(this);
+    return this;
+  }
+
+  plugin(plugin: KernelPlugin): this {
+    plugin(this);
+    return this;
+  }
+
+  on(listener: (event: KernelEvent) => void): Unsubscribe {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  get snapshot(): PresenceSnapshot {
+    return Object.freeze({
+      t: this.now(),
+      phase: this.phase,
+      mood: this.mood,
+      peers: this.activePeerCount(),
+      whisper: this.whisperMsg || undefined,
+    });
+  }
+
+  private tick() {
+    pulse$.set(pulse$.value + 1);
+    const snap = this.snapshot;
+    this.publish({ type: 'tick', snap });
+    for (const adapter of this.adapters) adapter.onTick?.(snap);
+  }
+
+  private publish(event: KernelEvent) {
+    this.listeners.forEach((listener) => {
+      try {
+        listener(event);
+      } catch {
+        // keep kernel resilient when listeners misbehave
+      }
+    });
+    for (const adapter of this.adapters) adapter.emit?.(event);
+  }
+}
+
+export { Heartbeat } from './Heartbeat';
+export { ConstellationHUD } from './ConstellationHUD';
+
+export { usePhaseSound } from './usePhaseSound';
+export { usePhaseSpatialSound } from './usePhaseSpatialSound';
+
+// Re-export micro signal primitives to preserve historical import patterns
+// for downstream packages that previously consumed signals via presence-kernel.
+export { createSignal } from '@gratiaos/signal';
+export type { Signal, SignalListener } from '@gratiaos/signal';

package/src/phase-sound-profile.ts

@@ -0,0 +1,15 @@
+export type PhaseSoundProfile = {
+  root: number;
+  intervals: number[];
+  interval: number;
+  filter: BiquadFilterType;
+};
+
+export const PHASE_SOUND_PROFILE: Record<string, PhaseSoundProfile> = {
+  presence: { root: 220, intervals: [0, 3, 7], interval: 4500, filter: 'lowpass' },
+  soft: { root: 294, intervals: [0, 4, 7], interval: 3500, filter: 'bandpass' },
+  focused: { root: 392, intervals: [0, 3, 6], interval: 2000, filter: 'highpass' },
+  celebratory: { root: 523.25, intervals: [0, 4, 8], interval: 1500, filter: 'notch' },
+};
+
+export const DEFAULT_SOUND_PROFILE = PHASE_SOUND_PROFILE.presence;

package/src/useConstellationAudio.ts

@@ -0,0 +1,16 @@
+import { usePhaseSpatialSound } from './usePhaseSpatialSound';
+import { usePhaseSound } from './usePhaseSound';
+
+/**
+ * useConstellationAudio — unified audio gating for Constellation HUD.
+ * Always calls underlying hooks (Rules of Hooks) but passes enabled flags
+ * derived from soundMode so audio engines mount/unmount cleanly.
+ */
+export function useConstellationAudio(soundMode: 'spatial' | 'phase' | 'both' | 'none', selfId?: string, opts?: { haptics?: boolean }) {
+  const spatialEnabled = soundMode === 'spatial' || soundMode === 'both';
+  const phaseEnabled = soundMode === 'phase' || soundMode === 'both';
+
+  // Pass enabled flags; underlying hooks early-exit when disabled.
+  usePhaseSpatialSound(selfId, spatialEnabled);
+  usePhaseSound(opts?.haptics ?? false, phaseEnabled);
+}

package/src/usePhaseSound.ts

@@ -0,0 +1,163 @@
+import { useEffect, useRef } from 'react';
+import { phase$ } from './index';
+import { DEFAULT_SOUND_PROFILE, PHASE_SOUND_PROFILE, type PhaseSoundProfile } from './phase-sound-profile';
+
+type AudioWindow = Window & {
+  AudioContext?: typeof AudioContext;
+  webkitAudioContext?: typeof AudioContext;
+};
+
+type PendingTone = {
+  freq: number;
+  duration: number;
+  delay: number;
+  filter: BiquadFilterType;
+};
+
+export function usePhaseSound(enableHaptics = false, enabled: boolean = true) {
+  const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const ctxRef = useRef<AudioContext | null>(null);
+  const readyRef = useRef(false);
+  const pendingRef = useRef<PendingTone[]>([]);
+
+  useEffect(() => {
+    if (!enabled) return; // gated effect; previous teardown runs before disabled state
+    if (typeof window === 'undefined') return;
+
+    const win = window as AudioWindow;
+    const events: Array<keyof WindowEventMap> = ['pointerdown', 'keydown', 'touchstart'];
+
+    const playToneInternal = (frequency: number, duration = 0.25, delay = 0, filterType: BiquadFilterType = 'lowpass') => {
+      const ctx = ctxRef.current;
+      if (!ctx) return;
+
+      const start = ctx.currentTime + Math.max(0, delay);
+      const osc = ctx.createOscillator();
+      const gain = ctx.createGain();
+      const filter = ctx.createBiquadFilter();
+
+      osc.type = 'sine';
+      osc.frequency.setValueAtTime(frequency, start);
+
+      filter.type = filterType;
+      const defaultFreq = 1200;
+      const filterFreq = filterType === 'lowpass' ? 650 : filterType === 'bandpass' ? 1500 : filterType === 'highpass' ? 2600 : defaultFreq;
+      filter.frequency.setValueAtTime(filterFreq, start);
+
+      gain.gain.setValueAtTime(0.05, start);
+      gain.gain.exponentialRampToValueAtTime(0.001, start + duration);
+
+      osc.connect(filter);
+      filter.connect(gain);
+      gain.connect(ctx.destination);
+      osc.start(start);
+      osc.stop(start + duration);
+    };
+
+    const flushPending = () => {
+      if (!ctxRef.current || pendingRef.current.length === 0) return;
+      const pending = pendingRef.current.splice(0, pendingRef.current.length);
+      pending.forEach(({ freq, duration, delay, filter }) => playToneInternal(freq, duration, delay, filter));
+    };
+
+    const removeUnlockListeners = () => {
+      events.forEach((event) => win.removeEventListener(event, unlock));
+    };
+
+    const ensureContext = (allowResume: boolean): boolean => {
+      const AudioCtx = win.AudioContext ?? win.webkitAudioContext;
+      if (!AudioCtx) return false;
+
+      try {
+        if (!ctxRef.current) {
+          ctxRef.current = new AudioCtx();
+        }
+      } catch {
+        return false;
+      }
+
+      if (!ctxRef.current) return false;
+
+      if (ctxRef.current.state === 'suspended') {
+        if (!allowResume) return false;
+        void ctxRef.current
+          .resume()
+          .then(() => {
+            readyRef.current = true;
+            removeUnlockListeners();
+            flushPending();
+          })
+          .catch(() => {
+            // still awaiting gesture
+          });
+        return false;
+      }
+
+      readyRef.current = true;
+      removeUnlockListeners();
+      flushPending();
+      return true;
+    };
+
+    const playTone = (frequency: number, duration: number, delay: number, filter: BiquadFilterType) => {
+      if (!readyRef.current && !ensureContext(false)) {
+        pendingRef.current.push({ freq: frequency, duration, delay, filter });
+        return;
+      }
+      readyRef.current = true;
+      playToneInternal(frequency, duration, delay, filter);
+    };
+
+    const scheduleBaseline = (profile: PhaseSoundProfile) => {
+      if (timerRef.current) {
+        window.clearInterval(timerRef.current);
+        timerRef.current = null;
+      }
+      timerRef.current = window.setInterval(() => {
+        playTone(profile.root, 0.18, 0, profile.filter);
+      }, profile.interval);
+    };
+
+    const unlock = () => {
+      if (ensureContext(true)) {
+        readyRef.current = true;
+        flushPending();
+      }
+    };
+
+    events.forEach((event) => win.addEventListener(event, unlock, { passive: true }));
+
+    // Try to initialize immediately in case interaction already happened
+    ensureContext(false);
+
+    const stopPhase = phase$.subscribe((phase) => {
+      const profile = PHASE_SOUND_PROFILE[phase as keyof typeof PHASE_SOUND_PROFILE] ?? DEFAULT_SOUND_PROFILE;
+
+      profile.intervals.forEach((semi, index) => {
+        const freq = profile.root * Math.pow(2, semi / 12);
+        playTone(freq, 0.25, index * 0.08, profile.filter);
+      });
+
+      if (enableHaptics && typeof navigator !== 'undefined' && 'vibrate' in navigator) {
+        navigator.vibrate?.([30, 60, 30]);
+      }
+
+      scheduleBaseline(profile);
+    });
+
+    return () => {
+      stopPhase();
+      removeUnlockListeners();
+      if (timerRef.current) {
+        window.clearInterval(timerRef.current);
+        timerRef.current = null;
+      }
+      pendingRef.current = [];
+      readyRef.current = false;
+      void ctxRef.current?.close().catch(() => {
+        // ignore close errors
+      });
+      ctxRef.current = null;
+    };
+  }, [enableHaptics, enabled]);
+}

package/src/usePhaseSpatialSound.ts

@@ -0,0 +1,237 @@
+import { useEffect, useRef } from 'react';
+import { phase$, peers$, pulse$ } from './index';
+import { DEFAULT_SOUND_PROFILE, PHASE_SOUND_PROFILE, type PhaseSoundProfile } from './phase-sound-profile';
+
+type AudioWindow = Window & {
+  AudioContext?: typeof AudioContext;
+  webkitAudioContext?: typeof AudioContext;
+};
+
+type PendingPlayback = () => void;
+
+const LISTEN_EVENTS: Array<keyof WindowEventMap> = ['pointerdown', 'keydown', 'touchstart'];
+
+const BASE_GAIN = 0.14;
+
+const filterFrequency = (type: BiquadFilterType) => {
+  switch (type) {
+    case 'lowpass':
+      return 720;
+    case 'bandpass':
+      return 1500;
+    case 'highpass':
+      return 2600;
+    case 'notch':
+      return 1800;
+    default:
+      return 1200;
+  }
+};
+
+const hashCode = (input: string) =>
+  Array.from(input).reduce(
+    (acc, char, index) => (acc + char.charCodeAt(0) * (index + 1)) % 2147483647,
+    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<string, { hash: number; pan: number; detune: number }>();
+
+const getPeerMetrics = (peerId: string) => {
+  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; // 9 discrete steps 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: number) => {
+  const centerBoost = 1 - Math.min(Math.abs(pan), 0.85) * 0.45;
+  return 0.028 + centerBoost * 0.018;
+};
+
+const mergePeers = (ids: string[], selfId?: string) => {
+  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?: string, enabled: boolean = true) {
+  const ctxRef = useRef<AudioContext | null>(null);
+  const masterRef = useRef<GainNode | null>(null);
+  const readyRef = useRef(false);
+  const pendingRef = useRef<PendingPlayback[]>([]);
+  const peersRef = useRef<string[]>(mergePeers(peers$.value, selfId));
+  const profileRef = useRef<PhaseSoundProfile>(DEFAULT_SOUND_PROFILE);
+
+  useEffect(() => {
+    if (!enabled) return; // gated; cleanup occurs when toggling from enabled→false
+    if (typeof window === 'undefined') return;
+
+    const win = window as AudioWindow;
+
+    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: boolean) => {
+      const AudioCtx = win.AudioContext ?? 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: PendingPlayback) => {
+      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: string, profile: PhaseSoundProfile, index: number) => {
+      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: PhaseSoundProfile) => {
+      const peers = peersRef.current.length ? [...peersRef.current] : selfId ? [selfId] : [];
+      peers.forEach((peerId, index) => playPeerTone(peerId, profile, index));
+    };
+
+    const phaseSub = phase$.subscribe((phase) => {
+      const profile = PHASE_SOUND_PROFILE[phase as keyof typeof PHASE_SOUND_PROFILE] ?? 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]);
+}