@hugpy/video-intelligence-ui 0.1.0

package/src/video/useMoviePresets.ts

@@ -0,0 +1,97 @@
+// The Movie-tab TEMPLATE dropdown source. Fetches the curated movie templates
+// (GET /movie/presets), validates them with the tolerant moviePresetSchema, and
+// exposes the list + loading/error as data (never throws) — the same
+// data-not-throws contract as usePresets.ts, which the Generate station imports
+// alongside it.
+//
+// Two deliberate differences from usePresets:
+//   1. The wire is a BARE ARRAY of presets (not the {presets:[…]} envelope), each
+//      item carrying its whole `goals` shot list — see moviePresetSchema.
+//   2. The fetch is GATED behind an `active` flag: the Movie tab is one of three
+//      Generate sub-modes, so the list only loads once the movie tab is entered
+//      (and stays cached after). Passing active=false keeps it idle.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { z } from "zod";
+import { request, okValue, errorOf, describeAppError } from "../transport/client";
+import { hugpyConfig } from "../config";
+import { moviePresetSchema, type MoviePreset } from "./contract";
+
+export interface MoviePresetsState {
+  presets: MoviePreset[];
+  loading: boolean;
+  error: string | null;
+  /** Force an immediate re-fetch of the movie-template list. */
+  refresh: () => void;
+}
+
+// GET /movie/presets returns a {presets:[…]} envelope (matches /video/presets).
+// Tolerant parse of the envelope; each item is a tolerant moviePresetSchema.
+const moviePresetsResponseSchema = z.object({ presets: z.array(moviePresetSchema) });
+
+/**
+ * Load the curated movie templates. `active` gates the network call: pass
+ * `mode === "movie"` so the list only fetches once the Movie tab is entered.
+ * While inactive the hook reports loading:false / an empty list (nothing to show).
+ */
+export function useMoviePresets(active: boolean): MoviePresetsState {
+  const [state, setState] = useState<Omit<MoviePresetsState, "refresh">>({
+    presets: [],
+    loading: false,
+    error: null,
+  });
+
+  const mounted = useRef(true);
+  const inFlight = useRef(false);
+  const loadedRef = useRef(false);
+  const ctrlRef = useRef<AbortController | null>(null);
+
+  const load = useCallback(async (background: boolean) => {
+    if (inFlight.current) return;
+    inFlight.current = true;
+    if (!background) setState((s) => ({ ...s, loading: true }));
+    const signal = ctrlRef.current?.signal;
+    try {
+      const res = await request<unknown>(hugpyConfig.moviePresetsUrl, {
+        signal,
+        meta: { specKey: "generate", operation: "movie.presets.list" },
+      });
+      if (!mounted.current) return;
+
+      if (!res.ok) {
+        // A background refresh that fails must not wipe a working picker.
+        if (background) return;
+        setState({ presets: [], loading: false, error: describeAppError(errorOf(res)) });
+        return;
+      }
+      const parsed = moviePresetsResponseSchema.safeParse(okValue(res));
+      if (!parsed.success) {
+        if (background) return;
+        setState({ presets: [], loading: false, error: "Malformed movie templates response." });
+        return;
+      }
+      loadedRef.current = true;
+      setState({ presets: parsed.data.presets, loading: false, error: null });
+    } finally {
+      inFlight.current = false;
+    }
+  }, []);
+
+  // Load once, the first time the movie tab becomes active. Stays cached after.
+  useEffect(() => {
+    mounted.current = true;
+    if (!active || loadedRef.current) return;
+    const ctrl = new AbortController();
+    ctrlRef.current = ctrl;
+    void load(false);
+    return () => {
+      mounted.current = false;
+      ctrl.abort();
+    };
+  }, [active, load]);
+
+  const refresh = useCallback(() => {
+    void load(loadedRef.current);
+  }, [load]);
+
+  return { ...state, refresh };
+}

package/src/video/useMovieSessions.ts

@@ -0,0 +1,292 @@
+// CINEMA SESSIONS — the durable movie sessions on the studio-movies root, plus the
+// two actions on one (pause / resume).
+//
+// WHY A SESSION AND NOT A JOB. A studio movie is ONE bus job that can run for hours,
+// and the job id was the only handle on it: when the job ended — cancelled, reaped,
+// or simply lost with the browser tab — the rendered segments stayed on disk and
+// became unreachable. GET /video/studio/movies lists the DIRS instead, so a session
+// outlives the job that made it; its id is the dir leaf and therefore survives a
+// resume (which mints a NEW job id). See video_routes.py's `studio/movies` block.
+//
+// Cadence + shape follow the studio arm's existing list hooks (useStudioClips'
+// background poll, useMediaJobs' mounted-ref guard): the poll runs ONLY while a
+// consumer asks for it (`active` — the sessions panel is collapsed by default, and a
+// filesystem walk is not worth paying for behind a closed panel), a failed poll keeps
+// the last-good list rather than flashing empty, and a late response never setStates
+// after unmount.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { z } from "zod";
+import {
+  hugpyConfig,
+  mediaBytesUrl,
+  studioMoviePauseUrl,
+  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;
+
+// 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
+// whether a row gets a Pause affordance.
+const IN_FLIGHT = new Set(["queued", "claimed", "running", "cancelling"]);
+
+// ── wire schemas ────────────────────────────────────────────────────────────
+// Tolerant/passthrough like the movie composer's local schemas: every field beyond
+// the ones we render is optional, so a drifted-forward payload never breaks the
+// parse and one odd row never blanks the list.
+const segmentErrorSchema = z
+  .object({
+    code: z.string().nullable().optional(),
+    message: z.string().nullable().optional(),
+  })
+  .passthrough();
+
+const movieSegmentSchema = z
+  .object({
+    index: z.number(),
+    segment_id: z.string().nullable().optional(),
+    prompt: z.string().nullable().optional(),
+    status: z.string().nullable().optional(),
+    resumed: z.boolean().nullable().optional(),
+    frames: z.number().nullable().optional(),
+    duration_s: z.number().nullable().optional(),
+    error: segmentErrorSchema.nullable().optional(),
+    /** Honest "can I watch this right now" — false for a failed segment AND for one
+     *  whose record exists but whose bytes are gone (the url is then omitted). */
+    clip_available: z.boolean().nullable().optional(),
+    media: z.string().nullable().optional(),
+  })
+  .passthrough();
+
+export type MovieSegment = z.infer<typeof movieSegmentSchema>;
+
+const movieSessionSchema = z
+  .object({
+    movie_id: z.string(),
+    job_id: z.string().nullable().optional(),
+    job_status: z.string().nullable().optional(),
+    title: z.string().nullable().optional(),
+    project: z.string().nullable().optional(),
+    status: z.string().nullable().optional(),
+    segments_completed: z.number().nullable().optional(),
+    segments_total: z.number().nullable().optional(),
+    segments: z.array(movieSegmentSchema).optional(),
+    /** Server-computed: there is a persisted spec to re-enqueue AND the work is
+     *  neither finished nor already in flight. The Resume affordance keys on this
+     *  rather than re-deriving the rule per client. */
+    resumable: z.boolean().nullable().optional(),
+    updated: z.number().nullable().optional(),
+    width: z.number().nullable().optional(),
+    height: z.number().nullable().optional(),
+    fps: z.number().nullable().optional(),
+    id_lock: z.boolean().nullable().optional(),
+    /** The assembled movie.mp4, when one was stitched AND still exists on disk. */
+    movie: z.string().nullable().optional(),
+  })
+  .passthrough();
+
+export type MovieSession = z.infer<typeof movieSessionSchema>;
+
+const moviesResponseSchema = z
+  .object({ movies: z.array(movieSessionSchema) })
+  .passthrough();
+
+// ── derived reads (one definition each, shared by the panel) ────────────────
+
+/**
+ * A playable `<video src>` for a wire media url (a segment clip or the assembled
+ * movie), or null when there is nothing to serve.
+ *
+ * The route hands over a ready `/video/media?handle=<path>` url, but every other
+ * element-src in this console goes through `mediaBytesUrl` — which is where the
+ * share-session credential is stamped into the query (an element load carries no
+ * header) and where canned-demo handles pass through. So the HANDLE is unwrapped
+ * and re-issued through that one seam rather than the url being used raw, and a
+ * shape this parser doesn't recognise degrades to "not playable" instead of a
+ * link that 404s.
+ */
+export function movieMediaSrc(wire: string | null | undefined): string | null {
+  if (!wire) return null;
+  const q = wire.indexOf("?");
+  if (q < 0) return null;
+  const handle = new URLSearchParams(wire.slice(q + 1)).get("handle");
+  return handle ? mediaBytesUrl(handle) : null;
+}
+
+/** The segment's clip src — null unless the route says its bytes are on disk NOW. */
+export function segmentClipSrc(seg: MovieSegment): string | null {
+  if (!seg.clip_available) return null;
+  return movieMediaSrc(seg.media);
+}
+
+/** True when this session's CURRENT job is still on the bus — the Pause affordance. */
+export function isSessionLive(s: MovieSession): boolean {
+  return IN_FLIGHT.has(s.job_status ?? "");
+}
+
+/**
+ * WHY this session cannot be resumed right now, or null when it can. The rule is the
+ * server's (`resumable`); this only names the reason, so a disabled button always says
+ * what it is waiting for instead of being silently dead.
+ */
+export function resumeBlockedReason(s: MovieSession): string | null {
+  if (s.resumable) return null;
+  if (s.status === "done") return "This movie finished — there is nothing left to render.";
+  if (isSessionLive(s) || s.status === "running") {
+    return "This movie is already running — pause it first.";
+  }
+  return (
+    "This movie has no persisted spec.json, so it cannot be re-enqueued (it predates " +
+    "resumable sessions); its rendered segments are still listed and playable."
+  );
+}
+
+export interface MovieSessionsState {
+  sessions: MovieSession[];
+  loading: boolean;
+  /** List-level failure (the poll keeps the last-good list; this is the foreground read). */
+  error: string | null;
+  /** Force an immediate reload (fired right after a pause/resume lands). */
+  reload: () => void;
+  /** Movie ids with a pause/resume in flight — the per-row button's busy state. */
+  busy: Set<string>;
+  /** Per-movie action failure, kept VERBATIM from the route (the 409 bodies say why). */
+  actionError: Record<string, string>;
+  pause: (movieId: string) => void;
+  resume: (movieId: string) => void;
+}
+
+/**
+ * The Cinema session list + its two actions. `active` gates the poll: pass the
+ * panel's own visibility so a collapsed panel costs nothing (the route walks the
+ * movies root on every call).
+ */
+export function useMovieSessions(active: boolean): MovieSessionsState {
+  const [sessions, setSessions] = useState<MovieSession[]>([]);
+  // Starts TRUE so a freshly-opened panel reads "reading the movies root…" instead of
+  // flashing "no sessions" for one round trip — to an operator looking for a render
+  // they think they lost, those two say opposite things.
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState<Set<string>>(new Set());
+  const [actionError, setActionError] = useState<Record<string, string>>({});
+
+  const mounted = useRef(true);
+  const inFlight = useRef(false);
+  // Only the NEWEST read may write the list. Without this a poll issued BEFORE a
+  // pause/resume can land after it and restore the pre-action rows, making the action
+  // look like it did nothing for a whole tick.
+  const seq = useRef(0);
+  // First load of a newly-opened panel shows a spinner; every poll after it is
+  // silent, so an open panel never flickers between ticks.
+  const loaded = useRef(false);
+
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+
+  // `force` is for the reload that follows a pause/resume: it must not be swallowed by
+  // the in-flight guard that keeps the 6s poll from stacking up on a slow route.
+  const load = useCallback(async (force = false) => {
+    if (inFlight.current && !force) return;
+    inFlight.current = true;
+    const mine = (seq.current += 1);
+    if (!loaded.current) setLoading(true);
+    try {
+      const res = await request<unknown>(hugpyConfig.studioMoviesUrl, {
+        meta: { specKey: "studio", operation: "studio.movies.list" },
+      });
+      if (!mounted.current || mine !== seq.current) return;
+      if (!res.ok) {
+        // A failed poll must not wipe a working list — only the FIRST read (nothing
+        // on screen yet) is allowed to surface as an error.
+        if (!loaded.current) setError(describeAppError(errorOf(res)));
+        return;
+      }
+      const parsed = moviesResponseSchema.safeParse(okValue(res));
+      if (!parsed.success) {
+        if (!loaded.current) setError("Malformed movie-sessions response.");
+        return;
+      }
+      loaded.current = true;
+      setError(null);
+      setSessions(parsed.data.movies);
+    } finally {
+      inFlight.current = false;
+      if (mounted.current) setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!active) return;
+    void load();
+    const id = window.setInterval(() => void load(), POLL_MS);
+    return () => window.clearInterval(id);
+  }, [active, load]);
+
+  // Pause and resume differ only in their url and their telemetry op, so they share
+  // ONE runner: mark the row busy, clear its last error, POST, keep the route's own
+  // message verbatim on failure (the 409s — "no persisted spec.json", "already
+  // running" — ARE the explanation), then reload so the row's new status is the
+  // server's answer rather than an optimistic guess.
+  const act = useCallback(
+    async (movieId: string, url: string, operation: string) => {
+      setBusy((prev) => new Set(prev).add(movieId));
+      setActionError((prev) => {
+        const next = { ...prev };
+        delete next[movieId];
+        return next;
+      });
+      try {
+        const res = await request<unknown>(url, {
+          method: "POST",
+          meta: { specKey: "studio", operation },
+        });
+        if (!mounted.current) return;
+        if (!res.ok) {
+          setActionError((prev) => ({
+            ...prev,
+            [movieId]: describeAppError(errorOf(res)),
+          }));
+          return;
+        }
+        await load(true);
+      } finally {
+        if (mounted.current) {
+          setBusy((prev) => {
+            const next = new Set(prev);
+            next.delete(movieId);
+            return next;
+          });
+        }
+      }
+    },
+    [load],
+  );
+
+  const pause = useCallback(
+    (movieId: string) => {
+      void act(movieId, studioMoviePauseUrl(movieId), "studio.movie.pause");
+    },
+    [act],
+  );
+
+  const resume = useCallback(
+    (movieId: string) => {
+      void act(movieId, studioMovieResumeUrl(movieId), "studio.movie.resume");
+    },
+    [act],
+  );
+
+  const reload = useCallback(() => {
+    void load();
+  }, [load]);
+
+  return { sessions, loading, error, reload, busy, actionError, pause, resume };
+}

package/src/video/usePresets.ts

@@ -0,0 +1,167 @@
+// The Generate-station preset dropdown source. Fetches the curated "ideal default
+// loads" (GET /video/presets), validates them with a tolerant passthrough schema,
+// and exposes the options + loading/error as data (never throws) — the exact same
+// data-not-throws contract as useModels.ts, which the station imports alongside it.
+//
+// Presets are curated server-side and rarely change mid-session (unlike the model
+// registry, which grows as ComfyUI checkpoints get adopted), so this hook does a
+// single foreground load and a manual `refresh()` — it deliberately skips the
+// focus/visibility/interval revalidation machinery useModels.ts needs.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { z } from "zod";
+import { request, okValue, errorOf, describeAppError } from "../transport/client";
+import { hugpyConfig } from "../config";
+
+// The knob defaults a preset prefills onto the Generate station. All optional +
+// nullable: a preset may omit any field (the station keeps its current value), and
+// the wire may carry extras we ignore (passthrough). Shared by the apply echo.
+export interface PresetDefaults {
+  strength?: number | null;
+  steps?: number | null;
+  guidance?: number | null;
+  width?: number | null;
+  height?: number | null;
+  n_frames?: number | null;
+  fps?: number | null;
+  negative?: string | null;
+}
+
+export interface Preset {
+  /** Opaque id — the path segment of the apply POST. */
+  id: string;
+  /** Human label for the dropdown + status line. */
+  name: string;
+  /** One-line description surfaced under the picker when selected. */
+  description?: string | null;
+  /** Generation sub-mode this preset targets ("text-to-image" | "edit-chain" | "img2img" | …). */
+  mode: string;
+  /** The model the station selects + the apply POST pre-warms. */
+  model_key: string;
+  /** Knob values to prefill. */
+  defaults: PresetDefaults;
+  /** Advisory placement hint (e.g. "gpu"). */
+  recommended?: string | null;
+}
+
+export interface PresetsState {
+  presets: Preset[];
+  loading: boolean;
+  error: string | null;
+  /** Force an immediate re-fetch of the preset list. */
+  refresh: () => void;
+}
+
+// Tolerant schemas — passthrough keeps unknown fields; we only assert what we read.
+export const presetDefaultsSchema = z
+  .object({
+    strength: z.number().nullable().optional(),
+    steps: z.number().nullable().optional(),
+    guidance: z.number().nullable().optional(),
+    width: z.number().nullable().optional(),
+    height: z.number().nullable().optional(),
+    n_frames: z.number().nullable().optional(),
+    fps: z.number().nullable().optional(),
+    negative: z.string().nullable().optional(),
+  })
+  .passthrough();
+
+export const presetSchema = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().nullable().optional(),
+    mode: z.string(),
+    model_key: z.string(),
+    defaults: presetDefaultsSchema,
+    recommended: z.string().nullable().optional(),
+  })
+  .passthrough();
+
+const presetsResponseSchema = z
+  .object({ presets: z.array(presetSchema) })
+  .passthrough();
+
+// The per-id apply response — a discriminated pair sharing `ok`. On success it
+// echoes the (possibly server-adjusted) model_key/mode/defaults the station honors
+// as authoritative; on failure it carries {error:{code,message}}. Tolerant so a
+// partial worker block or extra fields never fail the parse.
+export const presetApplyResponseSchema = z
+  .object({
+    ok: z.boolean(),
+    worker: z
+      .object({ name: z.string().nullable().optional(), id: z.string().nullable().optional() })
+      .passthrough()
+      .nullable()
+      .optional(),
+    model_key: z.string().nullable().optional(),
+    mode: z.string().nullable().optional(),
+    defaults: presetDefaultsSchema.nullable().optional(),
+    warming: z.boolean().nullable().optional(),
+    error: z
+      .object({
+        code: z.string().nullable().optional(),
+        message: z.string().nullable().optional(),
+      })
+      .passthrough()
+      .nullable()
+      .optional(),
+  })
+  .passthrough();
+
+export function usePresets(): PresetsState {
+  const [state, setState] = useState<Omit<PresetsState, "refresh">>({
+    presets: [],
+    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 res = await request<unknown>(hugpyConfig.presetsUrl, {
+        signal,
+        meta: { specKey: "generate", operation: "presets.list" },
+      });
+      if (!mounted.current) return;
+
+      if (!res.ok) {
+        // A background refresh that fails must not wipe a working picker.
+        if (background) return;
+        setState({ presets: [], loading: false, error: describeAppError(errorOf(res)) });
+        return;
+      }
+      const parsed = presetsResponseSchema.safeParse(okValue(res));
+      if (!parsed.success) {
+        if (background) return;
+        setState({ presets: [], loading: false, error: "Malformed presets response." });
+        return;
+      }
+      setState({ presets: parsed.data.presets, loading: false, error: null });
+    } finally {
+      inFlight.current = false;
+    }
+  }, []);
+
+  useEffect(() => {
+    mounted.current = true;
+    const ctrl = new AbortController();
+    ctrlRef.current = ctrl;
+    void load(false);
+    return () => {
+      mounted.current = false;
+      ctrl.abort();
+    };
+  }, [load]);
+
+  const refresh = useCallback(() => {
+    void load(true);
+  }, [load]);
+
+  return { ...state, refresh };
+}

package/src/video/useProjects.ts

@@ -0,0 +1,87 @@
+// The Settings-tab "Project" combobox source. Fetches the distinct known project
+// names (GET /video/projects → { projects: [name, …] }) so the field can offer
+// existing names as a datalist while still letting the user FREE-TYPE a brand-new
+// one (choose-or-type). Data-not-throws, like useStudioPresets (from which the fetch
+// idiom is cloned): a failed/absent list just yields [] — the field still works as a
+// plain free-text input (empty = auto-named, the default). `refresh` re-pulls so a
+// name coined on this enqueue can appear in the list next time.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { z } from "zod";
+import { request, okValue, errorOf, describeAppError } from "../transport/client";
+import { hugpyConfig } from "../config";
+
+const projectsResponseSchema = z.object({ projects: z.array(z.string()) });
+
+export interface ProjectsState {
+  projects: string[];
+  loading: boolean;
+  error: string | null;
+  /** Force an immediate re-fetch of the project-name list. */
+  refresh: () => void;
+}
+
+/**
+ * Load the distinct known project names. `active` gates the network call; while
+ * inactive the hook reports loading:false / an empty list. Stays cached after the
+ * first successful pull; `refresh` re-pulls in the background.
+ */
+export function useProjects(active: boolean): ProjectsState {
+  const [state, setState] = useState<Omit<ProjectsState, "refresh">>({
+    projects: [],
+    loading: false,
+    error: null,
+  });
+
+  const mounted = useRef(true);
+  const inFlight = useRef(false);
+  const loadedRef = useRef(false);
+  const ctrlRef = useRef<AbortController | null>(null);
+
+  const load = useCallback(async (background: boolean) => {
+    if (inFlight.current) return;
+    inFlight.current = true;
+    if (!background) setState((s) => ({ ...s, loading: true }));
+    const signal = ctrlRef.current?.signal;
+    try {
+      const res = await request<unknown>(hugpyConfig.projectsUrl, {
+        signal,
+        meta: { specKey: "studio", operation: "video.projects.list" },
+      });
+      if (!mounted.current) return;
+      if (!res.ok) {
+        // A background refresh that fails must not wipe a working list.
+        if (background) return;
+        setState({ projects: [], loading: false, error: describeAppError(errorOf(res)) });
+        return;
+      }
+      const parsed = projectsResponseSchema.safeParse(okValue(res));
+      if (!parsed.success) {
+        if (background) return;
+        setState({ projects: [], loading: false, error: "Malformed projects response." });
+        return;
+      }
+      loadedRef.current = true;
+      setState({ projects: parsed.data.projects, loading: false, error: null });
+    } finally {
+      inFlight.current = false;
+    }
+  }, []);
+
+  useEffect(() => {
+    mounted.current = true;
+    if (!active || loadedRef.current) return;
+    const ctrl = new AbortController();
+    ctrlRef.current = ctrl;
+    void load(false);
+    return () => {
+      mounted.current = false;
+      ctrl.abort();
+    };
+  }, [active, load]);
+
+  const refresh = useCallback(() => {
+    void load(loadedRef.current);
+  }, [load]);
+
+  return { ...state, refresh };
+}