diff --git a/docs/astro.config.ts b/docs/astro.config.ts index 08af4564..1aa43f0d 100644 --- a/docs/astro.config.ts +++ b/docs/astro.config.ts @@ -77,7 +77,7 @@ export default defineConfig({ starlightLlmsTxt({ projectName: "RocketSim", description: - "RocketSim enhances the iOS Simulator with features for capturing screenshots and recordings, comparing designs, testing push notifications, deep links, location simulation, network speed control, accessibility toggles, and more.", + "RocketSim enhances iOS Simulator and physical-device development with screenshots and recordings, design comparison, agentic development through the RocketSim CLI and Agent Skill, push notification testing, deep links, location simulation, network tools, accessibility workflows, and more.", rawContent: true, }), ], @@ -150,6 +150,10 @@ export default defineConfig({ label: "Status Bar", link: "/docs/features/capturing/statusbar-appearance", }, + { + label: "Physical Devices", + link: "/docs/features/capturing/physical-device-support", + }, { label: "Design Comparison", collapsed: true, diff --git a/docs/src/content/docs/docs/features/agentic-development/agent-skill.md b/docs/src/content/docs/docs/features/agentic-development/agent-skill.md index 71213c4f..f0d57c06 100644 --- a/docs/src/content/docs/docs/features/agentic-development/agent-skill.md +++ b/docs/src/content/docs/docs/features/agentic-development/agent-skill.md @@ -1,67 +1,75 @@ --- title: "Agent Skill" -description: "Install the RocketSim Agent Skill to give AI coding tools a reliable, version-matched way to inspect and interact with iOS Simulator apps through RocketSim." +description: "Install RocketSim's bundled Agent Skill so AI coding tools can use the version-matched RocketSim CLI safely and reliably." sidebar: order: 3 --- -The RocketSim Agent Skill is the only part you need to install. Once installed, it automatically detects the RocketSim version on your machine, connects your agent to RocketSim's built-in interaction layer, and enables reliable Simulator automation through the RocketSim CLI. +The RocketSim Agent Skill is the recommended way to connect AI coding tools to RocketSim. It teaches your agent how to use the version-matched `rocketsim` CLI, when to read elements, when to interact, how to recover after screen changes, and when to use a screenshot fallback. -## What you install +Install it from **RocketSim → Settings → CLI & Agent**. -The RocketSim Agent Skill is a lightweight, installable skill that lives in its own repository: +## Why the skill is recommended -- [RocketSim-Agent-Skill](https://github.com/AvdLee/RocketSim-Agent-Skill) +You can run the CLI yourself, but agents perform best when they have clear, tool-specific instructions. The RocketSim Agent Skill provides those instructions without requiring you to copy prompts into every project. -It supports popular AI coding tools like Claude Code, Cursor, and Codex. The easiest way to install is through [skills.sh](https://skills.sh): +The skill helps agents: -```bash -npx skills add https://github.com/AvdLee/RocketSim-Agent-Skill --skill rocketsim -``` +- Use RocketSim's compact `--agent` output before deciding what to do +- Prefer semantic interactions over fragile coordinate taps when possible +- Work with RocketSim's `rs/1` agent protocol without needing to know its internals +- Recover when a screen changes between inspection and interaction +- Use screenshots when accessibility data is sparse or incomplete +- Run `rocketsim doctor` when setup needs to be checked -For more installation options, see the [RocketSim-Agent-Skill README](https://github.com/AvdLee/RocketSim-Agent-Skill). +In our internal research, RocketSim's CLI completed the same agent workflows about **19% faster, avoided wrong taps entirely**, and used about **63% fewer estimated tokens** than a popular alternative. -## What happens after installation +## Install from RocketSim -When an agent triggers the RocketSim skill, the following happens automatically: +1. Open **RocketSim → Settings → CLI & Agent** +2. Install the **Command Line Tool** if `rocketsim` is not on your `PATH` yet +3. In **Agent Skill**, choose **General Agents** +4. Click **Install** or **Repair** +5. Restart or refresh your AI coding tool if it does not discover new skills automatically -1. The skill finds a valid RocketSim installation on your machine -2. It validates that RocketSim includes the built-in skill and CLI -3. It hands off to the built-in skill, which contains the version-matched CLI reference -4. The agent can now inspect visible elements and interact with the Simulator +RocketSim installs the skill as a symlink to the bundled skill inside `RocketSim.app`. When RocketSim updates, the skill keeps pointing at the latest installed app version. -You do not need to configure anything beyond the initial install. The handoff is seamless. +![CLI & Agent settings showing Agent Skill installation options](./agent-skill/cli-agent-settings.png) -## Why the built-in skill updates automatically +## Supported destinations -RocketSim ships a built-in skill alongside its CLI inside the app. Every time RocketSim updates, the built-in skill updates with it. That means the CLI reference your agent uses is always accurate for the RocketSim version you have installed. +We recommend **General Agents** for most setups. It installs the skill into the shared `.agents/skills` location, so multiple AI coding tools can use the same version-matched RocketSim skill instead of each tool needing its own copy. -This is the key advantage of the two-layer architecture: +Use a tool-specific destination like **Cursor**, **Claude**, or **Codex** if that tool only scans its own skill folder. You can also choose a custom skill folder if your tool stores skills somewhere else. -- **The public skill** (what you install) stays small, stable, and rarely changes -- **The built-in skill** (inside RocketSim) stays version-matched and ships with every update +If RocketSim shows **Repair**, the existing symlink points somewhere unexpected or the app has moved. Repairing updates the symlink to the current RocketSim app. -You get a simple installation experience and version-matched accuracy without maintaining anything yourself. +## Why it stays up to date -## You only install the public skill +RocketSim ships the CLI and Agent Skill inside the app bundle. The installed files are symlinks, not copied snapshots. That matters because the CLI surface and skill instructions evolve together. -The built-in skill is not something you install separately. It is part of the RocketSim app and is read automatically by the public skill during handoff. - -If you see references to a "bundled skill" or "built-in skill" in other documentation, that is the version-matched layer inside RocketSim that the public skill connects to. You do not need to interact with it directly. +After an App Store update, your `rocketsim` command and installed skill still resolve to the current app bundle. Agents get the guidance that matches the RocketSim version they are controlling. ## What the agent can do after setup Once the skill is installed and RocketSim is running, your agent can: -- Read visible accessibility elements before interacting +- Read visible accessibility elements, including navigation and tab bar items - Tap, long-press, swipe, and type using labels or coordinates - Press simulator hardware buttons like Home, Lock, or Siri - Navigate multi-step app flows with fewer retries -- Use compact `--agent` output to spend fewer tokens per screen read +- Use compact screen summaries to spend fewer tokens per screen read +- Capture a screenshot when visual context is needed ## How to verify it works -Open an agent and try: +First, check your setup: + +```bash +rocketsim doctor +``` + +Then open your AI coding tool and try: > Use RocketSim to navigate through `` in the Simulator @@ -71,3 +79,4 @@ If the skill is installed and RocketSim is running, the agent should detect Rock - [RocketSim CLI](/docs/features/agentic-development/rocketsim-cli) -- the commands agents use to inspect and interact with the Simulator - [Agentic Development with RocketSim](/docs/features/agentic-development/) -- scenarios, example prompts, and why RocketSim is effective for agent-driven Simulator automation +- [CLI & Agent settings](/docs/settings/cli-and-agent) -- installing and repairing the CLI and skill diff --git a/docs/src/content/docs/docs/features/agentic-development/agent-skill/cli-agent-settings.png b/docs/src/content/docs/docs/features/agentic-development/agent-skill/cli-agent-settings.png new file mode 100644 index 00000000..1b69a5b9 Binary files /dev/null and b/docs/src/content/docs/docs/features/agentic-development/agent-skill/cli-agent-settings.png differ diff --git a/docs/src/content/docs/docs/features/agentic-development/index.md b/docs/src/content/docs/docs/features/agentic-development/index.md index fa267177..c0a9cd8c 100644 --- a/docs/src/content/docs/docs/features/agentic-development/index.md +++ b/docs/src/content/docs/docs/features/agentic-development/index.md @@ -1,18 +1,19 @@ --- title: "Agentic Development with RocketSim" -description: "Let AI coding agents see and interact with your running iOS Simulator app. Automate repetitive flows, validate UI states, and navigate faster without re-describing the screen on every step." +description: "Let AI coding agents see and interact with your running iOS Simulator app through RocketSim's version-matched CLI and Agent Skill." sidebar: order: 1 --- -RocketSim helps AI coding agents see and interact with your running Simulator app. That makes it possible to automate repetitive flows, validate UI states, and move through app navigation faster without re-describing the screen on every step. +RocketSim helps AI coding agents see and interact with your running Simulator app. The RocketSim Mac app stays connected to the Simulator, keeps useful state warm, and exposes a compact CLI that agents can use to inspect screens, tap controls, type text, and verify UI changes. -With the RocketSim Agent Skill installed and RocketSim running, your agent can: +With the RocketSim Agent Skill installed from **Settings → CLI & Agent**, your agent can: -- Read visible accessibility elements before deciding what to do +- Read visible accessibility elements, including common navigation and tab bar items - Tap, swipe, type, and navigate through your app reliably -- Stay in a tight interaction loop without losing context between steps -- Spend fewer tokens by using RocketSim's compact screen summaries +- Stay in a tight interaction loop without rebuilding context between steps +- Use compact screen summaries to spend fewer tokens per UI read +- Fall back to screenshots when accessibility data is not enough ## What you can do with it @@ -44,6 +45,8 @@ Try these with any AI coding tool that has the RocketSim Agent Skill installed: > Use RocketSim to inspect the visible elements on screen and tap the primary CTA +> Use RocketSim to take a screenshot if the accessibility snapshot does not expose the web content clearly + > Use RocketSim to navigate to settings and toggle the feature flag for dark mode > Use RocketSim to reproduce the crash described in this issue by navigating to the affected screen @@ -54,31 +57,38 @@ Try these with any AI coding tool that has the RocketSim Agent Skill installed: ### Stateful by design -RocketSim runs continuously alongside the Simulator. It maintains a live connection, so agents work against the current app state rather than reconnecting from scratch on every command. That keeps interaction loops tight and reduces the amount of context agents need to rebuild between steps. +RocketSim runs continuously alongside the Simulator. Because there is already a Mac app watching the active device, RocketSim can reuse state, cache expensive work, and optimize repeated agent loops in ways one-off commands cannot. In our internal research, RocketSim's CLI completed the same agent workflows about **19% faster, avoided wrong taps entirely**, and used about **63% fewer estimated tokens** than a popular alternative. ### Compact screen summaries -RocketSim's `--agent` output format gives agents a focused, token-efficient snapshot of visible elements. Instead of processing a full JSON accessibility tree, agents get a compact pipe-delimited summary with just the element type, label, and coordinates they need to act. +RocketSim's `--agent` output format gives agents a focused, token-efficient snapshot of visible elements. Instead of processing a full JSON accessibility tree, agents get a compact summary with the element type, label, and coordinates they need to act. + +RocketSim also recovers many elements that are easy to miss in raw accessibility output, including top bars, navigation bars, tab bars, and visible controls that are needed to move through an app. ### Selector-based interaction Agents can target elements by label, type, or value instead of guessing coordinates. RocketSim uses semantic accessibility activation when possible, which is more reliable than coordinate-only approaches for buttons, toggles, and list rows. +### Agent-optimized protocol + +The CLI uses RocketSim's `rs/1` protocol for agent workflows. You do not need to learn the protocol details; the important part is that it is designed for compact, reliable interaction through the running RocketSim app. + ### Version-matched automation -RocketSim ships a built-in skill alongside its CLI. That means the interaction instructions agents receive always match the installed RocketSim version. When RocketSim updates, the built-in skill updates with it automatically. +RocketSim ships the CLI and Agent Skill inside the app. When RocketSim updates, the installed command and the skill instructions can update with it, so your agent keeps using guidance that matches the RocketSim version you have installed. ## How it works RocketSim's agentic development support has three layers: -1. **The RocketSim CLI** lets agents inspect visible elements and perform interactions through a stateful connection to the Simulator. -2. **The built-in skill** ships inside RocketSim and documents the exact CLI for that installed version, so agents always use version-matched guidance. -3. **The RocketSim Agent Skill** is the installable entry point that discovers RocketSim on your machine and hands off to the built-in layer automatically. +1. **The RocketSim Mac app** keeps the live Simulator connection, caches state, and performs the optimized work. +2. **The RocketSim CLI** exposes that running app to agents through commands such as `elements`, `interact`, `wait`, `screenshot`, and `doctor`. +3. **The RocketSim Agent Skill** teaches your AI coding tool how to use the CLI safely and consistently. -You only install the public Agent Skill. RocketSim handles the rest. +Install both the command line tool and Agent Skill from **RocketSim → Settings → CLI & Agent**. RocketSim creates symlinks into your chosen folders, so the CLI and skill keep pointing at the latest installed app. ## Learn more - [RocketSim CLI](/docs/features/agentic-development/rocketsim-cli) -- how agents inspect and interact with the Simulator -- [Agent Skill](/docs/features/agentic-development/agent-skill) -- what to install and how the architecture works +- [Agent Skill](/docs/features/agentic-development/agent-skill) -- how to install the recommended agent workflow +- [CLI & Agent settings](/docs/settings/cli-and-agent) -- how to install the CLI and skill from RocketSim diff --git a/docs/src/content/docs/docs/features/agentic-development/rocketsim-cli.md b/docs/src/content/docs/docs/features/agentic-development/rocketsim-cli.md index 9bc4241f..921054fe 100644 --- a/docs/src/content/docs/docs/features/agentic-development/rocketsim-cli.md +++ b/docs/src/content/docs/docs/features/agentic-development/rocketsim-cli.md @@ -1,11 +1,26 @@ --- title: "RocketSim CLI" -description: "Inspect visible elements, navigate screens, and automate taps, swipes, typing, and hardware button presses through RocketSim's built-in CLI." +description: "Install and use RocketSim's built-in CLI to inspect visible elements, automate interactions, and give agents a fast path into your running Simulator." sidebar: order: 2 --- -RocketSim includes a built-in CLI that lets agents inspect visible UI and interact with the Simulator through a running RocketSim session. The CLI communicates with RocketSim over IPC, so interaction is fast and stateful. +RocketSim includes a built-in CLI that lets agents inspect visible UI and interact with the Simulator through the running RocketSim Mac app. The app stays connected to the Simulator, keeps useful state warm, and exposes a compact command line surface for agents and local automation. + +For agentic development, we recommend installing both the CLI and [RocketSim Agent Skill](/docs/features/agentic-development/agent-skill) from **RocketSim → Settings → CLI & Agent**. + +## Installing the CLI + +1. Open **RocketSim → Settings → CLI & Agent** +2. In **Command Line Tool**, click **Install Command Line Tool** +3. Choose the default selected folder if it is on your `PATH`, or pick another folder such as `/opt/homebrew/bin` or `/usr/local/bin` +4. Confirm the installation + +RocketSim creates a `rocketsim` symlink in that folder. The real executable stays inside `RocketSim.app`, so App Store updates keep the command up to date automatically. + +![CLI & Agent settings showing the command line tool installer](./rocketsim-cli/cli-agent-settings.png) + +This symlink setup is useful for both agents and CI scripts. Anything that runs `rocketsim` from `PATH` uses the same RocketSim version you have installed. ## The agent interaction loop @@ -18,10 +33,26 @@ The CLI gives agents a compact workflow: 5. Read the updated UI state 6. Repeat -That loop is fast because RocketSim is already connected to the Simulator. There is no reconnection overhead between steps. +That loop is fast because RocketSim is already connected to the Simulator. There is no reconnection overhead between steps, and the running app can cache and optimize work across repeated commands. + +## Why RocketSim is fast for agents + +RocketSim is not just a standalone command that starts from scratch every time. The CLI talks to the running Mac app, which can keep simulator state, reuse context between commands, and optimize repeated screen reads and interactions. + +The CLI uses RocketSim's `rs/1` protocol for agent workflows. You do not need to learn the protocol details; it is the compact, agent-optimized layer that lets RocketSim provide reliable screen reads, interaction feedback, and recovery paths while keeping output small. + +In our internal research, RocketSim's CLI completed the same agent workflows about **19% faster, avoided wrong taps entirely**, and used about **63% fewer estimated tokens** than a popular alternative. ## Key commands +### Doctor + +Checks whether the CLI install, RocketSim app, IPC connection, Simulator state, accessibility permission, and snapshot store are ready for agent workflows. + +```bash +rocketsim doctor +``` + ### Focused simulator Returns the currently focused simulator as JSON, including name, runtime, and UDID. @@ -40,6 +71,40 @@ rocketsim elements [--udid ] [--agent] The `--agent` flag is the recommended default for agent workflows. It returns a compact, pipe-delimited format that is easier and cheaper for agents to process. +RocketSim's element pipeline is designed for real app navigation. It can include visible controls from top bars, navigation bars, tab bars, and other chrome that agents often need to move through a flow. When web content or other complex views expose limited accessibility data, RocketSim can add recovery hints so the agent knows when to use visual context. + +### Screen summary and snapshots + +For agents that need a stable view of the current screen, RocketSim provides screen and snapshot commands: + +```bash +rocketsim screen +rocketsim snapshot +``` + +These commands are optimized for agent workflows and help agents reason about whether the screen changed after an interaction. + +### Screenshot fallback + +When accessibility data is not enough, agents can request a plain PNG screenshot: + +```bash +rocketsim screenshot > screen.png +``` + +This is useful for visual fallback flows, sparse web content, or debugging what the agent sees. + +### Waiting for UI changes + +Agents can wait for screen changes or elements before continuing: + +```bash +rocketsim wait screen-changed +rocketsim wait element --label "Continue" +``` + +This keeps agent flows from racing ahead before the app has finished navigating or rendering. + ### Interactions RocketSim supports the most common agent interactions through `rocketsim interact`: @@ -54,6 +119,8 @@ rocketsim interact type "hello@example.com" rocketsim interact button home ``` +`interact` is designed to work with fresh screen state. When an agent uses the Agent Skill, RocketSim can guide it toward safer command sequences and recovery paths if the screen changes between inspection and interaction. + ## Why `--agent` matters The `--agent` flag reduces the element output from full JSON to a compact pipe-delimited format. That means fewer tokens per screen read, faster agent decision loops, and easier recovery after each interaction. @@ -104,7 +171,7 @@ The agent format contains everything an agent typically needs to decide what to Use the full JSON output when you need extra metadata like `value`, `role`, or the full accessibility frame. -This structured output for agents works especially well with the [RocketSim Agent Skill](/docs/features/agentic-development/agent-skill), which connects your AI coding tool to the CLI automatically. We highly recommend using the Agent Skill instead of communicating directly with the CLI when doing agentic development. +This structured output for agents works especially well with the [RocketSim Agent Skill](/docs/features/agentic-development/agent-skill), which connects your AI coding tool to the CLI automatically. We highly recommend using the Agent Skill instead of asking an agent to invent CLI calls on its own. ## Selector-based interaction @@ -151,4 +218,5 @@ The CLI works when: - RocketSim is running - At least one iOS Simulator is booted +- The command line tool is installed from **Settings → CLI & Agent** - The [RocketSim Agent Skill](/docs/features/agentic-development/agent-skill) has been installed so agents can discover RocketSim automatically diff --git a/docs/src/content/docs/docs/features/agentic-development/rocketsim-cli/cli-agent-settings.png b/docs/src/content/docs/docs/features/agentic-development/rocketsim-cli/cli-agent-settings.png new file mode 100644 index 00000000..1b69a5b9 Binary files /dev/null and b/docs/src/content/docs/docs/features/agentic-development/rocketsim-cli/cli-agent-settings.png differ diff --git a/docs/src/content/docs/docs/features/capturing/physical-device-support.md b/docs/src/content/docs/docs/features/capturing/physical-device-support.md new file mode 100644 index 00000000..24042ed6 --- /dev/null +++ b/docs/src/content/docs/docs/features/capturing/physical-device-support.md @@ -0,0 +1,72 @@ +--- +title: "Physical Device Support" +description: "Use RocketSim with connected physical iOS devices for live previews, screenshots, recordings, and design comparison workflows." +sidebar: + order: 3 +--- + +RocketSim 16 adds first-class support for connected physical iOS devices. Plug in a supported iPhone over USB and RocketSim can show a live device preview window next to your Simulator workflows. + +Physical device support is useful when you need to validate behavior that is hard to trust in the Simulator, such as real-device rendering, performance, camera behavior, or device-specific capture output. + +![Physical iPhone preview window with RocketSim's side window attached](./physical-device-support/live-preview.png) + +## What you can do + +With a connected physical device, you can: + +- Capture screenshots from the device stream +- Capture GIFs +- Record videos with device audio +- Use comparing overlays, grids, and rulers on the physical device window + +RocketSim opens a live preview window for the device and attaches the side window automatically, so these workflows feel similar to working with the Simulator. + +Not every RocketSim feature supports physical devices yet. Simulator app actions, Network Monitoring, and environment toggles are still Simulator-only for now. We're hoping to add support for more physical-device workflows in the future. + +## Getting started + +1. Connect your iPhone to your Mac using USB +2. Open RocketSim +3. Wait for the physical device preview window to appear +4. Use the RocketSim side window next to the device window, just like you would with the Simulator + +If the device does not appear, open **RocketSim → Settings → Physical Devices** and make sure USB device support is enabled. + +![A network-discovered physical device asking to connect via USB](./physical-device-support/connect-via-usb.png) + +## Discovery and streaming + +RocketSim can discover devices that are paired with your Mac for development, including devices that are reachable on the local network. Network discovery helps RocketSim explain that a known device exists, but live streaming requires a USB cable. + +Connect the device with a cable to start the live preview and use physical-device screenshots, recordings, and design comparison tools. + +![Physical Devices settings with USB and network discovery options](./physical-device-support/physical-devices-settings.png) + +## Screenshots and recordings + +Physical-device screenshots and recordings use the device stream directly. That means you can capture what is happening on a real device while still using RocketSim's capture workflow. + +Recordings include audio from the device stream. If a device disconnects while recording, RocketSim treats the disconnect as a clean stop and keeps the footage captured up to that point. + +For capture options that also apply to Simulator recordings, see [Creating Recordings](/docs/features/capturing/recordings) and [Taking Screenshots](/docs/features/capturing/screenshots). + +## Design comparison + +The physical device window supports RocketSim's design comparison tools. You can use grids and rulers on top of the device preview to check spacing, alignment, and layout behavior on real hardware. + +![Grids and rulers over a physical device preview](./physical-device-support/design-comparison.png) + +See [Grids & Rulers](/docs/features/design-comparison/grids-and-rulers) for the shared comparison workflow. + +## Device windows + +Physical device windows use dark preview chrome and full-bleed device bezels so the device content stays visually focused. RocketSim also restores window positions and supports resizing from the visible device corners. + +USB discovery and reconnect handling are designed to recover from common attach, detach, and rediscovery transitions. If a device is temporarily unavailable, reconnect it over USB and let RocketSim refresh the preview. + +## Managing devices + +Use [Physical Devices settings](/docs/settings/physical-devices) to control whether RocketSim monitors USB devices, whether network-detected devices are shown, and which devices should be ignored. + +If there is a device you do not want RocketSim to manage, use the device window menu to ignore it. You can stop ignoring it later from Settings. diff --git a/docs/src/content/docs/docs/features/capturing/physical-device-support/connect-via-usb.png b/docs/src/content/docs/docs/features/capturing/physical-device-support/connect-via-usb.png new file mode 100644 index 00000000..63ef4580 Binary files /dev/null and b/docs/src/content/docs/docs/features/capturing/physical-device-support/connect-via-usb.png differ diff --git a/docs/src/content/docs/docs/features/capturing/physical-device-support/design-comparison.png b/docs/src/content/docs/docs/features/capturing/physical-device-support/design-comparison.png new file mode 100644 index 00000000..01d29dcf Binary files /dev/null and b/docs/src/content/docs/docs/features/capturing/physical-device-support/design-comparison.png differ diff --git a/docs/src/content/docs/docs/features/capturing/physical-device-support/live-preview.png b/docs/src/content/docs/docs/features/capturing/physical-device-support/live-preview.png new file mode 100644 index 00000000..cdab6db7 Binary files /dev/null and b/docs/src/content/docs/docs/features/capturing/physical-device-support/live-preview.png differ diff --git a/docs/src/content/docs/docs/features/capturing/physical-device-support/physical-devices-settings.png b/docs/src/content/docs/docs/features/capturing/physical-device-support/physical-devices-settings.png new file mode 100644 index 00000000..96ff74b2 Binary files /dev/null and b/docs/src/content/docs/docs/features/capturing/physical-device-support/physical-devices-settings.png differ diff --git a/docs/src/content/docs/docs/features/capturing/recordings.md b/docs/src/content/docs/docs/features/capturing/recordings.md index 515f2e47..e7ba7c62 100644 --- a/docs/src/content/docs/docs/features/capturing/recordings.md +++ b/docs/src/content/docs/docs/features/capturing/recordings.md @@ -1,17 +1,19 @@ --- title: "Creating Recordings" -description: "Record high-quality GIF and MP4 videos from the iOS Simulator with touch indicators, device bezels, audio narration, and custom backgrounds." +description: "Record high-quality GIF and MP4 videos from the iOS Simulator and connected physical devices with touch indicators, device bezels, audio, and custom backgrounds." sidebar: order: 2 --- -RocketSim lets you create GIF and MP4 recordings of the Xcode Simulator from the **Captures** tab in the side window. You can record with touches, audio, device bezels, and transparent or custom backgrounds. If you need recordings optimized for App Store Connect, see [App Store Connect Optimization](/docs/features/capturing/app-store-connect-optimization). +RocketSim lets you create GIF and MP4 recordings from the **Captures** tab in the side window. You can record the Xcode Simulator with touches, audio, device bezels, and transparent or custom backgrounds. If you need recordings optimized for App Store Connect, see [App Store Connect Optimization](/docs/features/capturing/app-store-connect-optimization). -For final tweaks after recording, RocketSim 15 also includes a built-in [Post Editor](/docs/features/capturing/post-editor) that lets you trim and restyle the exported result. +RocketSim 16 also supports video recordings from connected physical iOS devices, including audio from the device stream. See [Physical Device Support](/docs/features/capturing/physical-device-support) for setup and device-specific behavior. + +For final tweaks after recording, RocketSim includes a built-in [Post Editor](/docs/features/capturing/post-editor) that lets you trim and restyle the exported result. ## Creating a recording -1. Open the Simulator +1. Open the Simulator or connect a supported physical iOS device 2. Select the **Captures** tab inside the RocketSim Side Window 3. Click **GIF Record** or **MP4 Record** and perform your interactions @@ -45,6 +47,7 @@ When you use device bezels, you can turn on **Device shadow** to add a shadow be ### Audio - **Simulator audio** — Records only the audio that comes out of the Simulator (your app's sound). It does not record system audio or other apps. Enable it with **Record audio** in the Captures tab or **Record Simulator audio during recordings** in Settings → Captures. No custom drivers are required. +- **Physical device audio** — When recording a connected physical device, RocketSim records audio from the device stream. - **Microphone** — Optionally record from any system microphone (e.g. for voiceover). In the Captures tab, use the **Microphone** picker and choose **None** or a device. You can use Simulator audio and a microphone at the same time. ### Output ratio diff --git a/docs/src/content/docs/docs/features/capturing/screenshots.md b/docs/src/content/docs/docs/features/capturing/screenshots.md index f80d02fb..b910e257 100644 --- a/docs/src/content/docs/docs/features/capturing/screenshots.md +++ b/docs/src/content/docs/docs/features/capturing/screenshots.md @@ -1,17 +1,19 @@ --- title: "Taking Screenshots" -description: "Capture professional iOS Simulator screenshots with device bezels, custom backgrounds, and App Store Connect optimization. Drag and drop directly into App Store Connect." +description: "Capture professional iOS Simulator and physical-device screenshots with device bezels, custom backgrounds, and App Store Connect optimization." sidebar: order: 1 --- RocketSim lets you create screenshots from the **Captures** tab in the side window, with bezels, custom backgrounds (including transparent), and optional [App Store Connect optimization](/docs/features/capturing/app-store-connect-optimization). When optimized, you can drag screenshots directly into App Store Connect. -If you want to refine the final output after capture, RocketSim 15 also includes a built-in [Post Editor](/docs/features/capturing/post-editor) for screenshots and recordings. +If you want to refine the final output after capture, RocketSim includes a built-in [Post Editor](/docs/features/capturing/post-editor) for screenshots and recordings. + +RocketSim 16 also supports screenshots from connected physical iOS devices. See [Physical Device Support](/docs/features/capturing/physical-device-support) for setup and device-specific behavior. ## Creating a screenshot -1. Open the Simulator +1. Open the Simulator or connect a supported physical iOS device 2. Select the **Captures** tab inside the RocketSim Side Window 3. Click **JPEG Screenshot** (when App Preview Optimized is enabled) or **PNG Screenshot** diff --git a/docs/src/content/docs/docs/features/design-comparison/grids-and-rulers.md b/docs/src/content/docs/docs/features/design-comparison/grids-and-rulers.md index dcf8633d..fee4e97c 100644 --- a/docs/src/content/docs/docs/features/design-comparison/grids-and-rulers.md +++ b/docs/src/content/docs/docs/features/design-comparison/grids-and-rulers.md @@ -1,13 +1,15 @@ --- title: "Grids & Rulers" -description: "Add grid overlays and rulers to the iOS Simulator for precise layout alignment. Customize grid size, color, and spacing to match your design system." +description: "Add grid overlays and rulers to the iOS Simulator or a connected physical device for precise layout alignment." --- Aligning elements based on grids and rulers allows you to create a balanced design. +RocketSim 16 supports grids and rulers on both Simulator windows and connected physical-device preview windows, so you can inspect spacing on real hardware as well. + ## Showing the Grid -1. Open the Simulator +1. Open the Simulator or connect a supported physical iOS device 2. Select the comparing tab 3. Click on the Grid button: @@ -15,7 +17,7 @@ Aligning elements based on grids and rulers allows you to create a balanced desi ## Showing Rulers -1. Open the Simulator +1. Open the Simulator or connect a supported physical iOS device 2. Select the comparing tab 3. Click on the Rulers button 4. Hover over the horizontal or vertical ruler and left-mouse click to store a ruler: diff --git a/docs/src/content/docs/docs/settings/cli-and-agent.md b/docs/src/content/docs/docs/settings/cli-and-agent.md new file mode 100644 index 00000000..fe631440 --- /dev/null +++ b/docs/src/content/docs/docs/settings/cli-and-agent.md @@ -0,0 +1,82 @@ +--- +title: "CLI & Agent" +description: "Install RocketSim's command line tool and bundled Agent Skill from Settings so agents and scripts use the latest installed app version." +--- + +Use **RocketSim → Settings → CLI & Agent** to install the `rocketsim` command line tool and the RocketSim Agent Skill. + +This is the recommended setup for agentic development. The command line tool gives agents a fast way to interact with the running Simulator through RocketSim, while the Agent Skill teaches your AI coding tool how to use that CLI reliably. + +## Install the command line tool + +1. Open **RocketSim → Settings → CLI & Agent** +2. In **Command Line Tool**, click **Install Command Line Tool** +3. Choose the default selected folder if it is on your `PATH`, or pick another folder such as `/opt/homebrew/bin` or `/usr/local/bin` +4. Confirm the installation + +RocketSim creates a `rocketsim` symlink in the folder you choose. The real executable stays inside `RocketSim.app`. + +![CLI & Agent settings showing the command line tool installer](./cli-and-agent/cli-agent-settings.png) + +That means: + +- `rocketsim` is available from Terminal, agents, and CI scripts +- The command stays tied to the RocketSim app you installed +- App Store updates keep the command up to date automatically +- Repairing the install updates the symlink if RocketSim moved + +## Install the Agent Skill + +The Agent Skill is installed from the same settings page. + +1. Open **RocketSim → Settings → CLI & Agent** +2. Install the command line tool first if it is not installed yet +3. In **Agent Skill**, choose **General Agents** +4. Click **Install** +5. Restart or refresh your tool if it does not detect new skills automatically + +RocketSim installs the skill as a symlink to the bundled skill inside the app. The skill and CLI are version-matched, so your agent receives instructions that match the RocketSim version it is controlling. + +![CLI & Agent settings showing Agent Skill installation options](./cli-and-agent/cli-agent-settings.png) + +We recommend **General Agents** because it installs into the shared `.agents/skills` location. Multiple AI coding tools can reuse that same version-matched RocketSim skill. Use a tool-specific destination only if your tool does not scan the shared location. + +## Why this setup is recommended + +The RocketSim Mac app is already running beside the Simulator. It can keep state, cache expensive work, and optimize repeated agent loops. The CLI exposes that running app to agents, and the Agent Skill helps agents use the CLI in the right order. + +In our internal research, RocketSim's CLI completed the same agent workflows about **19% faster, avoided wrong taps entirely**, and used about **63% fewer estimated tokens** than a popular alternative. + +## Verify the setup + +Run: + +```bash +rocketsim doctor +``` + +The doctor command checks whether RocketSim, the CLI install, the Simulator, accessibility permissions, and agent workflow state are ready. + +Then ask your AI coding tool: + +> Use RocketSim to inspect the visible elements in the focused Simulator + +If everything is installed correctly, the agent should use RocketSim to read the current screen and continue from there. + +## Troubleshooting + +### The command is not found + +Make sure you chose a folder that is on your shell `PATH`. You can reinstall from **Settings → CLI & Agent** and choose another folder. + +### RocketSim says the command needs repair + +The existing `rocketsim` symlink points somewhere unexpected. Click **Repair Command Line Tool** to point it back to the current RocketSim app. + +### My agent does not see the skill + +Some AI coding tools only scan skill folders when they start. Restart the tool or reload its workspace after installing the skill. + +### I use a custom skill folder + +Use **Choose Custom Skill Folder...** in the Agent Skill section and select the folder your tool scans for skills. diff --git a/docs/src/content/docs/docs/settings/cli-and-agent/cli-agent-settings.png b/docs/src/content/docs/docs/settings/cli-and-agent/cli-agent-settings.png new file mode 100644 index 00000000..1b69a5b9 Binary files /dev/null and b/docs/src/content/docs/docs/settings/cli-and-agent/cli-agent-settings.png differ diff --git a/docs/src/content/docs/docs/settings/physical-devices.md b/docs/src/content/docs/docs/settings/physical-devices.md new file mode 100644 index 00000000..e316332b --- /dev/null +++ b/docs/src/content/docs/docs/settings/physical-devices.md @@ -0,0 +1,45 @@ +--- +title: "Physical Devices" +description: "Configure how RocketSim discovers, shows, and ignores connected physical iOS devices." +--- + +Use **RocketSim → Settings → Physical Devices** to control how RocketSim monitors connected iOS devices. + +Physical device support lets RocketSim show a live preview window for a USB-connected iPhone, attach the side window to that preview, and use capture or comparison workflows on real hardware. + +![Physical Devices settings page](./physical-devices/physical-devices-settings.png) + +## Enable USB device support + +Keep **Enable USB device support** turned on if you want RocketSim to detect physical devices connected by USB. + +When you turn it off, RocketSim stops monitoring physical devices and closes any open physical-device windows. Turning it back on restarts monitoring without requiring an app restart. + +## Network-detected devices + +Some paired devices can appear as reachable on the local network even when they are not currently connected by USB. + +Use **Show device window when detected on the network** to decide whether RocketSim should show these devices. Turning this off keeps RocketSim focused on cabled devices only. + +USB-connected devices are still shown when USB support is enabled. + +## Ignored devices + +If there is a device you do not want RocketSim to manage, use the device window menu and choose **Ignore this device**. + +![Ignore this device option in the physical device toolbar menu](./physical-devices/ignore-this-device-menu.png) + +Ignored devices: + +- Stop opening physical-device preview windows +- Stay ignored across app launches +- Appear in **Settings → Physical Devices → Ignored Devices** +- Can be restored by clicking **Stop Ignoring** + +This is useful when multiple devices are connected but you only want RocketSim to work with one of them. + +## Related docs + +- [Physical Device Support](/docs/features/capturing/physical-device-support) +- [Taking Screenshots](/docs/features/capturing/screenshots) +- [Creating Recordings](/docs/features/capturing/recordings) diff --git a/docs/src/content/docs/docs/settings/physical-devices/ignore-this-device-menu.png b/docs/src/content/docs/docs/settings/physical-devices/ignore-this-device-menu.png new file mode 100644 index 00000000..2b76516c Binary files /dev/null and b/docs/src/content/docs/docs/settings/physical-devices/ignore-this-device-menu.png differ diff --git a/docs/src/content/docs/docs/settings/physical-devices/physical-devices-settings.png b/docs/src/content/docs/docs/settings/physical-devices/physical-devices-settings.png new file mode 100644 index 00000000..96ff74b2 Binary files /dev/null and b/docs/src/content/docs/docs/settings/physical-devices/physical-devices-settings.png differ diff --git a/docs/src/styles/starlight-custom.css b/docs/src/styles/starlight-custom.css index 4d20728a..a8d9de93 100644 --- a/docs/src/styles/starlight-custom.css +++ b/docs/src/styles/starlight-custom.css @@ -135,6 +135,17 @@ starlight-toc a[aria-current="true"] { text-decoration: underline; } +/* Keep emphasized product and settings names high-contrast in docs copy. */ +.sl-markdown-content :where(p, li) strong { + color: var(--sl-color-white); + font-weight: 700; +} + +/* Preserve link accent color for emphasized text inside links. */ +.sl-markdown-content a:not(.card):not(.action-button) strong { + color: inherit; +} + /* ========================================================================== Cards ========================================================================== */