@hugpy/video-intelligence-ui 0.1.0 → 0.3.0

package/src/video/coordinationReport.ts

@@ -0,0 +1,266 @@
+// COORDINATION REPORT (k121) — the wire shape of the words-vs-knobs review.
+//
+// The backend kernel is `video_intel/prompt_coordination.py`. Every generated or
+// enhanced video prompt path now returns a `coordination` block:
+// `/video/prompt/assist` (spread + detail/generate) and `POST /video/studio/movie`.
+//
+// WHY THE UI HAS TO SHOW THIS. The operator's cinema session produced four
+// prompts that all declared continuity — continuous scenes, a scene drawn from
+// the previous scene's render, a recurring character — with every joint left at
+// `cut`, no parent link, no lengthening and no identity. Nothing failed; it
+// rendered the wrong film. The backend now turns the ratchet-safe knobs itself,
+// but a knob turned invisibly is the same defect wearing the other hat, so every
+// decision surfaces on the row it belongs to, with the operator's OWN WORDS as
+// the evidence.
+//
+// Pure: no React, no fetch. Reader-shaped like `spreadAssist.readSpreadResult` —
+// anything malformed is dropped, never defaulted into a false "ok".
+
+/** What the review did about one knob. Worst-first, matching `STATUS_ORDER`. */
+export type CoordinationStatus = "mismatch" | "proposed" | "set" | "ok";
+
+/** Worst-first. Folding a segment's decisions into one badge picks the first hit. */
+export const COORDINATION_STATUS_ORDER: CoordinationStatus[] = [
+  "mismatch",
+  "proposed",
+  "set",
+  "ok",
+];
+
+/** One claim the prose made. `evidence_quote` is verbatim from the row's text. */
+export interface CoordinationExpectation {
+  kind: string;
+  segments: string[];
+  evidence_quote: string;
+  confidence: number;
+  source: string;
+  detail: Record<string, unknown>;
+}
+
+/** One knob decision — the diff a badge renders. */
+export interface CoordinationDecision {
+  segment_id: string;
+  index: number;
+  knob: string;
+  current: unknown;
+  proposed: unknown;
+  status: CoordinationStatus;
+  reason: string;
+  confidence: number;
+  blocking: boolean;
+  evidence_quote: string;
+  /** Set only for a work STEP that is not a knob (`IDENTITY_CAPTURE`). */
+  step?: string;
+  expectation?: CoordinationExpectation | null;
+  detail?: Record<string, unknown>;
+}
+
+/** One row of the review. EVERY segment gets one, including the `ok` ones. */
+export interface CoordinationSegment {
+  segment_id: string;
+  index: number;
+  status: CoordinationStatus;
+  decisions: CoordinationDecision[];
+}
+
+export interface CoordinationReport {
+  version: string;
+  status: CoordinationStatus;
+  counts: Record<string, number>;
+  llm_used: boolean;
+  notes: string[];
+  segments: CoordinationSegment[];
+  expectations: CoordinationExpectation[];
+  decisions: CoordinationDecision[];
+}
+
+function str(v: unknown): string {
+  return typeof v === "string" ? v : "";
+}
+
+function num(v: unknown, fallback = 0): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+
+function statusOf(v: unknown): CoordinationStatus {
+  const s = str(v);
+  return (COORDINATION_STATUS_ORDER as string[]).includes(s)
+    ? (s as CoordinationStatus)
+    : "ok";
+}
+
+function dict(v: unknown): Record<string, unknown> {
+  return v != null && typeof v === "object" && !Array.isArray(v)
+    ? (v as Record<string, unknown>)
+    : {};
+}
+
+function readExpectation(v: unknown): CoordinationExpectation | null {
+  const r = dict(v);
+  const kind = str(r.kind);
+  if (!kind) return null;
+  return {
+    kind,
+    segments: Array.isArray(r.segments) ? r.segments.map(str).filter(Boolean) : [],
+    evidence_quote: str(r.evidence_quote),
+    confidence: num(r.confidence),
+    source: str(r.source) || "rule",
+    detail: dict(r.detail),
+  };
+}
+
+function readDecision(v: unknown): CoordinationDecision | null {
+  const r = dict(v);
+  const segment_id = str(r.segment_id);
+  const knob = str(r.knob);
+  if (!segment_id || !knob) return null;
+  const step = str(r.step);
+  return {
+    segment_id,
+    index: num(r.index),
+    knob,
+    current: r.current,
+    proposed: r.proposed,
+    status: statusOf(r.status),
+    reason: str(r.reason),
+    confidence: num(r.confidence),
+    blocking: r.blocking === true,
+    evidence_quote: str(r.evidence_quote),
+    ...(step ? { step } : {}),
+    expectation: readExpectation(r.expectation),
+    detail: dict(r.detail),
+  };
+}
+
+/**
+ * Read a `coordination` block. Returns null when it is not a report at all — the
+ * caller then shows nothing rather than a badge built out of guesses.
+ */
+export function readCoordinationReport(value: unknown): CoordinationReport | null {
+  const v = dict(value);
+  if (!Array.isArray(v.segments) || !Array.isArray(v.decisions)) return null;
+  const decisions = v.decisions
+    .map(readDecision)
+    .filter((d): d is CoordinationDecision => d != null);
+  const segments: CoordinationSegment[] = [];
+  for (const raw of v.segments) {
+    const r = dict(raw);
+    const segment_id = str(r.segment_id);
+    if (!segment_id) continue;
+    segments.push({
+      segment_id,
+      index: num(r.index),
+      status: statusOf(r.status),
+      decisions: Array.isArray(r.decisions)
+        ? r.decisions.map(readDecision).filter((d): d is CoordinationDecision => d != null)
+        : [],
+    });
+  }
+  return {
+    version: str(v.version),
+    status: statusOf(v.status),
+    counts: dict(v.counts) as Record<string, number>,
+    llm_used: v.llm_used === true,
+    notes: Array.isArray(v.notes) ? v.notes.map(str).filter(Boolean) : [],
+    segments,
+    expectations: Array.isArray(v.expectations)
+      ? v.expectations
+          .map(readExpectation)
+          .filter((e): e is CoordinationExpectation => e != null)
+      : [],
+    decisions,
+  };
+}
+
+/** The review row for one segment, or null when it was not reviewed. */
+export function segmentReview(
+  report: CoordinationReport | null,
+  segmentId: string,
+): CoordinationSegment | null {
+  if (!report) return null;
+  return report.segments.find((s) => s.segment_id === segmentId) ?? null;
+}
+
+/** The one-word badge label for a status. */
+export function coordinationLabel(status: CoordinationStatus): string {
+  switch (status) {
+    case "mismatch":
+      return "knobs ≠ words";
+    case "proposed":
+      return "knobs proposed";
+    case "set":
+      return "knobs set";
+    default:
+      return "knobs ok";
+  }
+}
+
+/**
+ * The existing assist-log badge palette, reused rather than reinvented:
+ * `--err` red / `--warn` amber / `--ok` green / base dim. One badge language
+ * across the console (`style/app.css` §.vi-assistlog-badge).
+ */
+export function coordinationClass(status: CoordinationStatus): string {
+  switch (status) {
+    case "mismatch":
+      return "vi-assistlog-badge vi-assistlog-badge--err";
+    case "proposed":
+      return "vi-assistlog-badge vi-assistlog-badge--warn";
+    case "set":
+      return "vi-assistlog-badge vi-assistlog-badge--ok";
+    default:
+      return "vi-assistlog-badge";
+  }
+}
+
+/** Human name for a knob, for the diff line. */
+export function knobLabel(knob: string): string {
+  switch (knob) {
+    case "joint_mode":
+      return "join";
+    case "parent_segment_id":
+      return "parent";
+    case "branch_frame":
+      return "branch frame";
+    case "reference_images":
+      return "identity refs";
+    case "frames":
+      return "clip length";
+    default:
+      return knob;
+  }
+}
+
+/** Render a knob value for the diff line. Never throws on an odd shape. */
+export function knobValue(v: unknown): string {
+  if (v == null) return "—";
+  if (Array.isArray(v)) return v.length ? `${v.length} ref(s)` : "—";
+  if (typeof v === "object") {
+    const o = v as Record<string, unknown>;
+    if (typeof o.profile === "string") return `profile ${o.profile}`;
+    if (typeof o.from_segment === "string") return `capture from ${o.from_segment}`;
+    return "…";
+  }
+  return String(v);
+}
+
+/**
+ * A knob decision projected onto the movie composer's own GoalRow field names.
+ * `null` when the knob has no editable home on this surface (a parent pointer is
+ * implicit in the composer's linear chain; an identity plan is a work step, not
+ * a field), so accepting it can never write a field that does not exist.
+ */
+export function knobPatch(d: CoordinationDecision): Record<string, string> | null {
+  switch (d.knob) {
+    case "joint_mode":
+      return typeof d.proposed === "string" ? { joint: d.proposed } : null;
+    case "seed":
+      return typeof d.proposed === "number" ? { seed: String(d.proposed) } : null;
+    case "frames":
+      return typeof d.proposed === "number" ? { frames: String(d.proposed) } : null;
+    case "branch_frame":
+      return { branchFrame: d.proposed == null ? "" : String(d.proposed) };
+    default:
+      return null;
+  }
+}

package/src/video/jobClock.ts

@@ -0,0 +1,104 @@
+/**
+ * k117 — the feed's clock, told honestly.
+ *
+ * THE BUG the operator reported: the Active-Processes feed showed jobs at 875+
+ * minutes in "loading", 25h in "awaiting_capacity", and DONE rows whose timers
+ * kept ticking under a stale stage label ("archiving"). Keeper triage found the
+ * server rows were CORRECT — the "done · 946m · archiving" row had really run
+ * 9.4 seconds. Two client-side lies produced that display:
+ *
+ *   1. The row rendered `elapsedSince(createdAt)` — i.e. `now - created`, a
+ *      ticking AGE — as if it were runtime. For a terminal row that number keeps
+ *      counting for ever; for a live row it conflates a 25h queue wait with a
+ *      9s render.
+ *   2. The row rendered `current_stage` — the last IN-FLIGHT stage — on terminal
+ *      rows, so a finished render was labelled "archiving" permanently.
+ *
+ * The server (video_intel/job_lifecycle.py) now sends the facts this file needs:
+ * FROZEN `run_s`/`queue_wait_s`/`total_s`/`terminal_at` + the true
+ * `terminal_stage` on terminal rows, and `elapsed_in_stage_s` +
+ * `last_progress_at` (with queue wait kept separate) on live ones. Nothing here
+ * derives a duration from `Date.now()` — that is the entire point.
+ *
+ * A row from an older server (or the demo fixtures) carries none of these, so
+ * every helper degrades to the honest fallback: it says AGE, and labels it age,
+ * rather than passing an age off as a runtime.
+ */
+import type { MediaJob } from "./useMediaJobs";
+
+/** Seconds as "9.4s" / "3m 4s" / "1h 02m" — compact, never lossy about scale. */
+export function fmtDuration(secs: number | null): string {
+  if (secs == null || !isFinite(secs) || secs < 0) return "";
+  if (secs < 10) return `${secs.toFixed(1)}s`;
+  const s = Math.floor(secs);
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ${s % 60}s`;
+  const h = Math.floor(s / 3600);
+  return `${h}h ${String(Math.floor((s % 3600) / 60)).padStart(2, "0")}m`;
+}
+
+/**
+ * The stage label for a row. A TERMINAL row says what it ended as ("done",
+ * "failed", "cancelled") — never the stage it happened to be in when it ended.
+ * That stage is still available (`atStage`) and the expanded timeline shows it;
+ * it is simply no longer allowed to masquerade as a current stage.
+ */
+export function jobStageLabel(job: MediaJob): string {
+  const raw = job.terminal ? job.terminalStage ?? job.status : job.stage;
+  return raw ? raw.replace(/_/g, " ") : "";
+}
+
+/**
+ * The stage a TERMINAL job was in when it ended, for the secondary "(in
+ * archiving)" note — empty when it adds nothing (a job that ended in no stage,
+ * or whose last stage is the outcome itself).
+ */
+export function terminalAtStage(job: MediaJob): string {
+  if (!job.terminal) return "";
+  const at = job.atStage;
+  if (!at || at === job.terminalStage || at === job.status) return "";
+  return at.replace(/_/g, " ");
+}
+
+/**
+ * The clock chips for one row, in display order.
+ *
+ * TERMINAL: exactly one FROZEN duration — how long it actually ran — plus the
+ * queue wait when there was a meaningful one. Nothing ticks.
+ *
+ * LIVE: the two clocks kept APART, which is the whole fix: time in the CURRENT
+ * stage, and the queue wait, as separate facts. A 9s render that waited 25h
+ * reads as "queued 25h" + "in generating 9s", never as "875m".
+ */
+export function jobClockParts(job: MediaJob): string[] {
+  const out: string[] = [];
+  if (job.terminal) {
+    if (job.runS != null) {
+      out.push(`ran ${fmtDuration(job.runS)}`);
+      // Only worth showing when the wait was a real part of the story.
+      if (job.queueWaitS != null && job.queueWaitS >= 5)
+        out.push(`queued ${fmtDuration(job.queueWaitS)}`);
+      return out;
+    }
+    // No recorded start (a pre-k117 row whose runner wrote no stage entries):
+    // the total span is known, the queue/run split is not. Say "took", which is
+    // true of the whole span, rather than inventing a runtime.
+    if (job.totalS != null) return [`took ${fmtDuration(job.totalS)}`];
+    // Older server / demo fixture: say AGE, and say that it is age.
+    const age = ageSeconds(job.createdAt);
+    return age == null ? [] : [`${fmtDuration(age)} ago`];
+  }
+  if (job.elapsedInStageS != null && job.stage)
+    out.push(`in ${job.stage.replace(/_/g, " ")} ${fmtDuration(job.elapsedInStageS)}`);
+  if (job.queueWaitS != null && job.queueWaitS >= 1)
+    out.push(`queued ${fmtDuration(job.queueWaitS)}`);
+  if (job.runS != null && job.runS >= 1) out.push(`running ${fmtDuration(job.runS)}`);
+  if (out.length) return out;
+  const age = ageSeconds(job.createdAt);
+  return age == null ? [] : [`${fmtDuration(age)} ago`];
+}
+
+function ageSeconds(createdAt: number | null): number | null {
+  if (createdAt == null) return null;
+  return Math.max(0, Date.now() / 1000 - createdAt);
+}

package/src/video/spreadAssist.ts

@@ -43,11 +43,25 @@ export interface IdentityContextWire {
   do_not_invent?: string[];
 }
 
+/**
+ * k93 §C — ONE reference media the assist is given as PRETEXT. The backend
+ * samples ≤ 4 frames of a video (one description for an image), describes them
+ * with a vision model and prepends a "Reference video: …" paragraph to the
+ * assist prompt. `uri` is the library uri; `mime` "video/mp4" | "image/*".
+ */
+export interface AssistMediaWire {
+  uri: string;
+  mime: string;
+  label?: string;
+}
+
 /** The typed `context` object shared by detail/generate/negative/spread. */
 export interface AssistContextWire {
   kind?: "image" | "scene" | "movie";
   /** FREE-FORM user text only — structured row state rides the typed fields (§1c). */
   hint?: string;
+  /** Optional reference media described server-side as pretext (k93 §C). */
+  media?: AssistMediaWire;
   segment?: SegmentRefWire;
   previous_segment?: SegmentRefWire;
   next_segment?: SegmentRefWire;
@@ -75,6 +89,10 @@ export interface SpreadSegmentResult {
   continuity_note: string;
   directions_used: unknown[];
   warnings: string[];
+  /** k121: the knob values the coordination review APPLIED to this row
+      (joint_mode / parent_segment_id / branch_frame / seed / frames /
+      reference_images). Mechanics only — never prose (invariant 9). */
+  knobs: Record<string, unknown>;
 }
 
 /** The parsed 200 body of a spread call. */
@@ -89,6 +107,9 @@ export interface SpreadResult {
   model: string | null;
   model_requested: string | null;
   model_resolved: string | null;
+  /** k121: the words-vs-knobs review of the whole set. Read it with
+      `readCoordinationReport` (video/coordinationReport.ts). */
+  coordination: unknown;
 }
 
 // ── intent routing (§1d) ────────────────────────────────────────────────────
@@ -300,6 +321,10 @@ export function readSpreadResult(value: unknown): SpreadResult | null {
       continuity_note: str(r.continuity_note).trim(),
       directions_used: Array.isArray(r.directions_used) ? r.directions_used : [],
       warnings: strArray(r.warnings),
+      knobs:
+        r.knobs != null && typeof r.knobs === "object" && !Array.isArray(r.knobs)
+          ? (r.knobs as Record<string, unknown>)
+          : {},
     });
   }
   const seed = v.steering_seed;
@@ -316,6 +341,7 @@ export function readSpreadResult(value: unknown): SpreadResult | null {
     model: typeof v.model === "string" ? v.model : null,
     model_requested: typeof v.model_requested === "string" ? v.model_requested : null,
     model_resolved: typeof v.model_resolved === "string" ? v.model_resolved : null,
+    coordination: v.coordination ?? null,
   };
 }
 

package/src/video/useMediaJobs.ts

@@ -68,6 +68,22 @@ export interface MediaJob {
   failure: JobFailure | null;
   terminal: boolean; // done | failed | cancelled (only present with the history filter)
   progressedAt: number | null; // last REAL movement (the stall/stale basis)
+  // ---- k117 LIFECYCLE CLOCK (video_intel/job_lifecycle.py) ----------------
+  // The feed used to render `now - created` as if it were runtime, so a 9.4s
+  // render created 946 minutes ago read as "946m · archiving". These are the
+  // server's own facts, computed ONCE at the terminal transition and therefore
+  // FROZEN: nothing below is a function of the browser's clock. Null on a row
+  // from an older server (or a demo fixture) — see video/jobClock.ts for the
+  // honest fallback.
+  terminalAt: number | null; // when it ended (epoch seconds); null while live
+  terminalStage: string | null; // the TRUE outcome: done | failed | cancelled
+  atStage: string | null; // the live stage it was in when it ended ("archiving")
+  startedAt: number | null; // when the run actually began
+  queueWaitS: number | null; // time spent waiting, kept SEPARATE from runtime
+  runS: number | null; // frozen runtime when terminal; time-so-far while running
+  totalS: number | null; // queue + run, terminal only
+  elapsedInStageS: number | null; // time in the CURRENT stage (live rows only)
+  lastProgressAt: number | null; // last reported progress (epoch seconds)
 }
 
 function str(v: unknown): string | null {
@@ -170,6 +186,16 @@ function parseJobs(raw: unknown, includeTerminal: boolean): MediaJob[] {
       failure: parseFailure(row.failure),
       terminal,
       progressedAt: num(row.progressed_at) ?? num(row.last_movement_ts),
+      // k117 — read verbatim; never derived here (deriving is what lied).
+      terminalAt: num(row.terminal_at),
+      terminalStage: str(row.terminal_stage),
+      atStage: str(row.at_stage),
+      startedAt: num(row.started_at),
+      queueWaitS: num(row.queue_wait_s),
+      runS: num(row.run_s),
+      totalS: num(row.total_s),
+      elapsedInStageS: num(row.elapsed_in_stage_s),
+      lastProgressAt: num(row.last_progress_at) ?? num(row.progressed_at),
     });
   }
   return out;

package/src/video/useOperatorHistory.ts

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