@zafu/media 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Penumbra Labs (upstream: prax-wallet/prax, penumbra-zone/web)
+Copyright (c) 2025-2026 Rotko Networks OÜ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# @zafu/media
+
+Framework-agnostic P2P media primitives for [zafu](https://zafu.pro) - opt-in WebRTC voice/video with perfect negotiation, Meet-style background blur, and pluggable signaling.
+
+```sh
+npm install @zafu/media
+```
+
+## What it is
+
+A call is **direct P2P**: audio and video never touch a server. Only the SDP/ICE setup has to travel, and you inject that transport - so pointing it at a `@zafu/zid` Noise channel makes call setup end-to-end, post-quantum encrypted as well.
+
+Nothing heavy is dragged in unless you ask for it. No UI framework is imported - state is exposed as `Readable<T>` (a getter that is also `.subscribe`-able). Blur is an injected factory. `@mediapipe/tasks-vision` is an _optional_ peer dependency, loaded lazily and only when you pass `blur`.
+
+## Quick start
+
+```ts
+import { createCall, createVideoBlur, zidSignaling } from '@zafu/media';
+
+const call = createCall({
+  signaling: zidSignaling(zidChannel), // SDP/ICE over the E2EE channel
+  polite: myId < peerId, // exactly one side must be polite
+  blur: () => createVideoBlur(), // optional - omit it and blur costs nothing
+});
+
+call.acknowledge(); // consent gate - nothing connects before this
+await call.toggleMic();
+await call.toggleCam();
+
+call.remoteStream.subscribe(s => {
+  if (s) videoEl.srcObject = s;
+});
+```
+
+## Opt-in, or nothing happens
+
+Media is hard opt-in, because a direct connection reveals each peer's IP to the other. Until `acknowledge()` is called:
+
+- `getUserMedia` is never called and no `RTCPeerConnection` is created;
+- inbound SDP/ICE is **ignored**, so a remote peer cannot force a connection (or a candidate-gathering IP probe);
+- `incomingPending` flips to `true` when the peer offers - render your own prompt, then `acknowledge()` or `dismissIncoming()`.
+
+`revoke()` stops the tracks, closes the connection and re-arms the gate; the `Call` stays subscribed, so a later `acknowledge()` can connect again. `cleanup()` is the final teardown - it also unsubscribes from signaling.
+
+## ICE defaults (privacy-first)
+
+`iceServers` defaults to `[]` - host candidates only. No TURN (it would relay your media through a server, defeating "media is direct") and no third-party STUN (it would hand a third party your reflexive IP). This connects on reachable networks and may fail behind symmetric NAT; that is the deliberate default. Pass your own `iceServers` - a self-hosted STUN, typically - to change it.
+
+## Background blur (optional)
+
+`createVideoBlur()` segments each outgoing frame (MediaPipe selfie segmenter) and composites a sharp person over a blurred or replaced background, exposed as a canvas `MediaStream` and swapped into the sender with `replaceTrack()` - no renegotiation.
+
+```ts
+const blur = createVideoBlur({ assetBase: '/mediapipe', blurPx: 14 });
+const call = createCall({ signaling, polite, blur: () => blur });
+
+await call.setBlurMode('blur'); // 'off' | 'blur' | 'image'
+call.setBlurImage(myImageBitmap); // used by 'image' mode
+```
+
+**Assets are same-origin.** The wasm runtime and the `.tflite` model are served from `assetBase` (default `/mediapipe`) - vendor `@mediapipe/tasks-vision`'s wasm directory and `selfie_segmenter.tflite` there. Nothing is fetched from a CDN. MediaPipe compiles wasm at load time, so a strict CSP needs `script-src 'wasm-unsafe-eval'` (this does not re-open JS `eval`).
+
+If the model fails to initialise, `setBlurMode` rejects, `blurUnavailable` goes true, and the **raw camera track keeps being sent** - never a black frame.
+
+## Errors
+
+`lastError` carries the last unrecovered failure, tagged with the step to re-run and a kind you can branch on:
+
+```ts
+call.lastError.subscribe(e => {
+  if (e) showBanner(e.message); // { step: 'mic'|'cam'|'connect', kind: 'denied'|'busy'|'notfound'|'negotiation'|'unknown' }
+});
+await call.retry(); // re-runs the failed step; idempotent
+call.clearError(); // or just dismiss the banner
+```
+
+## Bridging to your framework
+
+```ts
+// React - Readable is a getter plus a subscribe, i.e. exactly useSyncExternalStore's shape
+const micOn = useSyncExternalStore(call.micEnabled.subscribe, call.micEnabled);
+
+// SolidJS / plain JS
+const stop = call.connected.subscribe(up => setState({ up }));
+```
+
+## Signaling
+
+`Signaling` is `send(msg)` + `onSignal(handler)` over two message kinds: `_sdp` and `_ice`. `zidSignaling(channel, tag = 0xf0)` bridges a `@zafu/zid` `ZidChannel` (or anything with `send`/`on('message')`) by JSON-framing those messages behind a one-byte tag, so media control never collides with your own chat frames - frames that do not start with the tag are left untouched for the app's own handler.
+
+Written your own transport? Implement the two methods:
+
+```ts
+const signaling: Signaling = {
+  send: msg => socket.send(JSON.stringify(msg)),
+  onSignal: handler => {
+    socket.on('message', handler);
+    return () => socket.off('message', handler);
+  },
+};
+```
+
+One `Call` talks to exactly one peer.
+
+## API
+
+| Export                        | Purpose                                                                                                                           |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `createCall(options)`         | Start a call session → `Call`. `options`: `signaling`, `polite`, `iceServers?`, `video?` (default 320x240 front camera), `blur?`. |
+| `createVideoBlur(options?)`   | Background processing for an outgoing track → `VideoBlur`. `options`: `assetBase?`, `modelFile?`, `blurPx?`.                      |
+| `zidSignaling(channel, tag?)` | Bridge a byte channel into `Signaling` for SDP/ICE.                                                                               |
+| `writable(initial)`           | `[read, write]` - the reactive primitive the call state is built on, if you want your own.                                        |
+
+`Call`: `localStream`, `remoteStream`, `micEnabled`, `camEnabled`, `connected`, `acknowledged`, `incomingPending`, `blurMode`, `blurUnavailable`, `lastError` (all `Readable`), plus `acknowledge()`, `revoke()`, `dismissIncoming()`, `toggleMic()`, `toggleCam()`, `setBlurMode(mode)`, `setBlurImage(img)`, `retry()`, `clearError()`, `cleanup()`.
+
+`VideoBlur`: `outputTrack()`, `mode()`, `ready()`, `setMode(mode, source?)`, `setBackgroundImage(img)`, `stop()`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Blur types with NO dependency on `@mediapipe/tasks-vision`.
+ *
+ * Kept separate from blur.ts (the implementation, which type-imports MediaPipe)
+ * so that consumers using only createCall - and injecting or omitting blur - can
+ * type-check without the optional mediapipe peer dep being installed.
+ */
+type BlurMode = 'off' | 'blur' | 'image';
+interface VideoBlur {
+    /** the processed outgoing track (canvas capture). null until a non-off setMode(). */
+    outputTrack: () => MediaStreamTrack | null;
+    /** current mode. */
+    mode: () => BlurMode;
+    /**
+     * Switch modes at runtime. 'off' stops the processing loop and the caller
+     * should replaceTrack() back to the raw camera track. Resolves once applied.
+     * Throws if the segmenter could not initialise (caller falls back to raw).
+     */
+    setMode: (m: BlurMode, source?: MediaStreamTrack) => Promise<void>;
+    /** provide/replace the background image (used by 'image' mode). */
+    setBackgroundImage: (img: HTMLImageElement | ImageBitmap | null) => void;
+    /** true once MediaPipe initialised successfully. */
+    ready: () => boolean;
+    /** tear everything down and release the model + canvas track. */
+    stop: () => void;
+}
+interface VideoBlurOptions {
+    /**
+     * Same-origin base URL holding the vendored MediaPipe wasm + model. The host
+     * app copies `@mediapipe/tasks-vision`'s wasm dir and the selfie segmenter
+     * `.tflite` here. Default '/mediapipe'.
+     */
+    assetBase?: string;
+    /** model file name under assetBase. Default 'selfie_segmenter.tflite'. */
+    modelFile?: string;
+    /** background blur strength in px (canvas filter). Default 10. */
+    blurPx?: number;
+}
+
+/**
+ * Pluggable signaling transport for the media session.
+ *
+ * The call only needs to move two kinds of tiny control messages to the peer -
+ * SDP descriptions and ICE candidates. It does NOT care how they travel. The
+ * host app injects a `Signaling` and thereby chooses the transport:
+ *
+ *   - zitadel: over a `@zafu/zid` Noise channel (see zidSignaling) - so call
+ *     setup is itself end-to-end, post-quantum encrypted.
+ *   - poker: over its existing encrypted blind relay.
+ *
+ * Media (the audio/video RTP) never flows through here - it is direct P2P once
+ * ICE connects. Only offer/answer/candidate setup rides this channel.
+ */
+type MediaSignal = {
+    t: '_sdp';
+    d: {
+        sdp: RTCSessionDescriptionInit;
+    };
+} | {
+    t: '_ice';
+    d: {
+        candidate: RTCIceCandidateInit;
+    };
+};
+interface Signaling {
+    /** Send a control message to the single remote peer. */
+    send(msg: MediaSignal): void;
+    /** Register the inbound handler. Returns an unsubscribe function. */
+    onSignal(handler: (msg: MediaSignal) => void): () => void;
+}
+/** A `@zafu/zid`-style encrypted channel: send bytes, receive bytes. */
+interface ByteChannel {
+    send(data: string | Uint8Array): void;
+    on(event: 'message', handler: (data: Uint8Array) => void): void;
+}
+/**
+ * Bridge a `@zafu/zid` ZidChannel (or any ByteChannel) into `Signaling`, so
+ * SDP/ICE ride the same E2EE channel as the DMs. Messages are JSON, framed with
+ * a 1-byte tag so media control never collides with the app's own chat frames.
+ *
+ * @param tag byte prefix distinguishing media-signal frames (default 0xF0).
+ */
+declare function zidSignaling(channel: ByteChannel, tag?: number): Signaling;
+
+/**
+ * A minimal framework-agnostic reactive value.
+ *
+ * `Readable<T>` is BOTH a getter (`value()`) - so it drops straight into a
+ * SolidJS template like a signal - AND a `.subscribe(fn)` source, so a React
+ * consumer can bridge it with `useSyncExternalStore` and plain JS can just
+ * listen. No framework is imported here; consumers adapt it to theirs.
+ */
+interface Readable<T> {
+    (): T;
+    subscribe(fn: (value: T) => void): () => void;
+}
+type Writable<T> = [read: Readable<T>, write: (value: T) => void];
+declare function writable<T>(initial: T): Writable<T>;
+
+/**
+ * Opt-in P2P voice/video call primitive (framework-agnostic).
+ *
+ * Ported from the poker media layer. All reactive state is exposed as
+ * `Readable<T>` (a getter that is also `.subscribe`-able), so it drops into
+ * SolidJS as a signal, bridges to React via useSyncExternalStore, or is polled
+ * from plain JS. No UI framework is imported.
+ *
+ * PRIVACY / OPT-IN. Media connects the two clients DIRECTLY (audio/video never
+ * touches a server), which necessarily reveals each peer's IP to the other.
+ * Therefore media is HARD opt-in: nothing calls getUserMedia and no
+ * RTCPeerConnection is created until `acknowledge()`. Incoming SDP/ICE is
+ * ignored until then, so a remote peer cannot force a connection (or a
+ * candidate-gathering IP probe) before we consent. `revoke()` tears down and
+ * re-arms the gate.
+ *
+ * ICE default: EMPTY iceServers (host candidates only) - no TURN (would relay
+ * media through a server, defeating "media is direct"), no third-party STUN
+ * (would hand a third party the reflexive IP). Connects on reachable networks;
+ * may fail behind symmetric NAT - the privacy-first default. Pass your own
+ * `iceServers` (e.g. a self-hosted STUN) to change this.
+ */
+
+type MediaErrorStep = 'mic' | 'cam' | 'connect';
+type MediaErrorKind = 'denied' | 'busy' | 'notfound' | 'negotiation' | 'unknown';
+interface MediaError {
+    step: MediaErrorStep;
+    kind: MediaErrorKind;
+    message: string;
+}
+interface CallOptions {
+    /** SDP/ICE transport. See Signaling / zidSignaling. */
+    signaling: Signaling;
+    /**
+     * Perfect-negotiation role: exactly one side must be `polite`. A stable rule
+     * both peers can compute independently is e.g. `myId < peerId`.
+     */
+    polite: boolean;
+    /** ICE servers. Default [] (host candidates only, privacy-first). */
+    iceServers?: RTCIceServer[];
+    /** outgoing video constraints. Default 320x240 front camera. */
+    video?: MediaTrackConstraints;
+    /**
+     * Background-blur pipeline factory (e.g. () => createVideoBlur()). Optional -
+     * omit it and blur controls become no-ops (and the mediapipe dep is never
+     * loaded). Injected so a consumer that does not want blur pays nothing.
+     */
+    blur?: () => VideoBlur;
+}
+interface Call {
+    localStream: Readable<MediaStream | null>;
+    remoteStream: Readable<MediaStream | null>;
+    micEnabled: Readable<boolean>;
+    camEnabled: Readable<boolean>;
+    connected: Readable<boolean>;
+    /** last unrecovered error (tagged with the step to re-run), or null. */
+    lastError: Readable<MediaError | null>;
+    /** clear the error banner without retrying. */
+    clearError: () => void;
+    /** re-run the step that last failed. Idempotent; the "never get stuck" button. */
+    retry: () => Promise<void>;
+    /** true once the user consented to direct-P2P media + IP exposure. */
+    acknowledged: Readable<boolean>;
+    /** record consent; media stays inert until this is called. */
+    acknowledge: () => void;
+    /** withdraw consent: stop tracks, close the peer connection, re-arm the gate. */
+    revoke: () => void;
+    /** true when the peer offered but we have not opted in (drives a prompt). */
+    incomingPending: Readable<boolean>;
+    /** dismiss the incoming-media prompt without opting in. */
+    dismissIncoming: () => void;
+    /** outgoing-webcam background mode. */
+    blurMode: Readable<BlurMode>;
+    /** change the outgoing-webcam background mode (falls back to raw on failure). */
+    setBlurMode: (m: BlurMode) => Promise<void>;
+    /** background image for 'image' mode. */
+    setBlurImage: (img: HTMLImageElement | ImageBitmap | null) => void;
+    /** true if blur was requested but the model failed to init (sending raw). */
+    blurUnavailable: Readable<boolean>;
+    toggleMic: () => Promise<void>;
+    toggleCam: () => Promise<void>;
+    /** fully stop media and close the connection (also re-arms the gate). */
+    cleanup: () => void;
+}
+declare function createCall(options: CallOptions): Call;
+
+/**
+ * Google-Meet-style webcam BACKGROUND processing for an OUTGOING video track.
+ *
+ * Modes:
+ *   - 'off'   : pass the raw camera track through unchanged (no processing).
+ *   - 'blur'  : keep the person sharp, blur the background.
+ *   - 'image' : keep the person sharp, replace the background with an image.
+ *
+ * A per-frame person/background segmentation mask (MediaPipe ImageSegmenter,
+ * the selfie segmenter) composites a sharp foreground over a blurred/image
+ * background on a canvas, exposed as a MediaStream via captureStream(). The
+ * processed track is swapped into the RTCRtpSender via replaceTrack() - no
+ * renegotiation.
+ *
+ * FULLY OFFLINE / STRICT-CSP: `@mediapipe/tasks-vision` is an OPTIONAL peer dep
+ * loaded lazily, and the wasm runtime + .tflite model are served SAME-ORIGIN
+ * from `assetBase` (default '/mediapipe'). The host app vendors those assets;
+ * nothing is fetched from a CDN. MediaPipe compiles its wasm at load time, so a
+ * strict CSP needs script-src 'wasm-unsafe-eval' (does not re-open JS eval).
+ *
+ * GRACEFUL FALLBACK: if the model fails to init, setMode() rejects and the
+ * caller keeps sending the RAW track - never a black frame.
+ */
+
+declare function createVideoBlur(options?: VideoBlurOptions): VideoBlur;
+
+export { type BlurMode, type ByteChannel, type Call, type CallOptions, type MediaError, type MediaErrorKind, type MediaErrorStep, type MediaSignal, type Readable, type Signaling, type VideoBlur, type VideoBlurOptions, type Writable, createCall, createVideoBlur, writable, zidSignaling };

package/dist/index.js

@@ -0,0 +1,656 @@
+// src/store.ts
+function writable(initial) {
+  let value = initial;
+  const subscribers = /* @__PURE__ */ new Set();
+  const read = (() => value);
+  read.subscribe = (fn) => {
+    subscribers.add(fn);
+    return () => subscribers.delete(fn);
+  };
+  const write = (next) => {
+    if (Object.is(next, value)) {
+      return;
+    }
+    value = next;
+    for (const fn of subscribers) {
+      fn(value);
+    }
+  };
+  return [read, write];
+}
+
+// src/call.ts
+var DEFAULT_VIDEO = { width: 320, height: 240, facingMode: "user" };
+function createCall(options) {
+  const { signaling, polite } = options;
+  const iceServers = options.iceServers ?? [];
+  const videoConstraints = options.video ?? DEFAULT_VIDEO;
+  const [localStream, setLocalStream] = writable(null);
+  const remoteStreamsMap = /* @__PURE__ */ new Map();
+  const PEER = "peer";
+  const [remoteStream, setRemoteStream] = writable(null);
+  const [micEnabled, setMicEnabled] = writable(false);
+  const [camEnabled, setCamEnabled] = writable(false);
+  const [connected, setConnected] = writable(false);
+  const [acknowledged, setAcknowledged] = writable(false);
+  const [incomingPending, setIncomingPending] = writable(false);
+  const [blurMode, setBlurModeState] = writable("off");
+  const [blurUnavailable, setBlurUnavailable] = writable(false);
+  const [lastError, setLastError] = writable(null);
+  function classifyError(step, e) {
+    const name = e?.name ?? "";
+    let kind = "unknown";
+    let message;
+    switch (name) {
+      case "NotAllowedError":
+      case "SecurityError":
+        kind = "denied";
+        message = step === "cam" ? "Camera permission was blocked. Allow camera access, then retry." : "Microphone permission was blocked. Allow mic access, then retry.";
+        break;
+      case "NotReadableError":
+      case "AbortError":
+        kind = "busy";
+        message = `${step === "cam" ? "Camera" : "Microphone"} is in use by another app or tab. Close it, then retry.`;
+        break;
+      case "NotFoundError":
+      case "OverconstrainedError":
+        kind = "notfound";
+        message = step === "cam" ? "No camera found. Connect one, then retry." : "No microphone found. Connect one, then retry.";
+        break;
+      default:
+        message = `Could not start ${step === "cam" ? "camera" : step === "mic" ? "microphone" : "the connection"}. Retry.`;
+    }
+    return { step, kind, message };
+  }
+  let pc = null;
+  let makingOffer = false;
+  let ignoreOffer = false;
+  const blur = options.blur?.() ?? null;
+  let rawCamTrack = null;
+  function ensurePeerConnection() {
+    if (pc) {
+      return pc;
+    }
+    pc = new RTCPeerConnection({ iceServers });
+    pc.onicecandidate = (e) => {
+      if (e.candidate) {
+        signaling.send({ t: "_ice", d: { candidate: e.candidate.toJSON() } });
+      }
+    };
+    pc.ontrack = () => {
+      const stream = new MediaStream();
+      for (const r of pc.getReceivers()) {
+        if (r.track) {
+          stream.addTrack(r.track);
+        }
+      }
+      remoteStreamsMap.set(PEER, stream);
+      setRemoteStream(stream);
+    };
+    pc.onconnectionstatechange = () => {
+      const st = pc?.connectionState;
+      setConnected(st === "connected");
+      if (st === "connected") {
+        if (lastError()?.step === "connect") {
+          setLastError(null);
+        }
+      } else if (st === "failed") {
+        setLastError({
+          step: "connect",
+          kind: "negotiation",
+          message: "The direct connection failed (restrictive network). Retry to reconnect."
+        });
+      }
+    };
+    pc.onnegotiationneeded = async () => {
+      try {
+        makingOffer = true;
+        await pc.setLocalDescription();
+        signaling.send({ t: "_sdp", d: { sdp: pc.localDescription.toJSON() } });
+      } catch {
+        setLastError({
+          step: "connect",
+          kind: "negotiation",
+          message: "Could not negotiate the media connection. Retry."
+        });
+      } finally {
+        makingOffer = false;
+      }
+    };
+    return pc;
+  }
+  async function getLocalMedia(audio, video) {
+    let stream = localStream();
+    let changed = false;
+    if (audio && !stream?.getAudioTracks().length) {
+      const s = await navigator.mediaDevices.getUserMedia({ audio: true });
+      if (!stream) {
+        stream = new MediaStream();
+      }
+      s.getAudioTracks().forEach((t) => stream.addTrack(t));
+      changed = true;
+    }
+    if (video && !stream?.getVideoTracks().length) {
+      const s = await navigator.mediaDevices.getUserMedia({ video: videoConstraints });
+      if (!stream) {
+        stream = new MediaStream();
+      }
+      s.getVideoTracks().forEach((t) => stream.addTrack(t));
+      changed = true;
+    }
+    if (!stream) {
+      stream = new MediaStream();
+    }
+    if (changed) {
+      setLocalStream(new MediaStream(stream.getTracks()));
+    }
+    return localStream();
+  }
+  function addTracksToPC(stream) {
+    const conn = ensurePeerConnection();
+    const existingSenders = conn.getSenders();
+    for (const track of stream.getTracks()) {
+      if (!existingSenders.some((s) => s.track?.id === track.id)) {
+        conn.addTrack(track, stream);
+      }
+    }
+  }
+  function videoSender() {
+    return pc?.getSenders().find((s) => s.track?.kind === "video") ?? null;
+  }
+  async function swapVideoTrack(next) {
+    const sender = videoSender();
+    if (sender && sender.track?.id !== next.id) {
+      try {
+        await sender.replaceTrack(next);
+      } catch (e) {
+        console.warn("[zafu-media] replaceTrack failed:", e);
+      }
+    }
+    const stream = localStream();
+    if (stream) {
+      const cur = stream.getVideoTracks()[0];
+      if (cur && cur.id !== next.id) {
+        stream.removeTrack(cur);
+        stream.addTrack(next);
+        setLocalStream(new MediaStream(stream.getTracks()));
+      }
+    }
+  }
+  async function applyBlurMode(mode) {
+    setBlurModeState(mode);
+    setBlurUnavailable(false);
+    if (!blur) {
+      return;
+    }
+    if (!camEnabled() || !rawCamTrack) {
+      return;
+    }
+    if (mode === "off") {
+      await blur.setMode("off");
+      await swapVideoTrack(rawCamTrack);
+      return;
+    }
+    try {
+      await blur.setMode(mode, rawCamTrack);
+      const out = blur.outputTrack();
+      if (out) {
+        await swapVideoTrack(out);
+      } else {
+        throw new Error("no processed track");
+      }
+    } catch {
+      setBlurUnavailable(true);
+      await swapVideoTrack(rawCamTrack);
+    }
+  }
+  async function enableMic() {
+    const stream = await getLocalMedia(true, camEnabled());
+    addTracksToPC(stream);
+    stream.getAudioTracks().forEach((t) => {
+      t.enabled = true;
+    });
+    setMicEnabled(true);
+    if (lastError()?.step === "mic") {
+      setLastError(null);
+    }
+  }
+  async function toggleMic() {
+    if (!acknowledged()) {
+      console.warn("[zafu-media] mic toggle blocked: not acknowledged");
+      return;
+    }
+    if (micEnabled()) {
+      localStream()?.getAudioTracks().forEach((t) => {
+        t.enabled = false;
+      });
+      setMicEnabled(false);
+      if (lastError()?.step === "mic") {
+        setLastError(null);
+      }
+    } else {
+      try {
+        await enableMic();
+      } catch (e) {
+        setMicEnabled(false);
+        setLastError(classifyError("mic", e));
+      }
+    }
+  }
+  async function enableCam() {
+    const stream = await getLocalMedia(micEnabled(), true);
+    rawCamTrack = stream.getVideoTracks()[0] ?? null;
+    if (rawCamTrack) {
+      rawCamTrack.enabled = true;
+    }
+    addTracksToPC(stream);
+    setCamEnabled(true);
+    if (lastError()?.step === "cam") {
+      setLastError(null);
+    }
+    if (blurMode() !== "off") {
+      await applyBlurMode(blurMode());
+    }
+  }
+  async function toggleCam() {
+    if (!acknowledged()) {
+      console.warn("[zafu-media] cam toggle blocked: not acknowledged");
+      return;
+    }
+    if (camEnabled()) {
+      localStream()?.getVideoTracks().forEach((t) => {
+        t.enabled = false;
+      });
+      blur?.setMode("off").catch(() => {
+      });
+      setCamEnabled(false);
+      if (lastError()?.step === "cam") {
+        setLastError(null);
+      }
+    } else {
+      try {
+        await enableCam();
+      } catch (e) {
+        setCamEnabled(false);
+        setLastError(classifyError("cam", e));
+      }
+    }
+  }
+  async function handleSignal(msg) {
+    if (!acknowledged()) {
+      if (msg.t === "_sdp" && msg.d.sdp?.type === "offer") {
+        setIncomingPending(true);
+      }
+      return;
+    }
+    if (msg.t === "_sdp") {
+      const conn = ensurePeerConnection();
+      const desc = new RTCSessionDescription(msg.d.sdp);
+      const offerCollision = desc.type === "offer" && (makingOffer || conn.signalingState !== "stable");
+      ignoreOffer = !polite && offerCollision;
+      if (ignoreOffer) {
+        return;
+      }
+      if (offerCollision) {
+        await conn.setLocalDescription({ type: "rollback" });
+      }
+      await conn.setRemoteDescription(desc);
+      if (desc.type === "offer") {
+        await conn.setLocalDescription();
+        signaling.send({ t: "_sdp", d: { sdp: conn.localDescription.toJSON() } });
+      }
+    }
+    if (msg.t === "_ice") {
+      const conn = ensurePeerConnection();
+      try {
+        await conn.addIceCandidate(new RTCIceCandidate(msg.d.candidate));
+      } catch (e) {
+        if (!ignoreOffer) {
+          console.warn("[zafu-media] ICE error:", e);
+        }
+      }
+    }
+  }
+  function teardown() {
+    blur?.stop();
+    rawCamTrack?.stop();
+    rawCamTrack = null;
+    localStream()?.getTracks().forEach((t) => t.stop());
+    setLocalStream(null);
+    remoteStreamsMap.clear();
+    setRemoteStream(null);
+    pc?.close();
+    pc = null;
+    makingOffer = false;
+    ignoreOffer = false;
+    setMicEnabled(false);
+    setCamEnabled(false);
+    setConnected(false);
+    setBlurUnavailable(false);
+    setLastError(null);
+  }
+  async function retry() {
+    const err = lastError();
+    if (!err) {
+      return;
+    }
+    setLastError(null);
+    try {
+      if (err.step === "mic") {
+        await enableMic();
+      } else if (err.step === "cam") {
+        await enableCam();
+      } else {
+        if (pc && pc.connectionState !== "closed") {
+          try {
+            pc.restartIce();
+          } catch {
+          }
+        }
+        if (!pc || pc.connectionState === "closed" || pc.connectionState === "failed") {
+          const wasCam = camEnabled();
+          pc?.close();
+          pc = null;
+          const stream = localStream();
+          if (stream) {
+            ensurePeerConnection();
+            addTracksToPC(stream);
+            if (blurMode() !== "off" && wasCam) {
+              await applyBlurMode(blurMode());
+            }
+          }
+        }
+      }
+    } catch (e) {
+      setLastError(classifyError(err.step, e));
+    }
+  }
+  const unsubscribe = signaling.onSignal((msg) => {
+    void handleSignal(msg);
+  });
+  return {
+    localStream,
+    remoteStream,
+    micEnabled,
+    camEnabled,
+    connected,
+    lastError,
+    clearError: () => setLastError(null),
+    retry,
+    acknowledged,
+    acknowledge: () => {
+      setAcknowledged(true);
+      setIncomingPending(false);
+    },
+    revoke: () => {
+      teardown();
+      setAcknowledged(false);
+      setIncomingPending(false);
+    },
+    incomingPending,
+    dismissIncoming: () => setIncomingPending(false),
+    blurMode,
+    setBlurMode: applyBlurMode,
+    setBlurImage: (img) => blur?.setBackgroundImage(img),
+    blurUnavailable,
+    toggleMic,
+    toggleCam,
+    cleanup: () => {
+      unsubscribe();
+      teardown();
+      setAcknowledged(false);
+      setIncomingPending(false);
+    }
+  };
+}
+
+// src/blur.ts
+function createVideoBlur(options = {}) {
+  const BASE = options.assetBase ?? "/mediapipe";
+  const MODEL_URL = `${BASE}/${options.modelFile ?? "selfie_segmenter.tflite"}`;
+  const BLUR_PX = options.blurPx ?? 10;
+  let segmenter = null;
+  let initPromise = null;
+  let isReady = false;
+  let currentMode = "off";
+  let sourceTrack = null;
+  let bgImage = null;
+  let video = null;
+  let canvas = null;
+  let ctx = null;
+  let maskCanvas = null;
+  let maskCtx = null;
+  let outStream = null;
+  let rafId = null;
+  let running = false;
+  async function ensureSegmenter() {
+    if (isReady) {
+      return;
+    }
+    if (initPromise) {
+      return initPromise;
+    }
+    initPromise = (async () => {
+      const vision = await import('@mediapipe/tasks-vision');
+      const { FilesetResolver, ImageSegmenter: Segmenter } = vision;
+      const fileset = await FilesetResolver.forVisionTasks(BASE);
+      segmenter = await Segmenter.createFromOptions(fileset, {
+        baseOptions: {
+          modelAssetPath: MODEL_URL,
+          delegate: "GPU"
+        },
+        runningMode: "VIDEO",
+        outputCategoryMask: false,
+        outputConfidenceMasks: true
+      });
+      isReady = true;
+    })();
+    try {
+      await initPromise;
+    } catch (e) {
+      initPromise = null;
+      isReady = false;
+      console.warn("[zafu-media/blur] segmenter init failed, falling back to raw:", e);
+      throw e;
+    }
+  }
+  function ensureSurfaces(w, h) {
+    if (!canvas) {
+      canvas = document.createElement("canvas");
+      ctx = canvas.getContext("2d", { willReadFrequently: false });
+    }
+    if (!maskCanvas) {
+      maskCanvas = document.createElement("canvas");
+      maskCtx = maskCanvas.getContext("2d", { willReadFrequently: true });
+    }
+    if (canvas.width !== w || canvas.height !== h) {
+      canvas.width = w;
+      canvas.height = h;
+      maskCanvas.width = w;
+      maskCanvas.height = h;
+    }
+  }
+  async function attachVideo(track) {
+    if (!video) {
+      video = document.createElement("video");
+      video.muted = true;
+      video.playsInline = true;
+      video.autoplay = true;
+    }
+    video.srcObject = new MediaStream([track]);
+    await video.play().catch(() => {
+    });
+    if (!video.videoWidth) {
+      await new Promise((res) => {
+        const onMeta = () => {
+          video?.removeEventListener("loadedmetadata", onMeta);
+          res();
+        };
+        video?.addEventListener("loadedmetadata", onMeta);
+      });
+    }
+  }
+  function composite(mask, w, h) {
+    if (!ctx || !canvas || !video || !maskCtx || !maskCanvas) {
+      return;
+    }
+    const imgData = maskCtx.createImageData(w, h);
+    const data = imgData.data;
+    for (let i = 0; i < mask.length; i++) {
+      data[i * 4 + 3] = (mask[i] ?? 0) > 0.5 ? 255 : Math.round((mask[i] ?? 0) * 255);
+    }
+    maskCtx.putImageData(imgData, 0, 0);
+    ctx.save();
+    ctx.filter = "none";
+    if (currentMode === "image" && bgImage) {
+      drawCover(ctx, bgImage, w, h);
+    } else {
+      ctx.filter = `blur(${BLUR_PX}px)`;
+      ctx.drawImage(video, 0, 0, w, h);
+      ctx.filter = "none";
+    }
+    ctx.restore();
+    maskCtx.save();
+    maskCtx.globalCompositeOperation = "source-in";
+    maskCtx.filter = "none";
+    maskCtx.drawImage(video, 0, 0, w, h);
+    maskCtx.restore();
+    ctx.drawImage(maskCanvas, 0, 0, w, h);
+  }
+  function drawCover(c, img, w, h) {
+    const iw = img.naturalWidth || img.width;
+    const ih = img.naturalHeight || img.height;
+    if (!iw || !ih) {
+      return;
+    }
+    const scale = Math.max(w / iw, h / ih);
+    const dw = iw * scale;
+    const dh = ih * scale;
+    c.drawImage(img, (w - dw) / 2, (h - dh) / 2, dw, dh);
+  }
+  function loop() {
+    if (!running || !video || !segmenter || !canvas || !ctx) {
+      return;
+    }
+    const w = canvas.width;
+    const h = canvas.height;
+    if (video.readyState >= 2 && w && h) {
+      try {
+        const result = segmenter.segmentForVideo(video, performance.now());
+        const masks = result.confidenceMasks;
+        if (masks && masks[0]) {
+          composite(masks[0].getAsFloat32Array(), w, h);
+        } else {
+          ctx.drawImage(video, 0, 0, w, h);
+        }
+        result.close();
+      } catch {
+        ctx.drawImage(video, 0, 0, w, h);
+      }
+    }
+    rafId = requestAnimationFrame(loop);
+  }
+  function startLoop() {
+    if (running) {
+      return;
+    }
+    running = true;
+    rafId = requestAnimationFrame(loop);
+  }
+  function stopLoop() {
+    running = false;
+    if (rafId != null) {
+      cancelAnimationFrame(rafId);
+      rafId = null;
+    }
+  }
+  async function setMode(m, source) {
+    if (source) {
+      sourceTrack = source;
+    }
+    currentMode = m;
+    if (m === "off") {
+      stopLoop();
+      return;
+    }
+    if (!sourceTrack) {
+      throw new Error("[zafu-media/blur] no source track");
+    }
+    await ensureSegmenter();
+    await attachVideo(sourceTrack);
+    const settings = sourceTrack.getSettings();
+    const w = video?.videoWidth || settings.width || 320;
+    const h = video?.videoHeight || settings.height || 240;
+    ensureSurfaces(w, h);
+    if (!outStream) {
+      outStream = canvas.captureStream(settings.frameRate || 30);
+    }
+    startLoop();
+  }
+  function stop() {
+    stopLoop();
+    outStream?.getTracks().forEach((t) => t.stop());
+    outStream = null;
+    if (video) {
+      video.srcObject = null;
+      video = null;
+    }
+    canvas = null;
+    ctx = null;
+    maskCanvas = null;
+    maskCtx = null;
+    try {
+      segmenter?.close();
+    } catch {
+    }
+    segmenter = null;
+    initPromise = null;
+    isReady = false;
+    currentMode = "off";
+    sourceTrack = null;
+  }
+  return {
+    outputTrack: () => outStream?.getVideoTracks()[0] ?? null,
+    mode: () => currentMode,
+    setMode,
+    setBackgroundImage: (img) => {
+      bgImage = img;
+    },
+    ready: () => isReady,
+    stop
+  };
+}
+
+// src/signaling.ts
+function zidSignaling(channel, tag = 240) {
+  const enc = new TextEncoder();
+  const dec = new TextDecoder();
+  const handlers = /* @__PURE__ */ new Set();
+  channel.on("message", (data) => {
+    if (data[0] !== tag) {
+      return;
+    }
+    try {
+      const msg = JSON.parse(dec.decode(data.subarray(1)));
+      for (const h of handlers) {
+        h(msg);
+      }
+    } catch {
+    }
+  });
+  return {
+    send(msg) {
+      const body = enc.encode(JSON.stringify(msg));
+      const framed = new Uint8Array(body.length + 1);
+      framed[0] = tag;
+      framed.set(body, 1);
+      channel.send(framed);
+    },
+    onSignal(handler) {
+      handlers.add(handler);
+      return () => handlers.delete(handler);
+    }
+  };
+}
+
+export { createCall, createVideoBlur, writable, zidSignaling };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@zafu/media",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Framework-agnostic P2P media primitives - opt-in WebRTC voice/video with perfect negotiation, local background blur, and pluggable (ZID-encrypted) signaling",
+  "type": "module",
+  "keywords": [
+    "webrtc",
+    "p2p",
+    "voice",
+    "video",
+    "background-blur",
+    "mediapipe",
+    "zid",
+    "zafu",
+    "primitives"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rotkonetworks/zafu.git",
+    "directory": "packages/media"
+  },
+  "homepage": "https://github.com/rotkonetworks/zafu/tree/main/packages/media#readme",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@mediapipe/tasks-vision": "^0.10.22"
+  },
+  "peerDependenciesMeta": {
+    "@mediapipe/tasks-vision": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@mediapipe/tasks-vision": "^0.10.22",
+    "tsup": "^8.5.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --treeshake",
+    "lint": "eslint \"**/*.ts*\"",
+    "test": "vitest run"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}