@stevecastaneda/paseo-progress 1.0.0 → 1.1.0

package/OVERVIEW.md

@@ -1,6 +1,6 @@
 Progress gives each worktree a live dashboard for long agent jobs. The agent records its tickets or steps with a `paseo-progress` command, along with what's stuck, questions for you and finished work. The Progress panel in Explorer shows all of it. Needs Paseo 0.11 or later, and Node.js 22.18 or later on the computer running the Paseo daemon.
 
-The panel shows how much of the estimated work is done, what the agent is doing right now, and where each ticket stands. A ticket turns stuck when it's blocked or runs past its estimate without an update. Press a ticket to see its timeline, activity, questions and deliverables. Images and text files the agent records open in a preview inside Paseo. Any other file opens in an app on the computer running the Paseo daemon, and so does a previewed file when you press Open. That's true from your phone too. The app opens on that computer, not on the phone.
+The panel shows how much of the estimated work is done, what the agent is doing right now, and where each ticket stands. A ticket turns stuck when it's blocked or runs past its estimate without an update. Press a ticket to see its timeline, activity, questions and deliverables. Images, videos and text files the agent records open in a preview inside Paseo. Videos play only in the desktop app. Any other file opens in an app on the computer running the Paseo daemon, and so does a previewed file when you press Open. That's true from your phone too. The app opens on that computer, not on the phone.
 
 When the agent needs a decision, it asks a numbered question with lettered options and says which one it recommends. A pill above the message box counts open questions and stuck work. Each option has a Copy button. Paste the answer into the chat and the agent records it.
 

package/README.md

@@ -13,7 +13,7 @@ The dashboard shows:
 - percent of estimated work done, time done of time estimated (like "1h 30m of 2h"; once everything is done, how long it really took), and a bar with one segment per ticket
 - **Stuck:** blocked tickets, working tickets with no update for longer than their estimate, and blockers the agent flags
 - **Tickets:** estimate, status, and the working ticket's stage. A ticket that waits for another (`--waits-for T03`) shows "Waits for Ticket 03" under its title until that one is done; waiting is the order of work, so it never counts as stuck, even if the agent also marked it blocked. Press a ticket for its story in a dialog. A summary on top shows its status and stage, time worked against the estimate as a bar that turns red past it, the agent's latest status line while it's working, and the agent on it. Tabs below hold the rest, each only when it has something: the ticket's write-up when it has a `--source` file (the start of it, with the rest a press away), a timeline of its stages and statuses with how long each took, and the activity, questions and deliverables that belong to it. The agent on a ticket shows by its chat title; pressing it opens that chat. Items tagged with `--ticket` belong exactly; older, untagged ones are matched by when they happened and marked "by time"
-- **Questions:** each with a permanent reference (Q1, Q2, ...), lettered options, and the option the agent recommends. The agent builds nothing a question affects until you answer; it works on other things meanwhile, and stops when nothing else is left. Press a question to open it in a dialog, then press **Copy Q2 B** to copy `Q2 (title): B` for your reply. Files and links the agent attached (`--file`) open like deliverables: images and text files preview in Paseo (with **Back** to the question), links open in Paseo's browser, and other files open in their default app. From the pill's popover, the preview opens over the popover, which stays open so you can go back to it. Answers stay listed under the same reference.
+- **Questions:** each with a permanent reference (Q1, Q2, ...), lettered options, and the option the agent recommends. The agent builds nothing a question affects until you answer; it works on other things meanwhile, and stops when nothing else is left. Press a question to open it in a dialog, then press **Copy Q2 B** to copy `Q2 (title): B` for your reply. Files and links the agent attached (`--file`) open like deliverables: images, videos and text files preview in Paseo (with **Back** to the question), links open in Paseo's browser, and other files open in their default app. From the pill's popover, the preview opens over the popover, which stays open so you can go back to it. Answers stay listed under the same reference.
 - **Activity**, **Answered** questions and **Deliverables** (press one to open it), sharing one card with a tab for each; the panel remembers the tab you picked. Each shows the newest 10, with **Show 10 older** below
 
 <img src="images/2-ticket.png" alt="A ticket's story: its status, time against the estimate, the agent on it, and its timeline" width="400"> <img src="images/3-question.png" alt="A question waiting for an answer, with lettered options, the agent's recommendation and Copy buttons" width="400">
@@ -22,7 +22,7 @@ The panel lives in Explorer, beside the agent chat, so you can watch both. Open
 
 <img src="images/4-pill.png" alt="The pill above the message box, showing two questions waiting" width="600">
 
-On phones, where Paseo has no Explorer pane, Progress opens as a tab of its own, and the pill stays above the message box while a run is open so there's always a way in. SVG files preview on desktop; on phones they open on the daemon host.
+On phones, where Paseo has no Explorer pane, Progress opens as a tab of its own, and the pill stays above the message box while a run is open so there's always a way in. SVG files and videos preview on desktop; on phones they open on the daemon host.
 
 The first time a run starts in a worktree whose Progress panel has never been opened, the pill shows a spinner and reads **Progress** instead; pressing it opens the panel. Once the panel has been opened there, the plugin writes an empty `progress-panel-opened` file next to the progress file and the nudge never comes back, even for later runs. It doesn't open the panel by itself because Paseo switches to a workspace to open its panel, which would pull you away from whatever you're looking at.
 
@@ -100,7 +100,7 @@ paseo-progress finish "Snapshots ship for all four tables"
 - `ticket add` and `ticket update` take an optional `--source <path or link>[=<label>]`: where the ticket is written up, like its spec file or issue. It shows under the ticket's status in its dialog and opens like a deliverable. `--source ""` clears it. Tickets without one are fine.
 - A working ticket is stuck once it goes longer than its estimate without an update, timed from its last status, stage or note change, or activity tagged to it. The ticket's dialog still shows total time worked against the estimate.
 - `question ask` needs `--recommend`, the agent's pick. The question dialog tags that option "Recommended".
-- Deliverable paths are stored relative to the worktree root. Web links open in Paseo's browser. Pressing an image (PNG, JPEG, GIF, WebP, up to 10 MB) or text deliverable (Markdown, text, logs, JSON, YAML, CSV; the first 256 KB) previews it in a dialog inside Paseo, which also works from a phone; **Open** there opens the file in its default app. Pressing any other local deliverable opens it with its default app on the machine running the Paseo daemon (for example HTML in your browser and folders in the file manager). On macOS, **Open** sends text files to your default browser. Only recorded deliverables inside the worktree open this way; otherwise the path is copied. The copy icon on each row copies the path.
+- Deliverable paths are stored relative to the worktree root. Web links open in Paseo's browser. Pressing an image (PNG, JPEG, GIF, WebP, up to 10 MB) or text deliverable (Markdown, text, logs, JSON, YAML, CSV; the first 256 KB) previews it in a dialog inside Paseo, which also works from a phone; **Open** there opens the file in its default app. A video (MP4, MOV, WebM, up to 200 MB) plays in the same dialog in the desktop app. When there are several files, **Previous** and **Next** step through them, and so do the left and right arrow keys. Pressing any other local deliverable opens it with its default app on the machine running the Paseo daemon (for example HTML in your browser and folders in the file manager). On macOS, **Open** sends text files to your default browser. Only recorded deliverables inside the worktree open this way; otherwise the path is copied. The copy icon on each row copies the path.
 - Several agents can share one run. When another session adds a ticket, each agent sees it at the end of its next command's output (and in `show`), and the skill has it work that ticket in order after its current one. An agent only hears about tickets added since its own last update in the run, and only once.
 - Subagents record their own progress. Since Paseo 0.11, an agent waiting on background subagents shows as idle, so only the subagents' updates show the work is still going. The skill has the agent give each subagent the worktree path and ticket id, and the subagent records its stages and a ticker line on that worktree's dashboard.
 - `start` begins a fresh dashboard. Earlier runs stay in the file. Question references stay unique across runs.
@@ -120,11 +120,17 @@ The progress file, `progress.jsonl`, holds one JSON event per line, each with a
 - Progress folders outside the repo stay behind when a worktree is deleted. They're small, and you can delete them from `~/.local/state/paseo-progress/`.
 - Paseo can't open a panel without switching you to its workspace. So a new run shows a "Progress" pill, and you open the panel yourself.
 - Pills check busy worktrees every 5 seconds and quiet ones every 30. In a quiet worktree, a new question can take up to half a minute to show.
-- Previews cover images up to 10 MB and the first 256 KB of a text file. Other files open in their default app.
+- Previews cover images up to 10 MB, videos up to 200 MB (desktop app only), and the first 256 KB of a text file. Other files open in their default app. A video the app can't decode shows the player's error, and **Open** still works.
 - Stale warnings and overdue times use the daemon host's clock.
 
 ## Changelog
 
+### 1.1.0
+
+- Videos play in the preview. MP4, MOV and WebM files up to 200 MB play in Paseo's desktop app, with a loading percentage while they arrive. On a phone, a video opens on the computer running the Paseo daemon, as before.
+- The left and right arrow keys move to the previous and next file in a preview. **Next** has focus when the preview opens, so Enter moves on too.
+- An image too tall for the preview, like a phone screenshot, could make it flicker between two sizes until you closed it. It now opens at its real shape and holds still.
+
 ### 1.0.0
 
 - Version 1.0. Nothing you use changes. From now on, a new first number means an update breaks something, a new middle number means a new feature, and a new last number means a fix.

package/client/attachments.tsx

@@ -25,7 +25,7 @@ export function absolutePath(path: string, root: string): string {
 }
 
 // Opens attachments the same way everywhere. Web links go to Paseo's browser
-// (the system browser where there is none); images and text go to `onPreview` when the
+// (the system browser where there is none); images, videos and text go to `onPreview` when the
 // caller can show the preview dialog; every other local file opens with its
 // default app on the daemon host.
 export function useAttachmentOpener({ workspaceId, workspaceDirectory, navigation, onPreview }: {

package/client/motion.tsx

@@ -1,5 +1,5 @@
 import React, { createContext, useContext, useEffect, useLayoutEffect, useRef, useState } from "react";
-import { AccessibilityInfo, Animated, Easing, Platform, Pressable, type PressableProps, type StyleProp, type ViewStyle } from "react-native";
+import { AccessibilityInfo, Animated, Easing, Platform, Pressable, type PressableProps, type StyleProp, type View, type ViewStyle } from "react-native";
 
 // Read at render time, not import time. The native driver can't run on web,
 // and web is the only place filter blur renders.
@@ -35,6 +35,8 @@ export function useLastPresent<T>(value: T | null): T | null {
 // A button that scales to 0.96 while pressed. `static` turns the scale off.
 export function PressScale({ static: isStatic, style, outerStyle, children, ...props }: Omit<PressableProps, "style" | "children"> & {
   static?: boolean;
+  // Reaches the pressable itself, e.g. to focus it.
+  ref?: React.Ref<View>;
   // Layout for the pressable itself, e.g. alignSelf; `style` is what scales.
   outerStyle?: StyleProp<ViewStyle>;
   style?: StyleProp<ViewStyle> | ((state: { pressed: boolean; hovered: boolean }) => StyleProp<ViewStyle>);

package/client/preview.tsx

@@ -4,9 +4,11 @@ import { useQuery, useQueryClient } from "@tanstack/react-query";
 import React, { useEffect, useRef, useState } from "react";
 import { ActivityIndicator, Image, Platform, Text, useWindowDimensions, View, type ViewStyle } from "react-native";
 import { type Attachment, attachmentIcon, isPreviewable } from "./attachments";
-import { previewDeliverable } from "../shared/rpc";
+import { previewKind } from "../shared/attachments";
+import { previewDeliverable, readDeliverablePiece } from "../shared/rpc";
 import { PressScale, useLastPresent } from "./motion";
 import { imageOutline, raised } from "./surfaces";
+import { loadVideo, VideoPlayer } from "./video";
 
 type Colors = PluginWorkspacePanelProps["theme"]["colors"];
 
@@ -71,31 +73,43 @@ export function PreviewBody(props: PreviewProps) {
 // its own scrolling and the file scrolls with the actions pinned below.
 export function PreviewContent({ colors, attachment, workspaceId, workspaceDirectory, onOpenOnHost, backLabel, onBack, gallery, onLong }: PreviewProps & { onLong(long: boolean): void }) {
   const fetchPreview = useRpc(previewDeliverable);
+  const readPiece = useRpc(readDeliverablePiece);
+  const queryClient = useQueryClient();
+  // How much of a video has arrived, for the line under the spinner.
+  const loadingKey = (target: Attachment) => ["progress", "preview-loading", workspaceId, target.ref, target.path];
   const previewQuery = (target: Attachment) => ({
     queryKey: ["progress", "preview", workspaceId, target.ref, target.path],
-    queryFn: () => fetchPreview({ workspaceId, workspaceDirectory, ref: target.ref }),
-    staleTime: 30_000,
-    // Images arrive as data URIs up to ~13 MB; let them go soon after the dialog moves on.
+    // An image or video's shape is measured here and cached with it, not held in
+    // this component: Paseo remounts it when `onLong` flips the host's scrolling,
+    // and a remount that forgot the shape fell back to 16:10, flipped `long` back,
+    // and so on, so a tall image made the dialog jump between two sizes until closed.
+    queryFn: async () => {
+      const data = await fetchPreview({ workspaceId, workspaceDirectory, ref: target.ref });
+      if (data.kind === "image") return { ...data, ratio: await imageRatio(data.dataUri) };
+      if (data.kind !== "video") return data;
+      queryClient.setQueryData(loadingKey(target), 0);
+      const video = await loadVideo({
+        bytes: data.bytes,
+        mimeType: data.mimeType,
+        readPiece: (offset) => readPiece({ workspaceId, workspaceDirectory, ref: target.ref, offset }),
+        onProgress: (loaded) => queryClient.setQueryData(loadingKey(target), loaded / data.bytes),
+      });
+      return { ...data, video, ratio: video.ratio };
+    },
+    // A video isn't refetched while it's open: that would load it again and stop it playing.
+    staleTime: previewKind(target.path ?? "") === "video" ? Infinity : 30_000,
+    // Images arrive as data URIs up to ~13 MB and videos run to 200 MB; let them
+    // go soon after the dialog moves on.
     gcTime: 30_000,
   });
   // Stepping to another file keeps this one on screen (dimmed) until the next loads,
   // so the dialog doesn't collapse to a spinner and back.
   const preview = useQuery({ ...previewQuery(attachment), placeholderData: (previous) => previous });
   const stepping = preview.isPlaceholderData;
-  // Measure the image from its data rather than waiting on onLoad, which doesn't
-  // report a size for data URIs on every platform; without it the box stays 16:10.
-  const imageUri = !stepping && preview.data?.kind === "image" ? preview.data.dataUri : null;
-  useEffect(() => {
-    if (!imageUri) return;
-    let current = true;
-    Image.getSize(imageUri, (width, height) => {
-      if (current && width && height) setMeasured({ ref: attachment.ref, ratio: width / height });
-    }, () => {});
-    return () => { current = false; };
-  }, [imageUri, attachment.ref]);
+  const loading = useQuery({ queryKey: loadingKey(attachment), queryFn: () => 0, enabled: false }).data;
   // Load the next file in the direction of travel ahead of time, so stepping is
-  // instant without holding both neighbors in memory.
-  const queryClient = useQueryClient();
+  // instant without holding both neighbors in memory. Not a video: it can be
+  // 200 MB, so it loads only when opened.
   const items = gallery?.items ?? [];
   const index = items.findIndex((item) => item.ref === attachment.ref);
   const lastIndex = useRef(index);
@@ -103,20 +117,42 @@ export function PreviewContent({ colors, attachment, workspaceId, workspaceDirec
     if (index < 0 || items.length < 2) return;
     const step = (lastIndex.current - index + items.length) % items.length === 1 ? -1 : 1;
     lastIndex.current = index;
-    void queryClient.prefetchQuery(previewQuery(items[(index + step + items.length) % items.length]));
+    const next = items[(index + step + items.length) % items.length];
+    if (previewKind(next.path ?? "") !== "video") void queryClient.prefetchQuery(previewQuery(next));
   }, [attachment.ref, items.length]);
-  // Screenshots vary from phone-tall to full-width; size to the real image once it loads.
-  // Kept per file, so stepping to the next image doesn't borrow this one's shape.
-  const [measured, setMeasured] = useState<{ ref: string; ratio: number } | null>(null);
-  const aspectRatio = measured && (measured.ref === attachment.ref || stepping) ? measured.ratio : 16 / 10;
+  // Previous and Next, wrapping at the ends. Left and right arrows do the same.
+  const step = (offset: number) => gallery?.onSelect(items[(Math.max(0, index) + offset + items.length) % items.length]);
+  useArrowKeys(items.length > 1 ? step : null);
+  // Next has focus when the preview opens, so Enter or Space moves on too.
+  const nextButton = useRef<View>(null);
+  useEffect(() => {
+    (nextButton.current as { focus?(): void } | null)?.focus?.();
+  }, []);
+  // Screenshots and recordings vary from phone-tall to full-width; size to the real
+  // file. While stepping, the dimmed one on screen keeps its shape until the next arrives.
+  const aspectRatio = preview.data && "ratio" in preview.data && preview.data.ratio ? preview.data.ratio : 16 / 10;
+  // A video fits the dialog whole, so the controls along its bottom stay in view
+  // without scrolling. A tall image scrolls instead, to keep it readable.
+  const { height: windowHeight } = useWindowDimensions();
+  const room = roomForContent(windowHeight);
+  const maxMediaHeight = preview.data?.kind === "video" ? Math.min(640, Math.max(200, room)) : 640;
+  const mediaStyle = { width: "100%", aspectRatio, maxHeight: maxMediaHeight, borderRadius: 6, ...imageOutline(colors), backgroundColor: colors.surface1, opacity: stepping ? 0.6 : 1 } as const;
   // A long file gets its own scroll area so the actions below it stay in view.
   // Short ones keep the dialog sized to them.
-  const { height: windowHeight } = useWindowDimensions();
-  const long = estimatedHeight(preview.data, aspectRatio) > roomForContent(windowHeight);
+  const long = estimatedHeight(preview.data, aspectRatio, maxMediaHeight) > room;
   useEffect(() => onLong(long), [long]);
+  // How far a video has loaded: under the spinner, or in place of the path while
+  // the last file stays on screen, so nothing moves.
+  const videoLoading = preview.isFetching && loading !== undefined && loading < 1 ? `Loading video, ${Math.floor(loading * 100)}%` : null;
+  const caption = { color: colors.foregroundMuted, fontSize: 12, lineHeight: 17 } as const;
   const content = (
     <>
-      {preview.isPending ? <ActivityIndicator color={colors.foregroundMuted} accessibilityLabel="Loading preview" style={{ padding: 24 }} /> : null}
+      {preview.isPending ? (
+        <View style={{ alignItems: "center", gap: 8, padding: 24 }}>
+          <ActivityIndicator color={colors.foregroundMuted} accessibilityLabel="Loading preview" />
+          {videoLoading ? <Text style={[caption, { fontVariant: ["tabular-nums"] }]}>{videoLoading}</Text> : null}
+        </View>
+      ) : null}
       {preview.error ? (
         <Text accessibilityRole="alert" selectable style={{ color: colors.statusDanger, fontSize: 12, lineHeight: 18 }}>
           Could not preview it: {preview.error.message}
@@ -135,17 +171,17 @@ export function PreviewContent({ colors, attachment, workspaceId, workspaceDirec
         </View>
       ) : null}
       {preview.data?.kind === "image" ? (
-        <Image accessibilityLabel={attachment.title} source={{ uri: preview.data.dataUri }} resizeMode="contain"
-          onLoad={(event) => {
-            const { width, height } = event.nativeEvent.source ?? {};
-            if (width && height && !stepping) setMeasured({ ref: attachment.ref, ratio: width / height });
-          }}
-          style={{ width: "100%", aspectRatio, maxHeight: 640, borderRadius: 6, ...imageOutline(colors), backgroundColor: colors.surface1, opacity: stepping ? 0.6 : 1 }} />
+        <Image accessibilityLabel={attachment.title} source={{ uri: preview.data.dataUri }} resizeMode="contain" style={mediaStyle} />
       ) : null}
+      {preview.data?.kind === "video" ? <VideoPlayer video={preview.data.video} label={attachment.title} style={mediaStyle} /> : null}
       {/* The path as a caption under the file, where it has the full width. */}
-      <Text selectable numberOfLines={1} ellipsizeMode="middle" style={{ marginTop: -4, color: colors.foregroundMuted, fontSize: 12, lineHeight: 17 }}>
-        {attachment.path}
-      </Text>
+      {!preview.isPending && videoLoading ? (
+        <Text style={[caption, { marginTop: -4, fontVariant: ["tabular-nums"] }]}>{videoLoading}</Text>
+      ) : (
+        <Text selectable numberOfLines={1} ellipsizeMode="middle" style={[caption, { marginTop: -4 }]}>
+          {attachment.path}
+        </Text>
+      )}
     </>
   );
   // Back on the left, Previous and Next in the middle, Open on the right.
@@ -154,7 +190,7 @@ export function PreviewContent({ colors, attachment, workspaceId, workspaceDirec
       <View style={{ flex: 1, alignItems: "flex-start" }}>
         {onBack ? <BackButton colors={colors} label={backLabel ?? "Back"} onPress={onBack} /> : null}
       </View>
-      {gallery && gallery.items.length > 1 ? <Stepper colors={colors} gallery={gallery} current={attachment} /> : null}
+      {items.length > 1 ? <Stepper colors={colors} index={Math.max(0, index)} count={items.length} onStep={step} nextRef={nextButton} /> : null}
       <View style={{ flex: 1, alignItems: "flex-end" }}>
         <DialogButton colors={colors} icon="ExternalLink" label="Open" accessibilityLabel="Open in its default app" onPress={onOpenOnHost} />
       </View>
@@ -179,13 +215,21 @@ const CONTENT_WIDTH = 472;
 const CHARS_PER_LINE = Math.floor((CONTENT_WIDTH - 20) / 7.2);
 
 // Roughly how tall the preview draws, including wrapped lines.
-function estimatedHeight(data: { kind: "image" } | { kind: "text"; text: string } | undefined, aspectRatio: number): number {
+function estimatedHeight(data: { kind: "image" | "video" } | { kind: "text"; text: string } | undefined, aspectRatio: number, maxMediaHeight: number): number {
   if (!data) return 0;
-  if (data.kind === "image") return Math.min(CONTENT_WIDTH / aspectRatio, 640);
+  if (data.kind !== "text") return Math.min(CONTENT_WIDTH / aspectRatio, maxMediaHeight);
   const lines = data.text.split("\n").reduce((sum, line) => sum + Math.max(1, Math.ceil(line.length / CHARS_PER_LINE)), 0);
   return lines * 18 + 20;
 }
 
+// An image's width over its height, or null if it can't be read. Read from the data
+// because onLoad doesn't report a size for data URIs on every platform.
+function imageRatio(uri: string): Promise<number | null> {
+  return new Promise((resolve) => {
+    Image.getSize(uri, (width, height) => resolve(width && height ? width / height : null), () => resolve(null));
+  });
+}
+
 // Height the dialog has for the preview before it must scroll: Paseo caps the card
 // at 85% of the window (inside a 24px margin), less its header and padding, the
 // path caption (17px after an 8px gap) and the footer (30px after a 20px gap).
@@ -194,9 +238,9 @@ function roomForContent(windowHeight: number): number {
 }
 
 // A dialog footer button: 13px label and 14px icon, 30px tall. Icon-only is a 30px square.
-export function DialogButton({ colors, icon, label, accessibilityLabel, onPress, outerStyle }: { colors: Colors; icon: string; label?: string; accessibilityLabel?: string; onPress(): void; outerStyle?: ViewStyle }) {
+export function DialogButton({ colors, icon, label, accessibilityLabel, onPress, outerStyle, ref }: { colors: Colors; icon: string; label?: string; accessibilityLabel?: string; onPress(): void; outerStyle?: ViewStyle; ref?: React.Ref<View> }) {
   return (
-    <PressScale accessibilityRole="button" accessibilityLabel={accessibilityLabel ?? label} onPress={onPress} outerStyle={outerStyle}
+    <PressScale ref={ref} accessibilityRole="button" accessibilityLabel={accessibilityLabel ?? label} onPress={onPress} outerStyle={outerStyle}
       style={({ pressed }) => ({
         flexDirection: "row", alignItems: "center", gap: 6,
         paddingVertical: label ? 6 : 8, paddingLeft: label ? 8 : 8, paddingRight: label ? 10 : 8,
@@ -213,16 +257,48 @@ export function BackButton({ colors, label, onPress }: { colors: Colors; label:
   return <DialogButton colors={colors} icon="ChevronLeft" label={label} onPress={onPress} outerStyle={{ alignSelf: "flex-start" }} />;
 }
 
-// Previous and next through a gallery, wrapping at the ends, with "2 of 3" between.
-function Stepper({ colors, gallery, current }: { colors: Colors; gallery: Gallery; current: Attachment }) {
-  const { items } = gallery;
-  const index = Math.max(0, items.findIndex((item) => item.ref === current.ref));
-  const go = (step: number) => gallery.onSelect(items[(index + step + items.length) % items.length]);
+// Previous and next through a gallery, with "2 of 3" between.
+function Stepper({ colors, index, count, onStep, nextRef }: { colors: Colors; index: number; count: number; onStep(offset: number): void; nextRef: React.Ref<View> }) {
   return (
     <View style={{ flexDirection: "row", alignItems: "center", gap: 10 }}>
-      <DialogButton colors={colors} icon="ChevronLeft" accessibilityLabel="Previous file" onPress={() => go(-1)} />
-      <Text style={{ minWidth: 44, textAlign: "center", color: colors.foregroundMuted, fontSize: 13, lineHeight: 18, fontVariant: ["tabular-nums"] }}>{index + 1} of {items.length}</Text>
-      <DialogButton colors={colors} icon="ChevronRight" accessibilityLabel="Next file" onPress={() => go(1)} />
+      <DialogButton colors={colors} icon="ChevronLeft" accessibilityLabel="Previous file" onPress={() => onStep(-1)} />
+      <Text style={{ minWidth: 44, textAlign: "center", color: colors.foregroundMuted, fontSize: 13, lineHeight: 18, fontVariant: ["tabular-nums"] }}>{index + 1} of {count}</Text>
+      <DialogButton ref={nextRef} colors={colors} icon="ChevronRight" accessibilityLabel="Next file" onPress={() => onStep(1)} />
     </View>
   );
 }
+
+// Calls `onStep` with -1 or 1 for the left and right arrow keys, in the desktop
+// app. Not while typing, nor on a focused video, whose controls seek with them.
+function useArrowKeys(onStep: ((offset: number) => void) | null) {
+  const latest = useRef(onStep);
+  latest.current = onStep;
+  const listening = Platform.OS === "web" && onStep !== null;
+  useEffect(() => {
+    if (!listening) return;
+    const window = globalThis as unknown as {
+      addEventListener(type: "keydown", listener: (event: KeyEvent) => void): void;
+      removeEventListener(type: "keydown", listener: (event: KeyEvent) => void): void;
+    };
+    const onKeyDown = (event: KeyEvent) => {
+      const offset = event.key === "ArrowLeft" ? -1 : event.key === "ArrowRight" ? 1 : 0;
+      if (!offset || event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
+      if (/^(VIDEO|INPUT|TEXTAREA|SELECT)$/.test(event.target?.tagName ?? "") || event.target?.isContentEditable) return;
+      event.preventDefault();
+      latest.current?.(offset);
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [listening]);
+}
+
+type KeyEvent = {
+  key: string;
+  altKey: boolean;
+  ctrlKey: boolean;
+  metaKey: boolean;
+  shiftKey: boolean;
+  defaultPrevented: boolean;
+  target: { tagName?: string; isContentEditable?: boolean } | null;
+  preventDefault(): void;
+};

package/client/video.tsx

@@ -0,0 +1,90 @@
+import React, { useEffect, useState } from "react";
+import { View, type ViewStyle } from "react-native";
+
+// Videos play only in Paseo's desktop app (see canPreview), which is a browser
+// underneath. The plugin compiles without the DOM's types, so these are just the
+// browser APIs used here.
+interface VideoElement {
+  preload: string;
+  src: string;
+  videoWidth: number;
+  videoHeight: number;
+  onloadedmetadata: (() => void) | null;
+  onerror: (() => void) | null;
+}
+const browser = globalThis as unknown as {
+  atob(data: string): string;
+  Blob: new (parts: Uint8Array[], options: { type: string }) => VideoBlob;
+  URL: { createObjectURL(blob: VideoBlob): string; revokeObjectURL(url: string): void };
+  document: { createElement(tag: "video"): VideoElement };
+};
+
+// A whole video held in the app, ready to play.
+export type VideoBlob = { readonly size: number };
+
+export interface LoadedVideo {
+  blob: VideoBlob;
+  // Width over height, or null when the app can't read it (the box stays 16:10).
+  ratio: number | null;
+}
+
+// Fetches a video piece by piece into one blob, then reads its shape.
+export async function loadVideo({ bytes, mimeType, readPiece, onProgress }: {
+  bytes: number;
+  mimeType: string;
+  readPiece(offset: number): Promise<{ data: string; bytes: number }>;
+  onProgress(loaded: number): void;
+}): Promise<LoadedVideo> {
+  const pieces: Uint8Array[] = [];
+  let loaded = 0;
+  while (loaded < bytes) {
+    const piece = await readPiece(loaded);
+    const decoded = decode(piece.data);
+    if (piece.bytes !== bytes || !decoded.length) throw new Error("the video changed while it was loading. Try again.");
+    pieces.push(decoded);
+    loaded += decoded.length;
+    onProgress(loaded);
+  }
+  const blob = new browser.Blob(pieces, { type: mimeType });
+  return { blob, ratio: await videoRatio(blob) };
+}
+
+function decode(data: string): Uint8Array {
+  const binary = browser.atob(data);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+  return bytes;
+}
+
+// Reads the size from the video's header without playing it. Gives up after a
+// few seconds, so a video the app can't decode still shows its player and error.
+function videoRatio(blob: VideoBlob): Promise<number | null> {
+  const url = browser.URL.createObjectURL(blob);
+  const video = browser.document.createElement("video");
+  return new Promise<number | null>((resolve) => {
+    setTimeout(() => resolve(null), 5_000);
+    video.onloadedmetadata = () => resolve(video.videoWidth && video.videoHeight ? video.videoWidth / video.videoHeight : null);
+    video.onerror = () => resolve(null);
+    video.preload = "metadata";
+    video.src = url;
+  }).finally(() => {
+    video.onloadedmetadata = video.onerror = null;
+    video.src = "";
+    browser.URL.revokeObjectURL(url);
+  });
+}
+
+// The browser's own player, with its controls, in a box styled like an image's.
+export function VideoPlayer({ video, label, style }: { video: LoadedVideo; label: string; style: ViewStyle }) {
+  const [url, setUrl] = useState<string | null>(null);
+  useEffect(() => {
+    const created = browser.URL.createObjectURL(video.blob);
+    setUrl(created);
+    return () => browser.URL.revokeObjectURL(created);
+  }, [video.blob]);
+  return (
+    <View style={[style, { overflow: "hidden" }]}>
+      {url ? <video src={url} controls playsInline aria-label={label} style={{ width: "100%", height: "100%", display: "block", objectFit: "contain" }} /> : null}
+    </View>
+  );
+}

package/index.server.ts

@@ -1,9 +1,9 @@
 import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { handleGetAttention, handleGetDashboard, handleListFolders, handleMarkPanelOpened, handleSetHistoryFolder } from "./server/dashboard";
 import { handleInstallLauncher, handleLauncherStatus } from "./server/launcher";
-import { handleOpenDeliverable, handlePreviewDeliverable } from "./server/open";
+import { handleOpenDeliverable, handlePreviewDeliverable, handleReadDeliverablePiece } from "./server/open";
 import { handleInstallSkill, handleSkillStatus } from "./server/skill";
-import { getAttention, getDashboard, getLauncherStatus, getSkillStatus, installLauncher, installSkill, listFolders, markPanelOpened, openDeliverable, previewDeliverable, setHistoryFolder } from "./shared/rpc";
+import { getAttention, getDashboard, getLauncherStatus, getSkillStatus, installLauncher, installSkill, listFolders, markPanelOpened, openDeliverable, previewDeliverable, readDeliverablePiece, setHistoryFolder } from "./shared/rpc";
 
 export default function contribute(server: PluginServerContext) {
   server.handle(getDashboard, handleGetDashboard);
@@ -13,6 +13,7 @@ export default function contribute(server: PluginServerContext) {
   server.handle(installLauncher, handleInstallLauncher);
   server.handle(openDeliverable, handleOpenDeliverable);
   server.handle(previewDeliverable, handlePreviewDeliverable);
+  server.handle(readDeliverablePiece, handleReadDeliverablePiece);
   server.handle(getSkillStatus, handleSkillStatus);
   server.handle(installSkill, handleInstallSkill);
   server.handle(listFolders, handleListFolders);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stevecastaneda/paseo-progress",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A live progress dashboard per worktree for Paseo, drawn from a file agents write with the paseo-progress command.",
   "license": "MIT",
   "author": "Steve Castaneda",

package/server/open.ts

@@ -4,7 +4,7 @@ import { open, readFile, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, relative, resolve } from "node:path";
 import { promisify } from "node:util";
-import { findAttachment, imageMimeType, previewKind } from "../shared/attachments.ts";
+import { findAttachment, imageMimeType, previewKind, videoMimeType } from "../shared/attachments.ts";
 import { readProgress } from "./progress-file.ts";
 import { findRoot, outside } from "./paths.ts";
 import { findStore } from "./store.ts";
@@ -68,8 +68,15 @@ export const MAX_PREVIEW_BYTES = 10 * 1024 * 1024;
 // Text past this is cut off in the preview; the full file is a click away.
 export const MAX_PREVIEW_TEXT_BYTES = 256 * 1024;
 
+// A video travels in pieces, so it's capped by what the app can hold, not the socket.
+export const MAX_PREVIEW_VIDEO_BYTES = 200 * 1024 * 1024;
+
+// Small enough that one piece doesn't hold up the agent output sharing the socket.
+export const VIDEO_PIECE_BYTES = 4 * 1024 * 1024;
+
 export type Preview =
   | { kind: "image"; dataUri: string; bytes: number }
+  | { kind: "video"; mimeType: string; bytes: number }
   | { kind: "text"; text: string; bytes: number; truncated: boolean };
 
 // An image (as a data URI) or a text file's contents, so any client (desktop
@@ -77,8 +84,12 @@ export type Preview =
 export async function previewDeliverable(directory: string, id: string): Promise<Preview> {
   const { path, target } = await resolveAttachment(directory, id, "previewed");
   const kind = previewKind(target);
-  if (!kind) throw new Error(`${path} isn't an image or text file, so it can't be previewed.`);
+  if (!kind) throw new Error(`${path} isn't an image, video or text file, so it can't be previewed.`);
   const { size } = await stat(target);
+  if (kind === "video") {
+    if (size > MAX_PREVIEW_VIDEO_BYTES) throw new Error(tooLarge(path, size));
+    return { kind, mimeType: videoMimeType(target)!, bytes: size };
+  }
   if (kind === "text") {
     // Read only what's shown, so a huge log doesn't load whole.
     const file = await open(target);
@@ -89,11 +100,33 @@ export async function previewDeliverable(directory: string, id: string): Promise
       await file.close();
     }
   }
-  if (size > MAX_PREVIEW_BYTES) throw new Error(`${path} is ${Math.round(size / 1024 / 1024)} MB, too large to preview.`);
+  if (size > MAX_PREVIEW_BYTES) throw new Error(tooLarge(path, size));
   const data = await readFile(target);
   return { kind, dataUri: `data:${imageMimeType(target)};base64,${data.toString("base64")}`, bytes: size };
 }
 
+function tooLarge(path: string, size: number): string {
+  return `${path} is ${Math.round(size / 1024 / 1024)} MB, too large to preview.`;
+}
+
+// One piece of a video, from `offset`. Resolved by reference each time, like the
+// preview, so a piece can only come from a video the agent recorded.
+export async function readDeliverablePiece(directory: string, id: string, offset: number): Promise<{ data: string; bytes: number }> {
+  const { path, target } = await resolveAttachment(directory, id, "previewed");
+  if (previewKind(target) !== "video") throw new Error(`${path} isn't a video.`);
+  const file = await open(target);
+  try {
+    const { size } = await file.stat();
+    if (size > MAX_PREVIEW_VIDEO_BYTES) throw new Error(tooLarge(path, size));
+    const length = Math.max(0, Math.min(VIDEO_PIECE_BYTES, size - offset));
+    if (!length) return { data: "", bytes: size };
+    const { buffer, bytesRead } = await file.read({ buffer: Buffer.alloc(length), position: offset });
+    return { data: buffer.subarray(0, bytesRead).toString("base64"), bytes: size };
+  } finally {
+    await file.close();
+  }
+}
+
 export async function handlePreviewDeliverable(
   input: { workspaceId: string; workspaceDirectory: string; ref: string },
   _context: PluginHandlerContext,
@@ -101,6 +134,13 @@ export async function handlePreviewDeliverable(
   return previewDeliverable(input.workspaceDirectory, input.ref);
 }
 
+export async function handleReadDeliverablePiece(
+  input: { workspaceId: string; workspaceDirectory: string; ref: string; offset: number },
+  _context: PluginHandlerContext,
+) {
+  return readDeliverablePiece(input.workspaceDirectory, input.ref, input.offset);
+}
+
 export async function handleOpenDeliverable(
   input: { workspaceId: string; workspaceDirectory: string; ref: string },
   _context: PluginHandlerContext,

package/shared/attachments.ts

@@ -55,6 +55,15 @@ const IMAGE_TYPES: Record<string, string> = {
   ".svg": "image/svg+xml",
 };
 
+// What Paseo's desktop app (Chromium) plays. A .mov plays when it holds H.264;
+// one that doesn't shows the player's error, and Open still works.
+const VIDEO_TYPES: Record<string, string> = {
+  ".mp4": "video/mp4",
+  ".m4v": "video/mp4",
+  ".mov": "video/quicktime",
+  ".webm": "video/webm",
+};
+
 // Plain text shown as-is in the preview dialog, and opened in the browser on
 // the host. HTML is left to the browser either way.
 const TEXT_EXTENSIONS = new Set([".md", ".markdown", ".mdx", ".txt", ".log", ".json", ".jsonl", ".yaml", ".yml", ".csv"]);
@@ -68,18 +77,24 @@ export function imageMimeType(path: string): string | null {
   return IMAGE_TYPES[extension(path) ?? ""] ?? null;
 }
 
-export function previewKind(path: string): "image" | "text" | null {
+// The video type of a path by its extension, or null when it isn't a video.
+export function videoMimeType(path: string): string | null {
+  return VIDEO_TYPES[extension(path) ?? ""] ?? null;
+}
+
+export function previewKind(path: string): "image" | "video" | "text" | null {
   if (imageMimeType(path)) return "image";
+  if (videoMimeType(path)) return "video";
   return TEXT_EXTENSIONS.has(extension(path) ?? "") ? "text" : null;
 }
 
-// Whether the preview dialog can show it. Only a browser draws SVG: Paseo's
-// desktop app can, the phone apps' image view can't, so there an SVG opens on
+// Whether the preview dialog can show it. Only a browser draws SVG and plays
+// video: Paseo's desktop app can, the phone apps can't, so there they open on
 // the host like any other file.
 export function canPreview(attachment: Attachment, where: { browser: boolean }): boolean {
   if (!attachment.path) return false;
   const kind = previewKind(attachment.path);
-  if (kind === "image" && extension(attachment.path) === ".svg") return where.browser;
+  if (kind === "video" || (kind === "image" && extension(attachment.path) === ".svg")) return where.browser;
   return kind !== null;
 }
 
@@ -98,7 +113,7 @@ export function attachmentIcon(attachment: Attachment): string {
   if (attachment.url) return "Globe";
   if (!attachment.path) return "File";
   const kind = previewKind(attachment.path);
-  return kind === "image" ? "Image" : kind === "text" ? "FileText" : /[\/]$/.test(attachment.path) ? "Folder" : "File";
+  return kind === "image" ? "Image" : kind === "video" ? "Video" : kind === "text" ? "FileText" : /[\/]$/.test(attachment.path) ? "Folder" : "File";
 }
 
 // The short name people recognize: a file or folder's own name, or a link's site.

package/shared/rpc.ts

@@ -124,7 +124,8 @@ export const openDeliverable = defineRpc({
   output: z.object({ opened: z.string() }),
 });
 
-// An image or text file's contents, for the preview dialog.
+// An image or text file's contents, for the preview dialog. A video comes back
+// as its type and size only; its bytes follow in pieces (readDeliverablePiece).
 export const previewDeliverable = defineRpc({
   name: "progress.deliverable.preview",
   input: z.object({
@@ -135,6 +136,20 @@ export const previewDeliverable = defineRpc({
   }),
   output: z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("image"), dataUri: z.string(), bytes: z.number() }),
+    z.object({ kind: z.literal("video"), mimeType: z.string(), bytes: z.number() }),
     z.object({ kind: z.literal("text"), text: z.string(), bytes: z.number(), truncated: z.boolean() }),
   ]),
 });
+
+// One piece of a video from `offset`, base64, with the file's size so the client
+// knows when it has it all.
+export const readDeliverablePiece = defineRpc({
+  name: "progress.deliverable.piece",
+  input: z.object({
+    workspaceId: z.string().min(1),
+    workspaceDirectory: z.string().min(1),
+    ref: z.string().min(1),
+    offset: z.number().int().min(0),
+  }),
+  output: z.object({ data: z.string(), bytes: z.number() }),
+});

package/skills/paseo-progress/SKILL.md

@@ -27,7 +27,7 @@ Record each change as it happens, on the ticket's id from `show` (T01, T02, ...)
 | --- | --- |
 | You start a ticket | `ticket update T03 --status working --stage Build` |
 | You move to the next stage | `ticket update T03 --stage Review`, then `Fixes`, then `Verify` |
-| Something reviewable lands (a screenshot folder, a report, a preview URL) | `deliverable add "<what it shows>" <path or URL> --ticket T03` |
+| Something reviewable lands (a screenshot folder, a screen recording, a report, a preview URL) | `deliverable add "<what it shows>" <path or URL> --ticket T03` |
 | A milestone the user would want in the story | `activity add "<one line>" --ticket T03` |
 | Between bigger events | `ticker set "<what you are doing right now>"` |
 | The ticket is finished | `ticket update T03 --status done`, then start the next one |
@@ -66,7 +66,7 @@ paseo-progress question ask "<short title>" "<the question, in one or two senten
 - Build no option before the user answers, not even the one you recommend. The point of asking is that the user decides before the work is done.
 - Keep working on whatever the question doesn't affect: other tickets, or other parts of this one. If nothing else is left, stop, tell the user in chat which questions you're waiting on, and leave the run open.
 - When the user replies ("Q7 A", or in their own words), run `question answer Q7 A --words "<their words>"`, then build what they chose.
-- When a question is about how something looks, attach the screenshot, mockup or preview link with `--file`. The user opens it from the question: images preview in Paseo, links open in its browser. Add more later with `question update Q7 --file <path>=<what it shows>`.
+- When a question is about how something looks, attach the screenshot, mockup or preview link with `--file`. The user opens it from the question: images and videos preview in Paseo, links open in its browser. Add more later with `question update Q7 --file <path>=<what it shows>`.
 - When the user asks about a question, answer in chat and also put the explanation on the question with `question update Q7 --background "<text>"`, so the dashboard carries it too.
 - `question remove Q7` withdraws a question that no longer applies.