feat: unicode support, recording fixes, screenshot improvements, device rotation & docs

[saen-ai]

Overview

A batch of fixes and features from real-world usage. Each change addresses an open issue.

---

Changes

fix: security & stability improvements

• record_video now routes through getBootedDeviceId() instead of hardcoded "booted" — fixes multi-simulator setups
• ui_view JSON.parse wrapped in try/catch with dimension validation
• Temp files cleaned immediately after use with random suffixes to prevent collisions
• record_video improved with exit listener + resolved state tracking to catch silent failures

feat: ui_paste — Unicode and emoji text input

idb ui text can't handle emoji or non-ASCII characters (no keycodes exist). The new ui_paste tool injects text via the system clipboard (pbcopy → pbsync → long-press → Paste), enabling full Unicode support including emoji, CJK, Arabic, and RTL text.

feat: terminate_app, open_url, list_apps

Standard simctl wrappers that were missing from the toolset.

fix: AZERTY keyboard layout (ui_type)

idb ui text sends QWERTY keycodes that get remapped by the simulator's keyboard layout, breaking input on AZERTY/QWERTZ systems. Rewrote ui_type to use the same clipboard injection as ui_paste, with auto-detection of the focused AXTextField/AXTextArea.

feat: screenshot — max_size and force params (fixes #42, fixes #19)

• max_size: resizes proportionally via sips when the image exceeds the given pixel dimension — solves the Claude 2000px API limit
• force: prevents silent overwrites by erroring when the output file already exists

fix: recording PID tracking (fixes #20)

stop_recording previously used pkill -f simctl.*recordVideo which killed every recording process on the machine. Now tracks each ChildProcess in a Map<udid, ChildProcess> and kills by specific PID. Falls back to pkill if no tracked process is found.

feat: record_video — timeout param (fixes #5)

Optional timeout (1–3600s) auto-stops recording after the given duration using the same targeted PID kill. No need for a separate stop_recording call.

feat: rotate_device (contributes to #49)

Rotates the simulator left/right via osascript keyboard shortcuts (Cmd+Left / Cmd+Right). Supports optional times (1–3) for multi-increment rotations in one call.

docs: rewrite use cases section (fixes #40)

Replaced the generic prompt list with five real developer workflows: bug repro recording, post-implementation validation, React Native Redbox debugging, Unicode text testing, and landscape/portrait layout checks. Also added missing tool entries for all new tools.

---

Issues addressed

Fixes #5, Fixes #19, Fixes #20, Fixes #40, Fixes #42, Contributes to #49

[saen-ai]

Update: Three more tools have been added to this branch since the original description:

• push_notification — send simulated APNs push notifications via xcrun simctl push
• set_permission — grant/revoke/reset any iOS privacy permission via xcrun simctl privacy (covers notifications, photos, microphone, location, etc.)
• get_clipboard — read the simulator clipboard via xcrun simctl pbpaste (useful for testing copy behaviour in apps)

These are covered individually in PR #69 if you prefer to review them separately.

[joshuayoes]

Closing this in favor of the individual PRs I'm already reviewing (#60, #61, #63, #64, #65, #66, #67). Details below.

Why the bundled PR won't merge as-is

This branch is saen-ai:main → joshuayoes:main — your fork's main is being used as a feature branch. Three problems with that:

1. Review surface. 1117 additions covering 9 distinct changes (unicode input, three simctl wrappers, screenshot params, recording fixes, recording timeout, rotation, docs, plus three more tools in commit 8109dd2f) can't be reviewed as one unit against the "keep it simple / real use cases only" principle in CLAUDE.md. The individual PRs you've already opened are the right shape — I've left actionable feedback on each.

2. Conflict with main. Merging would overwrite joshuayoes:main with your fork's divergent history, including commits that have already squash-merged (e.g. fa6f816e is now on main as fix: record_video ignores udid, ui_view JSON crash, temp file leaks, dep CVEs #59's merge commit). This is marked CONFLICTING by GitHub for exactly that reason.

3. Future hygiene. Using your fork's main as a branch makes subsequent contributions awkward — every new PR will drag stale history along. Recommend resetting your fork's main to match upstream:

   git fetch upstream
   git checkout main
   git reset --hard upstream/main
   git push --force-with-lease origin main
   

   Then branch fresh per PR: git checkout -b feat/some-thing upstream/main.

Next actions

• This PR and feat: add push_notification, set_permission, and get_clipboard tools #69 (which is the same saen-ai:main branch submitted twice — note the identical +1117/-132 stats and shared head commit 8109dd2f) will both be closed.
• Continue the review on each individual PR (feat: add ui_paste tool for emoji and Unicode text input #60, feat: add terminate_app, open_url, and list_apps tools #61, feat: add max_size and force params to screenshot tool #63, fix: track recording process by UDID for targeted stop #64, feat: add timeout param to record_video for auto-stop #65, feat: add rotate_device tool for simulator orientation control #66, docs: rewrite use cases section with real developer workflows #67) — I've left specific feedback on all of them.
• For the three new tools in the final commit (push_notification, set_permission, get_clipboard from 8109dd2f): please open a fresh PR from a clean topic branch cherry-picked off upstream/main. These three are independent of the others and look well-scoped — I'd like to review them on their own.

Thanks for the work — closing here, but actively working through the individual PRs.