fix(cli): propagate live capture budget

packages/cli/src/commands/capture.test.ts

@@ -52,6 +52,15 @@ describe("capture command — vision control", () => {
     });
   });
 
+  it("declares --capture-budget separately from navigation --timeout", () => {
+    const captureBudgetArg = captureCommand.args
+      ? Reflect.get(captureCommand.args, "capture-budget")
+      : undefined;
+    expect(captureBudgetArg).toMatchObject({ type: "string" });
+    expect(captureBudgetArg?.description.toLowerCase()).toContain("post-navigation");
+    expect(captureBudgetArg?.description).toContain("--timeout");
+  });
+
   it("plumbs --skip-vision into capture options", async () => {
     vi.spyOn(console, "log").mockImplementation(() => {});
     vi.spyOn(console, "error").mockImplementation(() => {});
@@ -72,6 +81,50 @@ describe("capture command — vision control", () => {
     );
   });
 
+  it("plumbs a positive --capture-budget into the post-navigation budget", async () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    vi.spyOn(console, "error").mockImplementation(() => {});
+
+    await captureCommand.run!({
+      args: {
+        url: "https://example.com",
+        output: "/tmp/hf-capture-budget-test",
+        "skip-assets": false,
+        "skip-vision": false,
+        "capture-budget": "45000",
+        json: true,
+      },
+    } as never);
+
+    expect(captureWebsiteMock).toHaveBeenCalledWith(
+      expect.objectContaining({ postNavigationBudgetMs: 45_000 }),
+      undefined,
+    );
+  });
+
+  it.each(["0", "-1", "Infinity", "not-a-number"])(
+    "rejects invalid --capture-budget %s before capture starts",
+    async (captureBudget) => {
+      vi.spyOn(console, "log").mockImplementation(() => {});
+      vi.spyOn(console, "error").mockImplementation(() => {});
+
+      await expect(
+        captureCommand.run!({
+          args: {
+            url: "https://example.com",
+            output: "/tmp/hf-invalid-capture-budget-test",
+            "skip-assets": false,
+            "skip-vision": false,
+            "capture-budget": captureBudget,
+            json: true,
+          },
+        } as never),
+      ).rejects.toBeInstanceOf(CliRuntimeError);
+
+      expect(captureWebsiteMock).not.toHaveBeenCalled();
+    },
+  );
+
   it("emits a versioned phase record without the captured URL", async () => {
     vi.spyOn(console, "log").mockImplementation(() => {});
     const error = vi.spyOn(console, "error").mockImplementation(() => {});

packages/cli/src/commands/capture.ts

@@ -12,6 +12,16 @@ function emitCapturePhase(event: CapturePhaseProgress): void {
   diag.notice(`${CAPTURE_PHASE_PREFIX}${JSON.stringify(event)}`);
 }
 
+function parseCaptureBudget(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    console.error("--capture-budget must be a positive finite number of milliseconds.");
+    failCommand();
+  }
+  return parsed;
+}
+
 export const examples: Example[] = [
   ["Capture a website into ./capture/", "hyperframes capture https://stripe.com"],
   ["Capture to a different directory", "hyperframes capture https://linear.app -o linear-video"],
@@ -60,6 +70,11 @@ export default defineCommand({
       type: "string",
       description: "Page load timeout in ms (default: 120000)",
     },
+    "capture-budget": {
+      type: "string",
+      description:
+        "Post-navigation capture budget in ms (default: 120000); separate from page-load --timeout",
+    },
     json: {
       type: "boolean",
       description: "Output JSON (for AI agents / programmatic use)",
@@ -112,6 +127,8 @@ export default defineCommand({
       failCommand();
     }
 
+    const captureBudgetMs = parseCaptureBudget(args["capture-budget"] as string | undefined);
+
     const isDefaultOutput = !args.output;
     let outputName = (args.output as string | undefined) ?? "capture";
     let outputDir = resolve(outputName);
@@ -157,6 +174,7 @@ export default defineCommand({
             ? parseInt(args["max-screenshots"] as string)
             : undefined,
           timeout: args.timeout ? parseInt(args.timeout as string) : undefined,
+          postNavigationBudgetMs: captureBudgetMs,
           json: isJson,
           onPhase: emitCapturePhase,
         },