Ceraph

Bring an app to the foreground without a cold restart on the active exact runtime. Uses WebDriverAgent on iOS or an exact-serial Android activity launch.

Return the foreground app's identity and name on the active exact runtime. Android also reports its activity.

Start, open, relaunch, or incrementally rebuild this project's iOS or Android app. With no bundleId—or when bundleId matches this project—starts/reuses Metro, connects the Expo dev client, and verifies that this project's JS bundle loaded. A physical iPhone Expo dev client may report reduced-confidence readiness when exact in-app confirmation is unavailable; other targets remain strict. It does not start or stop the platform automation driver or keep-awake service. Set rebuild:true only when the user explicitly asks for a native rebuild; it uses the managed build/install path without provisioning automation. For another app's explicit bundleId/package ID, performs a plain native launch without Metro. Use ceraph_start instead when the agent must inspect, test, or drive UI.

List apps installed on the active exact mobile runtime. Uses Apple device/simulator tooling on iOS or exact-serial package-manager data on Android.

Terminate an app by its iOS bundle ID or Android package ID on the active exact runtime. On a real iOS device, terminating the app under test keeps WebDriverAgent available for subsequent commands; the screen may show WDA's runner until app_activate or ceraph_start relaunches the app. iOS Simulator and Android runs do not need this iOS auto-lock safeguard.

Add a JPEG, PNG, WebP, or HEIC camera fixture up to 5 MB. Pass the image as base64 or a data URI with a lowercase, hyphen-separated `mediaKey` used by `<CeraphCamera mediaKey>`. An existing key is preserved unless `overwrite: true` is set. Returns the key, format, replacement status, and size. Fixtures are development-only; production builds use the real camera and exclude test media.

Add an MP4, MOV, or M4V camera video fixture up to 25 MB. Pass the video as base64 or a data URI with a lowercase, hyphen-separated `videoKey`; the matching `<CeraphCamera mediaKey>` uses it for recording. An existing key is preserved unless `overwrite: true` is set. Returns the key, format, replacement status, and size. Fixtures are development-only; production builds use the real camera and exclude test media.

Add an image or video to the selected runtime's system photo library so the agent can test the app's real native media picker. After adding it, open the app's picker and select the supplied media.

Run the available platform setup checks before driving the app: exact runtime connected, automation driver reachable, app installed, required env vars present, plus connectivity checks available for that platform. Returns a structured result — when ok: false, follow each finding's remediation and DO NOT attempt to fix environment issues by editing source code. To bring everything up in one call (Metro + build + verify), use ceraph_start.

Run the complete Ceraph project setup, equivalent to `npx @ceraph/react-native-mcp init`. This is the recommended agent path: it installs and integrates Ceraph, configures supported MCP clients and runtime-error delivery, prepares camera testing, and checks project and runtime readiness. It preserves existing project customizations and returns manual remediation when a file cannot be changed safely. It detects an active Pro account automatically. Otherwise it returns { status: 'needs-tier' } before mutation; show the plan options, call ceraph_init_select_tier with the user's choice, then re-call this tool. Starter continues without sign-in. Pro may return 'needs-auth' or 'needs-checkout'; complete that step and re-call. A temporary entitlement outage returns 'verification-unavailable'; retry it rather than presenting an upgrade. A 'needs-manual' result contains actions that must be completed before testing; 'ready' means no known setup actions remain. A userMcp call changes only user-level MCP registration, not project setup. Relay optional setup decisions when returned and complete them only after explicit user approval. Ask the collaboration question last. A collaboration follow-up uses Ceraph's narrowly scoped commit; do not substitute your own Git commit. Global CLI installation is also an approval-only follow-up. These optional decisions do not block testing; --agent and --yes do not authorize them.

Sign in to Ceraph through the browser. Returns { status: 'ok', email? } on success, or machine-selection-required with recently used installations when all three Pro slots are occupied. Relay the choices to the user; never select a machine to sign out without their explicit confirmation. After confirmation, resume with the selected id and generation. No second browser login is needed while approval remains valid. { status: 'aborted' } when the MCP client cancelled the tool call (don't prompt the user — just stop), or a stable remediation on failure. When browser sign-in cannot complete, relay the returned verificationUri to the user. If callback delivery fails, re-call with the browser-provided token. Treat the token as a secret and never repeat it in output. For complete project setup, prefer `ceraph_init`.

Repair Ceraph's development app integration and required project configuration. Preserves existing app and bundler customizations, is safe to re-run, and reports exact manual remediation for dynamic configuration it cannot change safely. Prefer complete `ceraph_init` unless remediation specifically asks for this repair.

Configure the development URL scheme Ceraph needs to reconnect to the app. Updates supported static configuration and returns exact manual instructions when a dynamic or native configuration cannot be changed safely.

Replace one Expo CameraView with a configured CeraphCamera, or set the mediaKey on an unconfigured CeraphCamera. Use `default` when fixture content does not matter, or a lowercase-dashes key matching a camera fixture. Pass the source location returned by `ceraph_init_scan_camera`; column is required only when two cameras share a line. Preserves unrelated source and is safe to re-run with the same key.

Find Expo CameraView components that can use deterministic camera fixtures. Returns only the source locations and suggested media keys needed for setup. Choose a descriptive key for the app scenario, and pass the returned line and column to `ceraph_init_replace_camera`.

Select the Ceraph plan and drive Pro onboarding. Call with no args to resume onboarding: an authenticated active Pro account returns { status: 'pro-ready' }; otherwise a fresh setup gets the two plan options ({ status: 'needs-tier' }). Call with { tier: 'starter' } for the free local toolset ({ status: 'starter-ready' }); call with { tier: 'pro' } to start Pro setup. The Pro path is a state machine resolved fresh each call: not signed in → { status: 'needs-auth', authUrl } (sign in via ceraph_init_auth_browser, then re-call); signed in but not yet paid → { status: 'needs-checkout', checkoutUrl } (selecting Pro is NOT being Pro — complete checkout, then re-call); paid → { status: 'pro-ready' }. Re-calling re-checks server-side, so an abandoned then-completed checkout self-heals. For a complete install (this tier step plus every other phase), call `ceraph_init` instead.

Configure Ceraph in every supported MCP client detected for this project. Preserves unrelated entries and leaves malformed or unfamiliar config untouched with a reason the user can resolve. In a monorepo, pass the chosen React Native app directory. This repairs client configuration only; prefer `ceraph_init` for complete project setup.

Read the current Ceraph setup state, including app integration, supported client configuration, camera readiness, and any incomplete steps. Read-only. Call `ceraph_init` for complete setup; use a granular init tool only when Ceraph remediation asks for that specific repair.

Replay an already-verified React Native path without model pauses and produce a clean MP4 with an ordered trace of structured snapshots and screenshots. Explore and debug first; call this only after the path works. Each wait-for marks a verified state and must reference the exploratory ceraph_snapshot capture ID with expectedSnapshotId. Use the resulting manifestPath to retrieve only the trace snapshots and screenshots relevant to a reported problem or a user's request; do not inspect every trace entry by default. If the requested screen is outside the recorded flow, navigate to it and use screen_screenshot. Exclude exploratory or debugging detours, loading frames, keyboard appearances, and incidental system UI. For a purely static settled change, use screen_screenshot with ceraph_snapshot instead of manufacturing a recording. Recorded steps share the interactive selector semantics for tap, type, swipe, scroll-to, long-press, press-key, tap-chain, add-media, set-camera-test-media (enabled: true/false), open-url, run-hook, set-orientation, app launch/terminate/activate, and wait-for. Enable camera test media before a camera flow and disable afterward; the setting lasts while connected. Cross-app native accessibility flows are supported; return to the project app before expecting Fiber-backed detail. An add-media step can insert a fixture while a native picker is open; its base64 payload is never persisted in the run manifest. Use snapshot bounds only with the source ceraph_snapshot capture ID; arbitrary screenshot coordinates are intentionally not replayable. The recording is screen-only evidence; it does not capture or verify audio.

Prepare a sanitized public Ceraph defect report and check GitHub CLI authentication. Submit only with explicit user approval or a matching account-bound lasting preference. Preview first when consent is absent; never attach source, logs, media, or credentials.

Fire a registered project-owned Ceraph hook by route when the real UI cannot reliably establish a testing prerequisite. Before considering a hook, prefer the real UI when it can establish that prerequisite: the path itself provides end-to-end coverage and may reveal regressions. After setup, continue the representative end-to-end flow rather than testing only the changed screen or component. If login or payment is under review, exercise that flow rather than skipping it. Before considering testing blocked, inspect ceraph_snapshot.meta.availableHooks. Hooks can create or sign in as disposable test users; prepare sessions, OTPs, or magic links; seed non-production backend/database states; establish roles, subscriptions, entitlements, or feature flags; simulate webhook, payment, email, or push state; dismiss development-only blockers; insert picker media through an app-owned physical-iPhone test seam; and reset or clean up disposable data. Hooks can reach backend and database code: verify a disposable non-production target, never modify production or real-user data or take irreversible action without explicit human authorization, reuse existing app authentication/configuration instead of embedding secrets, and prefer idempotent runId-scoped effects that return created IDs and have companion cleanup. A hook can return `data` (JSON such as created IDs or a disposable test user's credentials); use it to continue the flow, and when it holds disposable test credentials, share them with the user in your summary so they can test manually. The hook's run() code lives in your app (.ceraph/hooks, wired by `ceraph init`); this tool triggers it over Ceraph's command channel and reports the outcome.

Switch the running development app's CeraphCamera between registered test media and the real camera without rebuilding or restarting. Enable before camera testing and disable when finished. Uses each component's mediaKey; it does not add gallery media. Set save to retain the choice for later Ceraph sessions on this machine. The runtime choice stays active through thinking pauses while connected; production always uses the real camera. Replay runtime-only changes as set-camera-test-media in ceraph_record_run.

Return a structured snapshot of the CURRENT screen — the kind of accessibility-tree view the web exposes, for React Native: a tree of UI elements with roles (button/textInput/text/image/scrollView/switch/view), names, values, on-screen bounds (device points), live state (`onScreen`/enabled/focused), and a stable `ref` per element. `onScreen` means the node intersects the device viewport; it does not promise that every pixel is unobscured in a screenshot. To ACT on an element, ordinarily call screen_tap with its `ref`; use screen_tap_and_verify only when you also have an explicit postcondition. Other element actions (screen_type_into_field, screen_long_press, …) accept the same ref — never pass the snapshot `role` as a native-driver type. A `synthetic` or non-unique accessibility ref has no reliable identity handle, so pass its `bounds` directly to screen_tap. When a component is reused on one screen its instances share a testID, so each on-screen occurrence past the first gets a disambiguation ref `<id>::<N>` (e.g. `cer_btn::2`) and a `collision` field ({ baseRef, occurrence, totalOccurrences }); pass that `::N` ref back verbatim and the tap lands on that exact instance. `testIdCollisions` counts the colliding ids. Also returns a flat `tappable` list (on-screen + enabled interactive elements). Each successful response also includes `meta.capture.id`; link every clean-path snapshot that materially informs the recorded replay plan. Ceraph pairs those expected states with explicit replay waits and post-run observed frames. When this project's Ceraph-enabled app is foreground, the snapshot includes React Native Fiber detail. In another foreground app or native system surface, Ceraph returns the available native accessibility tree instead, which supports cross-app journeys without mixing project state into that screen. Requires a ready automation runtime; call ceraph_start first.

FIRST call for any app-driving session: the one-call bring-up that reaches a ready-to-test state. Starts or reuses Metro, the app, and the platform automation driver (WebDriverAgent on iOS or UiAutomator2 on Android), then verifies the selected exact runtime is ready. Runs only the steps that aren't already done and stops at the first failure with its remediation. Call this before ceraph_snapshot / screen_* taps / screenshots / typing — prefer it over calling rn_metro_start / rn_build_ios / rn_build_android / rn_wda_start / ceraph_doctor separately. Works against iOS or Android devices, iOS simulators, and Android emulators. Prefer target:'headless' for unattended or background simulator verification; use target:'simulator' when the user needs the Simulator.app window visible. For unattended Android verification use target:'no-window'; it launches the AVD without a window or host audio. Use target:'emulator' when a visible emulator window is useful.

Ensure the active iOS or Android runtime is awake and request keyguard dismissal. Returns a structured result with remediation guidance when the runtime cannot be made ready.

Request portrait or landscape through the active automation driver and verify both the device and active app's resulting orientation. Ceraph does not override the app's supported-orientation policy.

Advanced unmanaged Android build diagnostic. A bare call starts nothing and steers to `ceraph_start({ platform: 'android', rebuild: true })`. Set `unmanaged:true` only when you accept responsibility for the build process. `clean:true` may regenerate the Android native project for Expo apps.

Advanced unmanaged iOS build diagnostic. A bare call starts nothing and steers to `ceraph_start({ rebuild: true })`; use `app_launch({ rebuild: true })` only for rebuild-and-open. Set `unmanaged:true` only when you accept responsibility for the build process. `clean:true` may regenerate the iOS native project for Expo apps.

Check whether recent changes require rebuilding the app before testing, without starting a build. Reports the reasons and any checks that could not be completed.

Return recent app console output, including shim-forwarded output when Metro is externally owned, optionally filtered by log level.

Return all captured errors from build and runtime. Includes structured build errors (file, line, column, message), runtime JS errors (message, stack trace), and warnings.

Start or reuse this project's Metro dev server. Auto-detects Expo vs bare React Native. Monitors console output for runtime errors and warnings. To bring everything up in one call (Metro + build + verify), use ceraph_start.

Request a JS bundle reload on the running development app through Ceraph's installed app integration. Waits up to `timeoutMs` for the platform automation driver to become responsive again, then captures a screenshot. Dev-only; does nothing in a production build.

Stop all managed React Native processes and this session's managed no-window Android emulator, if any.

Refresh Ceraph camera fixtures after images or videos were added, removed, or changed manually under `.ceraph/`. The filename stem is the key used by `<CeraphCamera mediaKey>`. The camera fixture tools refresh their own writes, so call this only after manual file changes or a git update. Returns the available image and video keys.

Report the active platform, physical-device or virtual-runtime target, exact runtime ID, presentation mode, and automation readiness. Call this when the developer asks which runtime is under test or before starting a flow if uncertain which target is active.

Wait for a physical mobile runtime to connect. iOS uses macOS usbmuxd events; Android waits for one exact adb serial to become connected and authorized without selecting or probing a different runtime. The call waits until connection, an explicit deadline, or agent cancellation.

Advanced / simulator-only. Use `ceraph_start` for normal app bring-up. This tool prepares automation for an already-booted iOS Simulator and never targets a real iPhone. It requires the optional `appium-webdriveragent` dependency and may request the one-time Xcode signing setup. When a real iPhone is also connected, explicitly confirm simulator intent so Ceraph never changes targets silently.

Stop the managed iOS Simulator automation session started by rn_wda_start. Idempotent — calling it when no such session is running is a no-op. Real-device automation is unaffected.

Long-press an element (PREFER its `ref` from ceraph_snapshot; else text/accessibilityLabel). Default duration is 1000ms.

Open a URL / deep link on the device to jump straight to a screen — useful for testing your app's deep-link routes (e.g. myapp://product/42). If the scheme isn't registered in the app under test, the result carries an actionable message explaining the app needs a rebuild to pick up the scheme.

Press a hardware/system button: back, home, volumeUp, volumeDown, or lock. Back uses Android's system key and iOS navigation fallback.

Capture a screenshot of the current mobile screen through the active automation driver. Returns the PNG as a viewable image. Optional saveTo also saves a local project-relative PNG without overwriting an existing file.

Repeatedly swipe until an element is actually on-screen (PREFER its `ref` from ceraph_snapshot; else text/accessibilityLabel). Returns without tapping. Default direction is 'up' (swipe up — reveals content below the fold), max 10 swipes. Pass direction: 'down' to scroll backward toward the top.

Swipe on the current mobile screen. Direction is up/down/left/right; optional from-point and distance default to a center-screen swipe of ~60% of the relevant axis. Coordinates are device-space by default — keep it that way and pass ceraph_snapshot `bounds` directly. Only pass coordinateSource: 'screenshot' if `from` was measured off a screenshot, and treat that as best-effort: the delivered image is usually downscaled by a factor Ceraph cannot observe.

Tap by a `ref` from ceraph_snapshot, snapshot bounds, or explicit coordinates. Prefer a stable `ref`; use `index` only when a non-unique accessibility ref matches multiple elements. Use bounds for synthetic accessibility refs. Screenshot-derived coordinate taps are best-effort.

Tap an element and assert an explicit postcondition in one call. PREFER the element's `ref` from ceraph_snapshot; use ordinary screen_tap for a tap without a postcondition. Finds the target, taps its center, and asserts the follow-up selector is on screen — all in one logical step. The result reports whether the optimized path was used (`batched`).

Compound primitive: tap a sequence of elements in one optimized call. Each query resolves against the same screen state. If any query fails to resolve, the chain stops and ZERO gestures are sent (we never partial-tap an intent). On bulk-action failure, Ceraph may use individual taps (`batched: false`). Use only for controls that are simultaneously on-screen and whose layout will not change between taps; any navigation or menu re-render needs separate taps and fresh snapshots.

Compound primitive: focus an input field (PREFER its `ref` from ceraph_snapshot; else text/accessibilityLabel/type) and type into it. The result reports whether the optimized focus path was used (`batched`). Set `clearFirst: true` to clear an existing value before typing — off by default so we never silently overwrite form state. A successful Android call can set `dismissKeyboardAfter: true` to dismiss the software keyboard and verify it is no longer shown. A successful key dispatch is postcondition-checked against field value or focused edit state; phase timings are returned for latency diagnosis.

Poll the active automation driver's native source tree until an element matching the query is on-screen (or, if disappear is true, until it is no longer on-screen). This checks accessibility geometry, not screenshot pixels. Default timeout is 5s.