feat: add scale-only screenshot sizing (#1617)

* feat: add scale-only screenshot sizing

* fix: refuse retired --max-size inputs on every released surface

Released sizing inputs must fail closed with migration guidance instead of
silently producing native-size artifacts:

- contracts: RETIRED_SCREENSHOT_MAX_SIZE declaration + SCREENSHOT_SCALE_LIMITS
  as the single source for the scale bounds and migration messages
- .ad parser: released 'screenshot ... --max-size N' and 'record start ...
  --max-size N' lines now refuse at parse time (frozen replay-compat witnesses)
- daemon: screenshot rejects old-client screenshotMaxSize like recording does;
  the recording guard now shares the same contract data
- Node client: screenshot/record daemon writers refuse the removed { maxSize }
  option before transport
- CLI: --max-size unknown-flag error carries the migration guidance
- config/env: stale screenshotMaxSize config keys and the retired
  AGENT_DEVICE_SCREENSHOT_MAX_SIZE env var are refused for sizing commands
  (other commands keep working)

Quality: numberField now reuses the canonical readOptionalNumber contract
helper (AppError bounds instead of plain Error); png-resize inlines one-use
wrappers and restores the worker-thread rationale; docs typo fixed.

* test: drop retired maxSize entries from the MCP undocumented-input allowlist

* fix: refuse retired maxSize at the MCP field-projection seam + release-provenance corpus witnesses

- readFieldInput silently dropped undeclared keys before the daemon writers
  could refuse them, so an MCP call carrying { maxSize } reached transport and
  returned native-size success. New retiredField() combinator declares the
  removed key in the field map: the projection seam refuses it with the
  canonical migration message and the JSON schema no longer advertises it.
  Real-route MCP executor regressions cover screenshot and record.
- replay-compat corpus: derived v0.20.5 witnesses for the released screenshot
  and record --max-size forms (SHA-256 pinned, new retired-capture-size
  coverage surface) so check:replay-compat proves the shipped syntax refuses
  with migration guidance instead of degrading silently.

---------

Co-authored-by: Michał Pierzchała <thymikee@gmail.com>

Author: szdziedzic

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift

@@ -1506,24 +1506,18 @@ extension RunnerTests {
       if let requestedFps = command.fps, (requestedFps < minRecordingFps || requestedFps > maxRecordingFps) {
         return Response(ok: false, error: ErrorPayload(message: "recordStart fps must be between \(minRecordingFps) and \(maxRecordingFps)"))
       }
-      if let requestedMaxSize = command.maxSize, requestedMaxSize < 1 {
-        return Response(ok: false, error: ErrorPayload(message: "recordStart maxSize must be a positive integer"))
-      }
       do {
         let resolvedOutPath = resolveRecordingOutPath(requestedOutPath)
         let fpsLabel = command.fps.map(String.init) ?? String(RunnerTests.defaultRecordingFps)
-        let maxSizeLabel = command.maxSize.map(String.init) ?? "native"
         NSLog(
-          "AGENT_DEVICE_RUNNER_RECORD_START requestedOutPath=%@ resolvedOutPath=%@ fps=%@ maxSize=%@",
+          "AGENT_DEVICE_RUNNER_RECORD_START requestedOutPath=%@ resolvedOutPath=%@ fps=%@",
           requestedOutPath,
           resolvedOutPath,
-          fpsLabel,
-          maxSizeLabel
+          fpsLabel
         )
         let recorder = ScreenRecorder(
           outputPath: resolvedOutPath,
-          fps: command.fps.map { Int32($0) },
-          maxSize: command.maxSize
+          fps: command.fps.map { Int32($0) }
         )
         try recorder.start { [weak self] in
           return self?.captureRunnerFrame()

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift

@@ -136,7 +136,6 @@ struct Command: Codable {
   let gesturePlan: RunnerGesturePlan?
   let outPath: String?
   let fps: Int?
-  let maxSize: Int?
   let interactiveOnly: Bool?
   let preferredBackend: String?
   let depth: Int?

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift

@@ -7,7 +7,6 @@ extension RunnerTests {
   final class ScreenRecorder {
     private let outputPath: String
     private let fps: Int32?
-    private let maxSize: Int?
     private var effectiveFps: Int32 {
       max(1, fps ?? RunnerTests.defaultRecordingFps)
     }
@@ -26,10 +25,9 @@ extension RunnerTests {
     private var startedSession = false
     private var startError: Error?
 
-    init(outputPath: String, fps: Int32?, maxSize: Int?) {
+    init(outputPath: String, fps: Int32?) {
       self.outputPath = outputPath
       self.fps = fps
-      self.maxSize = maxSize
     }
 
     func start(captureFrame: @escaping () -> RunnerImage?) throws {
@@ -50,7 +48,7 @@ extension RunnerTests {
       while Date() < bootstrapDeadline {
         if let image = captureFrame(), let cgImage = runnerCGImage(from: image) {
           bootstrapImage = image
-          dimensions = scaledDimensions(width: cgImage.width, height: cgImage.height)
+          dimensions = CGSize(width: cgImage.width, height: cgImage.height)
           break
         }
         Thread.sleep(forTimeInterval: 0.05)
@@ -261,23 +259,5 @@ extension RunnerTests {
       return pixelBuffer
     }
 
-    private func scaledDimensions(width: Int, height: Int) -> CGSize {
-      guard let maxSize, maxSize > 0 else {
-        return CGSize(width: width, height: height)
-      }
-      let longest = max(width, height)
-      guard longest > maxSize else {
-        return CGSize(width: width, height: height)
-      }
-      let scale = Double(maxSize) / Double(longest)
-      return CGSize(
-        width: scaledEvenDimension(width, scale: scale),
-        height: scaledEvenDimension(height, scale: scale)
-      )
-    }
-
-    private func scaledEvenDimension(_ value: Int, scale: Double) -> Int {
-      max(2, Int((Double(value) * scale / 2.0).rounded()) * 2)
-    }
   }
 }

apple/runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift

@@ -32,7 +32,7 @@ Examples:
 ```
 
 ```json
-{ "command": "recordStart", "outPath": "/tmp/demo.mp4", "fps": 30, "maxSize": 720 }
+{ "command": "recordStart", "outPath": "/tmp/demo.mp4", "fps": 30 }
 ```
 
 ```json

apple/runner/RUNNER_PROTOCOL.md

@@ -50,18 +50,35 @@ test('formatPortableActionLine preserves inline open runtime hints', () => {
   );
 });
 
-test('record replay script parses fps, max-size, quality, and hide-touches flags', () => {
-  const script =
-    'record start "./capture.mp4" --fps 24 --max-size 1024 --quality high --hide-touches\n';
+test('record replay script parses fps, quality, and hide-touches flags', () => {
+  const script = 'record start "./capture.mp4" --fps 24 --quality high --hide-touches\n';
   const parsed = parseReplayScriptDetailed(script).actions;
 
   assert.deepEqual(parsed[0]?.positionals, ['start', './capture.mp4']);
   assert.equal(parsed[0]?.flags.fps, 24);
-  assert.equal(parsed[0]?.flags.screenshotMaxSize, 1024);
   assert.equal(parsed[0]?.flags.quality, 'high');
   assert.equal(parsed[0]?.flags.hideTouches, true);
 });
 
+// Parser-level witnesses of the retired `--max-size` refusal. The
+// release-provenance frozen forms live in the replay-compat corpus
+// (test/replay-compat/scripts/docs/{screenshot,record}-max-size.v0.20.5.ad);
+// these fast unit copies pin the same behavior at the parse seam: refusal
+// with migration guidance, never a silent degrade into extra positionals.
+test('released screenshot --max-size lines are refused with migration guidance', () => {
+  assert.throws(() => parseReplayScriptDetailed('screenshot "./page.png" --max-size 1024\n'), {
+    code: 'INVALID_ARGS',
+    message: /screenshot --max-size was removed; use --scale/,
+  });
+});
+
+test('released record --max-size lines are refused with migration guidance', () => {
+  assert.throws(() => parseReplayScriptDetailed('record start "./capture.mp4" --max-size 1024\n'), {
+    code: 'INVALID_ARGS',
+    message: /record --max-size was removed/,
+  });
+});
+
 test('screenshot replay script round-trips screenshot flags', () => {
   const actions: SessionAction[] = [
     {
@@ -71,7 +88,7 @@ test('screenshot replay script round-trips screenshot flags', () => {
       flags: {
         screenshotPixelDensity: 2,
         screenshotFullscreen: true,
-        screenshotMaxSize: 1024,
+        screenshotScale: 0.3,
         screenshotNoStabilize: true,
       },
     },
@@ -80,14 +97,14 @@ test('screenshot replay script round-trips screenshot flags', () => {
   const script = formatReplayScriptForTest(actions);
   assert.match(
     script,
-    /screenshot "\.\/page\.png" --pixel-density 2 --fullscreen --max-size 1024 --no-stabilize/,
+    /screenshot "\.\/page\.png" --pixel-density 2 --fullscreen --scale 0.3 --no-stabilize/,
   );
 
   const parsed = parseReplayScriptDetailed(script).actions;
   assert.deepEqual(parsed[0]?.positionals, ['./page.png']);
   assert.equal(parsed[0]?.flags.screenshotPixelDensity, 2);
   assert.equal(parsed[0]?.flags.screenshotFullscreen, true);
-  assert.equal(parsed[0]?.flags.screenshotMaxSize, 1024);
+  assert.equal(parsed[0]?.flags.screenshotScale, 0.3);
   assert.equal(parsed[0]?.flags.screenshotNoStabilize, true);
 });
 

packages/ad-script/src/internal/__tests__/script.test.ts

@@ -202,9 +202,6 @@ export function appendRecordActionScriptArgs(parts: string[], action: SessionAct
   if (typeof action.flags?.fps === 'number') {
     parts.push('--fps', String(action.flags.fps));
   }
-  if (typeof action.flags?.screenshotMaxSize === 'number') {
-    parts.push('--max-size', String(action.flags.screenshotMaxSize));
-  }
   if (typeof action.flags?.quality === 'number' || typeof action.flags?.quality === 'string') {
     parts.push('--quality', String(action.flags.quality));
   }