@hienlh/ppm 0.18.2 → 0.18.4

package/src/web/components/chat/team-member-list.tsx

@@ -0,0 +1,43 @@
+/**
+ * Roster for an agent team, working members first.
+ *
+ * Own scroll container so the roster stays put while the conversation grows —
+ * the two used to share one scroll and the members were pushed out of view.
+ */
+
+import { Loader2 } from "lucide-react";
+import { cn } from "@/lib/utils";
+import type { TeamMemberActivity } from "@/hooks/use-team-activity-feed";
+import { TeamMemberActivityRow } from "./team-member-activity-row";
+
+interface TeamMemberListProps {
+  members: TeamMemberActivity[];
+  loading: boolean;
+  onOpenMember: (name: string) => void;
+  className?: string;
+}
+
+export function TeamMemberList({ members, loading, onOpenMember, className }: TeamMemberListProps) {
+  if (members.length === 0) {
+    return (
+      <div className={cn("flex items-center justify-center gap-2 text-xs text-text-subtle py-4", className)}>
+        {loading ? (
+          <>
+            <Loader2 className="size-3 animate-spin" />
+            Reading member sessions…
+          </>
+        ) : (
+          "No member sessions recorded"
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn("overflow-y-auto space-y-0.5", className)}>
+      {members.map((member) => (
+        <TeamMemberActivityRow key={member.name} member={member} onOpen={onOpenMember} />
+      ))}
+    </div>
+  );
+}

package/src/web/components/chat/team-member-window-content.tsx

@@ -0,0 +1,97 @@
+/**
+ * Floating-window body replaying one teammate's whole work session.
+ *
+ * The transcript is fetched on demand and only for the member being opened —
+ * a single teammate transcript reaches several MB, so loading all of a team's
+ * transcripts up front is not an option. Steps render through the same
+ * `SubagentChildren` view the inline Agent card uses, so a teammate's session
+ * looks identical wherever it is read.
+ */
+
+import { useEffect, useState } from "react";
+import { Loader2, RefreshCw } from "lucide-react";
+import { api } from "@/lib/api-client";
+import { cn } from "@/lib/utils";
+import type { ChatEvent } from "../../../types/chat";
+import type { WindowContentProps } from "@/components/floating-window/window-content-registry";
+import { SubagentChildren } from "./tool-cards";
+
+/** Payload the team panel puts on the window when opening it. */
+export interface TeamMemberWindowPayload {
+  teamName: string;
+  memberName: string;
+  projectName?: string;
+}
+
+export default function TeamMemberWindowContent({ payload }: WindowContentProps) {
+  const { teamName, memberName, projectName } = (payload ?? {}) as unknown as TeamMemberWindowPayload;
+  const [events, setEvents] = useState<ChatEvent[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  // Bumped by the refresh button; a working teammate keeps appending steps.
+  const [reloadKey, setReloadKey] = useState(0);
+
+  useEffect(() => {
+    if (!teamName || !memberName) {
+      setError("Missing team or member");
+      setLoading(false);
+      return;
+    }
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    api
+      .get<{ events?: ChatEvent[] }>(
+        `/api/teams/${encodeURIComponent(teamName)}/members/${encodeURIComponent(memberName)}/transcript`,
+      )
+      .then((res) => {
+        if (cancelled) return;
+        setEvents(res?.events ?? []);
+      })
+      .catch(() => {
+        if (!cancelled) setError("Could not read this member's session");
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => { cancelled = true; };
+  }, [teamName, memberName, reloadKey]);
+
+  return (
+    <div className="flex flex-col h-full min-h-0 bg-surface">
+      <div className="flex items-center gap-2 px-3 py-1.5 border-b border-border/30 shrink-0">
+        <span className="text-xs font-medium truncate">{memberName}</span>
+        <span className="text-[10px] text-text-subtle">
+          {events.length > 0 ? `${events.length} steps` : ""}
+        </span>
+        <button
+          type="button"
+          onClick={() => setReloadKey((k) => k + 1)}
+          className="ml-auto text-text-subtle hover:text-foreground p-1 shrink-0"
+          aria-label="Reload session"
+        >
+          <RefreshCw className={cn("size-3", loading && "animate-spin")} />
+        </button>
+      </div>
+
+      {loading && events.length === 0 ? (
+        <div className="flex-1 flex items-center justify-center gap-2 text-xs text-text-subtle">
+          <Loader2 className="size-3 animate-spin" />
+          Loading session…
+        </div>
+      ) : error ? (
+        <div className="flex-1 flex items-center justify-center text-xs text-error px-4 text-center">{error}</div>
+      ) : events.length === 0 ? (
+        <div className="flex-1 flex items-center justify-center text-xs text-text-subtle">
+          This member has no recorded session
+        </div>
+      ) : (
+        <SubagentChildren
+          events={events}
+          projectName={projectName}
+          className="flex-1 min-h-0 overflow-y-auto px-3 py-2 space-y-1"
+        />
+      )}
+    </div>
+  );
+}

package/src/web/components/chat/team-message-badges.ts

@@ -0,0 +1,18 @@
+/**
+ * Badge vocabulary for agent-team messages.
+ *
+ * The team activity panel, the activity popover and the SendMessage tool card all
+ * label the same message kinds, so the map lives here instead of being copied per
+ * surface. Keys match `TeamMessageItem.parsedType` (see `src/types/team.ts`) and the
+ * protocol `type` a SendMessage payload can carry.
+ */
+export const TYPE_BADGES: Record<string, { label: string; className: string }> = {
+  task_assignment: { label: "task", className: "bg-primary/20 text-primary" },
+  idle_notification: { label: "idle", className: "bg-warning/20 text-warning" },
+  completion: { label: "done", className: "bg-success/20 text-success" },
+  shutdown_request: { label: "shutdown", className: "bg-error/20 text-error" },
+  shutdown_approved: { label: "shutdown ✓", className: "bg-text-3/20 text-text-3" },
+  shutdown_response: { label: "shutdown reply", className: "bg-text-3/20 text-text-3" },
+  plan_approval_request: { label: "plan review", className: "bg-primary/20 text-primary" },
+  plan_approval_response: { label: "plan reply", className: "bg-primary/20 text-primary" },
+};

package/src/web/components/chat/team-message-list.tsx

@@ -0,0 +1,88 @@
+/**
+ * Chat history for an agent team: the lead's task assignments merged with the
+ * replies teammates sent back.
+ *
+ * Split out of the panel so Members and Messages each own their own scroll
+ * container — sharing one made the member list scroll away as soon as the
+ * conversation grew.
+ */
+
+import { useEffect, useRef } from "react";
+import { cn } from "@/lib/utils";
+import type { TeamMessageItem } from "@/hooks/use-chat";
+import { TYPE_BADGES } from "./team-message-badges";
+import { previewTeamMessage } from "./team-message-preview";
+
+interface TeamMessageListProps {
+  messages: TeamMessageItem[];
+  className?: string;
+}
+
+export function TeamMessageList({ messages, className }: TeamMessageListProps) {
+  const endRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    endRef.current?.scrollIntoView({ behavior: "smooth" });
+  }, [messages.length]);
+
+  if (messages.length === 0) {
+    return <p className={cn("text-xs text-text-subtle text-center py-4", className)}>No messages yet</p>;
+  }
+
+  return (
+    <div className={cn("overflow-y-auto", className)}>
+      <div className="space-y-2">
+        {messages.map((msg, i) => {
+          const badge = msg.parsedType ? TYPE_BADGES[msg.parsedType] : null;
+          const { title, detail, taskId } = previewTeamMessage(msg.text, msg.summary);
+          return (
+            <div key={`${msg.timestamp}-${i}`} className="text-xs">
+              <div className="flex items-center gap-1 text-text-subtle">
+                <span className="font-medium" style={safeColor(msg.color)}>
+                  {msg.from}
+                </span>
+                <span>→</span>
+                <span>{msg.to}</span>
+                <span className="ml-auto text-[10px]">{formatTime(msg.timestamp)}</span>
+              </div>
+              <div className="mt-0.5 text-foreground/90 break-words">
+                {badge && (
+                  <span className={cn("inline-block px-1 py-0 rounded text-[9px] mr-1", badge.className)}>
+                    {badge.label}
+                  </span>
+                )}
+                {taskId && (
+                  <span className="inline-block px-1 py-0 rounded text-[9px] mr-1 bg-surface-elevated text-text-subtle">
+                    #{taskId}
+                  </span>
+                )}
+                {title}
+              </div>
+              {detail && (
+                <div className="mt-0.5 text-[11px] text-text-subtle break-words line-clamp-2">{detail}</div>
+              )}
+            </div>
+          );
+        })}
+        <div ref={endRef} />
+      </div>
+    </div>
+  );
+}
+
+function formatTime(timestamp: string): string {
+  try {
+    return new Date(timestamp).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", second: "2-digit" });
+  } catch {
+    return "";
+  }
+}
+
+/** Sanitize color value to prevent CSS injection */
+function safeColor(color?: string): React.CSSProperties | undefined {
+  if (!color) return undefined;
+  if (/^#[0-9a-fA-F]{3,8}$/.test(color) || /^[a-zA-Z]{3,20}$/.test(color)) {
+    return { color };
+  }
+  return undefined;
+}

package/src/web/components/chat/team-message-preview.ts

@@ -0,0 +1,87 @@
+/**
+ * Readable preview for an agent-team inbox message.
+ *
+ * A teammate's `text` is usually a JSON protocol payload, not prose — a
+ * task_assignment carries `{ type, taskId, subject, description, assignedBy }`.
+ * Rendering that raw dumps a wall of escaped JSON into the activity panel, so
+ * every payload is reduced to a headline plus an optional body here.
+ *
+ * Pure module: the panel stays a thin renderer and this stays unit-testable.
+ */
+
+/** Field order for the one-line headline. First non-empty wins. */
+const TITLE_FIELDS = ["subject", "summary", "text", "message", "content", "description", "reason", "feedback"];
+
+/** Fields worth showing under the headline when they say more than it does. */
+const DETAIL_FIELDS = ["description", "message", "content", "reason", "feedback"];
+
+/** Structural keys that describe the envelope, never the content. */
+const ENVELOPE_KEYS = new Set(["type", "taskId", "task_id", "assignedBy", "assigned_by", "timestamp", "request_id", "requestId"]);
+
+export interface TeamMessagePreview {
+  /** One-line headline — never raw JSON. */
+  title: string;
+  /** Longer body when the payload carries one beyond the headline. */
+  detail?: string;
+  /** Task id from a task_assignment, for a compact `#4` chip. */
+  taskId?: string;
+}
+
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : v == null ? "" : String(v));
+
+/** First non-empty value among `fields`, plus the key it came from. */
+function pick(obj: Record<string, unknown>, fields: string[], skip?: string): { key: string; value: string } | null {
+  for (const key of fields) {
+    if (key === skip) continue;
+    const value = str(obj[key]);
+    if (value) return { key, value };
+  }
+  return null;
+}
+
+/** `key: value` pairs for a payload none of the known fields matched. */
+function describeUnknownPayload(obj: Record<string, unknown>): string {
+  return Object.entries(obj)
+    .filter(([k, v]) => !ENVELOPE_KEYS.has(k) && str(v))
+    .map(([k, v]) => `${k}: ${str(v)}`)
+    .join(" · ");
+}
+
+/**
+ * Reduce a raw inbox `text` to a headline and optional body.
+ *
+ * @param raw     The message's `text` — JSON payload or plain prose.
+ * @param summary Author-supplied label; outranks anything inside the payload.
+ */
+export function previewTeamMessage(raw: string, summary?: string): TeamMessagePreview {
+  const authored = str(summary);
+  const text = str(raw);
+  if (!text) return { title: authored };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    // Plain prose: first line is the headline, the rest is the body.
+    const [first, ...rest] = text.split("\n");
+    const detail = rest.join("\n").trim();
+    return { title: authored || str(first), ...(detail ? { detail } : {}) };
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { title: authored || text };
+  }
+
+  const obj = parsed as Record<string, unknown>;
+  const taskId = str(obj.taskId) || str(obj.task_id);
+  const head = pick(obj, TITLE_FIELDS);
+  // Never repeat the headline as the body — skip whichever field supplied it.
+  const body = pick(obj, DETAIL_FIELDS, head?.key);
+
+  const title = authored || head?.value || describeUnknownPayload(obj) || str(obj.type) || text;
+  return {
+    title,
+    ...(body ? { detail: body.value } : {}),
+    ...(taskId ? { taskId } : {}),
+  };
+}

package/src/web/components/chat/tool-cards.tsx

@@ -4,9 +4,13 @@
  */
 import { useState, useEffect, useRef, useMemo, lazy, Suspense } from "react";
 import type { BashPartialEntry } from "../../hooks/use-chat";
-const MarkdownRenderer = lazy(() =>
-  import("@/components/shared/markdown-renderer").then((m) => ({ default: m.MarkdownRenderer }))
-);
+import { MiniMarkdown } from "./mini-markdown";
+import {
+  SendMessageSummary,
+  SendMessageDetails,
+  SendMessageOutcomeView,
+} from "./send-message-card";
+import { parseSendMessageResult } from "./send-message-parse";
 import {
   ChevronDown,
   ChevronRight,
@@ -30,12 +34,33 @@ import {
   Code,
   Columns2,
   Clock,
+  Send,
+  Users,
 } from "lucide-react";
 
+/**
+ * Handle of an agent that can be addressed later, or null for a one-shot subagent.
+ *
+ * Only a spawn that passed `name` stays reachable — that name is what SendMessage
+ * takes as its `to`. Teammates therefore always carry one, so the handle is what
+ * separates "a colleague working in the background" from "a scout that answers once".
+ */
+function addressableAgentName(toolName: string, input: Record<string, unknown>): string | null {
+  if (toolName !== "Agent" && toolName !== "Task") return null;
+  const name = input.name;
+  return typeof name === "string" && name.trim() ? name.trim() : null;
+}
+
 /** Per-tool-family icon chip: 24×24 rounded-7 tinted per the design spec. */
-function toolChip(name: string, isError: boolean): { Icon: React.ElementType; cls: string } {
+function toolChip(
+  name: string,
+  isError: boolean,
+  isAddressableAgent = false,
+): { Icon: React.ElementType; cls: string } {
   if (isError && (name === "Bash" || name === "PowerShell"))
     return { Icon: Terminal, cls: "bg-error/15 text-error" };
+  // A named teammate gets its own chip so it is not mistaken for a throwaway subagent.
+  if (isAddressableAgent) return { Icon: Users, cls: "bg-accent-2/15 text-accent-2" };
   switch (name) {
     case "Read": case "Glob": case "LS":
       return { Icon: FileSearch, cls: "bg-accent-wash text-primary" };
@@ -53,6 +78,8 @@ function toolChip(name: string, isError: boolean): { Icon: React.ElementType; cl
       return { Icon: ListChecks, cls: "bg-warning/15 text-warning" };
     case "Task": case "Agent":
       return { Icon: Bot, cls: "bg-accent-wash text-primary" };
+    case "SendMessage":
+      return { Icon: Send, cls: "bg-info/15 text-info" };
     case "AskUserQuestion":
       return { Icon: CircleHelp, cls: "bg-accent-wash text-primary" };
     case "ExitPlanMode":
@@ -69,6 +96,7 @@ import { useTabStore } from "@/stores/tab-store";
 import { basename } from "@/lib/utils";
 import { isImageExtension } from "../../../shared/image-extensions";
 import { resultHasImagePlaceholder } from "../../../shared/tool-result-content";
+import { isAsyncAgentLaunchAck } from "../../../shared/background-agent-status";
 import { ToolImagePreview } from "./tool-image-preview";
 
 /** Extract tool name and input from a ChatEvent */
@@ -141,7 +169,17 @@ export function ToolCard({
   const isSubagent = (toolName === "Agent" || toolName === "Task") && tool.type === "tool_use";
   const children = isSubagent ? (tool as any).children as ChatEvent[] | undefined : undefined;
   const hasChildren = children && children.length > 0;
-  const isDone = hasResult || hasAnswers || wasApproved || completed;
+  // A backgrounded subagent answers its tool call the instant it spawns ("Async agent
+  // launched successfully"), then runs on past the end of the turn. Neither that ack nor
+  // `completed` (which only means the parent turn stopped streaming) says the agent is
+  // finished — only the <task-notification> the SDK reports as bgStatus does. Without this
+  // the card showed a green check while its step count kept climbing.
+  const bgStatus = isSubagent && tool.type === "tool_use" ? tool.bgStatus : undefined;
+  const isBgAgent = isSubagent
+    && (bgStatus != null || (hasResult && !isError && isAsyncAgentLaunchAck(String((result as any).output ?? ""))));
+  const bgRunning = isBgAgent && bgStatus == null;
+  const bgFailed = bgStatus === "failed" || bgStatus === "stopped";
+  const isDone = bgRunning ? false : (hasResult || hasAnswers || wasApproved || completed);
   // File-mutation tools show their change via the inline diff/content preview — the SDK's
   // "file updated successfully" boilerplate is noise, so suppress it (but keep error output).
   const isFileMutation = ["Edit", "MultiEdit", "Write", "NotebookEdit"].includes(toolName);
@@ -172,7 +210,11 @@ export function ToolCard({
     }
   }, [isError, toolName]);
 
-  const { Icon: ChipIcon, cls: chipCls } = toolChip(toolName, isError);
+  const { Icon: ChipIcon, cls: chipCls } = toolChip(
+    toolName,
+    isError,
+    !!addressableAgentName(toolName, input),
+  );
   const isInteractive = toolName === "AskUserQuestion" || toolName === "ExitPlanMode" || isSubagent;
 
   return (
@@ -197,7 +239,10 @@ export function ToolCard({
           {hasChildren && !isStreamingBash && (
             <span className="text-[10px] text-text-3 font-mono">{children!.length} steps</span>
           )}
-          {isError
+          {bgRunning && (
+            <span className="text-[10px] text-primary">running…</span>
+          )}
+          {isError || bgFailed
             ? <XCircle className="size-3.5 text-error" />
             : isDone
               ? <CheckCircle2 className="size-3.5 text-success" />
@@ -254,8 +299,21 @@ function ToolSummary({ name, input }: { name: string; input: Record<string, unkn
     case "ToolSearch":
       return <><Search className="size-3 inline" /> {name} <span className="text-text-subtle">{truncate(s(input.query), 50)}</span></>;
     case "Agent":
-    case "Task":
-      return <><Bot className="size-3 inline" /> {name} <span className="text-text-subtle">{truncate(s(input.description || input.prompt), 60)}</span></>;
+    case "Task": {
+      // Lead with the handle when there is one: it is both the identity of the
+      // teammate and the exact string SendMessage needs to reach it.
+      const handle = addressableAgentName(name, input);
+      const task = truncate(s(input.description || input.prompt), handle ? 44 : 60);
+      return (
+        <>
+          {!handle && <Bot className="size-3 inline" />} {name}{" "}
+          {handle && <span className="text-text-primary font-medium">{handle}</span>}
+          <span className="text-text-subtle">{handle ? ` · ${task}` : task}</span>
+        </>
+      );
+    }
+    case "SendMessage":
+      return <SendMessageSummary name={name} input={input} />;
     case "TodoWrite": {
       const todos = Array.isArray(input.todos) ? input.todos as Array<{ content: string; status: string }> : [];
       const done = todos.filter((t) => t.status === "completed").length;
@@ -393,14 +451,32 @@ function ToolDetails({
     case "TodoWrite":
       return <TodoDetails todos={(input.todos as Array<{ content: string; status: string }>) ?? []} />;
     case "Agent":
-    case "Task":
+    case "Task": {
+      const handle = addressableAgentName(name, input);
       return (
         <div className="space-y-1">
+          {!!handle && (
+            <p className="flex flex-wrap items-center gap-1.5">
+              <span className="text-text-subtle">Name</span>
+              <span className="font-medium text-text-primary">{handle}</span>
+              <span className="inline-block rounded px-1.5 py-0.5 text-[10px] bg-accent-2/15 text-accent-2">
+                teammate
+              </span>
+              {input.isolation === "worktree" && (
+                <span className="inline-block rounded px-1.5 py-0.5 text-[10px] bg-panel-2 text-text-3">
+                  worktree
+                </span>
+              )}
+            </p>
+          )}
           {!!input.description && <p className="text-text-secondary font-medium">{s(input.description)}</p>}
           {!!input.subagent_type && <p className="text-text-subtle">Type: {s(input.subagent_type)}</p>}
           {!!input.prompt && <MiniMarkdown content={s(input.prompt)} maxHeight="max-h-48" />}
         </div>
       );
+    }
+    case "SendMessage":
+      return <SendMessageDetails input={input} />;
     case "ToolSearch":
       return (
         <div className="space-y-0.5">
@@ -556,6 +632,13 @@ function ToolResultView({ toolName, output }: { toolName: string; output: string
     return null;
   }, [toolName, output]);
 
+  // SendMessage answers with a JSON status object nested inside the SDK's text block —
+  // a raw dump would be JSON inside JSON, so collapse it to one delivery line.
+  // Declared after every hook above so the hook order stays stable.
+  if (toolName === "SendMessage" && parseSendMessageResult(output)) {
+    return <SendMessageOutcomeView output={output} />;
+  }
+
   // Agent with extracted markdown content
   if (agentContent) {
     return (
@@ -612,8 +695,12 @@ function CollapsibleOutput({ output }: { output: string }) {
   );
 }
 
-/** Render subagent child events — nested tool_use/tool_result + text */
-function SubagentChildren({ events, projectName }: { events: ChatEvent[]; projectName?: string }) {
+/** Render subagent child events — nested tool_use/tool_result + text.
+ *  Exported so the team member window can replay a teammate's whole work
+ *  session with the same step rendering the inline Agent card uses.
+ *  `className` overrides the container so a full-height surface can drop the
+ *  card's fixed max-height. */
+export function SubagentChildren({ events, projectName, className }: { events: ChatEvent[]; projectName?: string; className?: string }) {
   // Group children similar to InterleavedEvents: pair tool_use + tool_result, merge text
   type ChildGroup =
     | { kind: "text"; content: string }
@@ -656,7 +743,7 @@ function SubagentChildren({ events, projectName }: { events: ChatEvent[]; projec
         const el = e.currentTarget;
         userScrolledRef.current = el.scrollTop + el.clientHeight < el.scrollHeight - 20;
       }}
-      className="border-l-2 border-accent/20 pl-2 space-y-1 mt-1 max-h-64 md:max-h-96 overflow-y-auto"
+      className={className ?? "border-l-2 border-accent/20 pl-2 space-y-1 mt-1 max-h-64 md:max-h-96 overflow-y-auto"}
     >
       {groups.map((g, i) => {
         if (g.kind === "text") {
@@ -672,16 +759,6 @@ function SubagentChildren({ events, projectName }: { events: ChatEvent[]; projec
   );
 }
 
-/** Inline markdown renderer for tool details (prompt, result) */
-function MiniMarkdown({ content, maxHeight = "max-h-48" }: { content: string; maxHeight?: string }) {
-  return (
-    <Suspense fallback={<div className="animate-pulse h-4 bg-muted rounded" />}>
-      <MarkdownRenderer content={content} className={`text-text-secondary overflow-auto ${maxHeight}`} />
-    </Suspense>
-  );
-}
-
-
 /** Real-time streaming bash output with auto-scroll */
 function StreamingBashOutput({ content, lineCount }: { content: string; lineCount: number }) {
   const preRef = useRef<HTMLPreElement>(null);

package/src/web/components/editor/audio-preview.tsx

@@ -1,9 +1,11 @@
-import { Loader2, FileWarning, Music } from "lucide-react";
-import { useBlobUrl } from "@/hooks/use-blob-url";
+import { useState } from "react";
+import { FileWarning, Music } from "lucide-react";
 import { basename } from "@/lib/utils";
+import { rawMediaUrl } from "@/lib/media-url";
 
+/** Streams straight from the Range-capable URL — no whole-file blob, instant seek. */
 export function AudioPreview({ filePath, projectName }: { filePath: string; projectName: string }) {
-  const { blobUrl, error } = useBlobUrl(filePath, projectName);
+  const [error, setError] = useState(false);
 
   if (error) {
     return (
@@ -13,14 +15,11 @@ export function AudioPreview({ filePath, projectName }: { filePath: string; proj
       </div>
     );
   }
-  if (!blobUrl) {
-    return <div className="flex items-center justify-center h-full"><Loader2 className="size-5 animate-spin text-text-subtle" /></div>;
-  }
   return (
     <div className="flex flex-col items-center justify-center h-full gap-4 p-4 bg-surface">
       <Music className="size-16 text-text-subtle" />
       <p className="text-sm text-text-secondary truncate max-w-xs">{basename(filePath)}</p>
-      <audio src={blobUrl} controls className="w-full max-w-md" />
+      <audio key={filePath} src={rawMediaUrl(filePath, projectName)} controls preload="metadata" className="w-full max-w-md" onError={() => setError(true)} />
     </div>
   );
 }

package/src/web/components/editor/video-player/use-video-keyboard-shortcuts.ts

@@ -0,0 +1,62 @@
+import { useCallback, type KeyboardEvent } from "react";
+
+/** What the player exposes for keyboard control; the hook stays free of player state. */
+export interface VideoPlayerActions {
+  togglePlay: () => void;
+  /** Positive = forward, seconds. */
+  seekBy: (deltaSeconds: number) => void;
+  toggleFullscreen: () => void;
+  toggleMute: () => void;
+  /** Positive = louder, in 0..1 units. */
+  volumeBy: (delta: number) => void;
+  /** +1 = next speed step, -1 = previous. */
+  speedStep: (direction: 1 | -1) => void;
+  /** +1 = clockwise, -1 = counter-clockwise. */
+  rotate: (direction: 1 | -1) => void;
+}
+
+/** YouTube-style bindings, documented in the settings menu of the player. */
+export const VIDEO_SHORTCUTS: ReadonlyArray<[keys: string, action: string]> = [
+  ["Space / K", "Play / pause"],
+  ["← / →", "Seek 5s"],
+  ["J / L or Shift+← / →", "Seek 10s"],
+  ["↑ / ↓", "Volume"],
+  ["M", "Mute"],
+  ["F", "Fullscreen"],
+  ["< / >", "Speed"],
+  ["R / Shift+R", "Rotate"],
+];
+
+/**
+ * Returns an `onKeyDown` handler for the player root (which must be focusable).
+ * Keys typed into the range sliders are left alone so arrows still nudge the slider.
+ */
+export function useVideoKeyboardShortcuts(actions: VideoPlayerActions) {
+  return useCallback(
+    (e: KeyboardEvent<HTMLElement>) => {
+      const target = e.target as HTMLElement;
+      if (target.tagName === "INPUT" || target.tagName === "TEXTAREA" || target.isContentEditable) return;
+      if (e.ctrlKey || e.metaKey || e.altKey) return;
+
+      let handled = true;
+      switch (e.key) {
+        case " ": case "k": case "K": actions.togglePlay(); break;
+        case "ArrowLeft": actions.seekBy(e.shiftKey ? -10 : -5); break;
+        case "ArrowRight": actions.seekBy(e.shiftKey ? 10 : 5); break;
+        case "j": case "J": actions.seekBy(-10); break;
+        case "l": case "L": actions.seekBy(10); break;
+        case "ArrowUp": actions.volumeBy(0.1); break;
+        case "ArrowDown": actions.volumeBy(-0.1); break;
+        case "m": case "M": actions.toggleMute(); break;
+        case "f": case "F": actions.toggleFullscreen(); break;
+        case "<": case ",": actions.speedStep(-1); break;
+        case ">": case ".": actions.speedStep(1); break;
+        case "r": actions.rotate(1); break;
+        case "R": actions.rotate(-1); break;
+        default: handled = false;
+      }
+      if (handled) e.preventDefault();
+    },
+    [actions],
+  );
+}