@hugpy/video-intelligence-ui 0.1.0

package/src/stations/ops/ImageCropCore.tsx

@@ -0,0 +1,164 @@
+// ImageCropCore — the reusable body of the Image Crop station (Studio slice 2a).
+// This is the station's "Components view" MINUS the upload bar: the
+// SpatialRegionEditor + the useCropJobs enqueue hook + the result grid, all
+// parameterised by a `source` ref. The station (or, in slice 2b, an inline-on-item
+// surface) supplies the source; nothing here uploads or ingests.
+//
+// Behaviour is IDENTICAL to the pre-slice-2a ImageCropStation body: same
+// `vi-station-components` shell, same SpatialRegionEditor props, same run footer,
+// same `vi-result-grid` + JobCard. The one addition is `onProduced` — an OPTIONAL
+// sink slice 2b wires to catch each finished crop; when it is OMITTED (the station
+// case) the Core keeps the station's exact behaviour (crops land in the library via
+// the tracker, the grid renders unchanged).
+//
+// Source lifecycle: the station owned `reset()` + clearing the queued regions
+// inside onPick/clearSource. The Core now owns the `queued` state and the hook, so
+// it resets both whenever the `source` REFERENCE changes (i.e. a new pick or a
+// clear) — mirroring the station's per-pick reset. The initial mount is skipped
+// (prevSource seed) so a remount after a sub-tab switch does NOT wipe the durable
+// tracker's finished crops (they persist across tab switches by design).
+import { useEffect, useRef, useState } from "react";
+import { SpatialRegionEditor } from "../../regions/SpatialRegionEditor";
+import type { SpatialRegion } from "../../regions/types";
+import { useCropJobs, type TrackedJob } from "../useCropJobs";
+import { STILL_RUNNING_MESSAGE } from "../pollCaps";
+import { mediaBytesUrl } from "../../config";
+import type { MediaRef } from "../../video/contract";
+
+export interface ImageCropCoreProps {
+  /** Source image (kind==="image"), or null before one is loaded. */
+  source: MediaRef | null;
+  /** Multi-crop queue (station) vs single crop (inline-on-item, slice 2b). */
+  multiRegion?: boolean;
+  /** Additive (slice 2b): notified with each finished crop's ref + its region.
+      Omitted by the station — the crop still lands in the library via the tracker. */
+  onProduced?: (
+    ref: MediaRef,
+    meta: { spatial?: SpatialRegion | null; temporal?: null },
+  ) => void;
+}
+
+export function ImageCropCore({
+  source,
+  multiRegion = true,
+  onProduced,
+}: ImageCropCoreProps) {
+  const [queued, setQueued] = useState<SpatialRegion[]>([]);
+  const { jobs, runCrops, resume, reset } = useCropJobs(source);
+
+  // Reset the queue + this station's tracker rows when a NEW source is picked (or
+  // cleared) — keyed on the source reference so it fires exactly on a pick/clear,
+  // never on an unrelated re-render. The mount is skipped (prevSource seed) so a
+  // remount after a tab switch keeps the durable tracker's finished crops.
+  const prevSource = useRef<MediaRef | null>(source);
+  useEffect(() => {
+    if (prevSource.current === source) return;
+    prevSource.current = source;
+    setQueued([]);
+    reset();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [source]);
+
+  // Additive slice-2b sink: fire once per finished crop. Inert when onProduced is
+  // omitted (the station case) — the library push is owned by the tracker regardless.
+  const notified = useRef<Set<string>>(new Set());
+  useEffect(() => {
+    if (!onProduced) return;
+    for (const j of jobs) {
+      if (j.status === "done" && j.output && !notified.current.has(j.key)) {
+        notified.current.add(j.key);
+        onProduced(j.output, { spatial: j.region, temporal: null });
+      }
+    }
+  }, [jobs, onProduced]);
+
+  return (
+    <div className="vi-station-components">
+      {/* Image view + crop/manipulation options — ALWAYS rendered. With
+          no image loaded the editor shows its full chrome over a blank
+          canvas; loading an image only fills the canvas. */}
+      <SpatialRegionEditor
+        source={source}
+        values={queued}
+        onChange={(next) => setQueued(Array.isArray(next) ? next : [next])}
+        multiRegion={multiRegion}
+        numericInputs
+      />
+
+      {/* Run */}
+      <div className="vi-station-footer">
+        <div className="vi-station-footer-main">
+          <span className="vi-crop-hint">
+            Each queued box enqueues one crop job on the bus.
+          </span>
+        </div>
+        <div className="vi-station-footer-run">
+          <button
+            type="button"
+            className="vi-btn vi-btn-accent"
+            disabled={!source || queued.length === 0}
+            onClick={() => runCrops(queued)}
+          >
+            Run crop{queued.length === 1 ? "" : "s"}
+            {queued.length > 0 ? ` (${queued.length})` : ""}
+          </button>
+        </div>
+      </div>
+
+      {jobs.length > 0 && (
+        <div className="vi-result-grid">
+          {jobs.map((j) => (
+            <JobCard key={j.key} job={j} onResume={() => resume(j.key)} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+const STATUS_TEXT: Record<string, string> = {
+  queued: "queued",
+  claimed: "claimed",
+  running: "running",
+  done: "done",
+  failed: "failed",
+};
+
+function JobCard({ job, onResume }: { job: TrackedJob; onResume: () => void }) {
+  const statusKey = job.status ?? "queued";
+  const done = job.status === "done";
+  const failed = job.status === "failed";
+  return (
+    <figure className="vi-result-card">
+      <div className="vi-result-head">
+        <span className="vi-region-idx">#{job.index}</span>
+        <span className={`vi-status vi-status-${statusKey}`}>{STATUS_TEXT[statusKey]}</span>
+        <code className="vi-region-dims">
+          {job.region.w}×{job.region.h} @ {job.region.x},{job.region.y}
+        </code>
+      </div>
+      <div className="vi-result-body">
+        {done && job.output ? (
+          <img
+            className="vi-result-img"
+            src={mediaBytesUrl(job.output.uri)}
+            alt={`Crop ${job.index}`}
+          />
+        ) : failed ? (
+          <p className="vi-error">{job.error ?? "Crop job failed."}</p>
+        ) : job.capped ? (
+          <div className="vi-result-pending">
+            <p className="vi-crop-hint">{STILL_RUNNING_MESSAGE}</p>
+            <button type="button" className="vi-btn vi-btn-sm" onClick={onResume}>
+              Check again
+            </button>
+          </div>
+        ) : (
+          <div className="vi-result-pending" aria-hidden>
+            {STATUS_TEXT[statusKey]}…
+          </div>
+        )}
+      </div>
+    </figure>
+  );
+}

package/src/stations/ops/VideoCropCore.tsx

@@ -0,0 +1,193 @@
+// VideoCropCore — the NEW op primitive of Studio slice 2a: a spatial+temporal crop
+// of a VIDEO in ONE pass. It renders the SpatialRegionEditor (a native-px bbox over
+// the video frame) AND the TemporalRegionEditor (a [start,end) window over the
+// clip's timeline) together, and enqueues a SINGLE `/video/jobs/crop` job carrying
+// BOTH axes via useVideoCropJobs — because the crop backend applies spatial + temporal
+// in one ffmpeg pass when the CropSpec carries both (`-ss <start> -i <in> -t <dur> -vf
+// crop=w:h:x:y`). It is NOT a two-job chain.
+//
+// This Core is additive: it is not wired into any station in slice 2a (no new
+// user-facing surface — that is slice 2b). It exists as the reusable body 2b will
+// mount inline-on-item. It follows the crop-core shape: a `source` ref + an OPTIONAL
+// `onProduced` sink, the same `vi-station-components` shell + `vi-result-grid`.
+//
+// The result card is inlined onto an intrinsic <figure key=…> (the codebase's idiom
+// for a keyed map — mirrors SpatialRegionEditor's <li key> and FrameExtractCore's
+// <button key>), so this NEW file stays free of the bare-tsc `key`-prop artifact.
+//
+// Duration guard: a spatial crop needs the video's native width/height (always
+// present for a video); a temporal trim needs a real duration. Mirroring how the
+// Audio Crop station reads `duration = source.duration_s ?? 0`, when the source
+// reports NO duration the Run is DISABLED (and a hint shown) rather than sending a
+// bad interval to the backend. Both axes must be set to run (a video crop is, by
+// definition, both a box and a window).
+import { useEffect, useRef, useState } from "react";
+import { SpatialRegionEditor } from "../../regions/SpatialRegionEditor";
+import { TemporalRegionEditor } from "../../regions/TemporalRegionEditor";
+import type { SpatialRegion, TemporalRegion } from "../../regions/types";
+import { useVideoCropJobs } from "./useVideoCropJobs";
+import { STILL_RUNNING_MESSAGE } from "../pollCaps";
+import { mediaBytesUrl } from "../../config";
+import type { MediaRef } from "../../video/contract";
+
+const STATUS_TEXT: Record<string, string> = {
+  queued: "queued",
+  claimed: "claimed",
+  running: "running",
+  done: "done",
+  failed: "failed",
+};
+
+export interface VideoCropCoreProps {
+  /** Source video (kind==="video"), or null before one is loaded. */
+  source: MediaRef | null;
+  /** Additive (slice 2b): notified with each finished clip's ref + both axes.
+      Omitted by callers — the clip still lands in the library via the tracker. */
+  onProduced?: (
+    ref: MediaRef,
+    meta: { spatial?: SpatialRegion | null; temporal?: TemporalRegion | null },
+  ) => void;
+}
+
+export function VideoCropCore({ source, onProduced }: VideoCropCoreProps) {
+  // A video crop is a single {spatial, temporal} pair → ONE job.
+  const [spatial, setSpatial] = useState<SpatialRegion | null>(null);
+  const [temporal, setTemporal] = useState<TemporalRegion | null>(null);
+
+  const { jobs, runCrop, resume, reset } = useVideoCropJobs(source);
+
+  const duration = source?.duration_s ?? 0;
+  const hasDuration = duration > 0;
+
+  // Reset the working pair + this station's tracker rows when a NEW source is picked
+  // (or cleared) — keyed on the source reference, mount skipped (prevSource seed).
+  const prevSource = useRef<MediaRef | null>(source);
+  useEffect(() => {
+    if (prevSource.current === source) return;
+    prevSource.current = source;
+    setSpatial(null);
+    setTemporal(null);
+    reset();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [source]);
+
+  // Additive sink: fire once per finished clip. Inert when onProduced is omitted —
+  // the library push is owned by the tracker regardless.
+  const notified = useRef<Set<string>>(new Set());
+  useEffect(() => {
+    if (!onProduced) return;
+    for (const j of jobs) {
+      if (j.status === "done" && j.output && !notified.current.has(j.key)) {
+        notified.current.add(j.key);
+        onProduced(j.output, { spatial: j.spatial, temporal: j.temporal });
+      }
+    }
+  }, [jobs, onProduced]);
+
+  const canRun = !!source && !!spatial && !!temporal && hasDuration;
+
+  return (
+    <div className="vi-station-components">
+      {/* Spatial box over the video frame (native px). Single-region: "Set crop". */}
+      <SpatialRegionEditor
+        source={source}
+        onChange={(next) => setSpatial(Array.isArray(next) ? next[0] ?? null : next)}
+        multiRegion={false}
+        numericInputs
+      />
+
+      {/* Temporal window over the clip timeline. When the source reports no duration
+          the editor cannot place a valid window — show a hint and gate Run. */}
+      {hasDuration ? (
+        <TemporalRegionEditor
+          source={source}
+          duration={duration}
+          onChange={(next) => setTemporal(Array.isArray(next) ? next[0] ?? null : next)}
+          multiRegion={false}
+          numericInputs
+        />
+      ) : (
+        <p className="vi-crop-hint">
+          {source
+            ? "This video reports no duration — temporal trimming is unavailable."
+            : "Load a video to set a spatial box and a temporal window."}
+        </p>
+      )}
+
+      {/* Run */}
+      <div className="vi-station-footer">
+        <div className="vi-station-footer-main">
+          <span className="vi-crop-hint">
+            One crop job trims the video to the box AND the window in a single pass.
+          </span>
+        </div>
+        <div className="vi-station-footer-run">
+          <button
+            type="button"
+            className="vi-btn vi-btn-accent"
+            disabled={!canRun}
+            onClick={() => runCrop(spatial, temporal)}
+          >
+            Run video crop
+          </button>
+        </div>
+      </div>
+
+      {jobs.length > 0 && (
+        <div className="vi-result-grid">
+          {jobs.map((j) => {
+            const statusKey = j.status ?? "queued";
+            const done = j.status === "done";
+            const failed = j.status === "failed";
+            const box = j.spatial
+              ? `${j.spatial.w}×${j.spatial.h} @ ${j.spatial.x},${j.spatial.y}`
+              : "full frame";
+            const win = j.temporal
+              ? ` · ${j.temporal.start_s.toFixed(2)}–${j.temporal.end_s.toFixed(2)}s`
+              : "";
+            return (
+              <figure key={j.key} className="vi-result-card">
+                <div className="vi-result-head">
+                  <span className="vi-region-idx">#{j.index}</span>
+                  <span className={`vi-status vi-status-${statusKey}`}>
+                    {STATUS_TEXT[statusKey]}
+                  </span>
+                  <code className="vi-region-dims">
+                    {box}
+                    {win}
+                  </code>
+                </div>
+                <div className="vi-result-body">
+                  {done && j.output ? (
+                    <video
+                      controls
+                      className="vi-result-img"
+                      src={mediaBytesUrl(j.output.uri)}
+                    />
+                  ) : failed ? (
+                    <p className="vi-error">{j.error ?? "Crop job failed."}</p>
+                  ) : j.capped ? (
+                    <div className="vi-result-pending">
+                      <p className="vi-crop-hint">{STILL_RUNNING_MESSAGE}</p>
+                      <button
+                        type="button"
+                        className="vi-btn vi-btn-sm"
+                        onClick={() => resume(j.key)}
+                      >
+                        Check again
+                      </button>
+                    </div>
+                  ) : (
+                    <div className="vi-result-pending" aria-hidden>
+                      {STATUS_TEXT[statusKey]}…
+                    </div>
+                  )}
+                </div>
+              </figure>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/stations/ops/useVideoCropJobs.ts

@@ -0,0 +1,224 @@
+// useVideoCropJobs — the Video Crop enqueue surface (Studio slice 2a). The
+// spatial+temporal sibling of useCropJobs: it POSTs ONE crop job carrying BOTH a
+// spatial bbox AND a temporal window, because the crop backend applies both in a
+// SINGLE ffmpeg pass (`-ss <start> -i <in> -t <dur> -vf crop=w:h:x:y`) when the
+// CropSpec carries both axes — so a video crop is one `/video/jobs/crop` job, NOT a
+// two-job chain. (useCropJobs hardcodes `temporal: null`; useAudioCropJobs hardcodes
+// `spatial: null`; this hook sets both.)
+//
+// Everything else mirrors useCropJobs: it owns only request-body construction; the
+// moment it has a job_id it hands the job to jobTracker.trackJob and stops owning
+// polling/job state (poll cadence, caps, terminal parse, the single library push all
+// live in the tracker). `jobs` is DERIVED from the tracker (this station's crop
+// records) merged with any still-enqueuing local placeholders.
+//
+// StationId: this hook rides the dedicated "video-crop" StationId (added to the
+// closed union in jobTracker.ts as part of Studio slice 2b). It was modelled on
+// useCropJobs (which rides "image-crop") and keeps the video crop's spatial region
+// on the tracker record. The dedicated id is REQUIRED now that VideoCropCore is
+// wired ALONGSIDE ImageCropCore on studio items: both filter `station==<id> &&
+// kind==="crop"`, so a shared id would intermix their records — "video-crop" keeps
+// each op's tracker rows (and Video Crop's library origin) cleanly separate.
+import { useCallback, useMemo, useRef, useState } from "react";
+import { request, okValue, errorOf, describeAppError } from "../../transport/client";
+import { hugpyConfig } from "../../config";
+import {
+  enqueueResultSchema,
+  type CropJobRequest,
+  type JobStatus,
+  type MediaRef,
+} from "../../video/contract";
+import {
+  useJobTracker,
+  trackJob,
+  resumeJob,
+  resumeStation,
+  dismissTerminal,
+  type TrackedJob as TrackerRecord,
+} from "../../video/jobTracker";
+import type { SpatialRegion, TemporalRegion } from "../../regions/types";
+
+export interface TrackedVideoCropJob {
+  /** Stable local key (the server job id once enqueued). */
+  key: string;
+  /** 1-based position, for display. */
+  index: number;
+  /** The native-px spatial box this job crops (kept on the tracker record). */
+  spatial: SpatialRegion | null;
+  /** The temporal window (seconds) this job trims — local only (see note below). */
+  temporal: TemporalRegion | null;
+  /** Server job id once enqueued, else null. */
+  jobId: string | null;
+  /** Latest polled status (null = enqueued but not yet claimed). */
+  status: JobStatus;
+  /** Result clip MediaRef on success. */
+  output: MediaRef | null;
+  /** Human message on failure (enqueue error or job error). */
+  error: string | null;
+  /** Poll cap reached while non-terminal — NOT a failure. */
+  capped: boolean;
+  /** Enqueue timestamp — the anchor for the poll cap. */
+  startedAt: number;
+}
+
+// A pre-enqueue placeholder — see useCropJobs.ts for the rationale. It carries BOTH
+// axes; the tracker record it hands off to only carries the spatial region (its
+// `region` field is a single Region), so `temporal` on a job is surfaced from the
+// placeholder and is null once the tracker owns the row.
+interface Pending {
+  key: string;
+  index: number;
+  spatial: SpatialRegion | null;
+  temporal: TemporalRegion | null;
+  status: Extract<JobStatus, "queued" | "failed">;
+  error: string | null;
+  startedAt: number;
+}
+
+let _seq = 0;
+function makeKey(): string {
+  _seq += 1;
+  return `vcrop_${_seq.toString(36)}_${Date.now().toString(36)}`;
+}
+
+export interface VideoCropJobsApi {
+  jobs: TrackedVideoCropJob[];
+  /** Enqueue ONE crop job carrying BOTH the spatial box and the temporal window. */
+  runCrop: (spatial: SpatialRegion | null, temporal: TemporalRegion | null) => void;
+  /**
+   * Re-anchor the poll clock for a capped job (or every capped crop when `key`
+   * is omitted) and resume polling. Clears `capped`, keeps status.
+   */
+  resume: (key?: string) => void;
+  /** Forget this station's finished jobs (called when a new source is ingested). */
+  reset: () => void;
+}
+
+const STATION = "video-crop";
+
+export function useVideoCropJobs(source: MediaRef | null): VideoCropJobsApi {
+  const records = useJobTracker();
+  const [pending, setPending] = useState<Pending[]>([]);
+
+  // This station's crop records, newest-index last (stable via useMemo).
+  const mine = useMemo(
+    () => records.filter((r) => r.station === STATION && r.kind === "crop"),
+    [records],
+  );
+
+  const mineRef = useRef<TrackerRecord[]>(mine);
+  mineRef.current = mine;
+  const pendingRef = useRef<Pending[]>(pending);
+  pendingRef.current = pending;
+
+  const jobs = useMemo<TrackedVideoCropJob[]>(() => {
+    const fromTracker: TrackedVideoCropJob[] = mine.map((r) => ({
+      key: r.jobId,
+      index: r.index,
+      spatial: (r.region as SpatialRegion) ?? null,
+      temporal: null,
+      jobId: r.jobId,
+      status: r.status,
+      output: r.outputs[0] ?? null,
+      error: r.error,
+      capped: r.capped,
+      startedAt: r.startedAt,
+    }));
+    const fromPending: TrackedVideoCropJob[] = pending.map((p) => ({
+      key: p.key,
+      index: p.index,
+      spatial: p.spatial,
+      temporal: p.temporal,
+      jobId: null,
+      status: p.status,
+      output: null,
+      error: p.error,
+      capped: false,
+      startedAt: p.startedAt,
+    }));
+    return [...fromTracker, ...fromPending].sort((a, b) => a.index - b.index);
+  }, [mine, pending]);
+
+  const reset = useCallback(() => {
+    setPending([]);
+    dismissTerminal(STATION);
+  }, []);
+
+  const resume = useCallback((key?: string) => {
+    if (key != null) resumeJob(key);
+    else resumeStation(STATION);
+  }, []);
+
+  const runCrop = useCallback(
+    (spatial: SpatialRegion | null, temporal: TemporalRegion | null) => {
+      if (!source) return;
+      // Continue the 1-based numbering past any existing/pending rows.
+      const base = Math.max(
+        0,
+        ...mineRef.current.map((r) => r.index),
+        ...pendingRef.current.map((p) => p.index),
+      );
+      const key = makeKey();
+      const index = base + 1;
+      const enqueuedAt = Date.now();
+      const dims = spatial ? `${spatial.w}×${spatial.h}` : "full";
+      const win = temporal
+        ? ` ${temporal.start_s.toFixed(2)}–${temporal.end_s.toFixed(2)}s`
+        : "";
+      const label = `clip ${dims}${win}`;
+      setPending((prev) => [
+        ...prev,
+        { key, index, spatial, temporal, status: "queued", error: null, startedAt: enqueuedAt },
+      ]);
+
+      // ONE crop job, BOTH axes — the backend applies spatial + temporal in a single
+      // ffmpeg pass when the CropSpec carries both.
+      const body: CropJobRequest = { source, spatial, temporal };
+      void request<unknown>(hugpyConfig.cropEnqueueUrl, {
+        method: "POST",
+        body: JSON.stringify(body),
+        headers: { "Content-Type": "application/json" },
+        meta: { specKey: STATION, operation: "crop.enqueue" },
+      }).then((r) => {
+        if (!r.ok) {
+          setPending((prev) =>
+            prev.map((p) =>
+              p.key === key
+                ? { ...p, status: "failed", error: describeAppError(errorOf(r)) }
+                : p,
+            ),
+          );
+          return;
+        }
+        const parsed = enqueueResultSchema.safeParse(okValue(r));
+        if (!parsed.success) {
+          setPending((prev) =>
+            prev.map((p) =>
+              p.key === key
+                ? { ...p, status: "failed", error: "Malformed enqueue response." }
+                : p,
+            ),
+          );
+          return;
+        }
+        // Hand the job to the durable tracker, then drop the local placeholder. The
+        // tracker record carries the spatial region (single Region slot); the temporal
+        // window lives only on the placeholder above.
+        trackJob({
+          jobId: parsed.data.job_id,
+          kind: "crop",
+          station: STATION,
+          label,
+          libLabel: label,
+          enqueuedAt,
+          index,
+          region: spatial,
+        });
+        setPending((prev) => prev.filter((p) => p.key !== key));
+      });
+    },
+    [source],
+  );
+
+  return { jobs, runCrop, resume, reset };
+}

package/src/stations/pollCaps.ts

@@ -0,0 +1,87 @@
+// Phase 8 — shared poll-cap constants + "still running" copy for the five
+// job-poll hooks (useCropJobs, useFrameJobs, useGenerateJob, useAudioExtractJob,
+// useAudioCropJobs). Centralised here so the caps and the human message never
+// drift across the hooks.
+//
+// The old behaviour capped a poll loop at ~60s of wall-clock and marked the job
+// `failed` with "Timed out" — even though the backend often finished the work a
+// moment later (cold model loads especially). Phase 8 does two things:
+//   1. Raises the ceilings substantially (generation cold-loads can take minutes).
+//   2. On cap-expiry, STOPS hammering the poller but does NOT fail the job —
+//      instead each hook flips a `capped` flag, keeps the last real status, and
+//      exposes a `resume()` that re-anchors the poll clock (startedAt = now,
+//      clears capped) so polling simply continues. No SSE, no websockets.
+
+/** Generation cold-loads can take minutes — 5 min ceiling before we pause polling. */
+export const GENERATE_POLL_CAP_MS = 300_000;
+
+/** Crop / frame-extract / audio-extract / audio-crop — 3 min ceiling. */
+export const JOB_POLL_CAP_MS = 180_000;
+
+/**
+ * Copy shown when a poll loop hits its cap but the job may still be finishing
+ * server-side. Paired with a "Check again" affordance wired to the hook's resume.
+ */
+export const STILL_RUNNING_MESSAGE = "Still running on the server — check again.";
+
+/**
+ * Scene generation (Generate station, Scene mode) produces N frames — each a
+ * full text-to-image inference — plus an optional mp4 assemble, so the ceiling
+ * scales with n_frames rather than a single flat cap. Base 5 min (a cold model
+ * load like generate_image) + 1 min per frame.
+ *
+ * Chaining (`chain: true`) runs the frames as SEQUENTIAL img2img — each frame
+ * conditions on the previous, so they can't overlap and the wall-clock grows.
+ * When chaining we add an extra per-frame allowance on top of the base per-frame
+ * budget so the cap doesn't trip while a legitimately-slower chained scene runs.
+ */
+export const GENERATE_SCENE_POLL_CAP_BASE_MS = 300_000;
+export const GENERATE_SCENE_POLL_CAP_PER_FRAME_MS = 60_000;
+export const GENERATE_SCENE_POLL_CAP_CHAIN_PER_FRAME_MS = 60_000;
+
+/**
+ * The n_frames-scaled poll cap (ms) for a generate_scene job. `chain` adds extra
+ * per-frame time because chained frames run sequentially (img2img).
+ */
+export function generateScenePollCapMs(nFrames: number, chain?: boolean): number {
+  const frames = Math.max(1, nFrames | 0);
+  const perFrame =
+    GENERATE_SCENE_POLL_CAP_PER_FRAME_MS +
+    (chain ? GENERATE_SCENE_POLL_CAP_CHAIN_PER_FRAME_MS : 0);
+  return GENERATE_SCENE_POLL_CAP_BASE_MS + perFrame * frames;
+}
+
+/**
+ * Movie generation (Generate station, Movie mode) renders MANY segments, each an
+ * N-frame scene, plus an mp4 assemble — and with the vision director on, a segment
+ * may be re-rolled several times. So the ceiling scales with BOTH the segment count
+ * and the total frame count (segments × frames): base 5 min (a cold model load) +
+ * 1 min per segment + a per-total-frame budget. Chaining adds extra per-frame time
+ * (sequential img2img), matching the scene cap's chain allowance.
+ */
+export const GENERATE_MOVIE_POLL_CAP_BASE_MS = 300_000;
+export const GENERATE_MOVIE_POLL_CAP_PER_SEGMENT_MS = 60_000;
+export const GENERATE_MOVIE_POLL_CAP_PER_FRAME_MS = 20_000;
+export const GENERATE_MOVIE_POLL_CAP_CHAIN_PER_FRAME_MS = 15_000;
+
+/**
+ * The segments×frames-scaled poll cap (ms) for a generate_movie job. `framesTotal`
+ * is the timeline's total frame count (`total` = max end_frame); `chain` adds extra
+ * per-frame time because chained frames run sequentially (img2img).
+ */
+export function generateMoviePollCapMs(
+  segments: number,
+  framesTotal?: number,
+  chain?: boolean,
+): number {
+  const segs = Math.max(1, segments | 0);
+  const frames = Math.max(segs, framesTotal ? framesTotal | 0 : segs);
+  const perFrame =
+    GENERATE_MOVIE_POLL_CAP_PER_FRAME_MS +
+    (chain ? GENERATE_MOVIE_POLL_CAP_CHAIN_PER_FRAME_MS : 0);
+  return (
+    GENERATE_MOVIE_POLL_CAP_BASE_MS +
+    GENERATE_MOVIE_POLL_CAP_PER_SEGMENT_MS * segs +
+    perFrame * frames
+  );
+}