@hugpy/video-intelligence-ui 0.1.0

package/src/stations/GoalComposer.tsx

@@ -0,0 +1,139 @@
+// Shared GOAL-INPUT composer template (Round 7 addendum 2b/2c).
+//
+// Extracts the Movie mode's goal text-input idiom into ONE reusable, presentational
+// component so the tiers share a single goal-input look: a .vi-knob-styled labeled text
+// field (Movie's knob rhythm) with an OPTIONAL inline, chat-composer-style ATTACH TOOLBAR
+// ("＋ image from library" / "＋ video") and removable attached-media chips.
+//
+// Presentational by design: it OWNS no picker or MediaRef logic. Each host wires the
+// attach buttons to its OWN existing library pickers / MediaRef flows via callbacks
+// (`attachments[].onClick`) and renders whatever it already tracks as `attached` chips.
+// That keeps adoption per-mode and non-destabilizing — a mode adopts the idiom without
+// surrendering its editor's state model.
+//
+// Adoption status (see the Round 7 report): the STUDIO surface adopts this for its
+// prompt/negative. The image/scene (ordered-parts composer) and movie (goal/timeline)
+// editors already carry richer, working attach models, so they MIRROR the visual rhythm
+// and their full migration onto this component is flagged as a separate slice rather than
+// forced (per the operator's "mirror + flag what would destabilize" guardrail).
+import type { ReactNode } from "react";
+import { mediaBytesUrl } from "../config";
+import type { MediaRef } from "../video/contract";
+
+/** One inline attach button (e.g. "＋ image from library" / "＋ video"). */
+export interface GoalComposerAttach {
+  label: string;
+  onClick: () => void;
+  disabled?: boolean;
+  title?: string;
+}
+
+/** One attached-media chip (an already-picked MediaRef the host tracks). */
+export interface GoalComposerAttached {
+  ref: MediaRef;
+  onRemove?: () => void;
+  label?: string;
+}
+
+export interface GoalComposerProps {
+  id?: string;
+  label: string;
+  value: string;
+  onChange: (v: string) => void;
+  placeholder?: string;
+  rows?: number;
+  disabled?: boolean;
+  hint?: ReactNode;
+  /**
+   * Fired when the textarea loses focus. Optional and inert unless wired: the studio
+   * movie composer uses it to classify what was typed (scene vs direction) ON BLUR —
+   * never per keystroke — so it can pre-arm the right assist button.
+   */
+  onBlur?: () => void;
+  /** Inline chat-composer attach buttons. Omit/empty = a plain composer (no toolbar). */
+  attachments?: GoalComposerAttach[];
+  /** Attached media shown as removable thumbnail chips above the toolbar. */
+  attached?: GoalComposerAttached[];
+}
+
+export function GoalComposer({
+  id,
+  label,
+  value,
+  onChange,
+  placeholder,
+  rows = 2,
+  disabled = false,
+  hint,
+  onBlur,
+  attachments,
+  attached,
+}: GoalComposerProps) {
+  const hasToolbar = !!attachments && attachments.length > 0;
+  const hasChips = !!attached && attached.length > 0;
+  return (
+    <div className="vi-knob vi-goal-composer">
+      {id ? <label htmlFor={id}>{label}</label> : <label>{label}</label>}
+      <div className="vi-goal-composer-field">
+        <textarea
+          id={id}
+          className="vi-knob-input vi-goal-composer-input"
+          rows={rows}
+          value={value}
+          placeholder={placeholder}
+          disabled={disabled}
+          onChange={(e) => onChange(e.target.value)}
+          onBlur={onBlur}
+        />
+        {hasChips && (
+          <div className="vi-goal-composer-chips">
+            {attached!.map((a, i) => (
+              <span key={`${a.ref.uri}-${i}`} className="vi-goal-composer-chip">
+                {a.ref.kind === "image" ? (
+                  <img
+                    src={mediaBytesUrl(a.ref.uri)}
+                    alt={a.label ?? "attachment"}
+                    className="vi-goal-composer-chip-thumb"
+                  />
+                ) : (
+                  <span className="vi-goal-composer-chip-kind">{a.ref.kind}</span>
+                )}
+                <span className="vi-goal-composer-chip-label">
+                  {a.label ?? a.ref.asset_id.slice(0, 8)}
+                </span>
+                {a.onRemove && (
+                  <button
+                    type="button"
+                    className="vi-goal-composer-chip-x"
+                    onClick={a.onRemove}
+                    aria-label="Remove attachment"
+                    title="Remove"
+                  >
+                    ✕
+                  </button>
+                )}
+              </span>
+            ))}
+          </div>
+        )}
+        {hasToolbar && (
+          <div className="vi-goal-composer-toolbar">
+            {attachments!.map((a, i) => (
+              <button
+                key={`${a.label}-${i}`}
+                type="button"
+                className="vi-btn vi-btn-sm vi-btn-ghost vi-goal-composer-attach"
+                onClick={a.onClick}
+                disabled={a.disabled}
+                title={a.title}
+              >
+                {a.label}
+              </button>
+            ))}
+          </div>
+        )}
+      </div>
+      {hint ? <span className="vi-knob-hint">{hint}</span> : null}
+    </div>
+  );
+}

package/src/stations/ImageCropStation.tsx

@@ -0,0 +1,153 @@
+// Image Crop station (Phase 3) — the first real station. Flow:
+//   file → POST /uploads (multipart) → {path}
+//        → POST /video/ingest {path} → MediaRef (guard kind==="image")
+//        → ImageCropCore: SpatialRegionEditor + enqueue + result grid
+// Every hop goes through request<T>() + config URLs; errors surface via
+// describeAppError.
+//
+// Studio slice 2a: the region editor + enqueue hook + result grid were extracted
+// VERBATIM into stations/ops/ImageCropCore (the reusable "Components view minus
+// upload"). This station now owns only the upload/ingest lifecycle + the persistent
+// add-file bar; it renders <ImageCropCore/> in the Components slot with the same
+// `multiRegion` it always used. Behaviour is unchanged.
+import { useState } from "react";
+import type { StationSpec } from "./types";
+import { SectionTabs } from "./SectionTabs";
+import { AddFileBar } from "./AddFileBar";
+import { ImageCropCore } from "./ops/ImageCropCore";
+import { request, okValue, errorOf, describeAppError } from "../transport/client";
+import { hugpyConfig } from "../config";
+import { getSessionId } from "../session";
+import {
+  mediaRefSchema,
+  uploadResultSchema,
+  type MediaRef,
+} from "../video/contract";
+
+type Phase = "idle" | "uploading" | "ingesting" | "ready";
+
+const PHASE_LABEL: Record<Phase, string> = {
+  idle: "",
+  uploading: "Uploading…",
+  ingesting: "Ingesting…",
+  ready: "",
+};
+
+export function ImageCropStation({ spec }: { spec: StationSpec }) {
+  const [source, setSource] = useState<MediaRef | null>(null);
+  const [fileName, setFileName] = useState<string | null>(null);
+  const [phase, setPhase] = useState<Phase>("idle");
+  const [error, setError] = useState<string | null>(null);
+
+  const busy = phase === "uploading" || phase === "ingesting";
+
+  // Clear the loaded source back to the empty state. ImageCropCore resets its queued
+  // crops + tracker rows when the source reference changes (here → null).
+  function clearSource() {
+    setSource(null);
+    setFileName(null);
+    setError(null);
+  }
+
+  async function onPick(file: File) {
+    setError(null);
+    setFileName(file.name);
+    setSource(null);
+    setPhase("uploading");
+
+    // (a) multipart upload — field `file` + field `sid`. No Content-Type header:
+    // the browser sets the multipart boundary itself.
+    const fd = new FormData();
+    fd.append("file", file);
+    fd.append("sid", getSessionId());
+    const up = await request<unknown>(hugpyConfig.uploadUrl, {
+      method: "POST",
+      body: fd,
+      meta: { specKey: "image-crop", operation: "upload" },
+    });
+    if (!up.ok) {
+      setError(describeAppError(errorOf(up)));
+      setPhase("idle");
+      return;
+    }
+    const upParsed = uploadResultSchema.safeParse(okValue(up));
+    if (!upParsed.success) {
+      setError("Malformed upload response.");
+      setPhase("idle");
+      return;
+    }
+
+    // (b) ingest the server path into a typed MediaRef.
+    setPhase("ingesting");
+    const ing = await request<unknown>(hugpyConfig.videoIngestUrl, {
+      method: "POST",
+      body: JSON.stringify({ path: upParsed.data.path }),
+      headers: { "Content-Type": "application/json" },
+      meta: { specKey: "image-crop", operation: "ingest" },
+    });
+    if (!ing.ok) {
+      setError(describeAppError(errorOf(ing)));
+      setPhase("idle");
+      return;
+    }
+    const media = mediaRefSchema.safeParse(okValue(ing));
+    if (!media.success) {
+      setError("Malformed ingest response.");
+      setPhase("idle");
+      return;
+    }
+    if (media.data.kind !== "image") {
+      setError(
+        `Ingested asset is "${media.data.kind}", not an image — use the Audio or Frames station for that.`,
+      );
+      setPhase("idle");
+      return;
+    }
+    if (!media.data.width || !media.data.height) {
+      setError("Ingest returned no pixel dimensions for the image.");
+      setPhase("idle");
+      return;
+    }
+    setSource(media.data);
+    setPhase("ready");
+  }
+
+  return (
+    <section className="station-card station-wide">
+      {/* Same shared section framing as Frames/Generate, but with NO Options
+          panel — the crop params live inline in the Components view below the
+          image, so no [Components|Options] toggle / rail renders. */}
+      <SectionTabs
+        ariaLabel="Image crop station"
+        addFile={
+          <>
+            {/* ONE compact add control — a Choose button + filename, no dropbox. */}
+            <AddFileBar
+              accept="image/*"
+              onFile={onPick}
+              busy={busy}
+              buttonLabel={source ? "Choose another image" : "Choose image"}
+              onClear={source && !busy ? clearSource : undefined}
+            >
+              {busy && <span className="vi-crop-status">{PHASE_LABEL[phase]}</span>}
+              {!busy && source && (
+                <>
+                  {fileName && (
+                    <span className="vi-addbar-name" title={fileName}>
+                      {fileName}
+                    </span>
+                  )}
+                  <span className="vi-crop-meta">
+                    <code>{source.mime}</code> · {source.width}×{source.height}
+                  </span>
+                </>
+              )}
+            </AddFileBar>
+            {error && <p className="vi-error" role="alert">{error}</p>}
+          </>
+        }
+        components={<ImageCropCore source={source} multiRegion />}
+      />
+    </section>
+  );
+}

package/src/stations/KnobInfo.tsx

@@ -0,0 +1,64 @@
+// Compact "ⓘ" affordance for a knob's verbose explanation.
+//
+// The compacted knobs (width/height/steps/guidance/seed in the Generate rail)
+// used to carry their explanation as permanently-visible copy under the input
+// (`.vi-knob-hint`) — that copy IS the dead space the row-pairing reclaims. This
+// component moves it behind a small info affordance instead of dropping it.
+//
+// ONE pattern covers both desktop and touch (which has no hover), via two
+// INDEPENDENT reveal paths that don't fight each other:
+//   - desktop hover / keyboard focus: pure CSS (`:hover` / `:focus-within` in
+//     app.css) — no React state involved, so it can't be knocked closed by
+//     anything else.
+//   - click/tap: toggles `.vi-knob-info-open` via React state, driven ONLY by
+//     onClick. This is the mobile-equivalent — touch has no hover, so tapping
+//     the ⓘ is how the explanation gets discovered there; tap again to close.
+//     (An earlier version also wired onMouseEnter/onMouseLeave into the same
+//     state and that raced with the synthetic hover-compat events some touch
+//     browsers fire around a tap, closing the popover right after it opened —
+//     keeping the two paths independent avoids that.)
+//
+// Closing via tap/Escape also blurs the button. Without that, a tap leaves the
+// button focused, `:focus-within` stays true, and the popover would keep
+// showing even after `open` (and aria-expanded) flip back to false.
+import { useRef, useState, type KeyboardEvent } from "react";
+
+export function KnobInfo({ label, text }: { label: string; text: string }) {
+  const [open, setOpen] = useState(false);
+  const btnRef = useRef<HTMLButtonElement>(null);
+
+  function close() {
+    setOpen(false);
+    btnRef.current?.blur();
+  }
+
+  function onKeyDown(e: KeyboardEvent<HTMLButtonElement>) {
+    if (e.key === "Escape") close();
+  }
+
+  return (
+    <span className={`vi-knob-info${open ? " vi-knob-info-open" : ""}`}>
+      <button
+        ref={btnRef}
+        type="button"
+        className="vi-knob-info-btn"
+        aria-label={`About ${label}`}
+        aria-expanded={open}
+        onClick={(e) => {
+          // Don't let the click bubble to a document-level handler elsewhere
+          // in the tree — there isn't one today, but this keeps the toggle
+          // self-contained if one is added later.
+          e.stopPropagation();
+          if (open) close();
+          else setOpen(true);
+        }}
+        onKeyDown={onKeyDown}
+      >
+        ⓘ
+      </button>
+      <span className="vi-knob-info-pop" role="tooltip" aria-hidden={!open}>
+        {text}
+      </span>
+    </span>
+  );
+}

package/src/stations/PlaceholderStation.tsx

@@ -0,0 +1,26 @@
+// Placeholder body for a not-yet-built station. Shows what the station will do
+// and which roadmap phase makes it real, so the shell is honest about being a
+// Phase 0 scaffold — no dead controls pretending to work (the media console's
+// "shows features that don't function" lesson, learned once, applied here).
+import type { StationSpec } from "./types";
+
+export function PlaceholderStation({ spec }: { spec: StationSpec }) {
+  return (
+    <section className="station-card">
+      <header>
+        <span className="station-phase">{spec.phase} · builds {spec.buildsSpec}</span>
+        <h2>{spec.title}</h2>
+        <p className="station-blurb">{spec.blurb}</p>
+      </header>
+      <ul className="station-planned">
+        {spec.planned.map((item) => (
+          <li key={item}>{item}</li>
+        ))}
+      </ul>
+      <footer className="station-foot">
+        Planned — see <code>ROADMAP.md</code> ({spec.phase}) and{" "}
+        <code>hugpy_video_intelligence_map.md</code> for the schema and job wiring.
+      </footer>
+    </section>
+  );
+}

package/src/stations/SectionTabs.tsx

@@ -0,0 +1,276 @@
+// Shared responsive section layout for the Frames & Generate stations.
+//
+// A section has three logical parts: the persistent file/media intake bar
+// (`addFile`), the config knobs (`options`), and the working UI (`components`).
+//
+//   Mobile (<62rem): a PERSISTENT compact add-file bar on top (never a tab),
+//     then a two-state [ Components | Options ] toggle (reusing the .vi-gen-mode
+//     segmented-control idiom with real tab semantics — role="tablist"/"tab"/
+//     "tabpanel", aria-selected, aria-controls/aria-labelledby, roving tabindex,
+//     arrow-key movement, `hidden` on the inactive panel), and ONE panel below
+//     showing the selected state (default Components).
+//
+//   Desktop (>=62rem): no toggle — the working components on the LEFT (with the
+//     compact add-file bar atop that column) and the ~17rem Options rail on the
+//     RIGHT, both visible at once.
+//
+// When `options` is omitted (crop stations — their crop params live inline in
+// the Components view), there is NO toggle strip on mobile and NO right rail on
+// desktop: just the persistent add-file bar over the Components content.
+//
+// Slots may be plain nodes or render functions `(api) => node`, where `api`
+// carries `isDesktop`. Pure layout wrapper — it owns no station logic; all
+// per-station state lives in the station component.
+import {
+  useEffect,
+  useId,
+  useState,
+  type KeyboardEvent,
+  type ReactNode,
+} from "react";
+import { createPortal } from "react-dom";
+
+/** The two toggle states shown below the persistent add-file bar. */
+type ToggleId = "components" | "options";
+
+export interface SectionApi {
+  isDesktop: boolean;
+}
+
+type Slot = ReactNode | ((api: SectionApi) => ReactNode);
+
+function resolveSlot(slot: Slot | undefined, api: SectionApi): ReactNode {
+  if (typeof slot === "function") return (slot as (a: SectionApi) => ReactNode)(api);
+  return slot ?? null;
+}
+
+function tabElId(base: string, id: ToggleId): string {
+  return `${base}-tab-${id}`;
+}
+function panelElId(base: string, id: ToggleId): string {
+  return `${base}-panel-${id}`;
+}
+
+// matchMedia-backed media query, SSR-safe (defaults to no-match / mobile when
+// window/matchMedia are unavailable). Initial state reads synchronously on the
+// client so the correct layout paints on the first frame (no toggle flash).
+function useMediaQuery(query: string): boolean {
+  const read = () =>
+    typeof window !== "undefined" && typeof window.matchMedia === "function"
+      ? window.matchMedia(query).matches
+      : false;
+  const [matches, setMatches] = useState<boolean>(read);
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function")
+      return;
+    const mql = window.matchMedia(query);
+    const onChange = () => setMatches(mql.matches);
+    onChange();
+    mql.addEventListener("change", onChange);
+    return () => mql.removeEventListener("change", onChange);
+  }, [query]);
+  return matches;
+}
+
+export function SectionTabs({
+  ariaLabel,
+  options,
+  optionsLabel = "Options",
+  optionsHost,
+  addFile,
+  components,
+  componentsLabel = "Components",
+  initialTab = "components",
+}: {
+  ariaLabel: string;
+  /** Omit when the station has NO config knobs (crop stations) — then no
+      [Components|Options] toggle (mobile) and no right rail (desktop) render. */
+  options?: Slot;
+  optionsLabel?: string;
+  /** Round 9 (additive; default OFF): when a DOM node is passed, the options are
+      PORTALED into it (the arm shell's shared sidebar "Settings" tab) instead of the
+      desktop right rail / mobile [Components|Options] toggle — the work column then goes
+      FULL WIDTH (the movie-mirror). Stations that don't pass this (e.g. Frames) keep the
+      in-place rail/toggle EXACTLY as before. Null while the Settings tab is closed —
+      the options simply don't render until it opens (the knob state lives in the caller). */
+  optionsHost?: HTMLElement | null;
+  /** The persistent compact add-file bar (never a tab). */
+  addFile: Slot;
+  components: Slot;
+  componentsLabel?: string;
+  /** Which toggle state opens active on mobile. Defaults to Components. */
+  initialTab?: ToggleId;
+}) {
+  const base = useId();
+  const isDesktop = useMediaQuery("(min-width: 62rem)");
+  const hasOptions = options != null;
+  // When the caller OPTS IN to external hosting (passes the optionsHost prop at all —
+  // even null while the Settings tab is closed), the options live THERE (portaled), so
+  // the in-place layout behaves like the no-options case (full-width work column / no
+  // mobile toggle) REGARDLESS of whether the host node exists yet. Keying on "prop was
+  // passed" (not "element exists") is what stops the right rail from flickering back
+  // every time the Settings tab is closed. Stations that never pass the prop
+  // (optionsHost === undefined, e.g. Frames) keep the in-place rail/toggle unchanged.
+  const hostOptIn = hasOptions && optionsHost !== undefined;
+
+  // Toggle order: [ Components | Options ] (Options on the right). Only used
+  // when Options exist.
+  const order: { id: ToggleId; label: string }[] = [
+    { id: "components", label: componentsLabel },
+    { id: "options", label: optionsLabel },
+  ];
+
+  const [active, setActive] = useState<ToggleId>(() =>
+    order.some((o) => o.id === initialTab) ? initialTab : "components",
+  );
+
+  const api: SectionApi = { isDesktop };
+  const optionsNode = hasOptions ? resolveSlot(options, api) : null;
+  const addFileNode = resolveSlot(addFile, api);
+  const componentsNode = resolveSlot(components, api);
+  // Round 9: when a host is supplied, portal the options into it (the shell Settings
+  // tab). Renders nothing until the host node exists (Settings tab closed = no target).
+  const portalOptions =
+    hostOptIn && optionsHost != null && optionsNode != null
+      ? createPortal(optionsNode, optionsHost)
+      : null;
+
+  // ---- Desktop ----
+  if (isDesktop) {
+    // No options (or options portaled to the shell Settings tab): a single full-width
+    // work column (add-file bar atop the components) — no empty right rail.
+    if (!hasOptions || hostOptIn) {
+      return (
+        <div className="vi-section-tabs vi-section-tabs--stacked">
+          <section
+            className="vi-section-region vi-section-region--work"
+            aria-label={componentsLabel}
+          >
+            <div className="vi-section-addfile">{addFileNode}</div>
+            {componentsNode}
+          </section>
+          {portalOptions}
+        </div>
+      );
+    }
+    // Options: components (with the add-file bar atop) on the left, the Options
+    // rail on the right. No toggle.
+    return (
+      <div className="vi-section-tabs vi-section-tabs--beside">
+        <section
+          className="vi-section-region vi-section-region--work"
+          aria-label={componentsLabel}
+        >
+          <div className="vi-section-addfile">{addFileNode}</div>
+          {componentsNode}
+        </section>
+        <section
+          className="vi-section-region vi-section-region--options"
+          aria-label={optionsLabel}
+        >
+          {optionsNode}
+        </section>
+      </div>
+    );
+  }
+
+  // ---- Mobile, no options (or options portaled to the shell Settings tab): persistent
+  // add-file bar over the components only — no [Components|Options] toggle. ----
+  if (!hasOptions || hostOptIn) {
+    return (
+      <div className="vi-section-tabs vi-section-tabs--mobile">
+        <div className="vi-section-addfile">{addFileNode}</div>
+        {componentsNode}
+        {portalOptions}
+      </div>
+    );
+  }
+
+  // ---- Mobile, with options: persistent add-file bar, then a
+  // [ Components | Options ] toggle over a single panel. ----
+  function focusTab(index: number) {
+    const t = order[index];
+    if (!t) return;
+    setActive(t.id);
+    document.getElementById(tabElId(base, t.id))?.focus();
+  }
+
+  function onKeyDown(e: KeyboardEvent<HTMLButtonElement>, index: number) {
+    switch (e.key) {
+      case "ArrowRight":
+      case "ArrowDown":
+        e.preventDefault();
+        focusTab((index + 1) % order.length);
+        break;
+      case "ArrowLeft":
+      case "ArrowUp":
+        e.preventDefault();
+        focusTab((index - 1 + order.length) % order.length);
+        break;
+      case "Home":
+        e.preventDefault();
+        focusTab(0);
+        break;
+      case "End":
+        e.preventDefault();
+        focusTab(order.length - 1);
+        break;
+      default:
+        break;
+    }
+  }
+
+  const nodeFor = (id: ToggleId): ReactNode =>
+    id === "options" ? optionsNode : componentsNode;
+
+  return (
+    <div className="vi-section-tabs vi-section-tabs--mobile">
+      {/* PERSISTENT add-file bar — always visible, not a tab. */}
+      <div className="vi-section-addfile">{addFileNode}</div>
+
+      {/* Components | Options toggle. */}
+      <div
+        role="tablist"
+        aria-label={ariaLabel}
+        className="vi-gen-mode vi-section-tablist"
+      >
+        {order.map((t, i) => {
+          const selected = t.id === active;
+          return (
+            <button
+              key={t.id}
+              type="button"
+              role="tab"
+              id={tabElId(base, t.id)}
+              aria-selected={selected}
+              aria-controls={panelElId(base, t.id)}
+              tabIndex={selected ? 0 : -1}
+              className={`vi-gen-mode-btn vi-section-tab${
+                selected ? " vi-gen-mode-btn-active" : ""
+              }`}
+              onClick={() => setActive(t.id)}
+              onKeyDown={(e) => onKeyDown(e, i)}
+            >
+              {t.label}
+            </button>
+          );
+        })}
+      </div>
+
+      {/* Single panel below the toggle. */}
+      {order.map((t) => (
+        <div
+          key={t.id}
+          role="tabpanel"
+          id={panelElId(base, t.id)}
+          aria-labelledby={tabElId(base, t.id)}
+          hidden={t.id !== active}
+          tabIndex={0}
+          className="vi-section-tabpanel"
+        >
+          {nodeFor(t.id)}
+        </div>
+      ))}
+    </div>
+  );
+}