@hugpy/video-intelligence-ui 0.3.3 → 0.3.5

package/src/video/modelsFeed.ts

@@ -0,0 +1,105 @@
+// SHARED model catalog feed (2026-10-05) — the models twin of jobStream.ts.
+// Every model picker on the page SEEDS from ONE shared GET of /v1/models and
+// /prompt/tasks (the first hook to ask fetches; the rest reuse that answer), then
+// subscribes here. One EventSource on /api/llm/models/rows/stream (core pushes a
+// row the moment a box's `models` / `residents` row changes — DB trigger ->
+// pg_notify) marks the cached answer stale and tells subscribers to re-read it.
+// No focus/visibility revalidation and no timer: the catalog moves only when the
+// DB says it moved. Same reconnect rule as jobStream: re-attach only after a
+// stream that HAD opened drops (the server caps it at an hour).
+import { hugpyConfig } from "../config";
+import { request } from "../transport/client";
+
+type Result = Awaited<ReturnType<typeof request<unknown>>>;
+type Listener = () => void;
+
+const cache = new Map<string, Promise<Result>>();
+const listeners = new Set<Listener>();
+let es: EventSource | null = null;
+let refs = 0;
+let everOpened = false;
+let retryTimer: ReturnType<typeof setTimeout> | null = null;
+let notifyTimer: ReturnType<typeof setTimeout> | null = null;
+const RETRY_MS = 5000;
+const COALESCE_MS = 500; // one action touches several rows; re-read once
+
+/** The shared answer for `url` (one request for the whole page until the DB
+ *  reports a change). A failed answer is not kept, so the next caller retries. */
+export function sharedRequest(url: string, meta: Record<string, string>): Promise<Result> {
+  let p = cache.get(url);
+  if (!p) {
+    p = request<unknown>(url, { meta } as Parameters<typeof request>[1]);
+    cache.set(url, p);
+    p.then((r) => {
+      if (!r.ok && cache.get(url) === p) cache.delete(url);
+    });
+  }
+  return p;
+}
+
+function changed(): void {
+  if (notifyTimer) return;
+  notifyTimer = setTimeout(() => {
+    notifyTimer = null;
+    cache.clear();
+    for (const fn of listeners) {
+      try {
+        fn();
+      } catch {
+        /* one bad subscriber must not stall the rest */
+      }
+    }
+  }, COALESCE_MS);
+}
+
+function openStream(): void {
+  if (es || typeof window === "undefined" || typeof EventSource === "undefined") return;
+  let source: EventSource;
+  try {
+    source = new EventSource(`${hugpyConfig.apiBase}/llm/models/rows/stream`, {
+      withCredentials: true,
+    });
+  } catch {
+    return; // no EventSource — pickers keep their one-time seed
+  }
+  es = source;
+  source.onopen = () => {
+    everOpened = true;
+  };
+  source.onmessage = (e: MessageEvent) => {
+    let ev: { stage?: string };
+    try {
+      ev = JSON.parse(e.data);
+    } catch {
+      return;
+    }
+    if (ev.stage === "stream.ready") return; // transport hello, not a row
+    changed();
+  };
+  source.onerror = () => {
+    source.close();
+    es = null;
+    if (!everOpened || refs === 0 || retryTimer) return; // absent endpoint: stay on the seed
+    retryTimer = setTimeout(() => {
+      retryTimer = null;
+      if (refs > 0) openStream();
+    }, RETRY_MS);
+  };
+}
+
+/** Call `fn` whenever the DB reports a model-row change. Returns the unsubscribe. */
+export function subscribeModelChanges(fn: Listener): () => void {
+  listeners.add(fn);
+  refs += 1;
+  openStream();
+  return () => {
+    listeners.delete(fn);
+    refs -= 1;
+    if (refs <= 0) {
+      refs = 0;
+      es?.close();
+      es = null;
+      everOpened = false;
+    }
+  };
+}

package/src/video/studioOracle.ts

@@ -0,0 +1,48 @@
+import { hugpyConfig } from "../config";
+import { request, okValue, errorOf, describeAppError } from "../transport/client";
+
+export type OracleSettings = {
+  model_id?: string;
+  width?: number;
+  height?: number;
+  fps?: number;
+  frames?: number;
+  steps?: number;
+  cfg?: number;
+  seed?: number;
+};
+
+export async function planStudioSettings(
+  capability: "t2v" | "i2v",
+  prompt: string,
+  settings: OracleSettings,
+  explicit: string[],
+): Promise<OracleSettings> {
+  const res = await request<unknown>(hugpyConfig.studioPlanUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ capability, prompt, settings, explicit_settings: explicit }),
+    meta: { specKey: "studio", operation: "studio.oracle.plan" },
+  });
+  if (!res.ok) throw new Error(describeAppError(errorOf(res)));
+  const result = okValue(res) as { settings?: OracleSettings };
+  if (!result || !result.settings || !result.settings.model_id) {
+    throw new Error("Oracle returned no executable Studio settings plan.");
+  }
+  return result.settings;
+}
+
+export async function planStudioMovie(body: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const res = await request<unknown>(hugpyConfig.studioPlanUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    meta: { specKey: "studio", operation: "studio.oracle.movie.plan" },
+  });
+  if (!res.ok) throw new Error(describeAppError(errorOf(res)));
+  const result = okValue(res) as { body?: Record<string, unknown>; planning?: unknown[] };
+  if (!result || !result.body || !Array.isArray(result.planning)) {
+    throw new Error("Oracle returned no executable Cinema plan.");
+  }
+  return result.body;
+}

package/src/video/useMediaJobs.ts

@@ -12,13 +12,13 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { hugpyConfig } from "../config";
 import { request, okValue } from "../transport/client";
+import { subscribeJobStream } from "./jobStream";
 // The stage-timeline + failure shapes are the SAME wire objects the studio tab
 // already renders through `ProcessTimeline`; reusing its types (and, in the panel,
 // the component itself) keeps one renderer for "what it did / where it broke"
 // instead of a second, divergent one for the console-wide view.
 import type { StageEntry, JobFailure } from "../stations/studio/studioShared";
 
-const POLL_MS = 2000;
 const IN_FLIGHT = new Set(["queued", "claimed", "running", "cancelling"]);
 
 /** The numbers behind the bar (omit-when-unset on the wire). */
@@ -230,13 +230,27 @@ export function useMediaJobs(
     setJobs(parseJobs(okValue(r), includeTerminal));
   }, [includeTerminal]);
 
+  // Seed ONCE, then refresh on PUSH: a worker-reported transition arrives on the
+  // shared job stream and we re-read the catalog projection once (coalesced), so
+  // placement / stage-log / phase stay the server's list shape — never a timer.
   useEffect(() => {
     mounted.current = true;
     void load();
-    const id = window.setInterval(() => void load(), POLL_MS);
+    let coalesce: number | null = null;
+    const unsub = subscribeJobStream(() => {
+      if (coalesce != null) return; // already a reload pending this burst
+      coalesce = window.setTimeout(() => {
+        coalesce = null;
+        void load();
+      }, 300);
+    });
+    const onFocus = () => { void load(); };
+    window.addEventListener("focus", onFocus);
     return () => {
       mounted.current = false;
-      window.clearInterval(id);
+      if (coalesce != null) window.clearTimeout(coalesce);
+      unsub();
+      window.removeEventListener("focus", onFocus);
     };
   }, [load]);
 

package/src/video/useModels.ts

@@ -7,8 +7,7 @@
 // Staleness fix: the registry is no longer fetched only once on mount. Models
 // adopted MID-SESSION (e.g. ae ComfyUI checkpoints that appear once ComfyUI comes
 // up) must enter the picker WITHOUT a full page reload, so the hook now
-// stale-while-revalidates — it re-fetches on window focus / tab visibility, on a
-// gentle background interval (skipped while the tab is hidden), and on demand via
+// stale-while-revalidates — it re-fetches on window focus / tab visibility and on demand via
 // the exposed `refresh()`. Background revalidations never blank a working picker:
 // `loading` flips only for the very first load, and a failed poll keeps the last
 // good list. The public surface gained `refresh` (additive — existing consumers
@@ -17,6 +16,7 @@ import { useCallback, useEffect, useRef, useState } from "react";
 import { z } from "zod";
 import { request, okValue, errorOf, describeAppError } from "../transport/client";
 import { hugpyConfig } from "../config";
+import { sharedRequest, subscribeModelChanges } from "./modelsFeed";
 
 export interface ModelOption {
   /** The model id sent to the backend. */
@@ -119,10 +119,6 @@ function nonTargetReason(m: z.infer<typeof modelEntrySchema>): string {
   return "Unclassified — no task derived from this model's files yet.";
 }
 
-// Gentle background revalidation cadence (ms). Cheap same-origin GET; only ONE
-// picker instance is mounted at a time (studio sub-tabs share one WorkbenchStation),
-// and polls are skipped while the tab is hidden.
-const REFRESH_INTERVAL_MS = 45_000;
 
 // Capability = the FULL `tasks` list; the single `task` (primary) is only the
 // fallback for older payloads. Exported so task-specific pickers (e.g. the Movie
@@ -167,7 +163,7 @@ export function useImageModels(): ImageModelsState {
   });
 
   // `mounted` gates setState after unmount; `inFlight` collapses overlapping
-  // revalidations (interval + focus + manual) into one; `ctrlRef` lets every
+  // revalidations (focus + manual) into one; `ctrlRef` lets every
   // trigger — including a manual refresh — abort on unmount.
   const mounted = useRef(true);
   const inFlight = useRef(false);
@@ -176,17 +172,10 @@ export function useImageModels(): ImageModelsState {
   const load = useCallback(async (background: boolean) => {
     if (inFlight.current) return;
     inFlight.current = true;
-    const signal = ctrlRef.current?.signal;
     try {
       const [mRes, tRes] = await Promise.all([
-        request<unknown>(hugpyConfig.modelsUrl, {
-          signal,
-          meta: { specKey: "frames", operation: "models.list" },
-        }),
-        request<unknown>(hugpyConfig.promptTasksUrl, {
-          signal,
-          meta: { specKey: "frames", operation: "prompt.tasks" },
-        }),
+        sharedRequest(hugpyConfig.modelsUrl, { specKey: "frames", operation: "models.list" }),
+        sharedRequest(hugpyConfig.promptTasksUrl, { specKey: "frames", operation: "prompt.tasks" }),
       ]);
       if (!mounted.current) return;
 
@@ -284,28 +273,13 @@ export function useImageModels(): ImageModelsState {
     // Foreground load (the only one that toggles `loading` / surfaces an error).
     void load(false);
 
-    // Revalidate when the tab/window regains focus or becomes visible — a
-    // returning operator sees models adopted while they were away, no reload.
-    const revalidate = () => {
-      if (document.visibilityState === "hidden") return;
-      void load(true);
-    };
-    window.addEventListener("focus", revalidate);
-    document.addEventListener("visibilitychange", revalidate);
-
-    // Gentle interval backstop for the same-tab case (ComfyUI comes up while the
-    // operator is looking at the station). Skipped while the tab is hidden.
-    const timer = setInterval(() => {
-      if (document.visibilityState === "hidden") return;
-      void load(true);
-    }, REFRESH_INTERVAL_MS);
+    // Re-read only when the DB reports a model-row change (modelsFeed).
+    const off = subscribeModelChanges(() => void load(true));
 
     return () => {
       mounted.current = false;
       ctrl.abort();
-      window.removeEventListener("focus", revalidate);
-      document.removeEventListener("visibilitychange", revalidate);
-      clearInterval(timer);
+      off();
     };
   }, [load]);
 
@@ -328,7 +302,7 @@ export interface TaskModelsState {
  * task — the generic sibling of useImageModels for non-generation pickers. The
  * Movie director's judge-model select uses it with "image-text-to-text" to surface
  * the vision-language models that can SCORE a segment. Same tolerant fetch +
- * stale-while-revalidate posture (focus / visibility / interval / manual refresh);
+ * stale-while-revalidate posture (focus / visibility / manual refresh);
  * a failed background revalidation keeps the last good list. No task-defaults fetch
  * (there is no canonical default for an arbitrary task) — the caller supplies its
  * own default and keeps it selectable even when the list is empty.
@@ -348,12 +322,8 @@ export function useModelsByTask(task: string): TaskModelsState {
     async (background: boolean) => {
       if (inFlight.current) return;
       inFlight.current = true;
-      const signal = ctrlRef.current?.signal;
       try {
-        const mRes = await request<unknown>(hugpyConfig.modelsUrl, {
-          signal,
-          meta: { specKey: "generate", operation: "models.list" },
-        });
+        const mRes = await sharedRequest(hugpyConfig.modelsUrl, { specKey: "generate", operation: "models.list" });
         if (!mounted.current) return;
         if (!mRes.ok) {
           if (background) return;
@@ -386,22 +356,11 @@ export function useModelsByTask(task: string): TaskModelsState {
     const ctrl = new AbortController();
     ctrlRef.current = ctrl;
     void load(false);
-    const revalidate = () => {
-      if (document.visibilityState === "hidden") return;
-      void load(true);
-    };
-    window.addEventListener("focus", revalidate);
-    document.addEventListener("visibilitychange", revalidate);
-    const timer = setInterval(() => {
-      if (document.visibilityState === "hidden") return;
-      void load(true);
-    }, REFRESH_INTERVAL_MS);
+    const off = subscribeModelChanges(() => void load(true));
     return () => {
       mounted.current = false;
       ctrl.abort();
-      window.removeEventListener("focus", revalidate);
-      document.removeEventListener("visibilitychange", revalidate);
-      clearInterval(timer);
+      off();
     };
   }, [load]);
 

package/src/video/useMovieSessions.ts

@@ -23,10 +23,7 @@ import {
   studioMovieResumeUrl,
 } from "../config";
 import { request, okValue, errorOf, describeAppError } from "../transport/client";
-
-// 6s — the same background cadence useStudioClips polls the clip catalog at. A movie
-// segment takes minutes, so anything faster only costs a filesystem walk.
-const POLL_MS = 6000;
+import { subscribeJobStream } from "./jobStream";
 
 // The bus statuses that mean "this session's job is still going to do something" —
 // the client-side mirror of the route's _MOVIE_INFLIGHT_STATES, used to decide
@@ -223,11 +220,23 @@ export function useMovieSessions(active: boolean): MovieSessionsState {
     }
   }, []);
 
+  // Seed once when the panel opens, then re-read the movies root only when a
+  // worker reports a job transition (coalesced) — no 6s filesystem-walk poll.
   useEffect(() => {
     if (!active) return;
     void load();
-    const id = window.setInterval(() => void load(), POLL_MS);
-    return () => window.clearInterval(id);
+    let coalesce: number | null = null;
+    const unsub = subscribeJobStream(() => {
+      if (coalesce != null) return;
+      coalesce = window.setTimeout(() => {
+        coalesce = null;
+        void load();
+      }, 400);
+    });
+    return () => {
+      if (coalesce != null) window.clearTimeout(coalesce);
+      unsub();
+    };
   }, [active, load]);
 
   // Pause and resume differ only in their url and their telemetry op, so they share

package/src/video/useOperatorHistory.ts

@@ -1,105 +1,15 @@
-// OPERATOR HISTORY HYDRATION (operator ask 2026-08-13): the superadmin gets
-// COMPLETE visibility of previous renders in the Session Library — not just
-// what this browser tab produced. The library itself stays a per-session
-// sessionStorage working set (by design); this hook back-fills it from the
-// SERVER record once per session for an operator principal:
+// OPERATOR HISTORY HYDRATION — RETIRED (2026-10-05).
 //
-//   * probe: GET keysVideoShareUrl — the same 200⇒operator / 401⇒guest probe
-//     SharePanel uses (members and share guests never hydrate; their lists
-//     stay owner-scoped server-side).
-//   * source: GET /video/jobs?all=1 for terminal done generate_image /
-//     generate_scene / generate_movie rows (the list projection strips
-//     results, so each job detail is fetched for its outputs). Clips
-//     (studio_i2v) already hydrate via useStudioClips poll — not repeated.
-//   * sink: addToLibrary — idempotent by uri, tombstone-respecting (an item
-//     the operator removed stays removed), genKind-tagged so the Generate
-//     station can filter the strips by its CURRENT SECTION.
-//
-// Once-per-session guard in sessionStorage; canned demo never hydrates.
-import { useEffect } from "react";
-import { request, okValue } from "../transport/client";
-import { hugpyConfig, jobStatusUrl } from "../config";
-import { addToLibrary, type LibraryGenKind } from "./mediaLibrary";
-import { getSessionId } from "../session";
-import { isCanned } from "../demo/mode";
-import type { MediaRef } from "./contract";
-
-// generate_studio_movie = CINEMA renders — hydrated too (mapped onto the
-// generate_movie library kind: same Videos shelf, no schema change).
-const GEN_KINDS: readonly string[] = [
-  "generate_image", "generate_scene", "generate_movie", "generate_studio_movie",
-];
-// v2 (2026-08-13): the once-per-session flag must change whenever the
-// HYDRATED KINDS change — a tab that hydrated v1 (no cinema jobs) kept its
-// flag through every reload and never saw generate_studio_movie history.
-const FLAG_PREFIX = "vi.operatorHistory.v2";
-const DETAIL_CAP = 150; // newest-first; enough history without hammering the API
-
-function flagKey(): string {
-  try { return `${FLAG_PREFIX}:${getSessionId()}`; } catch { return FLAG_PREFIX; }
-}
+// This hook back-filled the Session Library from the server record once per
+// session, but ONLY for a console operator, and it decided operator-ness by
+// probing GET /keys/video-share — the same 200⇒operator / 401⇒guest probe
+// SharePanel used. That route has no backend in this build: the probe only ever
+// 404'd, so the hydration never ran. With no operator signal to replace it (and
+// per the directive to drop the dead /keys/video-share calls), this is now a
+// no-op rather than a dead request fired on every page load. The exported
+// signature is kept so its one caller stays valid.
 
+/** No-op: operator history hydration is retired (see the file header). */
 export function useOperatorHistory(): void {
-  useEffect(() => {
-    if (isCanned()) return;
-    try { if (sessionStorage.getItem(flagKey())) return; } catch { /* no-op */ }
-    let cancelled = false;
-    void (async () => {
-      // Operator probe — non-operators (401/403) never hydrate.
-      const probe = await request<unknown>(hugpyConfig.keysVideoShareUrl, {
-        meta: { specKey: "media", operation: "operator.probe" },
-      });
-      if (cancelled || !probe.ok) return;
-      // jobStatusUrl("") = `${apiBase}/video/jobs/` — trim the slash and query
-      // the list route with terminal rows included.
-      const list = await request<unknown>(
-        `${jobStatusUrl("").replace(/\/$/, "")}?all=1&limit=300`,
-        { meta: { specKey: "media", operation: "history.jobs.list" } },
-      );
-      if (cancelled || !list.ok) return;
-      const jobs = ((okValue(list) as { jobs?: unknown[] })?.jobs ?? []) as Array<
-        Record<string, unknown>
-      >;
-      const wanted = jobs
-        .filter((j) => j?.status === "done" && GEN_KINDS.includes(String(j?.name)))
-        .slice(0, DETAIL_CAP);
-      for (const j of wanted) {
-        if (cancelled) return;
-        const id = String(j.job_id ?? j.id ?? "");
-        if (!id) continue;
-        const det = await request<unknown>(jobStatusUrl(id), {
-          meta: { specKey: "media", operation: "history.job.detail" },
-        });
-        if (!det.ok) continue;
-        const result = (okValue(det) as { result?: { outputs?: unknown[] } })?.result;
-        for (const o of (result?.outputs ?? []) as Array<Record<string, unknown>>) {
-          if (!o?.uri || !o?.asset_id) continue;
-          const ref = {
-            asset_id: String(o.asset_id),
-            kind: (o.kind === "video" ? "video" : "image"),
-            uri: String(o.uri),
-            mime: (o.mime as string) ?? (o.kind === "video" ? "video/mp4" : "image/png"),
-            width: (o.width as number) ?? null,
-            height: (o.height as number) ?? null,
-            duration_s: (o.duration_s as number) ?? null,
-            fps_native: (o.fps_native as number) ?? null,
-            channels: (o.channels as number) ?? null,
-            sample_rate: (o.sample_rate as number) ?? null,
-          } as MediaRef;
-          addToLibrary(ref, "history", `${String(j.name)} · ${id.slice(0, 8)}`, {
-            genKind: (j.name === "generate_studio_movie"
-              ? "generate_movie"
-              : j.name) as LibraryGenKind,
-            // groupId = the producing job: each historical run groups as its own
-            // work (like live pushes) instead of one giant shared "history" pile
-            // whose identical key collided ACROSS the type sections (expanding
-            // Videos/history also expanded Images/history).
-            groupId: id,
-          });
-        }
-      }
-      try { sessionStorage.setItem(flagKey(), String(Date.now())); } catch { /* no-op */ }
-    })();
-    return () => { cancelled = true; };
-  }, []);
+  /* intentionally empty — no /keys/video-share probe, no history back-fill */
 }

package/src/video/usePromptAssist.ts

@@ -37,7 +37,7 @@ export type AssistMode = "detail" | "generate";
 export type AssistBusyMode = AssistMode | "spread" | "negative";
 
 /** The active sub-mode, sent as `context.kind` so video modes get motion/camera phrasing. */
-export type AssistKind = "image" | "scene" | "movie";
+export type AssistKind = "image" | "scene" | "movie" | "clip";
 
 /** The `specKey` a host's telemetry rides under (matches the host's other calls). */
 type SpecKey = "generate" | "studio";
@@ -53,11 +53,13 @@ export interface UsePromptAssistOptions {
 export interface AssistModel {
   /** Catalog key sent back as `body.model`. */
   model: string;
-  /** Seated on a worker right now (answers in ~1s) vs present but cold (first call loads it). */
+  /** Seated on a worker right now. */
   serving: boolean;
+  /** Present on a worker, but not necessarily loaded. */
+  held?: boolean;
   /** Canonical residency (STATE-MODEL.md #4): serving|loaded = ready; hot = on a
    *  worker drive (pays a t_load); cold = central only (pays a download + load). */
-  state?: "serving" | "loaded" | "hot" | "cold";
+  state?: "serving" | "loaded" | "hot" | "cold" | "unknown";
   framework?: string | null;
   /** True for the fleet default — used when the user has never chosen. */
   default?: boolean;
@@ -183,6 +185,7 @@ async function assistCall(
   const value = okValue(res) as { ticket?: string; pending?: boolean } | null;
   const ticket = value?.ticket;
   if (!ticket) return res; // direct (non-ticket) result — serve as-is
+  if (value?.pending === false) return res; // current orbit returns the completed result with its ticket
   const deadline = Date.now() + TICKET_CEILING_MS;
   for (;;) {
     await new Promise((r) => setTimeout(r, TICKET_POLL_MS));

package/src/video/useToks.ts

@@ -15,8 +15,8 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { hugpyConfig } from "../config";
 import { request, okValue } from "../transport/client";
+import { subscribeJobStream } from "./jobStream";
 
-const POLL_MS = 2000;
 const RECENT_LIMIT = 100;
 
 /** One recent inference sample (omit-when-unset tolerated on the wire). */
@@ -127,22 +127,30 @@ export function useToks(): {
     setLive(recent.ok || report.ok);
   }, []);
 
+  // Seed once, then refresh on PUSH: the shared job stream fires on every
+  // worker-reported transition (coalesced), so the tok/s tail tracks live work
+  // without a 2s timer. No job activity → the last-good snapshot simply stands.
   useEffect(() => {
     mounted.current = true;
     void load();
-    const id = window.setInterval(() => void load(), POLL_MS);
+    let coalesce: number | null = null;
+    const unsub = subscribeJobStream(() => {
+      if (coalesce != null) return;
+      coalesce = window.setTimeout(() => {
+        coalesce = null;
+        void load();
+      }, 400);
+    });
     return () => {
       mounted.current = false;
-      window.clearInterval(id);
+      if (coalesce != null) window.clearTimeout(coalesce);
+      unsub();
     };
   }, [load]);
 
   return { entries, groups, live };
 }
 
-/** The poll cadence, exported so the panel header can label it ("every 2s"). */
-export const TOKS_POLL_MS = POLL_MS;
-
 /** "12s ago" / "3m ago" from an epoch-seconds ts, "" when unknown. */
 export function tokAgo(ts: number | null, nowMs: number): string {
   if (ts == null) return "";

package/src/video/watchVideoJob.ts

@@ -0,0 +1,43 @@
+/** One status seed followed by pushed job transitions. No periodic GET loop. */
+import { videoJobUrl } from "../config";
+import { request, okValue } from "../transport/client";
+import { subscribeJobStream } from "./jobStream";
+
+export function watchVideoJob(
+  jobId: string,
+  onJob: (job: Record<string, unknown>) => boolean | void,
+  onTimeout: () => void,
+  timeoutMs: number,
+): () => void {
+  let active = true;
+  let pushed = false;
+  let unsubscribe: (() => void) | null = null;
+  const deadline = Date.now() + timeoutMs;
+  const timer = window.setTimeout(() => {
+    if (!active || Date.now() < deadline) return;
+    stop();
+    onTimeout();
+  }, timeoutMs);
+  const stop = () => {
+    if (!active) return;
+    active = false;
+    window.clearTimeout(timer);
+    unsubscribe?.();
+    unsubscribe = null;
+  };
+  const deliver = (row: unknown) => {
+    if (!active || !row || typeof row !== "object") return;
+    if (onJob(row as Record<string, unknown>) === true) stop();
+  };
+  unsubscribe = subscribeJobStream((ev) => {
+    if (ev.job_id !== jobId || !ev.job) return;
+    pushed = true;
+    deliver(ev.job);
+  });
+  void request<unknown>(videoJobUrl(jobId), {
+    meta: { specKey: "studio", operation: "video.job.seed" },
+  }).then((res) => {
+    if (res.ok && !pushed) deliver(okValue(res));
+  });
+  return stop;
+}