feat: add screencast fps option

[mturac]

Addresses #2291.

Summary

• add an --experimental-screencast-fps option for screencast recording
• validate the value as a positive integer and imply --experimental-screencast
• pass the configured FPS through to Puppeteer's screencast() call
• update generated option docs and flag telemetry metadata

Testing

• git diff --check origin/main...HEAD
• npm run check-format
• npm run typecheck
• npm test -- --test-only tests/tools/screencast.test.ts tests/cli.test.ts

[mturac]

Validation refreshed on the current head:

git diff --check origin/main...HEAD
npm run test -- tests/tools/screencast.test.ts tests/cli.test.ts
npm run check-format

All three passed locally.

[mturac]

Rebased this branch onto the current main and re-ran validation.

Validation:

• git diff --check origin/main...HEAD
• npm run test -- tests/tools/screencast.test.ts tests/cli.test.ts
• npm run check-format

[nattallius]

Thanks for your pr! Since the direction for the linked issue #2291 hasn't been fully confirmed yet, let's hold off on merging or closing it for now. We can keep this on hold until we get definitive confirmation on the final direction

[AuraquanTech]

I ran the measurement from my #2291 comment against this PR's current branch directly, using the built MCP server rather than calling Puppeteer on its own.

The server was driven through the MCP path from new_page to the aquarium demo and then screencast_start and screencast_stop, at 1920×1080 in headless mode. Memory was sampled inside the server process every 10 seconds after forced GC. Completed recordings were checked with ffprobe to confirm that they ran at the requested frame rate.

In one sweep, the observed post-GC RSS growth was approximately:

Requested FPS	Observed RSS growth
10	2.5 MB/min, with no sustained accumulation during the 10 minute window
15	0.9 MB/min, with no sustained accumulation during the 10 minute window
20	15.5 MB/min
30	615.6 MB/min, linear, reaching approximately 3.96 GB when the run was stopped externally after 5.8 minutes

The growth was again concentrated in external and arrayBuffers, while the V8 heap remained approximately flat.

Under this machine and workload, the observed crossover was between 15 and 20 FPS. More importantly for this PR, --experimental-screencast-fps is correctly passed through the real MCP tool path, the generated recordings use the requested rate, and selecting 10 or 15 FPS prevented the severe accumulation seen at 30 FPS during the measured window.

Happy to repeat the measurement against a revised implementation or run additional durations if useful.

Ayrton R. Goodman