Observer.ts

/**
 * Observer — safe, client-side-only signal detectors (SPEC.md §6, §7).
 *
 * STRICT RULE: this file may ONLY implement the whitelisted detectors below.
 * Never add canvas/WebGL fingerprinting, font enumeration, precise
 * geolocation, timezone-to-city triangulation, or any signal combination
 * that could build a unique identifier. Nothing here is ever persisted,
 * logged, or sent over the network — every value is recomputed on demand
 * and forgotten on refresh.
 */

import type { DetectorName } from '@/types/observation';
import { pickPhase } from '@/core/TimeOfDay';

interface NavigatorUAData {
  platform?: string;
}

interface BatteryManager {
  charging: boolean;
  level: number;
}

interface NetworkInformation {
  effectiveType?: string;
}

/** `navigator.userAgentData` / UA -> coarse OS bucket. */
function detectOs(): string | undefined {
  const uaData = (navigator as Navigator & { userAgentData?: NavigatorUAData }).userAgentData;
  // navigator.platform is deprecated but still the most accurate fallback on
  // browsers without userAgentData (e.g. Safari/Firefox); userAgent is the last resort.
  const platform = uaData?.platform ?? navigator.platform ?? navigator.userAgent;
  if (!platform) return undefined;

  if (/win/i.test(platform)) return 'Windows';
  if (/mac/i.test(platform)) return 'macOS';
  if (/linux/i.test(platform)) return 'Linux';
  return 'other';
}

/** Local clock bucket, reusing TimeOfDay's phase logic plus a lateNight refinement. */
function detectTimeOfDay(): string {
  const now = new Date();
  const hour = now.getHours();
  if (hour >= 0 && hour < 4) return 'lateNight';
  return pickPhase(now);
}

/** Battery Status API -> 'low' | 'charging' | 'normal', or undefined if unsupported. */
async function detectBattery(): Promise<string | undefined> {
  const getBattery = (navigator as Navigator & { getBattery?: () => Promise<BatteryManager> })
    .getBattery;
  if (!getBattery) return undefined;
  try {
    const battery = await getBattery();
    if (battery.charging) return 'charging';
    if (battery.level <= 0.2) return 'low';
    return 'normal';
  } catch {
    return undefined;
  }
}

/** `navigator.connection.effectiveType` -> 'slow' | 'fast', or undefined if unsupported. */
function detectConnection(): string | undefined {
  const connection = (
    navigator as Navigator & { connection?: NetworkInformation }
  ).connection;
  const effectiveType = connection?.effectiveType;
  if (!effectiveType) return undefined;
  return effectiveType === '4g' ? 'fast' : 'slow';
}

/** `prefers-color-scheme` -> 'dark' | 'light'. */
function detectColorScheme(): string {
  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
}

/** `prefers-reduced-motion` -> 'reduce' | 'no-preference'. */
function detectReducedMotion(): string {
  return window.matchMedia('(prefers-reduced-motion: reduce)').matches
    ? 'reduce'
    : 'no-preference';
}

/** `navigator.language`, e.g. 'en-US', 'de'. */
function detectLocale(): string | undefined {
  return navigator.language || undefined;
}

/** `navigator.hardwareConcurrency`, bucketed into 'few' (<=4) or 'many' (>4). */
function detectCores(): string | undefined {
  const cores = navigator.hardwareConcurrency;
  if (typeof cores !== 'number') return undefined;
  return cores <= 4 ? 'few' : 'many';
}

/** `matchMedia('(pointer: coarse)')` -> 'touch' | 'mouse'. */
function detectPointer(): string {
  return window.matchMedia('(pointer: coarse)').matches ? 'touch' : 'mouse';
}

/** Do Not Track / Global Privacy Control -> 'enabled' | 'disabled'. */
function detectPrivacy(): string {
  const dnt = navigator.doNotTrack;
  const gpc = (navigator as Navigator & { globalPrivacyControl?: boolean }).globalPrivacyControl;
  const enabled = dnt === '1' || dnt === 'yes' || gpc === true;
  return enabled ? 'enabled' : 'disabled';
}

/**
 * Resolves every safe detector's current value. Detectors that are
 * unsupported in this browser resolve to `undefined` and are simply
 * omitted from the snapshot (never guessed or defaulted to a fake value).
 *
 * @param osOverride Optional debug-only override (`?os=` — see
 *   debugOverrides.ts) that replaces the real detected OS bucket. Purely a
 *   developer/demo convenience for exercising OS-gated observations
 *   without needing a different machine; never derived from anything the
 *   server sends or any additional browser signal.
 */
export async function resolveSignalSnapshot(
  osOverride?: string,
): Promise<Partial<Record<DetectorName, string>>> {
  const battery = await detectBattery();

  const snapshot: Partial<Record<DetectorName, string>> = {
    os: osOverride ?? detectOs(),
    timeOfDay: detectTimeOfDay(),
    battery,
    connection: detectConnection(),
    colorScheme: detectColorScheme(),
    reducedMotion: detectReducedMotion(),
    locale: detectLocale(),
    cores: detectCores(),
    pointer: detectPointer(),
    privacy: detectPrivacy(),
  };

  for (const key of Object.keys(snapshot) as DetectorName[]) {
    if (snapshot[key] === undefined) {
      delete snapshot[key];
    }
  }

  return snapshot;
}