@hugpy/video-intelligence-ui 0.1.0

package/src/video/usePromptAssist.ts

@@ -0,0 +1,394 @@
+// Shared LLM PROMPT-ASSIST hook — the Enhance / Generate transport + busy/error
+// model, extracted from GenerateStation so the Generate, Studio Clip, and Studio
+// Movie composers all POST the SAME promptAssistUrl with ONE in-flight call at a
+// time and identical error semantics.
+//
+// Presentational-by-callback, like GoalComposer: this hook owns NO editor state.
+// Each host passes the current draft when it fires a call and an `apply` callback
+// that drops the returned prompt wherever that host keeps its text (replace the
+// primary text part / set the prompt string / patch a goal row). A failed call
+// NEVER reaches `apply`, so a bad response can't clobber the existing prompt — it
+// surfaces on `assistError` instead. The paired <PromptAssistButtons> renders the
+// button cluster; keeping the two beside each other keeps adoption a small,
+// non-destabilizing flip per composer.
+import { useCallback, useEffect, useState } from "react";
+import { request, okValue, errorOf, describeAppError } from "../transport/client";
+import { hugpyConfig } from "../config";
+import {
+  readIntentResult,
+  readSpreadResult,
+  type AssistContextWire,
+  type IntentResult,
+  type SpreadRequestWire,
+  type SpreadResult,
+} from "./spreadAssist";
+
+/** The two assist actions: "detail" = Enhance (enrich a draft), "generate" = write fresh. */
+export type AssistMode = "detail" | "generate";
+
+/**
+ * Every mode that can hold the ONE in-flight assist slot. The two whole-request
+ * modes added by STUDIO-SPREAD-SPEC ("spread" = one call rewriting N selected rows,
+ * "negative" = an exclusion list rather than prose) are NOT `AssistMode`, because
+ * they take no `draft` and do not return a prompt for a single field — but they DO
+ * share the concurrency gate and the error model, so they share the busy value.
+ * Widening only the BUSY type keeps `runAssist`'s signature honest.
+ */
+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";
+
+/** The `specKey` a host's telemetry rides under (matches the host's other calls). */
+type SpecKey = "generate" | "studio";
+
+export interface UsePromptAssistOptions {
+  /** Sub-mode sent as `context.kind` (image | scene | movie). */
+  kind: AssistKind;
+  /** Telemetry spec key for the request meta (the host's own key). */
+  specKey: SpecKey;
+}
+
+/** One selectable text generator, as offered by the backend's discovery route. */
+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). */
+  serving: boolean;
+  framework?: string | null;
+  /** True for the fleet default — used when the user has never chosen. */
+  default?: boolean;
+}
+
+/**
+ * The per-call typed extras (SPEC §1c). Purely ADDITIVE: a host that passes nothing
+ * sends the byte-identical body it sent before, which is what keeps GenerateStation
+ * and StudioGenerateTab compiling and behaving unchanged.
+ */
+export interface AssistExtras {
+  /**
+   * Typed row/identity state merged into `context` beside `kind`. This is the
+   * carrier for structured state — `hint` stays free-form user text (§1c ruling).
+   */
+  context?: Omit<AssistContextWire, "kind">;
+  /**
+   * Per-CALL model override. When set, this generator writes THIS call's prompt
+   * regardless of the hook-wide `assistModel` — the carrier for per-component
+   * assist-model selection (each prompt component can pick its own). Omitted by
+   * hosts that pass nothing, which then use the hook `assistModel` / fleet default.
+   */
+  model?: string | null;
+}
+
+export interface PromptAssistApi {
+  /** The ACTIVE mode while a call is in flight, or null when idle. Blocks concurrency + drives labels. */
+  assistBusy: AssistBusyMode | null;
+  /** The dismissible inline notice; a failed call sets it and leaves the prompt intact. */
+  assistError: string | null;
+  /** Clear the inline error notice. */
+  dismissError: () => void;
+  /**
+   * Fire an assist call. `draft` is the host's current prompt text (Enhance requires it;
+   * Generate sends it as a loose theme). On success the returned prompt is handed to
+   * `apply`; on ANY failure `apply` is never called and `assistError` is set instead.
+   */
+  runAssist: (
+    mode: AssistMode,
+    draft: string,
+    apply: (prompt: string) => void,
+    extra?: AssistExtras,
+  ) => Promise<void>;
+  /**
+   * Generate a NEGATIVE prompt (mode "negative", §1b) — an artifact/quality exclusion
+   * list, not prose. `subject` is what is being negated (the row's own prompt); a
+   * failure never reaches `apply`, exactly like runAssist.
+   */
+  runNegative: (
+    opts: { subject?: string; draft?: string; extra?: AssistExtras },
+    apply: (negative: string) => void,
+  ) => Promise<void>;
+  /**
+   * Run ONE coherent spread across the selected rows (mode "spread", §1a). Resolves
+   * to the parsed result, or null when the call failed (the reason is on
+   * `assistError`). NEVER N sequential per-row calls — that is the incoherence this
+   * whole feature exists to delete.
+   */
+  runSpread: (body: SpreadRequestWire) => Promise<SpreadResult | null>;
+  /**
+   * Classify a field's text (§1d). Deliberately OUTSIDE the busy gate: this is called
+   * on blur, must not be blocked by an in-flight generation, and must never surface as
+   * an error — any failure reads as a degraded `ambiguous`, i.e. "show both actions".
+   */
+  classifyIntent: (text: string, scope?: "segment" | "movie") => Promise<IntentResult>;
+  /** The text generators this fleet can actually run (empty until discovery returns). */
+  assistModels: AssistModel[];
+  /** The selected generator, or null to let the backend use the fleet default. */
+  assistModel: string | null;
+  /** Choose a generator; persisted so the choice survives a reload. */
+  setAssistModel: (model: string | null) => void;
+}
+
+// The user's pick is a PREFERENCE, not app state: persist it in localStorage so it
+// survives a reload, and share it across all three composers (Generate, Studio Clip,
+// Studio Movie) — they each mount their own hook, so a module-level key is what makes
+// the choice feel like one setting rather than three.
+const ASSIST_MODEL_KEY = "hugpy.promptAssist.model";
+
+function readStoredModel(): string | null {
+  try {
+    return window.localStorage.getItem(ASSIST_MODEL_KEY) || null;
+  } catch {
+    return null;                      // private mode / storage disabled — not fatal
+  }
+}
+
+// Defensively pull `.prompt` (a non-empty string) out of the prompt-assist 200 body
+// ({ prompt, model, kind }). Returns null for any malformed/empty shape so a bad
+// response surfaces as a notice instead of clobbering the prompt with junk. (Lifted
+// verbatim from GenerateStation's local helper so every host parses identically.)
+function readAssistPrompt(value: unknown): string | null {
+  if (value != null && typeof value === "object" && "prompt" in value) {
+    const p = (value as { prompt?: unknown }).prompt;
+    if (typeof p === "string" && p.trim() !== "") return p;
+  }
+  return null;
+}
+
+export function usePromptAssist({ kind, specKey }: UsePromptAssistOptions): PromptAssistApi {
+  // One in-flight call at a time: `assistBusy` holds the ACTIVE mode or null when idle —
+  // it both blocks concurrent calls and drives which button shows its loading label.
+  const [assistBusy, setAssistBusy] = useState<AssistBusyMode | null>(null);
+  const [assistError, setAssistError] = useState<string | null>(null);
+  const [assistModels, setAssistModels] = useState<AssistModel[]>([]);
+  const [assistModel, setAssistModelState] = useState<string | null>(readStoredModel);
+
+  // Discover the offerable generators once per mount. A failure is SILENT on purpose:
+  // the picker simply stays empty and assist keeps working on the fleet default, so a
+  // discovery hiccup can never block Enhance/Generate.
+  useEffect(() => {
+    let alive = true;
+    (async () => {
+      const res = await request<unknown>(hugpyConfig.promptAssistModelsUrl, {
+        method: "GET",
+        timeoutMs: 15_000,
+        meta: { specKey, operation: "prompt.assist.models" },
+      });
+      if (!alive || !res.ok) return;
+      const value = okValue(res);
+      const rows =
+        value != null && typeof value === "object" && Array.isArray((value as { models?: unknown }).models)
+          ? ((value as { models: AssistModel[] }).models)
+          : [];
+      setAssistModels(rows);
+      // Drop a stored pick the fleet no longer offers (model retired, worker gone) —
+      // otherwise the UI shows a selection that would fail on use.
+      setAssistModelState((current) =>
+        current && !rows.some((r) => r.model === current) ? null : current,
+      );
+    })();
+    return () => {
+      alive = false;
+    };
+  }, [specKey]);
+
+  const setAssistModel = useCallback((model: string | null) => {
+    setAssistModelState(model);
+    try {
+      if (model) window.localStorage.setItem(ASSIST_MODEL_KEY, model);
+      else window.localStorage.removeItem(ASSIST_MODEL_KEY);
+    } catch {
+      /* storage disabled — the choice still applies for this session */
+    }
+  }, []);
+
+  const dismissError = useCallback(() => setAssistError(null), []);
+
+  const runAssist = useCallback(
+    async (
+      mode: AssistMode,
+      draft: string,
+      apply: (prompt: string) => void,
+      extra?: AssistExtras,
+    ): Promise<void> => {
+      if (assistBusy) return; // block concurrent calls
+      const trimmed = draft.trim();
+      if (mode === "detail" && trimmed === "") return; // Enhance needs a draft
+      setAssistError(null);
+      setAssistBusy(mode);
+
+      // `model` is sent ONLY when the user has picked one; omitting it lets the backend
+      // apply the fleet default (flux2-klein-9b-uncensored-text-encoder, served from
+      // computron). The old comment here claimed "the backend picks the best resolvable
+      // chat model" — it did not, it used one hardcoded key; the picker plus a resolved
+      // default is what finally made that sentence true. The draft is omitted when blank
+      // (Generate from a truly empty box) and context.kind carries the active sub-mode so
+      // video modes get motion/camera phrasing.
+      //
+      // Thinking is suppressed server-side for EVERY generator (the assist route appends
+      // a no-think directive and strips any <think>...</think> that survives), so picking
+      // a reasoning model here cannot dump a monologue into the prompt box.
+      //
+      // TYPED CONTEXT (§1c): `extra.context` carries the STRUCTURED row state — this
+      // segment, its neighbours, the locked identity — beside `kind`. The backend
+      // renders joint modes into plain sentences and attaches the identity's
+      // do-not-invent list, which is what stopped the generator making up wardrobes
+      // for a bare character name. Omitted entirely by hosts that pass nothing, so
+      // their request body is unchanged.
+      const body: {
+        mode: AssistMode;
+        draft?: string;
+        model?: string;
+        context: AssistContextWire;
+      } = {
+        mode,
+        ...(trimmed !== "" ? { draft: trimmed } : {}),
+        ...((extra?.model ?? assistModel) ? { model: extra?.model ?? assistModel ?? undefined } : {}),
+        context: { kind, ...(extra?.context ?? {}) },
+      };
+
+      const res = await request<unknown>(hugpyConfig.promptAssistUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        timeoutMs: 90_000, // a few seconds typically; generous for an on-demand worker
+        meta: { specKey, operation: `prompt.assist.${mode}` },
+      });
+      if (!res.ok) {
+        setAssistError(describeAppError(errorOf(res)));
+        setAssistBusy(null);
+        return;
+      }
+      const prompt = readAssistPrompt(okValue(res));
+      if (prompt == null) {
+        setAssistError("The assistant returned an empty prompt — try again.");
+        setAssistBusy(null);
+        return;
+      }
+      apply(prompt);
+      setAssistBusy(null);
+    },
+    [assistBusy, kind, specKey, assistModel],
+  );
+
+  // ── mode "negative" (§1b) ────────────────────────────────────────────────
+  // A negative prompt is an ARTIFACT/QUALITY EXCLUSION LIST, not prose — reusing the
+  // scene system prompt returns a poem, which is why this is its own mode rather than
+  // a `detail` call with different words. `prompt` and `negative` carry the same text
+  // on the wire (no existing key moved); we read `prompt` via the shared reader.
+  const runNegative = useCallback(
+    async (
+      opts: { subject?: string; draft?: string; extra?: AssistExtras },
+      apply: (negative: string) => void,
+    ): Promise<void> => {
+      if (assistBusy) return;
+      setAssistError(null);
+      setAssistBusy("negative");
+      const body: Record<string, unknown> = {
+        mode: "negative",
+        context: { kind, ...(opts.extra?.context ?? {}) },
+      };
+      if (opts.subject && opts.subject.trim()) body.subject = opts.subject.trim();
+      if (opts.draft && opts.draft.trim()) body.draft = opts.draft.trim();
+      const negModel = opts.extra?.model ?? assistModel;
+      if (negModel) body.model = negModel;
+
+      const res = await request<unknown>(hugpyConfig.promptAssistUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        timeoutMs: 90_000,
+        meta: { specKey, operation: "prompt.assist.negative" },
+      });
+      if (!res.ok) {
+        setAssistError(describeAppError(errorOf(res)));
+        setAssistBusy(null);
+        return;
+      }
+      const text = readAssistPrompt(okValue(res));
+      if (text == null) {
+        setAssistError("The assistant returned an empty negative — try again.");
+        setAssistBusy(null);
+        return;
+      }
+      apply(text);
+      setAssistBusy(null);
+    },
+    [assistBusy, kind, specKey, assistModel],
+  );
+
+  // ── mode "spread" (§1a) ──────────────────────────────────────────────────
+  // ONE call for the whole selection. Returns the parsed result to the caller instead
+  // of applying anything itself: only the host knows which editor rows the returned
+  // segment_ids map to, and the "apply ONLY to rows that came back" rule is the whole
+  // safety property. A 502 carries the raw reply — surfaced honestly by the shared
+  // error mapper, never replaced with a fabricated segment.
+  const runSpread = useCallback(
+    async (body: SpreadRequestWire): Promise<SpreadResult | null> => {
+      if (assistBusy) return null;
+      setAssistError(null);
+      setAssistBusy("spread");
+      const payload = { ...body, ...(assistModel ? { model: assistModel } : {}) };
+      const res = await request<unknown>(hugpyConfig.promptAssistUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+        // A spread writes N paragraphs in one generation, so it is the longest assist
+        // call there is — and on a cold generator it pays a model load first.
+        timeoutMs: 180_000,
+        meta: { specKey, operation: "prompt.assist.spread" },
+      });
+      if (!res.ok) {
+        setAssistError(describeAppError(errorOf(res)));
+        setAssistBusy(null);
+        return null;
+      }
+      const parsed = readSpreadResult(okValue(res));
+      setAssistBusy(null);
+      if (parsed == null) {
+        setAssistError("The assistant returned a malformed spread — nothing was changed.");
+        return null;
+      }
+      if (parsed.segments.length === 0) {
+        setAssistError("The assistant wrote no usable segments — nothing was changed.");
+        return null;
+      }
+      return parsed;
+    },
+    [assistBusy, specKey, assistModel],
+  );
+
+  // ── the intent router (§1d) ──────────────────────────────────────────────
+  // Outside the busy gate on purpose (see the API doc above) and outside the error
+  // model too: this route ALWAYS returns 200, and a transport failure reads as a
+  // degraded "ambiguous" — the UI then offers both actions, which is the correct
+  // answer to "we don't know", not an error the user has to dismiss.
+  const classifyIntent = useCallback(
+    async (text: string, scope: "segment" | "movie" = "segment"): Promise<IntentResult> => {
+      const res = await request<unknown>(hugpyConfig.promptIntentUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ text, scope }),
+        timeoutMs: 30_000,
+        meta: { specKey, operation: "prompt.intent" },
+      });
+      if (!res.ok) {
+        return { intent: "ambiguous", operation: null, confidence: 0, cached: false, degraded: true };
+      }
+      return readIntentResult(okValue(res));
+    },
+    [specKey],
+  );
+
+  return {
+    assistBusy,
+    assistError,
+    dismissError,
+    runAssist,
+    runNegative,
+    runSpread,
+    classifyIntent,
+    assistModels,
+    assistModel,
+    setAssistModel,
+  };
+}

package/src/video/useRenderPresets.ts

@@ -0,0 +1,221 @@
+// GET /video/render/presets — WHAT THIS FLEET CAN ACTUALLY RENDER TODAY, read by the
+// console instead of guessed at.
+//
+// This is the fourth and only MEASURED preset surface (video_intel/studio/presets.py:
+// the eight ratified `RenderPreset` rows). The other three answer "what did we
+// curate?"; this one answers "what will come back as pixels?" — and until 2026-07-29
+// NOTHING in this SPA read it. The studio instead carried hand-maintained mirrors of
+// backend facts (a static model-id list, a hand-curated capability union, a
+// `STUDIO_REAL_FLOOR_GB = 6` that had drifted below every real row in the table), so a
+// user could compose a request the server was always going to refuse and only find out
+// at render time.
+//
+// WHAT THE PAYLOAD CARRIES, and why each half matters to a compatibility-aware UI:
+//   • `presets[]`  — per row: capability, model, precision, geometry (width/height/fps),
+//                    frame budget, `inputs[]` (what the CALLER must supply), `proven`
+//                    (this exact path has produced pixels on this fleet), and the
+//                    placement numbers (`vram_envelope_gb` = the minimum budget that can
+//                    bind this model; `vram_need_gib` / `fits_render_box` = provenance).
+//   • `unavailable[]` — every capability the enum declares that NO preset covers, with
+//                    the measured blocker and the full refusal text, straight from the
+//                    registry's own `capability_verdict`. A picker can therefore show
+//                    the dead options DISABLED with the real reason instead of hiding
+//                    the fleet's shape from the user.
+//
+// COURTESY LAYER, NEVER A GATE. The server-side refusal (POST /video/studio/i2v's
+// capability gate) stays authoritative — everything derived from this hook only decides
+// what to OFFER, never what to allow. If this fetch fails the surfaces fall back to
+// their prior hand-maintained lists and the server still refuses what it always did.
+//
+// SESSION-CACHED. The table is frozen data derived at request time from a registry that
+// only changes on deploy, so one fetch per page load is enough; the cache is a module
+// singleton shared by every mount (the Clip surface and the Movie composer both read
+// it) rather than a fetch per component.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { z } from "zod";
+import { request, okValue, errorOf, describeAppError } from "../transport/client";
+import { hugpyConfig } from "../config";
+
+// Tolerant/passthrough, like every other wire schema in this tree: assert only what we
+// read, so a payload that grows a field never breaks the parse.
+export const renderPresetSchema = z
+  .object({
+    id: z.string(),
+    title: z.string(),
+    description: z.string().nullable().optional(),
+    /** The PRIMARY capability — what a caller asks for to reach this preset. */
+    capability: z.string(),
+    /** The full set (every ratified row serves exactly one today). */
+    capabilities: z.array(z.string()).nullable().optional(),
+    model: z.string(),
+    framework: z.string().nullable().optional(),
+    task: z.string().nullable().optional(),
+    precision: z.string().nullable().optional(),
+    /** Human geometry string; "source" on the two ffmpeg enhance rows. */
+    geometry: z.string().nullable().optional(),
+    // null on the enhance rows — they inherit the source clip's geometry.
+    width: z.number().nullable().optional(),
+    height: z.number().nullable().optional(),
+    fps: z.number().nullable().optional(),
+    default_frames: z.number().nullable().optional(),
+    max_frames: z.number().nullable().optional(),
+    /** What the CALLER must supply — the compatibility spine of this whole module. */
+    inputs: z.array(z.string()).nullable().optional(),
+    /** Checked claim: this exact path has produced pixels on this fleet. */
+    proven: z.boolean().nullable().optional(),
+    evidence: z.string().nullable().optional(),
+    /** MOVIE ONLY: the preset ids a multi-segment render composes + its joint modes. */
+    composes: z.array(z.string()).nullable().optional(),
+    joints: z.array(z.string()).nullable().optional(),
+    // Placement (added backend-side 2026-07-29). vram_envelope_gb is the MINIMUM
+    // vram_budget_gb that can bind this row's model; the other two are provenance.
+    vram_envelope_gb: z.number().nullable().optional(),
+    vram_need_gib: z.number().nullable().optional(),
+    fits_render_box: z.boolean().nullable().optional(),
+  })
+  .passthrough();
+export type RenderPreset = z.infer<typeof renderPresetSchema>;
+
+export const unavailableCapabilitySchema = z
+  .object({
+    capability: z.string(),
+    /** The measured blocker, one clause — good tooltip material. */
+    reason: z.string().nullable().optional(),
+    /** The full user-facing refusal, including the menu of what IS available. */
+    refusal: z.string().nullable().optional(),
+  })
+  .passthrough();
+export type UnavailableCapability = z.infer<typeof unavailableCapabilitySchema>;
+
+const renderPresetsResponseSchema = z
+  .object({
+    presets: z.array(renderPresetSchema),
+    unavailable: z.array(unavailableCapabilitySchema).nullable().optional(),
+    menu: z.string().nullable().optional(),
+    /** Wan requires num_frames == 4k+1; the runner snaps down to the nearest. */
+    frame_cadence: z.number().nullable().optional(),
+    render_box: z.string().nullable().optional(),
+    render_box_vram_gib: z.number().nullable().optional(),
+  })
+  .passthrough();
+export type RenderPresetsPayload = z.infer<typeof renderPresetsResponseSchema>;
+
+export interface RenderPresetsState {
+  presets: RenderPreset[];
+  unavailable: UnavailableCapability[];
+  menu: string;
+  frameCadence: number | null;
+  renderBox: string;
+  renderBoxVramGib: number | null;
+  loading: boolean;
+  error: string | null;
+  /** True once a fetch has SUCCEEDED — the "is it safe to filter by this?" flag.
+   *  Every consumer must fall back to its unfiltered list while this is false, so a
+   *  slow or failed discovery call never presents an empty picker. */
+  loaded: boolean;
+  refresh: () => void;
+}
+
+// ── module-singleton session cache ──────────────────────────────────────────
+// One fetch per page load, shared by every mount. `inFlight` coalesces concurrent
+// first-mounts (the Clip surface and the Movie composer mount together) into one call.
+let cached: RenderPresetsPayload | null = null;
+let inFlight: Promise<void> | null = null;
+const subscribers = new Set<() => void>();
+
+function notify(): void {
+  for (const fn of subscribers) fn();
+}
+
+async function fetchOnce(force: boolean): Promise<string | null> {
+  if (cached && !force) return null;
+  if (inFlight && !force) {
+    await inFlight;
+    return null;
+  }
+  let err: string | null = null;
+  const p = (async () => {
+    const res = await request<unknown>(hugpyConfig.renderPresetsUrl, {
+      meta: { specKey: "studio", operation: "render.presets.list" },
+    });
+    if (!res.ok) {
+      err = describeAppError(errorOf(res));
+      return;
+    }
+    const parsed = renderPresetsResponseSchema.safeParse(okValue(res));
+    if (!parsed.success) {
+      err = "Malformed render-presets response.";
+      return;
+    }
+    cached = parsed.data;
+  })();
+  inFlight = p;
+  try {
+    await p;
+  } finally {
+    inFlight = null;
+    notify();
+  }
+  return err;
+}
+
+/** TEST/DEV seam: drop the session cache so the next mount re-fetches. */
+export function resetRenderPresetsCache(): void {
+  cached = null;
+  inFlight = null;
+}
+
+/**
+ * The fleet's measured render capability, as data. Never throws; a failed fetch
+ * reports `loaded:false` + an error string and every consumer keeps its fallback.
+ *
+ * `active` gates the network call the same way useStudioPresets/useMoviePresets do,
+ * so a surface that is not mounted costs nothing.
+ */
+export function useRenderPresets(active = true): RenderPresetsState {
+  const [, bump] = useState(0);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+  const mounted = useRef(true);
+
+  useEffect(() => {
+    mounted.current = true;
+    const rerender = () => {
+      if (mounted.current) bump((n) => n + 1);
+    };
+    subscribers.add(rerender);
+    return () => {
+      mounted.current = false;
+      subscribers.delete(rerender);
+    };
+  }, []);
+
+  const run = useCallback(async (force: boolean) => {
+    if (cached && !force) return;
+    setLoading(true);
+    const err = await fetchOnce(force);
+    if (!mounted.current) return;
+    setLoading(false);
+    setError(err);
+  }, []);
+
+  useEffect(() => {
+    if (!active) return;
+    void run(false);
+  }, [active, run]);
+
+  const refresh = useCallback(() => void run(true), [run]);
+
+  return {
+    presets: cached?.presets ?? [],
+    unavailable: cached?.unavailable ?? [],
+    menu: cached?.menu ?? "",
+    frameCadence: cached?.frame_cadence ?? null,
+    renderBox: cached?.render_box ?? "",
+    renderBoxVramGib: cached?.render_box_vram_gib ?? null,
+    loading,
+    error,
+    loaded: cached != null,
+    refresh,
+  };
+}