@ksp-gonogo/kerbcast 1.4.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./__generated__/types";
+export { KerbcastClient, BrowserKerbcastTransport, type BrowserKerbcastTransportOptions, type InboundVideoStats, type KerbcastCameraHandle, type KerbcastClientConfig, type KerbcastConnectionState, type KerbcastClientEvents, type KerbcastCameraEvents, type KerbcastTransport, type KerbcastPeer, type KerbcastDataChannel, type DiscoveredCamera, type NoiseConfig, } from "./client";
+export { PanZoomController, type PanZoomCommandSink, type PanZoomBounds, type PanZoomControllerOptions, } from "./panZoom";

package/dist/index.js

@@ -0,0 +1,7 @@
+// Re-export every type the typeshare codegen emits from the Rust
+// protocol module. New code should prefer the higher-level
+// `KerbcastClient` re-exported below, but the underlying wire types
+// stay available for consumers that want to roll their own transport.
+export * from "./__generated__/types";
+export { KerbcastClient, BrowserKerbcastTransport, } from "./client";
+export { PanZoomController, } from "./panZoom";

package/dist/noise.d.ts

@@ -0,0 +1,34 @@
+export interface NoisePipelineOptions {
+    /**
+     * Composite animated static over stalled and sourceless states (default
+     * true). When false: a stalled source holds its last decoded frame with no
+     * static (the consumer provides its own staleness chrome), and a sourceless
+     * path clears to black without noise (only the text overlay renders).
+     */
+    showStatic?: boolean;
+    /** Observe stall transitions (frames stopped / frames resumed). */
+    onStallChange?: (stalled: boolean) => void;
+}
+export interface NoisePipeline {
+    readonly processedStream: MediaStream;
+    setIntensity(level: number): void;
+    /**
+     * Swap (or remove) the source video. With a non-null stream the pipeline
+     * composites static over the live frame; with `null` it goes *sourceless*
+     * — `draw()` skips `drawImage` and renders pure static. The output
+     * `processedStream` stays valid across the swap, so consumers never see a
+     * gap.
+     */
+    setSource(stream: MediaStream | null): void;
+    /** Runtime switch for {@link NoisePipelineOptions.showStatic}. */
+    setShowStatic(enabled: boolean): void;
+    destroy(): void;
+}
+/**
+ * Wraps a (possibly absent) `MediaStream` in a canvas pipeline that
+ * composites digital static over the video. Pass `null` to run the pipeline
+ * sourceless — it emits pure static until a source is attached via
+ * {@link NoisePipeline.setSource}. Returns null when `captureStream` is
+ * unavailable (SSR, test environments without canvas support).
+ */
+export declare function tryCreateNoisePipeline(rawStream: MediaStream | null, initialIntensity: number, options?: NoisePipelineOptions): NoisePipeline | null;

package/dist/noise.js

@@ -0,0 +1,274 @@
+const NOISE_MAX_W = 320;
+const NOISE_MAX_H = 180;
+/*
+ * A live source that hasn't presented a decoded frame for this long is
+ * treated as stalled: the pipeline composites the same black + full-static
+ * look it uses when sourceless. Without this, a starved or mid-GOP WebRTC
+ * track shows the BROWSER DECODER's output — grey-green macroblock smear —
+ * which reads as a second, inconsistent "static" style. Long enough that a
+ * single late frame at 30 fps never flickers the overlay.
+ */
+const SOURCE_STALL_MS = 500;
+/*
+ * When a source that WAS delivering frames stalls, the full-static look
+ * ramps in over this window on top of the held last frame instead of
+ * cutting hard. Only degradation is softened: the first decoded frame
+ * drops the static outright, so recovery feels instant. Sources that
+ * never decoded a frame (fresh attach) keep the immediate full-static
+ * "waiting" look: there is no last frame to soften from.
+ */
+const STALL_RAMP_MS = 5000;
+/**
+ * Wraps a (possibly absent) `MediaStream` in a canvas pipeline that
+ * composites digital static over the video. Pass `null` to run the pipeline
+ * sourceless — it emits pure static until a source is attached via
+ * {@link NoisePipeline.setSource}. Returns null when `captureStream` is
+ * unavailable (SSR, test environments without canvas support).
+ */
+export function tryCreateNoisePipeline(rawStream, initialIntensity, options) {
+    const canvas = document.createElement("canvas");
+    if (typeof canvas.captureStream !== "function") {
+        return null;
+    }
+    const noiseCanvas = document.createElement("canvas");
+    const noiseCtx = noiseCanvas.getContext("2d");
+    const ctx = canvas.getContext("2d");
+    if (!noiseCtx || !ctx)
+        return null;
+    // Size the output canvas to video dimensions once metadata loads.
+    // Until then (and while sourceless), use a placeholder so captureStream
+    // has something to output.
+    canvas.width = NOISE_MAX_W;
+    canvas.height = NOISE_MAX_H;
+    noiseCanvas.width = Math.ceil(NOISE_MAX_W / 2);
+    noiseCanvas.height = Math.ceil(NOISE_MAX_H / 2);
+    let intensity = initialIntensity;
+    let showStatic = options?.showStatic ?? true;
+    const onStallChange = options?.onStallChange;
+    let rafId = null;
+    let destroyed = false;
+    const video = document.createElement("video");
+    video.muted = true;
+    video.playsInline = true;
+    /*
+     * Frame-stall tracking via requestVideoFrameCallback (per decoded frame).
+     * lastFrameTs = 0 on (re)attach, so a freshly connected track shows the
+     * full-static "waiting" look until its first real frame decodes. Where
+     * rVFC is unsupported (jsdom, old engines) stall detection is disabled
+     * and behaviour is unchanged.
+     */
+    const videoVfc = video;
+    const vfcSupported = typeof videoVfc.requestVideoFrameCallback === "function";
+    let lastFrameTs = 0;
+    let vfcId = null;
+    const armFrameCallback = () => {
+        if (destroyed || !vfcSupported)
+            return;
+        vfcId = videoVfc.requestVideoFrameCallback(() => {
+            lastFrameTs = performance.now();
+            armFrameCallback();
+        });
+    };
+    /*
+     * Stall presentation state. stallStartTs anchors the static ramp;
+     * lastFrameCanvas holds a copy of the final decoded frame so each stalled
+     * draw can restore it pristine before compositing the ramping scrim and
+     * static (painting onto an unrestored canvas would accumulate to black
+     * within a few frames regardless of the ramp position).
+     */
+    let stallStartTs = null;
+    let stallHasFrame = false;
+    let lastFrameCanvas = null;
+    let lastFrameCtx = null;
+    const snapshotLastFrame = () => {
+        if (!lastFrameCanvas) {
+            lastFrameCanvas = document.createElement("canvas");
+            lastFrameCtx = lastFrameCanvas.getContext("2d");
+        }
+        if (!lastFrameCtx)
+            return false;
+        lastFrameCanvas.width = canvas.width;
+        lastFrameCanvas.height = canvas.height;
+        lastFrameCtx.drawImage(canvas, 0, 0);
+        return true;
+    };
+    const setStalled = (next, now) => {
+        if (next === (stallStartTs !== null))
+            return;
+        if (next) {
+            stallStartTs = now;
+            stallHasFrame = lastFrameTs > 0 && snapshotLastFrame();
+        }
+        else {
+            stallStartTs = null;
+            stallHasFrame = false;
+        }
+        onStallChange?.(next);
+    };
+    const onMeta = () => {
+        const vw = video.videoWidth;
+        const vh = video.videoHeight;
+        if (!vw || !vh)
+            return;
+        canvas.width = vw;
+        canvas.height = vh;
+        const scale = Math.min(1, NOISE_MAX_W / vw, NOISE_MAX_H / vh);
+        noiseCanvas.width = Math.max(1, Math.round(vw * scale));
+        noiseCanvas.height = Math.max(1, Math.round(vh * scale));
+    };
+    video.addEventListener("loadedmetadata", onMeta);
+    const setSource = (stream) => {
+        if (destroyed)
+            return;
+        // Stall state belongs to the outgoing source; a swap starts clean.
+        setStalled(false, performance.now());
+        if (stream) {
+            video.srcObject = stream;
+            lastFrameTs = 0; // full static until the first frame actually decodes
+            armFrameCallback();
+            void video.play();
+        }
+        else {
+            // Sourceless: detach the video so draw() composites pure static. Reset
+            // the canvas to the placeholder size so a stale source's dimensions
+            // don't linger.
+            video.pause();
+            video.srcObject = null;
+            canvas.width = NOISE_MAX_W;
+            canvas.height = NOISE_MAX_H;
+            noiseCanvas.width = Math.ceil(NOISE_MAX_W / 2);
+            noiseCanvas.height = Math.ceil(NOISE_MAX_H / 2);
+        }
+    };
+    setSource(rawStream);
+    const draw = () => {
+        if (destroyed)
+            return;
+        const now = performance.now();
+        const cw = canvas.width;
+        const ch = canvas.height;
+        const nw = noiseCanvas.width;
+        const nh = noiseCanvas.height;
+        // A source that exists but hasn't decoded a frame recently (or yet) is
+        // treated as stalled; otherwise the decoder's starved output
+        // (macroblock smear) leaks through as a second static style.
+        const stalled = vfcSupported &&
+            video.srcObject !== null &&
+            now - lastFrameTs > SOURCE_STALL_MS;
+        setStalled(stalled, now);
+        /*
+         * Static strength and layer opacity for this frame. A delivering feed
+         * draws degrade-driven static at full layer opacity; a stall pins the
+         * static to full strength but ramps the LAYER in over the held last
+         * frame, so degradation eases in while recovery (the first decoded
+         * frame) is instant.
+         */
+        let eff = intensity;
+        let layerAlpha = 1;
+        if (video.srcObject && !stalled && video.readyState >= 2) {
+            ctx.drawImage(video, 0, 0, cw, ch);
+        }
+        else if (!video.srcObject) {
+            // Sourceless: clear to black so static composites over a blank field
+            // rather than the last live frame.
+            ctx.fillStyle = "#000";
+            ctx.fillRect(0, 0, cw, ch);
+            if (!showStatic) {
+                rafId = requestAnimationFrame(draw);
+                return;
+            }
+        }
+        else if (stalled) {
+            // Stall pins the noise to full strength; the handle's degrade-driven
+            // intensity (possibly near zero) belongs to a feed that is delivering.
+            eff = 1;
+            if (stallHasFrame && lastFrameCanvas) {
+                // Restore the held last frame, then ramp a black scrim in step with
+                // the static so the fully-ramped look matches the sourceless one.
+                ctx.drawImage(lastFrameCanvas, 0, 0, cw, ch);
+                if (!showStatic) {
+                    // Frozen last frame, no static: the consumer's chrome carries the
+                    // staleness indicator instead.
+                    rafId = requestAnimationFrame(draw);
+                    return;
+                }
+                layerAlpha = Math.min(1, (now - (stallStartTs ?? now)) / STALL_RAMP_MS);
+                ctx.globalAlpha = layerAlpha;
+                ctx.fillStyle = "#000";
+                ctx.fillRect(0, 0, cw, ch);
+                ctx.globalAlpha = 1;
+            }
+            else {
+                // Never decoded a frame (waiting after attach): the established
+                // immediate full-static look; nothing to soften from.
+                ctx.fillStyle = "#000";
+                ctx.fillRect(0, 0, cw, ch);
+                if (!showStatic) {
+                    rafId = requestAnimationFrame(draw);
+                    return;
+                }
+            }
+        }
+        // Build noise at reduced resolution; composited up to full canvas size.
+        const imageData = noiseCtx.createImageData(nw, nh);
+        const d = imageData.data;
+        const dropThreshold = (eff - 0.45) * 0.35;
+        const dropAlpha = Math.round(Math.min(eff * 1.8, 1) * 230);
+        const speckleAlpha = Math.round(eff * 210);
+        for (let row = 0; row < nh; row++) {
+            const dropped = eff > 0.45 && Math.random() < dropThreshold;
+            for (let col = 0; col < nw; col++) {
+                const i = (row * nw + col) * 4;
+                if (dropped) {
+                    d[i] = d[i + 1] = d[i + 2] = 0;
+                    d[i + 3] = dropAlpha;
+                }
+                else if (Math.random() < eff * 0.45) {
+                    const v = Math.floor(Math.random() * 155 + 100);
+                    d[i] = d[i + 1] = d[i + 2] = v;
+                    d[i + 3] = speckleAlpha;
+                }
+                // else: fully transparent (ImageData is zeroed on creation)
+            }
+        }
+        noiseCtx.putImageData(imageData, 0, 0);
+        ctx.globalAlpha = layerAlpha;
+        ctx.drawImage(noiseCanvas, 0, 0, cw, ch);
+        ctx.globalAlpha = 1;
+        rafId = requestAnimationFrame(draw);
+    };
+    rafId = requestAnimationFrame(draw);
+    let processedStream;
+    try {
+        processedStream = canvas.captureStream(30);
+    }
+    catch {
+        destroyed = true;
+        if (rafId !== null)
+            cancelAnimationFrame(rafId);
+        video.removeEventListener("loadedmetadata", onMeta);
+        video.pause();
+        video.srcObject = null;
+        return null;
+    }
+    return {
+        processedStream,
+        setIntensity(level) {
+            intensity = level;
+        },
+        setSource,
+        setShowStatic(enabled) {
+            showStatic = enabled;
+        },
+        destroy() {
+            destroyed = true;
+            if (rafId !== null)
+                cancelAnimationFrame(rafId);
+            if (vfcId !== null)
+                videoVfc.cancelVideoFrameCallback?.(vfcId);
+            video.removeEventListener("loadedmetadata", onMeta);
+            video.pause();
+            video.srcObject = null;
+        },
+    };
+}

package/dist/panZoom.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Headless pan/zoom control state machine extracted from the CameraFeed
+ * component. Manages rate deduplication, analog deadzone, optimistic
+ * accumulators for discrete nudges, debounced FoV slider, and echo-sync
+ * while idle -- all without any DOM or React dependency.
+ *
+ * `KerbcastCameraHandle` satisfies `PanZoomCommandSink` structurally: pass a
+ * camera handle directly as the sink and the controller will drive it.
+ *
+ * ```ts
+ * const cam = client.camera(flightId);
+ * const ctrl = new PanZoomController(cam);
+ *
+ * // Analog stick input
+ * ctrl.setPanRate(stickX, stickY);
+ *
+ * // Discrete nudge buttons
+ * ctrl.nudgePan(1, 0);   // pan right one step
+ * ctrl.nudgeZoom(-1);    // zoom in one step
+ *
+ * // FoV slider
+ * ctrl.setFovSliderDragging(true);
+ * ctrl.fovSliderInput(newFov);
+ * ctrl.setFovSliderDragging(false); // flushes immediately
+ *
+ * // Sync echoed state (call from camera "change" listener)
+ * ctrl.syncFromState({ fov, panYaw, panPitch, fovMin, fovMax,
+ *                      panYawMin, panYawMax, panPitchMin, panPitchMax });
+ *
+ * // Cleanup on unmount
+ * ctrl.stop();
+ * ```
+ */
+/**
+ * Command sink that the controller writes to. `KerbcastCameraHandle`
+ * satisfies this interface structurally -- no adapter needed.
+ */
+export interface PanZoomCommandSink {
+    setPan(yaw: number, pitch: number): Promise<void> | void;
+    setPanRate(yawRate: number, pitchRate: number): Promise<void> | void;
+    setFov(fov: number): Promise<void> | void;
+    setZoomRate(rate: number): Promise<void> | void;
+}
+/** Camera FoV and pan bounds for clamping. */
+export interface PanZoomBounds {
+    fovMin: number;
+    fovMax: number;
+    panYawMin: number;
+    panYawMax: number;
+    panPitchMin: number;
+    panPitchMax: number;
+}
+/** Tuning knobs for {@link PanZoomController}. All have safe defaults. */
+export interface PanZoomControllerOptions {
+    /**
+     * Degrees moved per discrete pan nudge (arrow buttons, keyboard).
+     * Default: 5.
+     */
+    panNudgeDeg?: number;
+    /**
+     * Degrees moved per discrete zoom nudge (zoom buttons, keyboard).
+     * Default: 5.
+     */
+    fovNudgeDeg?: number;
+    /**
+     * Debounce window (ms) for the FoV slider. Only the settled value is
+     * sent; intermediate drag positions do not stream commands.
+     * Default: 120.
+     */
+    fovSliderDebounceMs?: number;
+    /**
+     * Magnitude below which an analog axis is snapped to 0. Prevents tiny
+     * dithering near centre from emitting a stream of non-zero rate commands.
+     * Default: 0.05.
+     */
+    analogDeadzone?: number;
+}
+/**
+ * Headless pan/zoom state machine. Manages rate deduplication, analog
+ * deadzone, optimistic accumulators, FoV slider debounce, and echo-sync
+ * idle rules. Mirrors the behaviour of the CameraFeed component in gonogo
+ * (CameraFeed.tsx lines 323-592) without any React or DOM coupling.
+ */
+export declare class PanZoomController {
+    private readonly sink;
+    private readonly panNudgeDeg;
+    private readonly fovNudgeDeg;
+    private readonly fovSliderDebounceMs;
+    private readonly analogDeadzone;
+    private sentPanRate;
+    private sentZoomRate;
+    private localPan;
+    private localFov;
+    private _sliderFov;
+    private sliderDragging;
+    private fovDebounceTimer;
+    private pendingFov;
+    private ballDragging;
+    private bounds;
+    private readonly sliderFovListeners;
+    constructor(sink: PanZoomCommandSink, opts?: PanZoomControllerOptions);
+    /**
+     * Optimistic FoV value tracked by the slider. Follows the pointer while
+     * dragging, then the camera echo when idle. Reactive via
+     * {@link onSliderFov}.
+     */
+    get sliderFov(): number;
+    /**
+     * Sync from the camera's echoed state (call from the camera's `"change"`
+     * event listener). Applies the echoed pan to the pan accumulator only when
+     * the controller is pan-idle (no active pan rate, no active ball drag).
+     * Applies the echoed FoV to the accumulator and slider only when the
+     * controller is zoom-idle (zoom rate 0, slider not dragging, no pending
+     * debounced send). Mirrors CameraFeed.tsx:370-387.
+     */
+    syncFromState(state: {
+        fov: number;
+        panYaw: number;
+        panPitch: number;
+    } & PanZoomBounds): void;
+    /**
+     * Set a persistent normalised pan velocity (-1..1 per axis). Clamps,
+     * applies the analog deadzone, and deduplicates against the last-sent
+     * value before forwarding to the sink. Mirrors sendPanRate.
+     */
+    setPanRate(yaw: number, pitch: number): void;
+    /**
+     * Update one pan axis, preserving the other. Allows two independent inputs
+     * (e.g. a serial stick axis and the ball) to compose rather than clobber
+     * each other. Mirrors setPanAxis.
+     */
+    setPanAxis(axis: "yaw" | "pitch", value: number): void;
+    /**
+     * Set a persistent normalised zoom velocity (-1..1; +1 = zoom in, FoV
+     * decreasing). Clamps, applies deadzone, deduplicates. Mirrors sendZoomRate.
+     */
+    setZoomRate(rate: number): void;
+    /**
+     * Discrete pan step (+1/-1 per axis sign). Moves the pan accumulator by
+     * `panNudgeDeg`, clamped to bounds, then sends an absolute `setPan`.
+     * Mirrors nudgePan.
+     */
+    nudgePan(yawSign: number, pitchSign: number): void;
+    /**
+     * Discrete FoV step. `deltaSign: -1` = zoom in (FoV decreases by
+     * `fovNudgeDeg`), `+1` = zoom out (FoV increases). Clamped to fov bounds.
+     * Mirrors nudgeZoom (which calls onFovChange internally).
+     */
+    nudgeZoom(deltaSign: number): void;
+    /**
+     * Update the optimistic slider value and schedule a debounced `setFov`.
+     * The settled (paused) value is what gets sent; rapid drag input does not
+     * stream a command per pixel. Mirrors scheduleFovSlider.
+     */
+    fovSliderInput(fov: number): void;
+    /**
+     * Declare slider drag start/end. While dragging, echo-sync does not
+     * override the slider (the user is in control). Setting `false` flushes
+     * any pending debounced FoV immediately. Mirrors the pointer-up
+     * flushFovSlider call.
+     */
+    setFovSliderDragging(dragging: boolean): void;
+    /**
+     * Subscribe to slider FoV changes. The callback fires on `fovSliderInput`
+     * and on idle echo-sync (when the camera echo updates the slider). Returns
+     * an unsubscribe function.
+     */
+    onSliderFov(cb: (fov: number) => void): () => void;
+    /**
+     * Declare ball-drag start/end. While dragging, echo-sync does not apply
+     * the echoed pan to the local accumulator (the user is in control).
+     * The pixel-deflection-to-rate conversion happens in the UI layer; the
+     * UI calls `setPanRate` with the normalised result.
+     */
+    setBallDragging(dragging: boolean): void;
+    /**
+     * Send zero pan and zoom rates if (and only if) a non-zero rate is currently
+     * active, and clear drag flags and any pending FoV timer without sending it.
+     * Use on component unmount or camera hide -- mirrors the cleanup effects at
+     * CameraFeed.tsx:477-508.
+     */
+    stop(): void;
+    /**
+     * Stop the controller and drop all slider-change subscribers. Call when
+     * the owning component is permanently destroyed.
+     */
+    dispose(): void;
+    private flushFovSlider;
+    private setSliderFovInternal;
+}