Skip to content

AI-powered video editor that turns raw footage and a creative brief into a polished ad using an ensemble of AI agents (Google Gemini + FFmpeg)

Python
22.0 KB
Raw Blame
/**
 * AVE Studio — Progress View (US-005)
 *
 * Alpine.js v3 component factory that drives the live pipeline progress
 * dashboard. Registers itself as `window.progressView` so the template can
 * bind via `x-data="progressView()"` without needing ES modules or a build
 * step — same pattern as brief-builder.js (US-004).
 *
 * Responsibilities:
 *   1. Receive a job id (already created by brief-builder) and open exactly
 *      one WebSocket to /ws/jobs/{job_id}.
 *   2. Parse the three wire message shapes emitted by src/web/routes/ws.py:
 *        - {"type": "progress", "line": "...", "timestamp": "..."}
 *        - {"type": "status",   "status": "completed"|"failed", "error"?: "..."}
 *        - {"type": "result",   "data": { ...serialized PipelineResult... }}
 *   3. Render progress lines in a terminal-style scrolling container with
 *      auto-scroll to bottom.
 *   4. Parse `[pipeline] step N — {agent}` lines and highlight the active
 *      step in a Director → TrimRefiner → Editor → Reviewer indicator.
 *   5. Transition spinner → checkmark on completion, X on failure.
 *   6. On completion, derive the playable video src from
 *      result.data.final_video_path (absolute fs path → /media/ url).
 *   7. On failure, surface the error plus the last 10 log lines.
 *   8. Clean up the WebSocket in the Alpine destroy() hook and whenever a
 *      new job is watched.
 */
(function () {
  "use strict";

  /**
   * Canonical step order for the pipeline. The indicator renders these in
   * order and highlights whichever one is currently running (or marks it
   * done once a later step begins).
   *
   * These labels are DISPLAY-ONLY and are independent of the lowercase
   * agent names emitted by the runner (e.g. `director`, `trim_refiner`,
   * `editor`, `reviewer`). The indicator is keyed on the step NUMBER from
   * the `[pipeline] step N — {agent}` log line, NOT on string-matching the
   * agent name — so renaming an agent on the Python side does not break
   * the progress dashboard. The step number is 0-based and maps directly
   * to `STEP_NAMES[N]`.
   */
  const STEP_NAMES = ["Director", "TrimRefiner", "Editor", "Reviewer"];

  /**
   * Regex for the progress lines the pipeline runner emits to announce a
   * step boundary. The canonical form uses an em-dash (U+2014) between the
   * step number and the agent name, but older runs used an ASCII dash and
   * some environments may substitute it on copy/paste — accept all three
   * dash variants so the indicator keeps working without coupling the UI
   * to a single character.
   *
   * Note: only the "step N — {agent} starting" shape is matched. The
   * step-END log (`[pipeline] step — {agent} done in ...`) intentionally
   * omits the number, so this regex won't match it — that's correct,
   * step-start is the authoritative boundary for the indicator.
   *
   * Example matches:
   *   "[pipeline] step 0 — director starting"
   *   "[pipeline] step 1 - trim_refiner starting"
   *   "[pipeline] step 2 -- editor starting"
   */
  const STEP_LINE_RE = /\[pipeline\]\s+step\s+(\d+)\s*[—–\-]+\s*([A-Za-z_][\w]*)/;

  /**
   * WebSocket close code the server uses for unknown job ids. Matches the
   * UNKNOWN_JOB_CLOSE_CODE constant in src/web/routes/ws.py.
   */
  const UNKNOWN_JOB_CLOSE_CODE = 4004;

  /**
   * How many tail lines to show alongside the error banner on failure.
   * Matches the acceptance-criteria "last 10 progress lines for context".
   */
  const ERROR_TAIL_LINES = 10;

  /**
   * Normalize an absolute pipeline `final_video_path` into a URL the
   * browser can load through the FastAPI `/media/` static mount.
   *
   * The runner stores an absolute filesystem path (see
   * src/pipeline/runner.py PipelineResult.final_video_path) — e.g.
   *   /Users/.../agentic-video-editor/output/final/slug.mp4
   *
   * FastAPI mounts the repo's ./output directory at /media (see
   * src/web/app.py), so we just split on the first "output/" segment and
   * prepend "/media/". If the input already looks like a /media/ URL, pass
   * it straight through.
   *
   * Returns an empty string when the input is missing or unparseable — the
   * caller decides how to surface that to the user.
   */
  function toMediaUrl(rawPath) {
    if (!rawPath || typeof rawPath !== "string") return "";
    if (rawPath.startsWith("/media/")) return rawPath;
    const marker = "output/";
    const idx = rawPath.indexOf(marker);
    if (idx === -1) return "";
    const tail = rawPath.slice(idx + marker.length);
    if (!tail) return "";
    return "/media/" + tail;
  }

  /**
   * Build the initial Alpine state object. Exposed as a factory so each
   * `x-data="progressView()"` binding gets isolated state — important
   * because the Alpine root uses x-show to hide/show this section.
   */
  function progressView() {
    return {
      // --- Job tracking ---
      jobId: "",
      // One of: "idle" | "connecting" | "running" | "completed" | "failed"
      status: "idle",
      error: "",

      // --- Progress log (array of {line, timestamp}) ---
      entries: [],

      // --- Step indicator state ---
      stepNames: STEP_NAMES,
      /**
       * Index of the step currently running, 0-based to match the
       * `[pipeline] step N — {agent}` numbering the runner emits (which
       * comes from `enumerate(manifest.steps)` — see src/pipeline/runner.py).
       *
       * Values:
       *   -1                    → no step seen yet (all steps pending)
       *    0..STEP_NAMES.length-1 → that step is active
       *    STEP_NAMES.length    → pipeline completed (all steps done)
       */
      currentStep: -1,

      // --- Pipeline result (once status === "completed") ---
      result: null,
      videoSrc: "",

      // --- WebSocket bookkeeping ---
      _socket: null,
      _terminalSeen: false,

      /**
       * Alpine lifecycle: start watching the jobId declared via x-init.
       * The template passes the id through the shared Alpine root state,
       * so this hook is what actually opens the socket.
       */
      init() {
        this.$watch("jobId", (next, prev) => {
          // Any change (including clearing) tears down the old socket first.
          this._teardownSocket();
          if (next && next !== prev) {
            this._reset();
            this._connect(next);
          }
        });
        // If the template already set jobId before init fired, honor it.
        if (this.jobId) {
          this._reset();
          this._connect(this.jobId);
        }
      },

      /**
       * Alpine destroy hook — closes the socket when the component unmounts
       * (e.g. the user navigates away from the progress section). Alpine
       * calls this automatically for components inside an `x-if` that flips
       * to false; we also explicitly call `_teardownSocket` from the watcher
       * so a jobId change has the same effect.
       */
      destroy() {
        this._teardownSocket();
      },

      /**
       * Reset local state for a fresh job. Clears the log, step indicator,
       * result payload, and error banner so the UI doesn't accidentally
       * show stale data from a previous run.
       */
      _reset() {
        this.status = "connecting";
        this.error = "";
        this.entries = [];
        this.currentStep = -1;
        this.result = null;
        this.videoSrc = "";
        this._terminalSeen = false;
      },

      /**
       * Open a WebSocket to /ws/jobs/{jobId}. Uses the same scheme/host as
       * the current page so dev (http → ws) and any future TLS deploy
       * (https → wss) both work without reconfiguration.
       */
      _connect(jobId) {
        const proto = window.location.protocol === "https:" ? "wss:" : "ws:";
        const url = `${proto}//${window.location.host}/ws/jobs/${encodeURIComponent(
          jobId
        )}`;

        let socket;
        try {
          socket = new WebSocket(url);
        } catch (err) {
          // Invalid URL (shouldn't happen), CSP violation, etc. Surface it.
          this.status = "failed";
          this.error =
            err && err.message
              ? `Could not open WebSocket: ${err.message}`
              : "Could not open WebSocket.";
          return;
        }

        this._socket = socket;

        socket.addEventListener("message", (event) => {
          this._handleMessage(event.data);
        });

        socket.addEventListener("error", () => {
          // Browser doesn't give us a usable error payload on the "error"
          // event — the `close` handler below is where we actually decide
          // whether this was a failure or a clean terminal close.
          // eslint-disable-next-line no-console
          console.warn("[progress] WebSocket error event fired");
        });

        socket.addEventListener("close", (event) => {
          this._handleClose(event);
        });
      },

      /**
       * Parse and dispatch a single JSON frame from the server. Any frame
       * we don't recognize is dropped (with a console warning) rather than
       * crashing the view — we'd rather keep the connection alive than
       * show a broken UI for a harmless future extension.
       */
      _handleMessage(raw) {
        let payload;
        try {
          payload = JSON.parse(raw);
        } catch (err) {
          // eslint-disable-next-line no-console
          console.warn("[progress] Dropping non-JSON WebSocket frame", raw);
          return;
        }
        if (!payload || typeof payload !== "object") return;

        switch (payload.type) {
          case "progress":
            this._appendProgress(payload);
            // The first progress frame also flips us from "connecting"
            // into "running" so the spinner is correct.
            if (this.status === "connecting") {
              this.status = "running";
            }
            break;
          case "status":
            this._handleStatus(payload);
            break;
          case "result":
            this.result = payload.data || null;
            this.videoSrc = this._deriveVideoSrc(this.result);
            break;
          default:
            // eslint-disable-next-line no-console
            console.warn("[progress] Unknown message type", payload.type);
        }
      },

      /**
       * Append a progress entry to the rolling log, scroll the terminal
       * pane to the bottom, and update the step indicator if the line
       * matches the canonical `[pipeline] step N — {agent}` format.
       */
      _appendProgress(payload) {
        const line = typeof payload.line === "string" ? payload.line : "";
        const timestamp =
          typeof payload.timestamp === "string" ? payload.timestamp : "";
        this.entries.push({ line, timestamp });
        this._parseStep(line);
        // Defer scroll until Alpine has had a chance to render the new row.
        this.$nextTick(() => {
          const el = this.$refs.logPane;
          if (el) {
            el.scrollTop = el.scrollHeight;
          }
        });
      },

      /**
       * Update `currentStep` when a step boundary line is seen. We key on
       * the step NUMBER rather than the agent name so the indicator stays
       * in sync even if a pipeline run ever includes an agent name we
       * don't display (e.g. a future diagnostic step) — the number is the
       * authoritative ordering signal.
       *
       * The runner emits 0-based indices via `enumerate(manifest.steps)`,
       * so step 0 = Director, 1 = TrimRefiner, 2 = Editor, 3 = Reviewer.
       * Any number beyond STEP_NAMES.length-1 is clamped to the final
       * display slot so a 5th step (if one is ever added before this file
       * is updated) still marks the four known steps as done.
       */
      _parseStep(line) {
        if (!line) return;
        const match = line.match(STEP_LINE_RE);
        if (!match) return;
        const stepNumber = parseInt(match[1], 10);
        if (!Number.isFinite(stepNumber) || stepNumber < 0) return;
        this.currentStep = Math.min(stepNumber, STEP_NAMES.length - 1);
      },

      /**
       * Handle a `{type: "status", ...}` frame from the server. Sets the
       * terminal state so the spinner disappears and -- on failure -- stores
       * the server-provided error message for the alert banner.
       *
       * We do NOT clear `currentJobId` here even though this marks the
       * logical end of the job. The parent Alpine root binds `jobId` on
       * this component to `currentJobId`, so clearing it synchronously
       * would fire the jobId watcher, which calls _teardownSocket() --
       * closing the socket BEFORE the server's follow-up `result` frame
       * is delivered. The net effect would be a completed job with no
       * video src or review scores. Instead, we defer the Run-button
       * re-enable to _handleClose, which runs after the server has
       * finished sending status -> result -> close in that order.
       *
       * Also note: we do NOT clear `this.result` or `this.videoSrc`
       * here because the completed state still renders the rendered
       * video and review panel from them.
       */
      _handleStatus(payload) {
        const status = payload.status;
        if (status === "completed") {
          this._terminalSeen = true;
          this.status = "completed";
          // Once the pipeline declares itself done, mark all steps as
          // complete so the indicator doesn't get stuck showing the final
          // step as "active". Setting currentStep === STEP_NAMES.length
          // means every `index < currentStep` check in stepState() is
          // true, so all steps render as "done".
          this.currentStep = STEP_NAMES.length;
        } else if (status === "failed") {
          this._terminalSeen = true;
          this.status = "failed";
          this.error =
            typeof payload.error === "string" && payload.error
              ? payload.error
              : "Pipeline failed with no error message.";
        }
      },

      /**
       * Clear the Alpine root scope's `currentJobId` so the brief-builder
       * Run button re-enables after a terminal state. Alpine's nested
       * scope inheritance makes `this.currentJobId` refer to the parent
       * when the child doesn't define its own — assigning it writes
       * through to the root, which is where the Run button's
       * `:disabled="... || !!currentJobId"` check reads from.
       *
       * The brief-builder → progressView bridge uses `promotedJobId` on
       * the root (see index.html x-effect) to avoid re-promoting the same
       * completed job after we clear currentJobId. We do NOT touch
       * `promotedJobId` here — leaving it set to the finished job id
       * is exactly what stops the x-effect from firing again.
       */
      _clearRootJobId() {
        // Guard for the standalone case (no parent scope) — Alpine
        // components nested inside <main x-data=...> always see the root
        // fields via scope inheritance, but a future unit-test harness
        // might render progressView in isolation.
        if (typeof this.currentJobId !== "undefined") {
          this.currentJobId = "";
        }
      },

      /**
       * Interpret the WebSocket close event. This is the single point where
       * we re-enable the Run button for ANY terminal outcome -- clean
       * completion, clean failure, 4004 unknown job, or an abnormal
       * disconnect. Doing it here (rather than in _handleStatus) guarantees
       * the server has already delivered status -> result -> close before
       * we clear `currentJobId`, so the jobId watcher-driven
       * _teardownSocket() never fires mid-stream and never drops the
       * `result` frame that carries the video src + review scores.
       *
       * Close outcomes:
       *   - _terminalSeen == true  -> clean wrap-up, do not overwrite
       *     status/error set by _handleStatus
       *   - code == 4004           -> server's unknown-job signal
       *   - anything else          -> abnormal disconnect before a
       *     terminal status frame arrived
       *
       * In all three cases we call _clearRootJobId() so the brief-builder
       * Run button re-enables. Previously the abnormal-close branches
       * (4004 and generic) set `status: "failed"` without clearing
       * currentJobId, which wedged the Run button permanently.
       */
      _handleClose(event) {
        // Drop the reference so `_teardownSocket` doesn't try to close a
        // socket that's already closed.
        this._socket = null;

        if (this._terminalSeen) {
          // Clean path: status + result already delivered before the
          // close frame. Re-enable the Run button now that the server is
          // definitively done with this job.
          this._clearRootJobId();
          return;
        }

        if (event.code === UNKNOWN_JOB_CLOSE_CODE) {
          this.status = "failed";
          this.error = `Unknown job id: ${this.jobId}`;
          this._clearRootJobId();
          return;
        }

        // Normal WebSocket close code per RFC 6455 is 1000. Anything else
        // (or a 1000 without a terminal status) means the stream died
        // before the pipeline finished.
        this.status = "failed";
        this.error =
          "WebSocket closed before the pipeline reported a terminal status" +
          (event.code ? ` (code ${event.code})` : "") +
          ".";
        this._clearRootJobId();
      },

      /**
       * Tear down the active WebSocket, if any. Safe to call repeatedly.
       * Uses close code 1000 so the server-side handler sees a clean
       * disconnect rather than an abnormal failure.
       */
      _teardownSocket() {
        const socket = this._socket;
        if (!socket) return;
        this._socket = null;
        try {
          // Only call close() if the socket hasn't already transitioned
          // to CLOSING/CLOSED — close() is a no-op in those states per
          // the spec, but the try/catch keeps us safe against older
          // browsers that throw InvalidStateError.
          if (
            socket.readyState === WebSocket.OPEN ||
            socket.readyState === WebSocket.CONNECTING
          ) {
            socket.close(1000, "client navigated away");
          }
        } catch (_err) {
          // Best-effort — if close throws we can't do anything useful.
        }
      },

      /**
       * Turn a `result.data` payload into the URL the <video> element
       * should load. Prefers `final_video_path`; falls back to an empty
       * string if the field is missing so the template can show its
       * "video unavailable" fallback instead of a broken <source>.
       */
      _deriveVideoSrc(result) {
        if (!result || typeof result !== "object") return "";
        const url = toMediaUrl(result.final_video_path);
        if (!url) {
          // eslint-disable-next-line no-console
          console.warn(
            "[progress] result.data.final_video_path missing or unparseable — video will be unavailable",
            result.final_video_path
          );
        }
        return url;
      },

      // ---------------------------------------------------------------- #
      // Template helpers                                                  #
      // ---------------------------------------------------------------- #

      /**
       * True while we're waiting on the WebSocket to deliver a terminal
       * status. Used to drive spinner visibility and the Run button's
       * disabled state in the parent component.
       */
      isRunning() {
        return this.status === "connecting" || this.status === "running";
      },

      /** Has the job finished successfully? */
      isCompleted() {
        return this.status === "completed";
      },

      /** Has the job failed? */
      isFailed() {
        return this.status === "failed";
      },

      /**
       * Step indicator classification for a 0-based step index (matching
       * the runner's `[pipeline] step N —` numbering).
       *   - "done"    → an earlier step (render as a check / filled dot)
       *   - "active"  → the current step (render with a spinner / ring)
       *   - "pending" → hasn't started yet (muted)
       *   - "failed"  → in-flight step at the moment of pipeline failure
       *
       * Treats currentStep === -1 (no step seen) as "all pending" and
       * currentStep === STEP_NAMES.length as "all done" — see
       * _handleStatus for why we bump currentStep to STEP_NAMES.length
       * on completion.
       */
      stepState(index) {
        if (this.status === "failed" && this.currentStep === index) {
          // Show the step that was in flight at the moment of failure as
          // "failed" so the user can see where the pipeline stopped.
          return "failed";
        }
        if (this.currentStep < 0) return "pending";
        if (index < this.currentStep) return "done";
        if (index === this.currentStep) return "active";
        return "pending";
      },

      /**
       * Return the last N progress lines, for the failure banner context.
       * Kept as a method (not a computed property) because Alpine doesn't
       * memoize and we want cheap re-evaluation each render.
       */
      tailLines(n) {
        const count = Number.isFinite(n) ? n : ERROR_TAIL_LINES;
        if (this.entries.length <= count) return this.entries;
        return this.entries.slice(this.entries.length - count);
      },

      /**
       * Summary score lookup for the review panel. Returns a display
       * string ("n/a" if missing) so the template can `x-text` each
       * dimension without an x-if wrapper for every value.
       */
      reviewValue(key) {
        if (!this.result || !this.result.review) return "n/a";
        const value = this.result.review[key];
        if (value === undefined || value === null) return "n/a";
        return typeof value === "number" ? value.toFixed(2) : String(value);
      },
    };
  }

  // Expose as a global so Alpine's x-data="progressView()" can find it.
  // No ES-module export needed — this script is loaded via a plain
  // <script defer> tag that executes BEFORE the Alpine CDN script, just
  // like brief-builder.js (see index.html for the ordering rationale).
  window.progressView = progressView;
})();