@agent-native/core 0.70.3 → 0.72.0

package/corpus/templates/clips/desktop/src/overlays/bubble.tsx

@@ -606,40 +606,90 @@ export function Bubble() {
   }, []);
 
   // ---- explicit drag handler --------------------------------------------
-  // We bypass `data-tauri-drag-region` entirely — it was unreliable across
-  // three iterations (see PR history). Tauri's attribute hook watches for
-  // elements with the attribute at page-load time, and also has gotchas
-  // with pointer-events, unfocused-window first-click swallowing, and
-  // WKWebView's latched event target. Calling `startDragging()` explicitly
-  // on mousedown is the canonical robust path (per Tauri's own docs for
-  // "customize drag behavior") and skips all of those footguns.
+  // Loom-style manual drag. We deliberately do NOT use Tauri's native
+  // `startDragging()` (or `data-tauri-drag-region`): with a native drag the OS
+  // window server owns the position, so the only way to keep the bubble on
+  // screen is to clamp AFTER each move and `set_position` it back — and the OS
+  // immediately shoves it back out toward the cursor on the next frame. That
+  // fight is exactly the jitter/snap-back we're killing here.
   //
-  // Interactive children (close X, size dots) are marked `data-no-drag`
-  // so their clicks land on their onClick handlers instead of starting
-  // a window drag.
-  const handleBubbleMouseDown = (e: React.MouseEvent) => {
-    // Only left mouse button initiates drag.
+  // Instead we drive the move ourselves. On pointer-down Rust snapshots the
+  // cursor + window anchor; each frame `bubble_drag_move` reads the live cursor,
+  // offsets the window by the cursor delta, and clamps BEFORE moving. The
+  // window therefore stops dead at the edge like a puck against a wall — the
+  // cursor keeps going, the bubble stays pinned, nothing to snap back from.
+  //
+  // Interactive children (close X, size dots) are marked `data-no-drag` so
+  // their clicks land on their onClick handlers instead of starting a drag.
+  const draggingRef = useRef(false);
+  const moveFrameRef = useRef<number | null>(null);
+
+  const handleBubblePointerDown = (e: React.PointerEvent) => {
+    // Only the left button initiates a drag.
     if (e.button !== 0) return;
     const target = e.target as HTMLElement;
-    // Walk up from the target — any ancestor marked `data-no-drag`
-    // means we're over a real control, not the draggable surface.
+    // Any ancestor marked `data-no-drag` means we're over a real control.
     if (target.closest("[data-no-drag]")) return;
-    console.log("[bubble] startDragging");
-    getCurrentWindow()
-      .startDragging()
-      .catch((err) => {
-        console.warn("[bubble] startDragging failed", err);
+    e.preventDefault();
+    draggingRef.current = true;
+    // Pointer capture keeps pointermove/up flowing even after the cursor
+    // leaves the (small) bubble window — which it will the moment the bubble
+    // hits an edge and the cursor outruns it.
+    try {
+      (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+    } catch {
+      // capture is best-effort
+    }
+    void invoke("bubble_drag_start").catch((err) => {
+      console.warn("[bubble] bubble_drag_start failed", err);
+    });
+  };
+
+  const handleBubblePointerMove = (e: React.PointerEvent) => {
+    if (!draggingRef.current) return;
+    // Coalesce a burst of pointermove events into at most one reposition per
+    // animation frame, no matter how fast the OS delivers them. Rust reads the
+    // live cursor itself, so the frame callback needs no coordinates.
+    if (moveFrameRef.current != null) return;
+    moveFrameRef.current = requestAnimationFrame(() => {
+      moveFrameRef.current = null;
+      if (!draggingRef.current) return;
+      void invoke("bubble_drag_move").catch(() => {
+        // Transient failures (e.g. window mid-teardown) are non-fatal; the
+        // next pointermove schedules another frame.
       });
+    });
+  };
+
+  const endBubbleDrag = (e: React.PointerEvent) => {
+    if (!draggingRef.current) return;
+    draggingRef.current = false;
+    if (moveFrameRef.current != null) {
+      cancelAnimationFrame(moveFrameRef.current);
+      moveFrameRef.current = null;
+    }
+    try {
+      (e.currentTarget as HTMLElement).releasePointerCapture(e.pointerId);
+    } catch {
+      // already released
+    }
+    void invoke("bubble_drag_end").catch((err) => {
+      console.warn("[bubble] bubble_drag_end failed", err);
+    });
   };
 
   return (
-    // The ENTIRE wrapper catches mousedown and calls `startDragging()`
-    // directly. No `data-tauri-drag-region` — see `handleBubbleMouseDown`.
+    // The ENTIRE wrapper is the drag surface — pointer-down drives the manual
+    // clamp-before-move drag loop. No `startDragging()`, no
+    // `data-tauri-drag-region` — see `handleBubblePointerDown` above.
     <div
       className={`bubble-wrapper bubble-${size}`}
       onMouseEnter={handleMouseEnter}
       onMouseLeave={handleMouseLeave}
-      onMouseDown={handleBubbleMouseDown}
+      onPointerDown={handleBubblePointerDown}
+      onPointerMove={handleBubblePointerMove}
+      onPointerUp={endBubbleDrag}
+      onPointerCancel={endBubbleDrag}
       data-path={activePath}
     >
       <div className="bubble-root">
@@ -676,7 +726,7 @@ export function Bubble() {
           }
         />
         {/* Close X — top-right of bubble, only visible on hover. Marked
-            `data-no-drag` so mousedown here does NOT call startDragging;
+            `data-no-drag` so pointer-down here does NOT start a drag;
             onClick fires normally. */}
         <button
           type="button"

package/corpus/templates/clips/desktop/src/overlays/countdown.tsx

@@ -46,12 +46,6 @@ export function Countdown() {
     };
   }, [closeWithEvent]);
 
-  useEffect(() => {
-    if (n === 1) {
-      emit("clips:countdown-one").catch(() => {});
-    }
-  }, [n]);
-
   useEffect(() => {
     if (n <= 0) {
       closeWithEvent("clips:countdown-done");

package/corpus/templates/clips/desktop/src/overlays/toolbar.tsx

@@ -14,7 +14,10 @@ import {
 const OVERLAY_SHADOW_GUTTER = 18;
 const TOOLBAR_CONTENT_WIDTH = 72;
 const TOOLBAR_COLLAPSED_HEIGHT = 150;
-const TOOLBAR_EXPANDED_HEIGHT = 234;
+// Collapsed content box (150 − 20 padding = 130) holds the centered primary
+// zone; the expanded height must fit that fixed 130 zone + the 88px hover
+// actions (+2 margin) + 20 vertical padding so nothing clips on hover.
+const TOOLBAR_EXPANDED_HEIGHT = 240;
 const TOOLBAR_WINDOW_WIDTH = TOOLBAR_CONTENT_WIDTH + OVERLAY_SHADOW_GUTTER * 2;
 const TOOLBAR_COLLAPSED_WINDOW_HEIGHT =
   TOOLBAR_COLLAPSED_HEIGHT + OVERLAY_SHADOW_GUTTER * 2;
@@ -225,51 +228,58 @@ export function Toolbar() {
       onFocusCapture={() => resizeToolbarWindow(true)}
       onBlurCapture={handleToolbarBlur}
     >
-      <button
-        className="toolbar-v-stop"
-        onClick={stop}
-        disabled={!!pendingAction || !enabled}
-        aria-label={
-          pendingAction === "stop" ? "Stopping recording" : "Stop recording"
-        }
-        title={
-          pendingAction === "stop"
-            ? pendingActionLabel
-            : enabled
-              ? "Stop recording"
-              : "Recording not started yet"
-        }
-        data-no-drag
-      >
-        {pendingAction === "stop" ? (
-          <IconLoader2 className="toolbar-v-spinner" size={18} />
-        ) : (
-          <span className="toolbar-v-stop-square" />
-        )}
-      </button>
-      <div className="toolbar-v-time">{formatTime(elapsed)}</div>
-      <button
-        className="toolbar-v-pause"
-        onClick={togglePause}
-        disabled={!enabled || !!pendingAction}
-        aria-label={paused ? "Resume" : "Pause"}
-        title={
-          pendingAction
-            ? pendingActionLabel
-            : enabled
-              ? paused
-                ? "Resume"
-                : "Pause"
-              : "Recording not started yet"
-        }
-        data-no-drag
-      >
-        {paused ? (
-          <IconPlayerPlayFilled size={18} />
-        ) : (
-          <IconPlayerPauseFilled size={18} />
-        )}
-      </button>
+      {/* Primary controls live in a fixed-height zone so they stay pinned
+          to the same vertical position whether or not the pill is hovered.
+          Centering happens INSIDE this zone (not on the pill), so the
+          collapsed→expanded `justify-content` change can't nudge the Stop
+          button up — only the hover actions below grow into the new space. */}
+      <div className="toolbar-v-primary">
+        <button
+          className="toolbar-v-stop"
+          onClick={stop}
+          disabled={!!pendingAction || !enabled}
+          aria-label={
+            pendingAction === "stop" ? "Stopping recording" : "Stop recording"
+          }
+          title={
+            pendingAction === "stop"
+              ? pendingActionLabel
+              : enabled
+                ? "Stop recording"
+                : "Recording not started yet"
+          }
+          data-no-drag
+        >
+          {pendingAction === "stop" ? (
+            <IconLoader2 className="toolbar-v-spinner" size={18} />
+          ) : (
+            <span className="toolbar-v-stop-square" />
+          )}
+        </button>
+        <div className="toolbar-v-time">{formatTime(elapsed)}</div>
+        <button
+          className="toolbar-v-pause"
+          onClick={togglePause}
+          disabled={!enabled || !!pendingAction}
+          aria-label={paused ? "Resume" : "Pause"}
+          title={
+            pendingAction
+              ? pendingActionLabel
+              : enabled
+                ? paused
+                  ? "Resume"
+                  : "Pause"
+                : "Recording not started yet"
+          }
+          data-no-drag
+        >
+          {paused ? (
+            <IconPlayerPlayFilled size={18} />
+          ) : (
+            <IconPlayerPauseFilled size={18} />
+          )}
+        </button>
+      </div>
       <div
         className="toolbar-v-hover-actions"
         role="group"

package/corpus/templates/clips/desktop/src/styles.css

@@ -2106,8 +2106,18 @@ body[data-clips-route="recording-pill"] #root {
   font-weight: 800;
   font-variant-numeric: tabular-nums;
   color: #ffffff;
-  -webkit-text-stroke: 1px rgba(17, 24, 39, 0.22);
+  /*
+   * Do NOT use -webkit-text-stroke here: it joins with a hard miter and no way
+   * to set stroke-linejoin, so at this size/weight the sharp concave corner of
+   * the "2" (where the curved top meets the flat bottom bar) sprouts star-shaped
+   * miter spikes. We fake a soft dark edge with a 4-direction 1px shadow halo
+   * instead, which has no join geometry and cannot spike.
+   */
   text-shadow:
+    1px 0 1px rgba(17, 24, 39, 0.22),
+    -1px 0 1px rgba(17, 24, 39, 0.22),
+    0 1px 1px rgba(17, 24, 39, 0.22),
+    0 -1px 1px rgba(17, 24, 39, 0.22),
     0 2px 4px rgba(0, 0, 0, 0.48),
     0 12px 34px rgba(0, 0, 0, 0.36),
     0 0 2px rgba(0, 0, 0, 0.72);
@@ -2420,8 +2430,12 @@ body[data-clips-route="recording-pill"] #root {
   display: flex;
   flex-direction: column;
   align-items: center;
-  justify-content: center;
-  gap: 10px;
+  /* Pin content to the top in BOTH states. The primary controls are
+     centered inside their own fixed-height zone (.toolbar-v-primary), so
+     the collapsed→expanded growth only adds room BELOW them. Without this,
+     flipping justify-content center→flex-start on hover yanked the Stop
+     button up toward the bar's top edge. */
+  justify-content: flex-start;
   /* Equal inset on all four sides from the pill edge to the buttons. */
   padding: 10px;
   overflow: hidden;
@@ -2440,8 +2454,9 @@ body[data-clips-route="recording-pill"] #root {
 
 .toolbar-v:hover,
 .toolbar-v:focus-within {
-  height: 234px;
-  justify-content: flex-start;
+  /* Matches TOOLBAR_EXPANDED_HEIGHT in toolbar.tsx — the fixed 130px primary
+     zone + 88px hover actions (+2 margin) + 20px vertical padding. */
+  height: 240px;
   border-radius: 26px;
 }
 
@@ -2449,6 +2464,19 @@ body[data-clips-route="recording-pill"] #root {
   cursor: grabbing;
 }
 
+/* Fixed-height home for Stop / time / Pause. Its height equals the collapsed
+   pill's content box (150px − 20px vertical padding = 130px), so the trio is
+   centered exactly as before when collapsed and never shifts when the pill
+   grows on hover — the extra height flows into .toolbar-v-hover-actions below. */
+.toolbar-v-primary {
+  flex: 0 0 130px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 10px;
+}
+
 .toolbar-v-stop {
   width: 30px;
   height: 30px;

package/corpus/templates/clips/desktop/src-tauri/src/clips/mod.rs

@@ -5,6 +5,7 @@ use std::process::Command;
 #[cfg(target_os = "macos")]
 use std::process::Stdio;
 use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Mutex, OnceLock};
 use std::thread;
 use std::time::Duration;
 use tauri::{
@@ -216,6 +217,36 @@ fn clamp_existing_bubble_window(app: &AppHandle, window: &WebviewWindow) {
     }
 }
 
+/// True while the user is hand-dragging the bubble through the JS pointer
+/// handlers (`bubble_drag_start` / `bubble_drag_move` / `bubble_drag_end`).
+///
+/// While this is set, the bubble's `Moved` event handler skips its own clamp.
+/// That handler used to re-clamp on EVERY move — including the OS-native drag's
+/// interpolated moves — calling `set_position` to snap the window back inside
+/// the screen. During a drag the OS keeps shoving the window back out toward the
+/// cursor, so the snap-back and the OS fought each frame and the bubble
+/// visibly jittered. Now the drag-move command is the sole authority on
+/// position during a drag and clamps every frame itself, so the handler must
+/// yield to it.
+static BUBBLE_DRAGGING: AtomicBool = AtomicBool::new(false);
+
+/// Anchor captured at the start of a hand-drag: the global cursor position and
+/// the bubble window's top-left, both in physical px with a desktop top-left
+/// origin (the same space `cursor_position()` / `outer_position()` report in).
+/// Each move computes `win_start + (cursor_now - cursor_start)` so the bubble
+/// tracks the cursor 1:1, then clamps to the monitor BEFORE moving.
+struct BubbleDragAnchor {
+    cursor_x: i32,
+    cursor_y: i32,
+    win_x: i32,
+    win_y: i32,
+}
+
+fn bubble_drag_anchor() -> &'static Mutex<Option<BubbleDragAnchor>> {
+    static ANCHOR: OnceLock<Mutex<Option<BubbleDragAnchor>>> = OnceLock::new();
+    ANCHOR.get_or_init(|| Mutex::new(None))
+}
+
 /// Path to the JSON blob that stores the last-known bubble position on disk.
 /// Lives in the Tauri app-data dir (platform-specific — `~/Library/Application
 /// Support/<bundle-id>/` on macOS). Returns None if the app-data dir cannot be
@@ -842,6 +873,13 @@ pub async fn show_bubble(app: AppHandle) -> Result<(), String> {
                 | tauri::WindowEvent::Resized(_)
                 | tauri::WindowEvent::ScaleFactorChanged { .. }
         ) {
+            // During a hand-drag the move command owns the position and clamps
+            // every frame; re-clamping here would race that loop and bring back
+            // the edge jitter, so yield until the drag ends (which runs a final
+            // clamp of its own).
+            if BUBBLE_DRAGGING.load(Ordering::SeqCst) {
+                return;
+            }
             clamp_existing_bubble_window(&app_for_bounds, &win_for_bounds);
         }
     });
@@ -1689,6 +1727,81 @@ pub async fn save_bubble_position(app: AppHandle, x: i32, y: i32) -> Result<(),
     Ok(())
 }
 
+/// Begin a Loom-style hand-drag of the bubble. The JS pointer handler calls
+/// this on pointer-down. We snapshot the current cursor and window position as
+/// the drag anchor and flip `BUBBLE_DRAGGING` so the bounds handler yields to
+/// the drag loop.
+///
+/// We deliberately do NOT use Tauri's native `startDragging()`: the OS window
+/// server owns the position during a native drag, so clamping it to the screen
+/// edge means fighting the OS every frame (the jitter/snap-back the user saw).
+/// Driving the move ourselves lets us clamp BEFORE moving, so the bubble stops
+/// dead at the edge like a puck hitting a wall.
+#[tauri::command]
+pub async fn bubble_drag_start(app: AppHandle) -> Result<(), String> {
+    let Some(window) = app.get_webview_window(BUBBLE_LABEL) else {
+        return Ok(());
+    };
+    let (Ok(cursor), Ok(pos)) = (window.cursor_position(), window.outer_position()) else {
+        return Ok(());
+    };
+    *bubble_drag_anchor().lock().unwrap_or_else(|e| e.into_inner()) = Some(BubbleDragAnchor {
+        cursor_x: cursor.x.round() as i32,
+        cursor_y: cursor.y.round() as i32,
+        win_x: pos.x,
+        win_y: pos.y,
+    });
+    BUBBLE_DRAGGING.store(true, Ordering::SeqCst);
+    Ok(())
+}
+
+/// Move the bubble to follow the cursor for the active hand-drag. The JS
+/// pointer handler calls this once per animation frame while dragging.
+///
+/// The new top-left is `win_start + (cursor_now - cursor_start)` — a 1:1
+/// follow in physical px — then clamped to the target monitor BEFORE the move.
+/// Because we clamp first, the window never overshoots the edge, so there is
+/// nothing to snap back from: the cursor can keep travelling past the edge
+/// while the bubble sits pinned against it. No-op if no drag is in progress.
+#[tauri::command]
+pub async fn bubble_drag_move(app: AppHandle) -> Result<(), String> {
+    let Some(window) = app.get_webview_window(BUBBLE_LABEL) else {
+        return Ok(());
+    };
+    let Ok(cursor) = window.cursor_position() else {
+        return Ok(());
+    };
+    let target = {
+        let guard = bubble_drag_anchor().lock().unwrap_or_else(|e| e.into_inner());
+        let Some(anchor) = guard.as_ref() else {
+            return Ok(());
+        };
+        (
+            anchor.win_x + (cursor.x.round() as i32 - anchor.cursor_x),
+            anchor.win_y + (cursor.y.round() as i32 - anchor.cursor_y),
+        )
+    };
+    let Ok(size) = window.outer_size() else {
+        return Ok(());
+    };
+    let (x, y) = clamp_bubble_window_position(&app, target.0, target.1, size.width, size.height);
+    let _ = window.set_position(PhysicalPosition::new(x, y));
+    Ok(())
+}
+
+/// End the hand-drag: clear the anchor, drop the dragging flag, and run one
+/// final clamp so the resting position is guaranteed in-bounds. The JS
+/// `onMoved` listener persists the final spot via `save_bubble_position`.
+#[tauri::command]
+pub async fn bubble_drag_end(app: AppHandle) -> Result<(), String> {
+    *bubble_drag_anchor().lock().unwrap_or_else(|e| e.into_inner()) = None;
+    BUBBLE_DRAGGING.store(false, Ordering::SeqCst);
+    if let Some(window) = app.get_webview_window(BUBBLE_LABEL) {
+        clamp_existing_bubble_window(&app, &window);
+    }
+    Ok(())
+}
+
 #[tauri::command]
 pub async fn show_popover(app: AppHandle) -> Result<(), String> {
     if let Some(window) = app.get_webview_window("popover") {

package/corpus/templates/clips/desktop/src-tauri/src/lib.rs

@@ -87,6 +87,9 @@ pub fn run() {
             clips::set_recording_state,
             clips::reset_state,
             clips::save_bubble_position,
+            clips::bubble_drag_start,
+            clips::bubble_drag_move,
+            clips::bubble_drag_end,
             clips::set_bubble_size,
             clips::load_bubble_size,
             // config commands

package/corpus/templates/clips/server/lib/media-permissions.ts

@@ -1,5 +1,9 @@
+// camera=* (not (self)) so the Clips browser extension's camera bubble — injected
+// as a cross-origin iframe — can run on Clips pages too; (self) only allows the
+// app's own same-origin camera. Display-capture stays same-origin. The browser
+// still prompts for camera/mic permission per origin.
 export const MEDIA_CAPTURE_PERMISSIONS_POLICY =
-  "camera=(self), microphone=(self), display-capture=(self), geolocation=(), screen-wake-lock=()";
+  "camera=*, microphone=(self), display-capture=(self), geolocation=(), screen-wake-lock=()";
 
 export function withMediaCapturePermissions(response: Response): Response {
   const headers = new Headers(response.headers);

package/corpus/templates/clips/shared/recording-audio.ts

@@ -0,0 +1,62 @@
+/**
+ * The canonical Clips "ready" chime, shared by every recorder surface so they
+ * all sound identical:
+ *   - the web app recorder   (app/lib/countdown-audio-cue.ts)
+ *   - the Chrome extension   (chrome-extension/src/offscreen.ts)
+ *   - mirrors the desktop app's start cue
+ *
+ * Framework-free Web Audio — safe to import anywhere; the functions only touch
+ * `window`/`AudioContext` when called, so importing the module is SSR-safe.
+ */
+
+/**
+ * Schedule the "ready" chime on an already-running {@link AudioContext}: a soft
+ * rising two-note (D5 → A5) with a faint high shimmer (A6). Each voice has a
+ * fast attack and a smooth exponential tail so it reads as a gentle
+ * confirmation rather than a harsh beep. Kept under ~380ms so it lands cleanly
+ * just as capture begins. The caller owns the context lifecycle; resolves once
+ * the last voice has finished.
+ */
+export function scheduleReadyChime(ctx: AudioContext): Promise<void> {
+  return new Promise<void>((resolve) => {
+    const t0 = ctx.currentTime + 0.005;
+    const voices = [
+      { freq: 587.33, at: 0.0, dur: 0.22, peak: 0.06 }, // D5
+      { freq: 880.0, at: 0.06, dur: 0.26, peak: 0.075 }, // A5
+      { freq: 1760.0, at: 0.065, dur: 0.14, peak: 0.02 }, // A6 shimmer
+    ];
+
+    let lastStop = t0;
+    for (const voice of voices) {
+      const startAt = t0 + voice.at;
+      const stopAt = startAt + voice.dur;
+      lastStop = Math.max(lastStop, stopAt);
+
+      const oscillator = ctx.createOscillator();
+      oscillator.type = "sine";
+      oscillator.frequency.setValueAtTime(voice.freq, startAt);
+
+      const gain = ctx.createGain();
+      gain.gain.setValueAtTime(0.0001, startAt);
+      gain.gain.exponentialRampToValueAtTime(voice.peak, startAt + 0.012);
+      gain.gain.exponentialRampToValueAtTime(0.0001, stopAt);
+
+      oscillator.connect(gain);
+      gain.connect(ctx.destination);
+
+      oscillator.start(startAt);
+      oscillator.stop(stopAt + 0.02);
+    }
+
+    let resolved = false;
+    const finish = (): void => {
+      if (resolved) return;
+      resolved = true;
+      resolve();
+    };
+    window.setTimeout(
+      finish,
+      Math.ceil((lastStop - ctx.currentTime) * 1000) + 60,
+    );
+  });
+}

package/corpus/templates/clips/shared/recording-core.ts

@@ -0,0 +1,94 @@
+/**
+ * Framework-agnostic recording primitives shared by BOTH recorders:
+ *   - the web app recorder  (app/components/recorder/recorder-engine.ts)
+ *   - the Chrome extension  (chrome-extension/src/offscreen.ts)
+ *
+ * Keep this free of React, chrome.*, Node-only APIs, and any DOM beyond the
+ * media types (MediaRecorder, URLSearchParams) so both build targets — the
+ * Vite app build and the extension's separate Vite build — can import it.
+ *
+ * The two recorders intentionally keep their own *orchestration* and *upload
+ * strategy* (the extension streams each timeslice chunk from an offscreen
+ * document that survives navigation; the web app assembles + slices on stop with
+ * retry/compression). What MUST stay identical is the on-the-wire contract with
+ * the server's chunk-upload route and the MediaRecorder codec choice — that's
+ * what lives here.
+ */
+
+/** MediaRecorder codecs to try, best-supported first.
+ *
+ * vp8 is listed before vp9 because some display-capture streams report vp9
+ * support but reject the encoder configuration; vp8 is the most broadly
+ * accepted. MP4/avc1 is the Safari/WebKit fallback. */
+export function pickMimeTypeCandidates(): string[] {
+  return [
+    "video/webm;codecs=vp8,opus",
+    "video/webm;codecs=vp9,opus",
+    "video/webm;codecs=vp8",
+    "video/webm;codecs=vp9",
+    "video/webm",
+    "video/mp4;codecs=avc1",
+    "video/mp4",
+  ];
+}
+
+/** First supported codec from {@link pickMimeTypeCandidates}, or "" to let the
+ * browser pick its own default (callers should treat "" as "omit mimeType"). */
+export function pickMimeType(): string {
+  if (typeof MediaRecorder === "undefined") return "video/webm";
+  for (const type of pickMimeTypeCandidates()) {
+    try {
+      if (MediaRecorder.isTypeSupported(type)) return type;
+    } catch {
+      // isTypeSupported can throw on some builds — treat as unsupported.
+    }
+  }
+  return "";
+}
+
+/** Query params understood by the chunk-upload route
+ * (`/api/uploads/:id/chunk`). This is the on-the-wire contract — the route in
+ * `server/routes/api/uploads/[recordingId]/chunk.post.ts` reads exactly these. */
+export type ChunkUploadParams = {
+  index: number;
+  total?: number;
+  isFinal?: boolean;
+  mimeType?: string;
+  durationMs?: number;
+  width?: number;
+  height?: number;
+  hasAudio?: boolean;
+  hasCamera?: boolean;
+};
+
+/** Encode {@link ChunkUploadParams} as the chunk-upload query string. Booleans
+ * become `1`/`0` and `durationMs` is rounded — matching what the route parses. */
+export function chunkUploadQuery(params: ChunkUploadParams): string {
+  const q = new URLSearchParams();
+  q.set("index", String(params.index));
+  if (params.total !== undefined) q.set("total", String(params.total));
+  q.set("isFinal", params.isFinal ? "1" : "0");
+  if (params.mimeType) q.set("mimeType", params.mimeType);
+  if (params.durationMs !== undefined) {
+    q.set("durationMs", String(Math.round(params.durationMs)));
+  }
+  if (params.width !== undefined) q.set("width", String(params.width));
+  if (params.height !== undefined) q.set("height", String(params.height));
+  if (params.hasAudio !== undefined) {
+    q.set("hasAudio", params.hasAudio ? "1" : "0");
+  }
+  if (params.hasCamera !== undefined) {
+    q.set("hasCamera", params.hasCamera ? "1" : "0");
+  }
+  return q.toString();
+}
+
+/** Full chunk-upload URL: `<chunkBaseUrl>?<encoded params>`. `chunkBaseUrl` is
+ * the per-recording endpoint (e.g. `/api/uploads/<id>/chunk` or its absolute
+ * form) with no existing query string. */
+export function chunkUploadUrl(
+  chunkBaseUrl: string,
+  params: ChunkUploadParams,
+): string {
+  return `${chunkBaseUrl}?${chunkUploadQuery(params)}`;
+}