Skip to content

Commit e406a40

Browse files
strzhaoclaude
andcommitted
feat(screenshot): add --count/--interval-ms animation burst capture in one request
A burst repeats the single capture path N times inside one admitted plan, so evidence for an animation no longer needs repeated single-shot calls. The flags reuse the shared count/intervalMs keys (press/swipe series own the same tokens), so the parser, dispatch pass-through, session recorder, and script round-trip carry them without new flag vocabulary. - contracts: burst limits (count 2-200, interval 100-10000, scheduled wait capped at 30s inside the standard request budget), one shared admission that also refuses --crop-on/--overlay-refs beside --count, frame destination helper (<base>-0001.<ext> sequence), and per-frame result records (path + capture wall clock) - command surface: count/intervalMs input fields, burst admission beside scale validation, help prose for the burst - daemon: sequential frame loop over the bound runtime, default interval 100ms when --interval-ms is absent, shared temp root for a burst without an explicit path, cancellation between frames through the request signal Co-Authored-By: Claude Code <[email protected]>
1 parent a68693c commit e406a40

10 files changed

Lines changed: 492 additions & 7 deletions

File tree

‎packages/command-registry/src/flag-definitions-action.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,8 @@ export const ACTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
2121
min: 1,
2222
max: 200,
2323
usageLabel: '--count <n>',
24-
usageDescription: 'Repeat count for press, swipe and gesture tap series',
24+
usageDescription:
25+
'Repeat count for press, swipe and gesture tap series; screenshot: burst frame count (2-200) captured sequentially into a numbered file sequence',
2526
projectConfig: true,
2627
recorded: true,
2728
},
@@ -85,7 +86,8 @@ export const ACTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
8586
min: 0,
8687
max: 10_000,
8788
usageLabel: '--interval-ms <ms>',
88-
usageDescription: 'Delay between press iterations',
89+
usageDescription:
90+
'Delay between press iterations; screenshot: wait between burst frames (100-10000, default 100)',
8991
projectConfig: true,
9092
recorded: true,
9193
},

‎packages/command-surface/src/capture/screenshot-options.test.ts‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,12 @@ import {
66
SCREENSHOT_COMMAND_FLAG_KEYS,
77
SCREENSHOT_SPECIFIC_FLAG_DEFINITIONS,
88
readScreenshotScriptFlag,
9+
screenshotBurstFramePath,
910
screenshotFlagsFromOptions,
1011
screenshotFlagsFromPublicOptions,
1112
screenshotOptionsFromFlags,
1213
validateNoRetiredScreenshotMaxSize,
14+
validateScreenshotBurst,
1315
validateScreenshotScale,
1416
type ScreenshotRequestFlags,
1517
} from '@agent-device/contracts/capture';
@@ -173,6 +175,8 @@ test('screenshot script flags use the shared recorded flag contract', () => {
173175
'screenshotNoStabilize',
174176
'screenshotNormalizeStatusBar',
175177
'screenshotCaptureBackend',
178+
'count',
179+
'intervalMs',
176180
]);
177181
});
178182

@@ -200,3 +204,82 @@ test('explicit screenshot stabilization survives SDK projection and script recor
200204
});
201205
assert.deepEqual(screenshotOptionsFromFlags(recorded), { stabilize: true });
202206
});
207+
208+
test('screenshot burst flags ride both projections', () => {
209+
assert.deepEqual(screenshotOptionsFromFlags({ count: 5, intervalMs: 250 }), {
210+
count: 5,
211+
intervalMs: 250,
212+
});
213+
assert.deepEqual(screenshotFlagsFromOptions({ count: 5, intervalMs: 250 }), {
214+
count: 5,
215+
intervalMs: 250,
216+
});
217+
assert.deepEqual(screenshotFlagsFromPublicOptions({ count: 3 }), { count: 3 });
218+
});
219+
220+
test('screenshot burst admission bounds the count, the interval, and their pair', () => {
221+
assert.doesNotThrow(() => validateScreenshotBurst({ count: 2 }));
222+
assert.doesNotThrow(() => validateScreenshotBurst({ count: 5, intervalMs: 250 }));
223+
assert.doesNotThrow(() => validateScreenshotBurst({}));
224+
assert.throws(() => validateScreenshotBurst({ intervalMs: 250 }), {
225+
message: /--interval-ms requires --count/,
226+
});
227+
assert.throws(() => validateScreenshotBurst({ count: 1 }), {
228+
message: /--count requires an integer from 2 to /,
229+
});
230+
assert.throws(() => validateScreenshotBurst({ count: 201 }), { code: 'INVALID_ARGS' });
231+
assert.throws(() => validateScreenshotBurst({ count: 2.5 }), { code: 'INVALID_ARGS' });
232+
assert.throws(() => validateScreenshotBurst({ count: 2, intervalMs: 50 }), {
233+
message: /--interval-ms requires an integer from 100 to /,
234+
});
235+
assert.throws(() => validateScreenshotBurst({ count: 2, intervalMs: 20_000 }), {
236+
code: 'INVALID_ARGS',
237+
});
238+
});
239+
240+
test('screenshot burst admission refuses crop and overlay combinations and overlong schedules', () => {
241+
assert.throws(() => validateScreenshotBurst({ count: 3, cropOn: 'role=button label=Save' }), {
242+
message: /--count cannot be combined with --crop-on or --overlay-refs/,
243+
});
244+
assert.throws(() => validateScreenshotBurst({ count: 3, overlayRefs: true }), {
245+
message: /--count cannot be combined with --crop-on or --overlay-refs/,
246+
});
247+
assert.doesNotThrow(() => validateScreenshotBurst({ count: 3, cropOn: undefined }));
248+
assert.throws(
249+
() => validateScreenshotBurst({ count: 150, intervalMs: 500 }),
250+
/keep the burst within 30000 ms/,
251+
);
252+
assert.doesNotThrow(() => validateScreenshotBurst({ count: 200 }));
253+
});
254+
255+
test('screenshot burst frame paths number the user sequence in place', () => {
256+
assert.equal(screenshotBurstFramePath('/tmp/page.png', 1), '/tmp/page-0001.png');
257+
assert.equal(screenshotBurstFramePath('/tmp/page.png', 12), '/tmp/page-0012.png');
258+
assert.equal(screenshotBurstFramePath('page.jpeg', 3), 'page-0003.jpeg');
259+
assert.equal(screenshotBurstFramePath('/tmp/page', 2), '/tmp/page-0002');
260+
assert.equal(screenshotBurstFramePath('/tmp/my.photos/page', 4), '/tmp/my.photos/page-0004');
261+
assert.equal(screenshotBurstFramePath('/tmp/.hidden', 5), '/tmp/.hidden-0005');
262+
});
263+
264+
test('screenshot burst flags round-trip through recorded scripts', () => {
265+
const parts: string[] = [];
266+
appendScreenshotScriptFlags(parts, { count: 5, intervalMs: 250 });
267+
assert.deepEqual(parts, ['--count', '5', '--interval-ms', '250']);
268+
const recorded: Partial<ScreenshotRequestFlags> = {};
269+
assert.deepEqual(readScreenshotScriptFlag({ args: parts, index: 0, flags: recorded }), {
270+
handled: true,
271+
nextIndex: 1,
272+
});
273+
assert.deepEqual(readScreenshotScriptFlag({ args: parts, index: 2, flags: recorded }), {
274+
handled: true,
275+
nextIndex: 3,
276+
});
277+
assert.deepEqual(screenshotOptionsFromFlags(recorded), { count: 5, intervalMs: 250 });
278+
assert.throws(() => readScreenshotScriptFlag({ args: ['--count', '1'], index: 0, flags: {} }), {
279+
code: 'INVALID_ARGS',
280+
});
281+
assert.throws(
282+
() => readScreenshotScriptFlag({ args: ['--interval-ms', '50'], index: 0, flags: {} }),
283+
{ code: 'INVALID_ARGS' },
284+
);
285+
});

‎packages/command-surface/src/capture/screenshot.ts‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,15 @@ import type { CaptureScreenshotOptions } from '@agent-device/contracts/client';
33
import { SESSION_SURFACES } from '@agent-device/contracts/session';
44
import {
55
RETIRED_SCREENSHOT_MAX_SIZE,
6+
SCREENSHOT_BURST_LIMITS,
67
SCREENSHOT_CAPTURE_BACKENDS,
78
SCREENSHOT_COMMAND_FLAG_KEYS,
89
SCREENSHOT_SCALE_LIMITS,
910
SCREENSHOT_SCREEN_MASKS,
1011
screenshotFlagsFromPublicOptions,
1112
screenshotOptionsFromFlags,
1213
validateNoRetiredScreenshotMaxSize,
14+
validateScreenshotBurst,
1315
validateScreenshotScale,
1416
} from '@agent-device/contracts/capture';
1517
import {
@@ -55,6 +57,14 @@ const screenshotCommandMetadata = defineFieldCommandMetadata(
5557
SCREENSHOT_CAPTURE_BACKENDS,
5658
'Capture through the XCTest runner instead of the platform default, which leaves out the simulator-drawn Dynamic Island. Local Apple targets only; refused on provider sessions and on a macOS surface the helper captures, and with pixelDensity, screenMask or normalizeStatusBar.',
5759
),
60+
count: integerField(
61+
'Capture a burst of this many frames in one request; the command writes a <path>-0001 style sequence and reports every frame. Cannot be combined with cropOn or overlayRefs.',
62+
{ min: SCREENSHOT_BURST_LIMITS.minCount, max: SCREENSHOT_BURST_LIMITS.maxCount },
63+
),
64+
intervalMs: integerField(
65+
`Wait this many milliseconds between burst frames; requires count. Defaults to ${SCREENSHOT_BURST_LIMITS.defaultIntervalMs}.`,
66+
{ min: SCREENSHOT_BURST_LIMITS.minIntervalMs, max: SCREENSHOT_BURST_LIMITS.maxIntervalMs },
67+
),
5868
surface: enumField(SESSION_SURFACES),
5969
},
6070
);
@@ -73,6 +83,7 @@ export const screenshotCliReader: CliReader = (positionals, flags) => ({
7383
export const screenshotDaemonWriter: DaemonWriter = (input) => {
7484
validateNoRetiredScreenshotMaxSize('screenshot', input);
7585
validateScreenshotScale(input as CaptureScreenshotOptions);
86+
validateScreenshotBurst(input as CaptureScreenshotOptions);
7687
return request(PUBLIC_COMMANDS.screenshot, optionalString(input.path), {
7788
...input,
7889
...screenshotFlagsFromPublicOptions(input as CaptureScreenshotOptions),
@@ -84,7 +95,7 @@ export const screenshotCommandFacet = defineCommandFacet({
8495
text: {
8596
summary: 'Capture a screenshot',
8697
cliDetail:
87-
"Web defaults to the viewport; use --fullscreen, --full, or -f for the entire page. iOS simulators default to 1x logical-point output; use --pixel-density to request a different screenshot density. Use --screen-mask black to fill the iOS simulator screen outline, including rounded corners, with black for this capture. It requires simctl: physical devices, tvOS and visionOS simulators, other platforms, provider captures and XCTest runner captures are refused. A masked capture fails if simctl fails instead of falling back to an unmasked runner capture. macOS app sessions default to the app window; use --fullscreen for full desktop, --scale to downscale, --crop-on <selector> to crop the capture to the frame the selector resolves on the same screen (currently iOS simulators, Android emulators, and CoreDevice physical iPhones), --overlay-refs to annotate current refs, --normalize-status-bar for deterministic iOS simulator or Android chrome. Physical iPhone crop verification covers portrait CoreDevice/devicectl captures only. XCTest, runner fallback, and physical iPad crops are refused; landscape iPhone crop is unverified. Android captures immediately by default; --normalize-status-bar also waits for transient UI to fade, and --no-stabilize keeps capture immediate. With the native macOS backend, the front window is the app's frontmost visible, nonempty normal-level (layer-0) window on the current Space: floating palettes and app-modal alerts at window level 8 are skipped, and a sheet is captured as its own window. On macOS, any --surface other than app (desktop, menubar, frontmost-app) always captures the main display and refuses an explicit --fullscreen. On single-display iOS simulators and Android devices, the result reports displayRotation, the rotation the display rendered the capture in, when the device returns a reading in time; otherwise the field is absent. On iOS simulators a screenshot waits for that simulator's status bar to be free, and a request its caller cancelled while it waits reports the cancellation instead of capturing.",
98+
"Web defaults to the viewport; use --fullscreen, --full, or -f for the entire page. iOS simulators default to 1x logical-point output; use --pixel-density to request a different screenshot density. Use --screen-mask black to fill the iOS simulator screen outline, including rounded corners, with black for this capture. It requires simctl: physical devices, tvOS and visionOS simulators, other platforms, provider captures and XCTest runner captures are refused. A masked capture fails if simctl fails instead of falling back to an unmasked runner capture. macOS app sessions default to the app window; use --fullscreen for full desktop, --scale to downscale, --crop-on <selector> to crop the capture to the frame the selector resolves on the same screen (currently iOS simulators, Android emulators, and CoreDevice physical iPhones), --overlay-refs to annotate current refs, --normalize-status-bar for deterministic iOS simulator or Android chrome. Physical iPhone crop verification covers portrait CoreDevice/devicectl captures only. XCTest, runner fallback, and physical iPad crops are refused; landscape iPhone crop is unverified. Android captures immediately by default; --normalize-status-bar also waits for transient UI to fade, and --no-stabilize keeps capture immediate. Use --count with --interval-ms to capture an animation burst in one request. The daemon captures frames sequentially and writes each frame as a numbered file beside the --out path, for example page-0001.png, and the result reports every frame path and capture time. A burst refuses --crop-on and --overlay-refs, because a crop binds one snapshot and overlay refs annotate one frame. Keep --count times --interval-ms within 30 seconds, because the frames must finish inside the request timeout. When --count is present without --interval-ms, the daemon waits 100ms between frames. With the native macOS backend, the front window is the app's frontmost visible, nonempty normal-level (layer-0) window on the current Space: floating palettes and app-modal alerts at window level 8 are skipped, and a sheet is captured as its own window. On macOS, any --surface other than app (desktop, menubar, frontmost-app) always captures the main display and refuses an explicit --fullscreen. On single-display iOS simulators and Android devices, the result reports displayRotation, the rotation the display rendered the capture in, when the device returns a reading in time; otherwise the field is absent. On iOS simulators a screenshot waits for that simulator's status bar to be free, and a request its caller cancelled while it waits reports the cancellation instead of capturing.",
8899
},
89100
metadata: screenshotCommandMetadata,
90101
run: (client, input) => client.capture.screenshot(input),

‎packages/contracts/src/client-capture.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,14 @@ export type CaptureScreenshotOptions = AgentDeviceRequestOverrides & {
121121
/** `runner`: capture an Apple target through the XCTest runner instead of `simctl`. */
122122
captureBackend?: ScreenshotCaptureBackend;
123123
surface?: SessionSurface;
124+
/**
125+
* Capture a burst of this many frames in one request; the daemon writes them as a
126+
* `<path>-0001` style sequence and reports each frame in `frames`. Cannot be combined
127+
* with `cropOn` or `overlayRefs`. See `SCREENSHOT_BURST_LIMITS` for the bounds.
128+
*/
129+
count?: number;
130+
/** Wait this many milliseconds between burst frames; requires `count`. */
131+
intervalMs?: number;
124132
};
125133

126134
export type CaptureScreenshotResult = ScreenshotResultData & {

‎packages/contracts/src/facades/capture.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ export type { DiffSnapshotCommandResult, SnapshotDiffLine, SnapshotDiffSummary }
22
export {
33
RETIRED_SCREENSHOT_MAX_SIZE,
44
SCREENSHOT_ACTION_FLAG_KEYS,
5+
SCREENSHOT_BURST_LIMITS,
56
SCREENSHOT_CAPTURE_BACKENDS,
67
SCREENSHOT_COMMAND_FLAG_KEYS,
78
SCREENSHOT_CROP_REASONS,
@@ -13,13 +14,16 @@ export {
1314
appendScreenshotScriptFlags,
1415
readScreenshotScriptFlag,
1516
retiredScreenshotMaxSizeFlagError,
17+
screenshotBurstFramePath,
1618
screenshotFlagsFromOptions,
1719
screenshotFlagsFromPublicOptions,
1820
screenshotOptionsFromFlags,
1921
validateNoRetiredScreenshotMaxSize,
22+
validateScreenshotBurst,
2023
validateScreenshotScale,
2124
} from '../screenshot.ts';
2225
export type {
26+
ScreenshotBurstFrame,
2327
ScreenshotCaptureBackend,
2428
ScreenshotCropReason,
2529
ScreenshotScreenMask,

0 commit comments

Comments
 (0)