@hugpy/video-intelligence-ui 0.1.0

package/src/transport/client.ts

@@ -0,0 +1,262 @@
+// Phase 5 — the one transport all hugpy calls go through.
+//
+// Placed at the shared hugpy level (sibling of config.ts) rather than under console/
+// so the lower-layer receptacle upload can use it too without a console⇄receptacle
+// import cycle. Every call gets: auth (configurable credentials), an AbortSignal,
+// a timeout ceiling, GET-only retry/backoff, a correlation id, and a typed
+// Result<T, AppError> return — failures cross the boundary as data, never as throws.
+import { hugpyConfig } from "../config";
+import { recordRequest, type Outcome } from "./telemetry";
+import { videoShareKey } from "../share";
+
+export type AppError =
+  | { kind: "network"; message: string; requestId: string }
+  | { kind: "timeout"; ms: number; requestId: string }
+  | { kind: "aborted"; requestId: string }
+  | { kind: "unauthorized"; status: number; requestId: string }
+  | {
+      kind: "server";
+      status: number;
+      message: string;
+      traceId?: string;
+      requestId: string;
+    };
+
+export type Result<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: AppError };
+
+export interface RequestOptions {
+  method?: string;
+  body?: BodyInit | null;
+  headers?: Record<string, string>;
+  /** Caller-owned abort (component unmount, explicit Cancel). */
+  signal?: AbortSignal;
+  /** Per-call timeout ceiling; defaults to DEFAULT_TIMEOUT_MS. */
+  timeoutMs?: number;
+  /** Extra retries — honored for idempotent GET/HEAD only. */
+  retries?: number;
+  /**
+   * Body parse hint; default tries JSON then falls back to text. "arraybuffer"
+   * returns the raw bytes untouched (e.g. audio bytes for Web-Audio waveform
+   * decode) — the ONLY way to pull binary through this transport without a raw
+   * fetch.
+   */
+  expect?: "json" | "text" | "arraybuffer";
+  /** Caller context for telemetry — the transport doesn't know these. */
+  meta?: { specKey?: string; operation?: string };
+}
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_GET_RETRIES = 2;
+
+let _counter = 0;
+function newRequestId(): string {
+  try {
+    return crypto.randomUUID();
+  } catch {
+    _counter += 1;
+    const t = typeof performance !== "undefined" ? performance.now() : 0;
+    return `req_${_counter.toString(36)}_${Math.floor(t).toString(36)}`;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function combineSignals(
+  caller: AbortSignal | undefined,
+  timeout: AbortSignal,
+): AbortSignal {
+  if (!caller) return timeout;
+  const anyFn = (AbortSignal as { any?: (s: AbortSignal[]) => AbortSignal }).any;
+  if (typeof anyFn === "function") return anyFn([caller, timeout]);
+
+  const ctrl = new AbortController();
+  if (caller.aborted || timeout.aborted) ctrl.abort();
+  else {
+    const onAbort = () => ctrl.abort();
+    caller.addEventListener("abort", onAbort, { once: true });
+    timeout.addEventListener("abort", onAbort, { once: true });
+  }
+  return ctrl.signal;
+}
+
+async function parseBody(
+  res: Response,
+  expect?: "json" | "text" | "arraybuffer",
+): Promise<unknown> {
+  // Binary bytes must be read before any text() call would mangle them.
+  if (expect === "arraybuffer") return res.arrayBuffer();
+  const text = await res.text();
+  if (expect === "text") return text;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function serverMessage(parsed: unknown, status: number): string {
+  if (isRecord(parsed) && "error" in parsed) return String(parsed.error);
+  if (typeof parsed === "string" && parsed.trim()) return parsed;
+  return `HTTP ${status}`;
+}
+
+function backoff(attempt: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt));
+}
+
+export async function request<T = unknown>(
+  url: string,
+  opts: RequestOptions = {},
+): Promise<Result<T>> {
+  const requestId = newRequestId();
+  const method = (opts.method ?? "GET").toUpperCase();
+  const idempotent = method === "GET" || method === "HEAD";
+  const maxAttempts = idempotent
+    ? Math.max(1, (opts.retries ?? DEFAULT_GET_RETRIES) + 1)
+    : 1;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const startedAt = typeof performance !== "undefined" ? performance.now() : 0;
+
+  let lastError: AppError = {
+    kind: "network",
+    message: "no attempt made",
+    requestId,
+  };
+  let final: Result<T> | null = null;
+  let finalStatus: number | undefined;
+  let finalTraceId: string | undefined;
+
+  for (let attempt = 0; attempt < maxAttempts && !final; attempt++) {
+    const timeoutCtrl = new AbortController();
+    const timer = setTimeout(() => timeoutCtrl.abort(), timeoutMs);
+
+    try {
+      const res = await fetch(url, {
+        method,
+        body: opts.body ?? null,
+        // Only attach the correlation header when explicitly enabled — a custom header
+        // forces a CORS preflight that the upload endpoint may not answer.
+        // k9: a video-share session stamps its credential on every XHR here (the
+        // single fetch choke point). Same-origin (dev.hugpy.ai → /api) so no CORS
+        // preflight; absent for a normal console/operator session (no stored key).
+        headers: {
+          ...(hugpyConfig.sendRequestId ? { "X-Request-Id": requestId } : {}),
+          ...(videoShareKey() ? { "X-Video-Share": videoShareKey() as string } : {}),
+          ...(opts.headers ?? {}),
+        },
+        signal: combineSignals(opts.signal, timeoutCtrl.signal),
+        credentials: hugpyConfig.withCredentials ? "include" : "same-origin",
+      });
+      clearTimeout(timer);
+      finalStatus = res.status;
+
+      if (res.status === 401 || res.status === 403) {
+        final = {
+          ok: false,
+          error: { kind: "unauthorized", status: res.status, requestId },
+        };
+        break;
+      }
+
+      const parsed = await parseBody(res, opts.expect);
+
+      if (!res.ok) {
+        const traceId =
+          res.headers.get("x-trace-id") ??
+          res.headers.get("x-request-id") ??
+          undefined;
+        finalTraceId = traceId;
+        const error: AppError = {
+          kind: "server",
+          status: res.status,
+          message: serverMessage(parsed, res.status),
+          ...(traceId ? { traceId } : {}),
+          requestId,
+        };
+        if (idempotent && res.status >= 500 && attempt < maxAttempts - 1) {
+          lastError = error;
+          await backoff(attempt);
+          continue;
+        }
+        final = { ok: false, error };
+        break;
+      }
+
+      final = { ok: true, value: parsed as T };
+    } catch (e) {
+      clearTimeout(timer);
+
+      // Caller aborted (unmount / Cancel) wins over timeout/network classification.
+      if (opts.signal?.aborted) {
+        final = { ok: false, error: { kind: "aborted", requestId } };
+        break;
+      }
+      if (timeoutCtrl.signal.aborted) {
+        lastError = { kind: "timeout", ms: timeoutMs, requestId };
+      } else {
+        lastError = {
+          kind: "network",
+          message: e instanceof Error ? e.message : String(e),
+          requestId,
+        };
+      }
+      if (idempotent && attempt < maxAttempts - 1) {
+        await backoff(attempt);
+        continue;
+      }
+      final = { ok: false, error: lastError };
+    }
+  }
+
+  const result: Result<T> = final ?? { ok: false, error: lastError };
+  const outcome: Outcome = result.ok ? "ok" : errorOf(result).kind;
+
+  recordRequest({
+    requestId,
+    url,
+    method,
+    outcome,
+    durationMs: Math.round(
+      (typeof performance !== "undefined" ? performance.now() : 0) - startedAt,
+    ),
+    ...(finalStatus != null ? { status: finalStatus } : {}),
+    ...(finalTraceId ? { traceId: finalTraceId } : {}),
+    ...(opts.meta?.specKey ? { specKey: opts.meta.specKey } : {}),
+    ...(opts.meta?.operation ? { operation: opts.meta.operation } : {}),
+  });
+
+  return result;
+}
+
+// Guarded Result accessors. TS only narrows discriminated unions with strictNullChecks,
+// which is OFF in the app's root tsconfig — so call sites can't rely on `if (r.ok)` to
+// narrow the negative branch. Each accessor centralizes a single cast; call only after
+// checking `r.ok` (errorOf) / in the ok branch (okValue).
+export function errorOf<T>(r: Result<T>): AppError {
+  return (r as { error: AppError }).error;
+}
+export function okValue<T>(r: Result<T>): T {
+  return (r as { value: T }).value;
+}
+
+/** Human-readable, kind-aware message for surfacing an AppError in the UI. */
+export function describeAppError(error: AppError): string {
+  switch (error.kind) {
+    case "unauthorized":
+      return "Your session has expired. Please sign in again.";
+    case "timeout":
+      return `The request timed out after ${Math.round(error.ms / 1000)}s.`;
+    case "aborted":
+      return "Cancelled.";
+    case "network":
+      return `Network error: ${error.message}`;
+    case "server":
+      return error.traceId
+        ? `${error.message} (trace ${error.traceId})`
+        : error.message;
+  }
+}

package/src/transport/telemetry.ts

@@ -0,0 +1,97 @@
+import type { AppError } from "./client";
+
+// Phase 10 — observability at the transport boundary. Every request emits one structured
+// event (request id, target, duration, outcome, + optional spec/op from the caller). A
+// pluggable sink defaults to structured console logging and can be swapped for Sentry or
+// any reporter via setTelemetrySink. In-memory metrics aggregate counts/error-rate/latency
+// for a debug surface.
+
+export type Outcome = "ok" | AppError["kind"];
+
+export interface RequestEvent {
+  requestId: string;
+  url: string;
+  method: string;
+  outcome: Outcome;
+  durationMs: number;
+  status?: number;
+  /** Caller context — the transport doesn't know these, so they're passed in. */
+  specKey?: string;
+  operation?: string;
+  /** Server/Sentry correlation id, when present. */
+  traceId?: string;
+}
+
+export interface TelemetrySink {
+  record(event: RequestEvent): void;
+}
+
+// ---- metrics ----
+const countByOp = new Map<string, number>();
+const errorByKind = new Map<Outcome, number>();
+const latencyByOp = new Map<string, number[]>();
+
+function percentile(values: number[], p: number): number {
+  if (!values.length) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const idx = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+  return sorted[Math.max(0, idx)] ?? 0;
+}
+
+export const metrics = {
+  snapshot() {
+    const latency: Record<string, { p50: number; p95: number; n: number }> = {};
+    for (const [op, samples] of latencyByOp) {
+      latency[op] = {
+        p50: Math.round(percentile(samples, 50)),
+        p95: Math.round(percentile(samples, 95)),
+        n: samples.length,
+      };
+    }
+    return {
+      countByOp: Object.fromEntries(countByOp),
+      errorByKind: Object.fromEntries(errorByKind),
+      latency,
+    };
+  },
+  reset() {
+    countByOp.clear();
+    errorByKind.clear();
+    latencyByOp.clear();
+  },
+};
+
+// ---- sink (default: structured console; swap for Sentry via setTelemetrySink) ----
+const consoleSink: TelemetrySink = {
+  record(event) {
+    const line = { evt: "hugpy.request", ...event };
+    if (event.outcome === "ok") {
+      console.debug(line);
+    } else {
+      console.warn(line);
+    }
+  },
+};
+
+let sink: TelemetrySink = consoleSink;
+
+export function setTelemetrySink(next: TelemetrySink): void {
+  sink = next;
+}
+
+export function recordRequest(event: RequestEvent): void {
+  const op = event.operation ?? event.specKey ?? event.method;
+  countByOp.set(op, (countByOp.get(op) ?? 0) + 1);
+  if (event.outcome !== "ok") {
+    errorByKind.set(event.outcome, (errorByKind.get(event.outcome) ?? 0) + 1);
+  }
+  const samples = latencyByOp.get(op) ?? [];
+  samples.push(event.durationMs);
+  latencyByOp.set(op, samples);
+
+  try {
+    sink.record(event);
+  } catch {
+    // a telemetry failure must never break a request
+  }
+}

package/src/video/DropReceptacle.tsx

@@ -0,0 +1,122 @@
+// Shared media-intake receptacle — the drag/drop + click-to-browse surface the
+// four stations mount in place of their empty item-view. NO upload logic lives
+// here: the station passes its EXISTING upload handler (onPick / onPickVideo) as
+// `onFile`, and this component only surfaces the single file the user drops or
+// picks, then hands it straight back. Mirrors the media arm's receptacle
+// interaction — a dashed `.vi-dropzone`, a hidden file input, a drag-active
+// highlight, keyboard activation — but authors it as literal `.vi-*` CSS here.
+// Single file by design: every station ingests exactly one source at a time.
+import { useRef, useState } from "react";
+import type { ChangeEvent, DragEvent, KeyboardEvent } from "react";
+
+export interface DropReceptacleProps {
+  /** The station's existing upload handler — receives the picked/dropped file. */
+  onFile: (file: File) => void;
+  /** Accept filter for the hidden <input> (e.g. "image/*", "audio/*,video/*"). */
+  accept: string;
+  /** Disable + show a "Working…" affordance while the station uploads/ingests. */
+  busy?: boolean;
+  /** Primary invite line. Falls back to the stable deploy marker below. */
+  title?: string;
+  /** Small station-specific secondary line. */
+  hint?: string;
+  /** Optional extra class on the dropzone (e.g. a compact variant). */
+  className?: string;
+}
+
+// Stable deploy marker — a literal that survives minification (grepped
+// post-deploy as the "new receptacle marker"). Doubles as the default title.
+const DROP_MARKER = "Drop a file or click to browse";
+
+export function DropReceptacle({
+  onFile,
+  accept,
+  busy = false,
+  title,
+  hint,
+  className,
+}: DropReceptacleProps) {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [dragActive, setDragActive] = useState(false);
+
+  function openPicker() {
+    if (busy) return;
+    inputRef.current?.click();
+  }
+
+  function onKeyDown(e: KeyboardEvent<HTMLDivElement>) {
+    if (busy) return;
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      openPicker();
+    }
+  }
+
+  function onChange(e: ChangeEvent<HTMLInputElement>) {
+    const file = e.target.files?.[0];
+    if (file) onFile(file);
+    // Reset so re-picking the SAME file re-fires onChange.
+    e.target.value = "";
+  }
+
+  function onDragOver(e: DragEvent<HTMLDivElement>) {
+    if (busy) return;
+    e.preventDefault();
+    setDragActive(true);
+  }
+  function onDragEnter(e: DragEvent<HTMLDivElement>) {
+    if (busy) return;
+    e.preventDefault();
+    setDragActive(true);
+  }
+  function onDragLeave() {
+    setDragActive(false);
+  }
+  function onDrop(e: DragEvent<HTMLDivElement>) {
+    e.preventDefault();
+    setDragActive(false);
+    if (busy) return;
+    const file = e.dataTransfer.files?.[0];
+    if (file) onFile(file);
+  }
+
+  const cls =
+    "vi-dropzone" +
+    (dragActive ? " vi-dropzone--active" : "") +
+    (busy ? " vi-dropzone--busy" : "") +
+    (className ? ` ${className}` : "");
+
+  return (
+    <div
+      className={cls}
+      role="button"
+      tabIndex={0}
+      aria-disabled={busy}
+      onClick={openPicker}
+      onKeyDown={onKeyDown}
+      onDragOver={onDragOver}
+      onDragEnter={onDragEnter}
+      onDragLeave={onDragLeave}
+      onDrop={onDrop}
+    >
+      <input
+        ref={inputRef}
+        type="file"
+        accept={accept}
+        className="vi-file-input"
+        onChange={onChange}
+        disabled={busy}
+      />
+      {busy ? (
+        <span className="vi-dropzone-title">Working…</span>
+      ) : (
+        <>
+          <span className="vi-dropzone-title">{title ?? DROP_MARKER}</span>
+          {hint ? <span className="vi-dropzone-hint">{hint}</span> : null}
+        </>
+      )}
+    </div>
+  );
+}
+
+export default DropReceptacle;

package/src/video/PromptAssistButtons.tsx

@@ -0,0 +1,118 @@
+// The PROMPT-ASSIST button cluster — the presentational half of usePromptAssist.
+// Renders the same .vi-prompt-assist row GenerateStation shipped (an "prompt assist"
+// lead + Enhance + Generate + a dismissible inline error), so every composer that
+// adopts the shared hook gets an identical look. It owns NO state: the host wires
+// the two clicks (Enhance passes its draft; Generate seeds from it) and passes the
+// hook's busy/error values straight through.
+import type { AssistBusyMode, AssistModel } from "./usePromptAssist";
+
+export interface PromptAssistButtonsProps {
+  /**
+   * The active in-flight mode (from usePromptAssist), or null when idle. Typed as the
+   * WIDER busy union so a host that also runs spread/negative calls can hand its
+   * `assistBusy` straight through and have both buttons correctly disable — the two
+   * labels below still key off "detail"/"generate" only.
+   */
+  busy: AssistBusyMode | null;
+  /** The dismissible inline error (from usePromptAssist), or null. */
+  error: string | null;
+  /** Clear the inline error. */
+  onDismissError: () => void;
+  /** Fire Enhance ("detail") — enriches the current draft. Disabled when `canEnhance` is false. */
+  onEnhance: () => void;
+  /** Fire Generate ("generate") — writes a full prompt from scratch (seeded by any current text). */
+  onGenerate: () => void;
+  /** Enhance needs a non-empty draft; the host computes this from its own prompt text. */
+  canEnhance: boolean;
+  /**
+   * The text generators the fleet can actually run (from usePromptAssist). OPTIONAL and
+   * defaulting to empty: a host that hasn't adopted the picker renders exactly the old
+   * cluster, so adoption stays a per-composer flip rather than a breaking change.
+   */
+  models?: AssistModel[];
+  /** The chosen generator, or null for the fleet default. */
+  model?: string | null;
+  /** Choose a generator (null = "use the fleet default"). */
+  onModelChange?: (model: string | null) => void;
+}
+
+export function PromptAssistButtons({
+  busy,
+  error,
+  onDismissError,
+  onEnhance,
+  onGenerate,
+  canEnhance,
+  models = [],
+  model = null,
+  onModelChange,
+}: PromptAssistButtonsProps) {
+  // Only render the picker once discovery has returned something AND the host wired a
+  // handler. An empty list means the fleet offered nothing (or discovery failed) — in
+  // that case assist still works on the backend default, so showing an empty <select>
+  // would advertise a choice that isn't there.
+  const showPicker = onModelChange != null && models.length > 0;
+  return (
+    <div className="vi-prompt-assist">
+      <span className="vi-prompt-assist-lead" aria-hidden="true">
+        prompt assist
+      </span>
+      {showPicker && (
+        <select
+          className="vi-select vi-select-sm"
+          value={model ?? ""}
+          disabled={busy != null}
+          onChange={(e) => onModelChange?.(e.target.value || null)}
+          aria-label="Text generator used to enhance or generate prompts"
+          title={
+            "Which text generator writes the prompt. Thinking is suppressed for all of " +
+            "them, so a reasoning model can't fill the box with its monologue."
+          }
+        >
+          <option value="">fleet default</option>
+          {models.map((m) => (
+            // "· cold" is not decoration: a non-seated model pays a load on first use,
+            // which is minutes, not milliseconds. Saying so up front stops that reading
+            // as a hang.
+            <option key={m.model} value={m.model}>
+              {m.model}
+              {m.serving ? "" : " · cold"}
+            </option>
+          ))}
+        </select>
+      )}
+      <button
+        type="button"
+        className="vi-btn vi-btn-sm vi-btn-ghost"
+        onClick={onEnhance}
+        disabled={!canEnhance || busy != null}
+        title="Enrich your current prompt with more descriptive detail"
+      >
+        {busy === "detail" ? "✨ Enhancing…" : "✨ Enhance"}
+      </button>
+      <button
+        type="button"
+        className="vi-btn vi-btn-sm vi-btn-ghost"
+        onClick={onGenerate}
+        disabled={busy != null}
+        title="Write a full prompt from scratch (uses any current text as a theme)"
+      >
+        {busy === "generate" ? "✨ Generating…" : "✨ Generate"}
+      </button>
+      {error && (
+        <span className="vi-prompt-assist-error" role="alert">
+          {error}
+          <button
+            type="button"
+            className="vi-prompt-assist-dismiss"
+            onClick={onDismissError}
+            aria-label="Dismiss assist error"
+            title="Dismiss"
+          >
+            ✕
+          </button>
+        </span>
+      )}
+    </div>
+  );
+}

package/src/video/composerBridge.ts

@@ -0,0 +1,66 @@
+// Tiny seam letting the shell-level session-library sidebar STAGE a request into
+// the Generate station's ordered composer while Generate is mounted — the same
+// entry point the Run/Submit path already reads (model + mode + ordered parts),
+// pre-filled. There is NO second generation pipeline: staging just drives the
+// station's own setters, then the user reviews and hits Run.
+//
+// Single-handler by design: exactly one GenerateStation is ever mounted (the
+// /generate route). Because Continue / Replicate fire from the shell sidebar on
+// ANY route — before Generate has mounted — a stage request raised while no
+// handler is registered is BUFFERED and drained the instant the station
+// registers (the sidebar navigates to /generate alongside the call). No deps;
+// never touches server media.
+import type { MediaRef } from "./contract";
+
+export interface PendingPart {
+  ref: MediaRef;
+  origin: string;
+  label?: string;
+}
+
+/**
+ * A staged composer request. Every field is optional and additive: `model` /
+ * `mode` drive the station's knobs, `text` appends a text prompt part, `parts`
+ * appends media parts (in order), and `replace` clears the composer first so a
+ * Replicate / Continue stages a clean prompt rather than appending to whatever
+ * was already there.
+ */
+export interface StageRequest {
+  model?: string;
+  mode?: "image" | "scene";
+  text?: string;
+  parts?: PendingPart[];
+  replace?: boolean;
+}
+
+type StageHandler = (req: StageRequest) => void;
+let handler: StageHandler | null = null;
+let pending: StageRequest[] = [];
+
+/**
+ * GenerateStation registers its stager while mounted. On register we drain any
+ * buffered request (raised from the sidebar before the station mounted). Returns
+ * an unregister.
+ */
+export function registerComposer(fn: StageHandler): () => void {
+  handler = fn;
+  if (pending.length > 0) {
+    const queued = pending;
+    pending = [];
+    for (const req of queued) fn(req);
+  }
+  return () => {
+    if (handler === fn) handler = null;
+  };
+}
+
+/** Ask the mounted composer to apply `req`. Buffered if Generate isn't mounted yet. */
+export function requestStage(req: StageRequest): void {
+  if (handler) handler(req);
+  else pending.push(req);
+}
+
+/** Back-compat convenience: append a single media part to the composer. */
+export function requestAddPart(part: PendingPart): void {
+  requestStage({ parts: [part] });
+}