@hugpy/video-intelligence-ui 0.1.0

package/src/video/useMediaJobs.ts

@@ -0,0 +1,279 @@
+// A live view of every IN-FLIGHT media-bus job (studio / movie / identity /
+// generate / crop / extract) WITH PLACEMENT — the console-wide "Active Processes"
+// feed. Polls GET /video/jobs (the media CATALOG projection), which unlike the
+// unified /llm/jobs feed carries a `placement` object: WHERE each render
+// physically executes (ae · cuda:0 · P-studio), and surfaces the reservation
+// `awaiting_capacity` HOLD phase + its shortfall reason + overtaken count.
+//
+// Honest rendering only: `progress` is projected ONLY when the server sends it —
+// no fabricated bars. Cadence ~2s; a fetch error keeps the last-good list rather
+// than flashing empty. Mounted-ref guarded so a late poll never setState after
+// unmount, and the interval is cleared on unmount.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { hugpyConfig } from "../config";
+import { request, okValue } from "../transport/client";
+// 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). */
+export interface ProgressDetail {
+  segmentDone: number | null;
+  segmentTotal: number | null;
+  step: number | null;
+  steps: number | null;
+  fraction: number | null;
+}
+
+/** WHERE a job physically executes (omit-when-unset on the wire). */
+export interface Placement {
+  source: string | null; // "reservation" | "template"
+  host: string | null; // box: "ae" | "central" | ...
+  workerId: string | null;
+  gpu: string | null; // device: "cuda:0" | null (cpu)
+  process: string | null; // "P-studio" | "P-comfy" | "P-identity" | "ffmpeg" | ...
+  reservedBytes: number | null;
+}
+
+/** The reservation HOLD marker (progress.phase === "awaiting_capacity"). */
+export interface HoldInfo {
+  reason: Record<string, unknown> | null;
+  heldSince: number | null;
+  overtaken: number;
+}
+
+/** One in-flight media-bus job, projected for the Active Processes panel. */
+export interface MediaJob {
+  id: string;
+  name: string; // bus job kind
+  status: string; // queued | claimed | running | cancelling
+  createdAt: number | null; // epoch seconds
+  principal: string | null;
+  /** Effective phase chip: the reservation hold overrides the raw status. */
+  phase: string; // queued | awaiting_capacity | running | claimed | cancelling
+  hold: HoldInfo | null; // set only when phase === "awaiting_capacity"
+  progress: number | null; // 0..1 when the server sends one, else null
+  progressDetail: ProgressDetail | null; // the numbers behind the bar
+  stage: string | null;
+  placement: Placement | null;
+  /** The server's stage timeline: a TAIL while live, the whole thing when terminal. */
+  stageLog: StageEntry[];
+  stageLogTotal: number; // how many entries exist server-side (tail elides the rest)
+  /** The failure envelope of a terminal-failed job — rendered verbatim, never "failed". */
+  failure: JobFailure | null;
+  terminal: boolean; // done | failed | cancelled (only present with the history filter)
+  progressedAt: number | null; // last REAL movement (the stall/stale basis)
+}
+
+function str(v: unknown): string | null {
+  return typeof v === "string" && v.trim() ? v : null;
+}
+function num(v: unknown): number | null {
+  return typeof v === "number" && isFinite(v) ? v : null;
+}
+
+function parsePlacement(raw: unknown): Placement | null {
+  if (!raw || typeof raw !== "object") return null;
+  const p = raw as Record<string, unknown>;
+  return {
+    source: str(p.source),
+    host: str(p.host),
+    workerId: str(p.worker_id),
+    gpu: str(p.gpu),
+    process: str(p.process),
+    reservedBytes: num(p.reserved_bytes),
+  };
+}
+
+/** The timeline entries, kept in their WIRE shape for `ProcessTimeline`. */
+function parseStageLog(raw: unknown): StageEntry[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.filter(
+    (e): e is StageEntry =>
+      !!e && typeof e === "object" && typeof (e as StageEntry).stage === "string",
+  );
+}
+
+/**
+ * The failure envelope, passed through UNTOUCHED. Whatever code/message the
+ * backend produced (e.g. `deps_missing` with its pip remedy) is what the panel
+ * renders — no summarising, no generic "failed".
+ */
+function parseFailure(raw: unknown): JobFailure | null {
+  if (!raw || typeof raw !== "object") return null;
+  const f = raw as JobFailure;
+  return f.code || f.message ? f : null;
+}
+
+function parseProgressDetail(raw: unknown): ProgressDetail | null {
+  if (!raw || typeof raw !== "object") return null;
+  const d = raw as Record<string, unknown>;
+  return {
+    segmentDone: num(d.segment_done),
+    segmentTotal: num(d.segment_total),
+    step: num(d.step),
+    steps: num(d.steps),
+    fraction: num(d.fraction),
+  };
+}
+
+function parseJobs(raw: unknown, includeTerminal: boolean): MediaJob[] {
+  const jobs = (raw as { jobs?: unknown } | null)?.jobs;
+  if (!Array.isArray(jobs)) return [];
+  const out: MediaJob[] = [];
+  for (const j of jobs) {
+    if (!j || typeof j !== "object") continue;
+    const row = j as Record<string, unknown>;
+    const id = str(row.job_id);
+    if (!id) continue;
+    const status = str(row.status) ?? "";
+    const terminal = !IN_FLIGHT.has(status);
+    if (terminal && !includeTerminal) continue;
+    const progress = (row.progress as Record<string, unknown> | null) ?? null;
+    const phaseRaw =
+      progress && typeof progress === "object" ? str(progress.phase) : null;
+    const isHold = phaseRaw === "awaiting_capacity";
+    let hold: HoldInfo | null = null;
+    if (isHold && progress) {
+      hold = {
+        reason:
+          progress.reason && typeof progress.reason === "object"
+            ? (progress.reason as Record<string, unknown>)
+            : null,
+        heldSince: num(progress.held_since),
+        overtaken: num(progress.overtaken) ?? 0,
+      };
+    }
+    out.push({
+      id,
+      name: str(row.name) ?? "",
+      status,
+      createdAt: num(row.created),
+      principal: str(row.principal),
+      phase: isHold ? "awaiting_capacity" : status,
+      hold,
+      // Honest: only surface a numeric progress the server actually sent. The
+      // server now computes it (segments done + the within-segment denoise
+      // fraction) and sends null when the runner reports nothing measurable, so a
+      // missing bar still means "unknown", never "zero".
+      progress: num(row.progress_ratio),
+      progressDetail: parseProgressDetail(row.progress_detail),
+      stage: str(row.current_stage) ?? (progress ? str(progress.stage) : null),
+      placement: parsePlacement(row.placement),
+      stageLog: parseStageLog(row.stage_log),
+      stageLogTotal: num(row.stage_log_total) ?? 0,
+      failure: parseFailure(row.failure),
+      terminal,
+      progressedAt: num(row.progressed_at) ?? num(row.last_movement_ts),
+    });
+  }
+  return out;
+}
+
+/**
+ * The live in-flight media jobs + a manual `refetch` (fired right after a cancel
+ * so the row disappears without waiting for the next poll tick). Polls only while
+ * a consumer is mounted.
+ *
+ * `includeTerminal` asks the server for recent terminal rows too (?all=1) — the
+ * panel's "history" filter, which is how a FAILED render (and its verbatim failure
+ * envelope) stays inspectable after it leaves the in-flight set. The default feed
+ * is live work only: the server hides in-flight rows abandoned by a dead process,
+ * so days-old ghosts no longer crowd the panel.
+ */
+export function useMediaJobs(
+  includeTerminal = false,
+): { jobs: MediaJob[]; refetch: () => void } {
+  const [jobs, setJobs] = useState<MediaJob[]>([]);
+  const mounted = useRef(true);
+
+  const load = useCallback(async () => {
+    const url = includeTerminal
+      ? `${hugpyConfig.mediaJobsUrl}?all=1`
+      : hugpyConfig.mediaJobsUrl;
+    const r = await request<unknown>(url, {
+      meta: { specKey: "media", operation: "media.jobs.poll" },
+    });
+    if (!mounted.current) return;
+    if (!r.ok) return; // transient — keep last-good, retry next tick
+    setJobs(parseJobs(okValue(r), includeTerminal));
+  }, [includeTerminal]);
+
+  useEffect(() => {
+    mounted.current = true;
+    void load();
+    const id = window.setInterval(() => void load(), POLL_MS);
+    return () => {
+      mounted.current = false;
+      window.clearInterval(id);
+    };
+  }, [load]);
+
+  return { jobs, refetch: load };
+}
+
+// ── shared render helpers (used by the console-wide panel + the studio tab) ──
+
+/** "ae · cuda:0 · P-studio" — the placement one-liner, or "" when unknown. */
+export function placementLine(p: Placement | null): string {
+  if (!p) return "";
+  const parts = [p.host, p.gpu ?? "cpu", p.process].filter(
+    (x): x is string => typeof x === "string" && x.length > 0,
+  );
+  return parts.join(" · ");
+}
+
+/** True when the job runs OFF the central box (an external worker/service). */
+export function isExternal(p: Placement | null): boolean {
+  return !!p && !!p.host && p.host !== "central";
+}
+
+/** Human GiB for a reserved-bytes value, or "" when absent. */
+export function reservedGib(p: Placement | null): string {
+  if (!p || p.reservedBytes == null) return "";
+  return `${(p.reservedBytes / 1024 ** 3).toFixed(1)} GB reserved`;
+}
+
+/**
+ * "42% · segment 1/2 · step 12/30" — the label under the bar, built only from the
+ * numbers the server actually sent. "" when there is nothing honest to say.
+ */
+export function progressLabel(job: MediaJob): string {
+  const parts: string[] = [];
+  if (job.progress != null) parts.push(`${Math.round(job.progress * 100)}%`);
+  const d = job.progressDetail;
+  if (d?.segmentTotal != null && d.segmentDone != null) {
+    // 1-based for humans: while segment 0 renders, an operator reads "segment 1/2".
+    const at = Math.min(d.segmentDone + 1, d.segmentTotal);
+    parts.push(`segment ${at}/${d.segmentTotal}`);
+  }
+  if (d?.step != null && d.steps != null) parts.push(`step ${d.step}/${d.steps}`);
+  return parts.join(" · ");
+}
+
+/**
+ * The freshest timeline line — "segment 0/2 · t2v · worker rendering". This is the
+ * one-line answer to "what is it doing", shown WITHOUT expanding the row, because
+ * "no logs are ever shown" was the operator's complaint and a detail that needs a
+ * click is still a detail nobody sees.
+ */
+export function latestEvent(job: MediaJob): string {
+  for (let i = job.stageLog.length - 1; i >= 0; i -= 1) {
+    const d = job.stageLog[i]?.detail;
+    if (typeof d === "string" && d.trim()) return d;
+  }
+  return "";
+}
+
+/** Elapsed since an epoch-seconds start, as "12s" / "3m 4s". */
+export function elapsedSince(createdAt: number | null): string {
+  if (createdAt == null) return "";
+  const secs = Math.max(0, Math.floor(Date.now() / 1000 - createdAt));
+  if (secs < 60) return `${secs}s`;
+  return `${Math.floor(secs / 60)}m ${secs % 60}s`;
+}

package/src/video/useModels.ts

@@ -0,0 +1,413 @@
+// The shared image-model dropdown source. Fetches the model registry and the task
+// defaults, filters to the GENERATION image tasks (text-to-image + image-to-image)
+// off the FULL `tasks` capability list, and exposes the options + the default id +
+// loading/error as data (never throws). Both the Frames station (config surface)
+// and the later Generate station import this verbatim.
+//
+// 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
+// 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
+// that destructure the four data fields are unaffected).
+import { useCallback, useEffect, useRef, useState } from "react";
+import { z } from "zod";
+import { request, okValue, errorOf, describeAppError } from "../transport/client";
+import { hugpyConfig } from "../config";
+
+export interface ModelOption {
+  /** The model id sent to the backend. */
+  id: string;
+  /** Human label for the dropdown (hub_id when present, else the id). */
+  label: string;
+  /**
+   * The model's FULL generation-capability list (from `capabilitiesOf`) — carried
+   * through so the Generate station can drive REQUIRED inputs from it (see
+   * `requiredInputsFor`). Previously discarded after the label was built.
+   */
+  tasks: string[];
+  /**
+   * Present but NOT pickable — a LoRA adapter or a pipeline component (an
+   * encoder/VAE split). Rendered greyed with `reason` rather than offered
+   * (it would refuse) or hidden (the operator then can't see the file they
+   * downloaded). See the k61 incident note on GENERATION_IMAGE_TASKS.
+   */
+  disabled?: boolean;
+  /** Why it can't be picked — shown as the option's title. */
+  reason?: string;
+}
+
+export interface ImageModelsState {
+  models: ModelOption[];
+  defaultId: string | null;
+  loading: boolean;
+  error: string | null;
+  /**
+   * Force an immediate re-fetch of the registry (manual refresh affordance).
+   * Runs as a background revalidation — it does not clear the current list.
+   */
+  refresh: () => void;
+}
+
+// Tolerant schemas — the registry carries many fields we ignore; passthrough keeps
+// them and we only assert the three we read.
+const modelEntrySchema = z
+  .object({
+    id: z.string(),
+    task: z.string().nullable().optional(),
+    // Full capability list (0.1.122+): `task` is only the PRIMARY — filtering
+    // on it alone hid secondary capabilities (dual t2i+img2img models).
+    tasks: z.array(z.string()).nullable().optional(),
+    hub_id: z.string().nullable().optional(),
+    // Why a present model still can't serve (0.1.x+, k61): adapters and
+    // pipeline components are real files that are not servable on their own.
+    adapter: z.boolean().nullable().optional(),
+    serveable: z.boolean().nullable().optional(),
+    unserveable_reason: z.string().nullable().optional(),
+  })
+  .passthrough();
+
+const modelsResponseSchema = z
+  .object({ data: z.array(modelEntrySchema) })
+  .passthrough();
+
+const promptTasksSchema = z
+  .object({
+    defaults: z.record(z.string()).nullable().optional(),
+  })
+  .passthrough();
+
+const IMAGE_TASK = "text-to-image";
+// Since the img2img go-live (map §12.5 follow-up), image-to-image models
+// (Qwen-Image-Edit, flux-klein) are first-class generate targets — but they
+// REQUIRE a start image (no text-only path), so their labels say so.
+const IMG2IMG_TASK = "image-to-image";
+// The full set of GENERATION / EDITING image tasks this workspace can drive: t2i
+// produces from text, img2img edits a start image. Both stations consume exactly
+// these. Analysis-only image tasks (classification, captioning, detection, …) are
+// NOT generate targets, so they are deliberately excluded — a model must advertise
+// one of these in its capability list to enter the picker.
+const GENERATION_IMAGE_TASKS: readonly string[] = [IMAGE_TASK, IMG2IMG_TASK];
+
+// Rows that are NOT generation targets but must still be explicable in an image
+// picker (k61, 2026-07-31). The flux2 incident put a text-encoder COMPONENT and
+// an image LoRA in front of the operator as if they were models: the encoder was
+// selectable in image UIs where it can never serve, and the LoRA — left
+// unclassified and defaulted to text-generation — refused with
+// "supported: ['text-generation']". They now enter the list GREYED, carrying the
+// backend's own reason, so the affordance says what the file is instead of
+// pretending it can generate.
+const ADAPTER_TASK = "adapter";
+const COMPONENT_TASK = "pipeline-component";
+const NEEDS_CLASSIFICATION_TASK = "needs-classification";
+const EXPLAINED_NON_TARGETS: readonly string[] = [
+  ADAPTER_TASK,
+  COMPONENT_TASK,
+  NEEDS_CLASSIFICATION_TASK,
+];
+
+function nonTargetReason(m: z.infer<typeof modelEntrySchema>): string {
+  if (m.unserveable_reason) return m.unserveable_reason;
+  const caps = capabilitiesOf(m);
+  if (m.adapter || caps.includes(ADAPTER_TASK))
+    return "LoRA adapter — apply it to a base image model; it can't generate on its own.";
+  if (caps.includes(COMPONENT_TASK))
+    return "Pipeline component (encoder/VAE) — served through its parent pipeline, not on its own.";
+  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
+// director's judge-VLM select) can filter the registry the same way.
+export function capabilitiesOf(m: z.infer<typeof modelEntrySchema>): string[] {
+  return m.tasks?.length ? m.tasks : m.task ? [m.task] : [];
+}
+
+/**
+ * The REQUIRED-input contract for a model, derived purely from its capability
+ * `tasks[]`. The Generate station drives its explicit prompt/start-image controls
+ * off this instead of leaving the user to hand-add parts. Truth table:
+ *
+ *   tasks includes…            → image
+ *   ─────────────────────────────────────────
+ *   text-to-image only         → "none"      (t2i can't take a start image)
+ *   text-to-image + img2img    → "optional"  (start image ⇒ img2img edit)
+ *   image-to-image only        → "required"  (edit model — no text-only path)
+ *   empty / unrecognized       → "optional"  (safe default: text + optional image)
+ *
+ * `text` is always "required" — every generation path here needs a prompt.
+ */
+export function requiredInputsFor(
+  tasks: string[],
+): { text: "required"; image: "required" | "optional" | "none" } {
+  const t2i = tasks.includes(IMAGE_TASK);
+  const i2i = tasks.includes(IMG2IMG_TASK);
+  let image: "required" | "optional" | "none";
+  if (i2i && !t2i) image = "required"; // edit-only model
+  else if (t2i && i2i) image = "optional"; // dual t2i + img2img
+  else if (t2i && !i2i) image = "none"; // pure text-to-image
+  else image = "optional"; // empty / unknown capabilities → safe default
+  return { text: "required", image };
+}
+
+export function useImageModels(): ImageModelsState {
+  const [state, setState] = useState<Omit<ImageModelsState, "refresh">>({
+    models: [],
+    defaultId: null,
+    loading: true,
+    error: null,
+  });
+
+  // `mounted` gates setState after unmount; `inFlight` collapses overlapping
+  // revalidations (interval + focus + manual) into one; `ctrlRef` lets every
+  // trigger — including a manual refresh — abort on unmount.
+  const mounted = useRef(true);
+  const inFlight = useRef(false);
+  const ctrlRef = useRef<AbortController | null>(null);
+
+  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" },
+        }),
+      ]);
+      if (!mounted.current) return;
+
+      if (!mRes.ok) {
+        // A background revalidation that fails must NOT wipe a working picker —
+        // keep the last good list; only the first (foreground) load surfaces it.
+        if (background) return;
+        setState({
+          models: [],
+          defaultId: null,
+          loading: false,
+          error: describeAppError(errorOf(mRes)),
+        });
+        return;
+      }
+      const mParsed = modelsResponseSchema.safeParse(okValue(mRes));
+      if (!mParsed.success) {
+        if (background) return;
+        setState({
+          models: [],
+          defaultId: null,
+          loading: false,
+          error: "Malformed models response.",
+        });
+        return;
+      }
+
+      // Only a model that ADVERTISES a generation image task is pickable. Adapters,
+      // pipeline components and unclassified rows are appended after them, greyed,
+      // so they are explained rather than offered or hidden.
+      const rows = mParsed.data.data.filter((m) => {
+        const caps = capabilitiesOf(m);
+        return (
+          caps.some((t) => GENERATION_IMAGE_TASKS.includes(t)) ||
+          m.adapter === true ||
+          caps.some((t) => EXPLAINED_NON_TARGETS.includes(t))
+        );
+      });
+      const models: ModelOption[] = rows
+        .map((m) => {
+          const caps = capabilitiesOf(m);
+          const t2i = caps.includes(IMAGE_TASK);
+          const i2i = caps.includes(IMG2IMG_TASK);
+          if (!t2i && !i2i) {
+            const reason = nonTargetReason(m);
+            return {
+              id: m.id,
+              label: `${m.hub_id ?? m.id}  · not selectable`,
+              tasks: caps,
+              disabled: true,
+              reason,
+            };
+          }
+          const suffix = i2i && !t2i
+            ? "  · img2img (needs a start image)"
+            : i2i && t2i
+              ? "  · t2i + img2img"
+              : "";
+          // Carry the full capability list through — the Generate station reads it
+          // via `requiredInputsFor(...)` to drive its required prompt/start-image UI.
+          return { id: m.id, label: (m.hub_id ?? m.id) + suffix, tasks: caps };
+        })
+        .sort((a, b) => Number(a.disabled ?? false) - Number(b.disabled ?? false));
+
+      // Task defaults are best-effort — a failure there still yields a usable list.
+      let defaultId: string | null = null;
+      if (tRes.ok) {
+        const tParsed = promptTasksSchema.safeParse(okValue(tRes));
+        if (tParsed.success) {
+          const d = tParsed.data.defaults?.[IMAGE_TASK];
+          if (typeof d === "string") defaultId = d;
+        }
+      }
+      // Guarantee a SELECTABLE default: fall back to the first pickable option
+      // when the task default is absent, greyed, or not in the list at all.
+      const pickable = models.filter((m) => !m.disabled);
+      if (
+        (!defaultId || !pickable.some((m) => m.id === defaultId)) &&
+        pickable.length > 0
+      ) {
+        defaultId = pickable[0].id;
+      }
+
+      setState({ models, defaultId, loading: false, error: null });
+    } finally {
+      inFlight.current = false;
+    }
+  }, []);
+
+  useEffect(() => {
+    mounted.current = true;
+    const ctrl = new AbortController();
+    ctrlRef.current = ctrl;
+
+    // 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);
+
+    return () => {
+      mounted.current = false;
+      ctrl.abort();
+      window.removeEventListener("focus", revalidate);
+      document.removeEventListener("visibilitychange", revalidate);
+      clearInterval(timer);
+    };
+  }, [load]);
+
+  const refresh = useCallback(() => {
+    void load(true);
+  }, [load]);
+
+  return { ...state, refresh };
+}
+
+export interface TaskModelsState {
+  models: ModelOption[];
+  loading: boolean;
+  error: string | null;
+  refresh: () => void;
+}
+
+/**
+ * A registry list filtered to models whose capability `tasks[]` include ONE given
+ * 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);
+ * 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.
+ */
+export function useModelsByTask(task: string): TaskModelsState {
+  const [state, setState] = useState<Omit<TaskModelsState, "refresh">>({
+    models: [],
+    loading: true,
+    error: null,
+  });
+
+  const mounted = useRef(true);
+  const inFlight = useRef(false);
+  const ctrlRef = useRef<AbortController | null>(null);
+
+  const load = useCallback(
+    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" },
+        });
+        if (!mounted.current) return;
+        if (!mRes.ok) {
+          if (background) return;
+          setState({ models: [], loading: false, error: describeAppError(errorOf(mRes)) });
+          return;
+        }
+        const mParsed = modelsResponseSchema.safeParse(okValue(mRes));
+        if (!mParsed.success) {
+          if (background) return;
+          setState({ models: [], loading: false, error: "Malformed models response." });
+          return;
+        }
+        const models: ModelOption[] = mParsed.data.data
+          .filter((m) => capabilitiesOf(m).includes(task))
+          .map((m) => ({
+            id: m.id,
+            label: m.hub_id ?? m.id,
+            tasks: capabilitiesOf(m),
+          }));
+        setState({ models, loading: false, error: null });
+      } finally {
+        inFlight.current = false;
+      }
+    },
+    [task],
+  );
+
+  useEffect(() => {
+    mounted.current = true;
+    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);
+    return () => {
+      mounted.current = false;
+      ctrl.abort();
+      window.removeEventListener("focus", revalidate);
+      document.removeEventListener("visibilitychange", revalidate);
+      clearInterval(timer);
+    };
+  }, [load]);
+
+  const refresh = useCallback(() => {
+    void load(true);
+  }, [load]);
+
+  return { ...state, refresh };
+}