@slack/radar-mcp 1.17.1 → 1.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Platform-agnostic MCP server and web dashboard for on-device debugging of mobile apps.
4
4
 
5
- Gives Claude Code direct access to network calls, RTM events, analytics (clogs), screenshots, logs, and more from a running debug build. Ships with Android support (ADB); the `DeviceTransport` interface makes adding iOS or other platforms straightforward.
5
+ Gives Claude Code direct access to network calls, RTM events, analytics (clogs), screenshots, logs, and more from a running debug build. Ships with Android device support (ADB) and initial iOS Simulator support; the `DeviceTransport` interface keeps platform-specific host behavior isolated.
6
6
 
7
7
  > **For Slack engineers.** The npm package is published publicly as a distribution convenience, but the source repository, issue tracker, and support live on Slack's internal GitHub Enterprise. External users can install the package but should not expect support or source access. The tool only functions against a Slack debug build, which is not distributed externally.
8
8
 
@@ -68,13 +68,14 @@ Clicking it starts the dashboard if it is not already running (the server auto-c
68
68
 
69
69
  A **▣ Screen** button opens a side panel that mirrors the live device screen, with a full-resolution screenshot and a screen recording. It is off by default and opens to a consent notice first, because it shows whatever is on the phone (open DMs, message content, notifications).
70
70
 
71
- * **Screenshot** works on any machine (pure `screencap`, no extra tools).
72
- * **Live mirror and recording** need `ffmpeg` on your machine. If it is missing, the panel shows the install command for your platform and the screenshot still works. ffmpeg is not bundled and is never installed for you.
71
+ * **Screenshot** needs no extra tools: Android uses `screencap`, and iOS Simulator uses `xcrun simctl io`.
72
+ * **Live mirror** uses the Android `screenrecord` stream (needs `ffmpeg`). For iOS Simulator, Radar polls native screenshots at 1fps — no ffmpeg dependency.
73
+ * **Recording** uses `ffmpeg` on Android and `simctl recordVideo` on iOS Simulator. If ffmpeg is missing on Android, the panel shows the install command. ffmpeg is not bundled and is never installed for you.
73
74
 
74
75
  ## Prerequisites
75
76
 
76
77
  * Node.js 18+
77
- * ADB with a single connected device (USB or wireless debug)
78
+ * ADB for Android, or Xcode (full installation, not just command-line tools) for iOS Simulator
78
79
  * A debug build of Slack installed on the device (must include the `slack-radar` modules)
79
80
 
80
81
  ## Environment Variables
@@ -89,6 +90,8 @@ All optional. Set them on the process that runs the MCP server or the dashboard.
89
90
  | `SLACK_RADAR_ALLOWED_HOSTS` | Extra `Host` values the dashboard will answer, comma-separated (`radar.local,myhost:8100`). Only needed when you reach it by a name other than localhost. See Security. |
90
91
  | `SLACK_RADAR_NO_OPEN=1` | Do not open a browser window on launch. Set automatically when an MCP tool spawns the dashboard. |
91
92
  | `SLACK_RADAR_NO_FFMPEG=1` | Pretend ffmpeg is absent, so screen recording degrades to screenshots. |
93
+ | `SLACK_RADAR_PLATFORM` | Transport to use: `android` (the default) or `ios`. Radar does not probe or infer a different platform. |
94
+ | `SLACK_RADAR_IOS_SIMULATOR_UDID` | Pin a specific iOS Simulator by UDID instead of auto-selecting the sole booted one. |
92
95
 
93
96
  ## Session Management
94
97
 
@@ -131,9 +134,9 @@ Radar starts **disabled** each session. All tools except `ping` return an error
131
134
  | `list_prefs` | List the app's on-device SharedPreferences files. Read-only. |
132
135
  | `get_prefs` | Read a preferences file's keys and values, optionally filtered to specific keys. |
133
136
  | `search_prefs` | Search preference keys and values across every file by a substring. |
134
- | `list_feature_flags` | List every feature flag with its live effective value and override status. Optionally filtered to just the overridden ones. |
135
- | `search_feature_flags` | Case-insensitive substring search on feature flag names, against the same live list as `list_feature_flags`. |
136
- | `get_feature_flag` | Look up one feature flag by its exact key. Returns one row per scope (authenticated/unauthenticated). |
137
+ | `list_feature_flags` | List every feature flag with its live effective value and override status. Optionally filtered to just the overridden ones. Boolean toggles carry `enabled`; multi-variant experiments carry `type: "experiment"` and a `group_name` string (the effective variant, e.g. `"treatment_a"`) instead. |
138
+ | `search_feature_flags` | Case-insensitive substring search on feature flag names, against the same live list as `list_feature_flags`. Rows carry the same `type`/`group_name` fields for experiments. |
139
+ | `get_feature_flag` | Look up one feature flag by its exact key. Returns one row per scope (authenticated/unauthenticated) and per signed-in org, since each workspace resolves its own value; pass `org_id` to narrow to one workspace. An experiment row carries `type: "experiment"` and its `group_name` variant rather than a boolean `enabled`. |
137
140
  | `clear_buffers` | Clear all captured buffers (network, RTM, clog, trace) on the device and locally. |
138
141
  | `open_radar_dashboard` | Author or refine a custom live dashboard tab from a spec (source, filters, widgets, alerts). Suggested when a request is not covered by the pre-built tabs; not auto-invoked. Returns the dashboard URL; debug builds only, local only. |
139
142
  | `_radar_session_enable` | Enable radar for the session. Called by `/radar-enable` skill. |
@@ -216,6 +219,20 @@ npm run test:smoke # Smoke tests
216
219
  npm run test:all # Both
217
220
  ```
218
221
 
222
+ Radar uses the Android transport by default. Choose the iOS transport explicitly when working
223
+ with a Simulator:
224
+
225
+ ```bash
226
+ npm run start:web
227
+ SLACK_RADAR_PLATFORM=ios npm run start:web
228
+ # Equivalent: npm run start:web -- --platform=ios
229
+ ```
230
+
231
+ Within the selected platform, Radar chooses the sole running device or shows the device picker
232
+ when several are available. It never probes the other platform. iOS support is currently limited
233
+ to screenshot, screen mirroring, and recording via `simctl`; the HTTP-based tools (network,
234
+ RTM, clogs) require a device-side server that is not yet available on iOS.
235
+
219
236
  ## Troubleshooting
220
237
 
221
238
  **"ADB port forwarding failed"**
@@ -13,8 +13,12 @@ export declare function createFeatureFlagsCache<T extends {
13
13
  export interface FeatureFlagRow {
14
14
  key: string;
15
15
  scope?: string;
16
+ type?: string;
16
17
  enabled?: boolean | string;
18
+ group_name?: string;
17
19
  is_overridden?: boolean;
20
+ org_id?: string;
21
+ timestamp?: number;
18
22
  }
19
23
  interface FeatureFlagsListResponse {
20
24
  feature_flags?: FeatureFlagRow[];
@@ -55,16 +59,17 @@ export declare function searchFeatureFlags(response: FeatureFlagsListResponse, q
55
59
  * found key always returns at least one row), so treating a miss as an error is the correct
56
60
  * and only outcome, not a fallback.
57
61
  *
58
- * A key is NOT unique on its own: every flag on a real device is listed once per scope
59
- * (authenticated/unauthenticated), so a bare key lookup has two rows, not one (verified live,
60
- * repeatedly, against a real Fold: every key duplicated exactly once, sometimes with
61
- * DIFFERENT enabled/is_overridden values between the two scopes). ALWAYS returns a `rows`
62
- * array on success, one element when the key is unambiguous, so the response shape never
63
- * depends on how many scopes happen to exist for a given key -- a caller reads `data.rows[0]`
64
- * (or filters/maps over `data.rows`) the same way regardless of count, rather than branching
65
- * on whether it got a bare object or a wrapper.
62
+ * A key is NOT unique on its own. Every flag is listed once per scope
63
+ * (authenticated/unauthenticated), and once per signed-in ORG within the authenticated scope,
64
+ * since each org resolves its own value and a flag can be on in one workspace and off in
65
+ * another. So a bare key lookup returns one row per (scope, org): two on a device with one
66
+ * workspace signed in, three when a second org is signed in, and passing `scope` narrows but
67
+ * does not guarantee one row. ALWAYS returns a `rows` array on success, so the response shape
68
+ * never depends on how many scopes or orgs happen to exist -- a caller filters/maps over
69
+ * `data.rows` the same way regardless of count, rather than branching on whether it got a bare
70
+ * object or a wrapper. Pass `orgId` to narrow to a single workspace.
66
71
  */
67
- export declare function getFeatureFlag(response: FeatureFlagsListResponse, key: string, scope?: string): {
72
+ export declare function getFeatureFlag(response: FeatureFlagsListResponse, key: string, scope?: string, orgId?: string): {
68
73
  data: unknown;
69
74
  isError: boolean;
70
75
  };
@@ -52,7 +52,24 @@ function wellFormedRows(response) {
52
52
  const raw = response.feature_flags;
53
53
  if (!Array.isArray(raw))
54
54
  return [];
55
- return raw.filter((f) => typeof f === "object" && f !== null && typeof f.key === "string");
55
+ return raw
56
+ .filter((f) => typeof f === "object" && f !== null && typeof f.key === "string")
57
+ .map(dropEmptyOrg);
58
+ }
59
+ // An empty org id means the same thing as no org id, so it is dropped rather than treated as a
60
+ // distinct org a caller could match or that an error message would render as a blank name. Same
61
+ // normalization the dashboard applies to the same wire.
62
+ function dropEmptyOrg(f) {
63
+ if (f.org_id !== "")
64
+ return f;
65
+ const { org_id: _dropped, ...rest } = f;
66
+ return rest;
67
+ }
68
+ // Rows repeat per scope and per org, so a row count is not a flag count. A toggle and an
69
+ // experiment can share a name, and those are two flags, so the kind is part of the identity.
70
+ // The :: join cannot collide: type is one of two fixed labels and keys are enum-derived names.
71
+ function distinctKeys(rows) {
72
+ return new Set(rows.map((f) => `${f.type ?? ""}::${f.key}`)).size;
56
73
  }
57
74
  // Only a real boolean `true` counts as overridden. `!!f.is_overridden` would also match a
58
75
  // string like `"false"` (truthy in JS) -- the exact class of bug this filter exists to work
@@ -85,10 +102,17 @@ export function listFeatureFlags(response, overridden) {
85
102
  }
86
103
  const all = wellFormedRows(response);
87
104
  const feature_flags = overridden === undefined ? all : all.filter((f) => isOverridden(f) === overridden);
88
- // total_flags is always the full list size; returned_flags counts the filtered result, same
89
- // split as the prefs tools' total_entries vs returned_entries.
105
+ // A model reads these field names literally, so rows are counted under *_rows and *_flags means
106
+ // distinct flags. One key occupies a row per scope and per signed-in org, so total_flags answers
107
+ // "how many flags does this app have" without a caller having to dedupe.
90
108
  return {
91
- data: { feature_flags, total_flags: all.length, returned_flags: feature_flags.length },
109
+ data: {
110
+ feature_flags,
111
+ total_rows: all.length,
112
+ returned_rows: feature_flags.length,
113
+ total_flags: distinctKeys(all),
114
+ returned_flags: distinctKeys(feature_flags),
115
+ },
92
116
  isError: false,
93
117
  };
94
118
  }
@@ -108,8 +132,10 @@ export function searchFeatureFlags(response, query) {
108
132
  data: {
109
133
  query,
110
134
  matches,
111
- total_flags: all.length,
112
- matched_flags: matches.length,
135
+ total_rows: all.length,
136
+ matched_rows: matches.length,
137
+ total_flags: distinctKeys(all),
138
+ matched_flags: distinctKeys(matches),
113
139
  },
114
140
  isError: false,
115
141
  };
@@ -122,19 +148,24 @@ export function searchFeatureFlags(response, query) {
122
148
  * found key always returns at least one row), so treating a miss as an error is the correct
123
149
  * and only outcome, not a fallback.
124
150
  *
125
- * A key is NOT unique on its own: every flag on a real device is listed once per scope
126
- * (authenticated/unauthenticated), so a bare key lookup has two rows, not one (verified live,
127
- * repeatedly, against a real Fold: every key duplicated exactly once, sometimes with
128
- * DIFFERENT enabled/is_overridden values between the two scopes). ALWAYS returns a `rows`
129
- * array on success, one element when the key is unambiguous, so the response shape never
130
- * depends on how many scopes happen to exist for a given key -- a caller reads `data.rows[0]`
131
- * (or filters/maps over `data.rows`) the same way regardless of count, rather than branching
132
- * on whether it got a bare object or a wrapper.
151
+ * A key is NOT unique on its own. Every flag is listed once per scope
152
+ * (authenticated/unauthenticated), and once per signed-in ORG within the authenticated scope,
153
+ * since each org resolves its own value and a flag can be on in one workspace and off in
154
+ * another. So a bare key lookup returns one row per (scope, org): two on a device with one
155
+ * workspace signed in, three when a second org is signed in, and passing `scope` narrows but
156
+ * does not guarantee one row. ALWAYS returns a `rows` array on success, so the response shape
157
+ * never depends on how many scopes or orgs happen to exist -- a caller filters/maps over
158
+ * `data.rows` the same way regardless of count, rather than branching on whether it got a bare
159
+ * object or a wrapper. Pass `orgId` to narrow to a single workspace.
133
160
  */
134
- export function getFeatureFlag(response, key, scope) {
161
+ export function getFeatureFlag(response, key, scope, orgId) {
135
162
  if (response.error) {
136
163
  return { data: { error: friendlyFeatureFlagError(response.error) }, isError: true };
137
164
  }
165
+ // Rows normalize an empty org id to "no org", so the arg means the same thing: a caller passing
166
+ // "" gets the unnarrowed lookup rather than an org that can never match.
167
+ if (orgId === "")
168
+ orgId = undefined;
138
169
  const all = wellFormedRows(response);
139
170
  const byKey = all.filter((f) => f.key === key);
140
171
  if (byKey.length === 0) {
@@ -143,16 +174,35 @@ export function getFeatureFlag(response, key, scope) {
143
174
  isError: true,
144
175
  };
145
176
  }
177
+ let matching = byKey;
146
178
  if (scope !== undefined) {
147
- const exact = byKey.find((f) => f.scope === scope);
148
- if (!exact) {
149
- const seenScopes = byKey.map((f) => f.scope ?? "(none)").join(", ");
179
+ // Every row for the scope, not the first: two signed-in orgs both resolve as "authenticated"
180
+ // with their own value, and returning one of them arbitrarily is the bug this filter had.
181
+ matching = matching.filter((f) => f.scope === scope);
182
+ if (matching.length === 0) {
183
+ // Deduped: with two orgs signed in the raw list repeats "authenticated" once per org, and
184
+ // an error naming the same scope twice reads like a bug in the tool.
185
+ const seenScopes = [...new Set(byKey.map((f) => f.scope ?? "(none)"))].join(", ");
150
186
  return {
151
187
  data: { error: `Flag "${key}" exists but not with scope "${scope}". Scopes present for this key: ${seenScopes}.` },
152
188
  isError: true,
153
189
  };
154
190
  }
155
- return { data: { key, rows: [exact] }, isError: false };
156
191
  }
157
- return { data: { key, rows: byKey }, isError: false };
192
+ if (orgId !== undefined) {
193
+ // The candidate set BEFORE the org filter, so a combined scope+org miss lists only orgs the
194
+ // requested scope actually has -- deriving from every scope could name the very org the error
195
+ // just called absent.
196
+ const candidates = matching;
197
+ matching = matching.filter((f) => f.org_id === orgId);
198
+ if (matching.length === 0) {
199
+ const seenOrgs = [...new Set(candidates.map((f) => f.org_id ?? "(no org)"))].join(", ");
200
+ const scopeClause = scope === undefined ? "" : ` with scope "${scope}"`;
201
+ return {
202
+ data: { error: `Flag "${key}" exists${scopeClause} but not for org "${orgId}". Orgs present: ${seenOrgs}.` },
203
+ isError: true,
204
+ };
205
+ }
206
+ }
207
+ return { data: { key, rows: matching }, isError: false };
158
208
  }
package/dist/mcp/index.js CHANGED
@@ -8,6 +8,7 @@ import http from "http";
8
8
  import path from "path";
9
9
  import { fileURLToPath } from "url";
10
10
  import { AndroidTransport } from "../shared/android.js";
11
+ import { IosSimulatorTransport } from "../shared/ios.js";
11
12
  import { WebappTransport } from "../shared/webapp.js";
12
13
  import { webChildEnv } from "./web-child-env.js";
13
14
  import { RADAR_HOST, RADAR_PORT, RADAR_VERSION, WEB_PORT_DEFAULT, WEBAPP_DEFAULT_PORT, MAX_RADAR_RESPONSE_BYTES, setRadarPort, } from "../shared/constants.js";
@@ -237,6 +238,8 @@ async function runMcpServer() {
237
238
  if (decision.note)
238
239
  console.error(`[radar] ${decision.note}`);
239
240
  return new AndroidTransport();
241
+ case "ios":
242
+ return new IosSimulatorTransport();
240
243
  case "webapp":
241
244
  // Never called on the android path: android's RADAR_PORT resolution stays
242
245
  // byte-for-byte identical to today (see constants.ts).
@@ -244,7 +247,7 @@ async function runMcpServer() {
244
247
  setRadarPort(WEBAPP_DEFAULT_PORT);
245
248
  return new WebappTransport();
246
249
  case "unsupported":
247
- throw new Error(`Unsupported platform: ${decision.requested}. Supported: android, webapp`);
250
+ throw new Error(`Unsupported platform: ${decision.requested}. Supported: android, ios, webapp`);
248
251
  }
249
252
  });
250
253
  }
@@ -395,6 +398,14 @@ async function runMcpServer() {
395
398
  return device.reassertForward?.() ?? device.ensureForward();
396
399
  }
397
400
  async function callRadar(requestPath) {
401
+ // The host port is global and may currently be occupied by an Android adb forward. A transport
402
+ // that has no Radar HTTP server (currently iOS Simulator) must stop before reassertForward():
403
+ // its simulator-presence check cannot prove that the listener belongs to the selected platform.
404
+ if (!device.supportsRadarHttpTools) {
405
+ return {
406
+ error: unsupportedCapabilityError(device.platform, "Radar HTTP tools"),
407
+ };
408
+ }
398
409
  if (!forwardForRead()) {
399
410
  return {
400
411
  error: "Port forwarding failed. Ensure a device is connected and the debug build is running.",
@@ -782,7 +793,7 @@ async function runMcpServer() {
782
793
  }
783
794
  }
784
795
  // --- MCP Server ---
785
- const server = new Server({ name: "slack-radar", version: "1.17.1" }, { capabilities: { tools: {} }, instructions: serverInstructions(device.platform) });
796
+ const server = new Server({ name: "slack-radar", version: "1.18.0" }, { capabilities: { tools: {} }, instructions: serverInstructions(device.platform) });
786
797
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
787
798
  tools: TOOL_DEFINITIONS,
788
799
  }));
@@ -896,9 +907,9 @@ async function runMcpServer() {
896
907
  return textResult(data, isError);
897
908
  }
898
909
  if (name === "get_feature_flag") {
899
- const { key, scope } = toolArgs;
910
+ const { key, scope, org_id: orgId } = toolArgs;
900
911
  const response = await callFeatureFlags();
901
- const { data, isError } = getFeatureFlag(response, key ?? "", scope);
912
+ const { data, isError } = getFeatureFlag(response, key ?? "", scope, orgId);
902
913
  return textResult(data, isError);
903
914
  }
904
915
  const apiPath = buildApiPath(name, toolArgs);
@@ -30,6 +30,8 @@ export interface PlatformDetectInput {
30
30
  export type PlatformDecision = {
31
31
  platform: "android";
32
32
  note?: string;
33
+ } | {
34
+ platform: "ios";
33
35
  } | {
34
36
  platform: "webapp";
35
37
  setPort: boolean;
@@ -89,6 +89,8 @@ export async function decidePlatform(input) {
89
89
  if (explicitPlatform !== undefined) {
90
90
  if (explicitPlatform === "android")
91
91
  return { platform: "android" };
92
+ if (explicitPlatform === "ios" || explicitPlatform === "ios-simulator")
93
+ return { platform: "ios" };
92
94
  if (explicitPlatform === "webapp") {
93
95
  return { platform: "webapp", setPort: !envPortOverride };
94
96
  }
package/dist/mcp/tools.js CHANGED
@@ -608,7 +608,7 @@ export const TOOL_DEFINITIONS = [
608
608
  },
609
609
  {
610
610
  name: "list_feature_flags",
611
- description: "List every feature flag the app knows about right now, with its EFFECTIVE value (local override if set, else the server value) and whether that value is a local override. This is the actual live state the app is using, unlike get_prefs/search_prefs on debug_features_*.xml, which shows only manual overrides. Requires a debug build with the feature-flag Radar plugin; older builds report a clear error instead of the list.",
611
+ description: "List every feature flag the app knows about right now, with its EFFECTIVE value (local override if set, else the server value) and whether that value is a local override. One key appears once per scope and once per signed-in org, each row carrying its own value (plus an org_id on authenticated rows, when the device build reports one), so total_rows counts rows while total_flags counts distinct flags. This is the actual live state the app is using, unlike get_prefs/search_prefs on debug_features_*.xml, which shows only manual overrides. Requires a debug build with the feature-flag Radar plugin; older builds report a clear error instead of the list.",
612
612
  inputSchema: {
613
613
  type: "object",
614
614
  properties: {
@@ -619,7 +619,7 @@ export const TOOL_DEFINITIONS = [
619
619
  },
620
620
  {
621
621
  name: "search_feature_flags",
622
- description: "Case-insensitive substring search on feature flag names, against the same live effective-value list as list_feature_flags. Use this instead of search_prefs when you need to know whether a flag is actually ON right now, not just whether it has a manual override.",
622
+ description: "Case-insensitive substring search on feature flag names, against the same live effective-value list as list_feature_flags. One key can match several rows, one per scope and per signed-in org, so matched_rows counts rows and matched_flags counts distinct flags. Use this instead of search_prefs when you need to know whether a flag is actually ON right now, not just whether it has a manual override.",
623
623
  inputSchema: {
624
624
  type: "object",
625
625
  properties: {
@@ -631,12 +631,13 @@ export const TOOL_DEFINITIONS = [
631
631
  },
632
632
  {
633
633
  name: "get_feature_flag",
634
- description: "Look up one feature flag by its exact key (case-sensitive) and return its effective value and override status. Always returns rows: an array, since every flag exists in TWO scopes (authenticated = the value for a signed-in user, unauthenticated = the value for a visitor who has not signed in yet) with potentially different values -- rows has one entry when scope is given or when the key has only one scope, two when both scopes exist and no scope was given. Use list_feature_flags or search_feature_flags first if you are not sure of the exact key.",
634
+ description: "Look up one feature flag by its exact key (case-sensitive) and return its effective value and override status. Always returns rows: an array, because one key resolves along two axes. Scope (authenticated = the value for a signed-in user, unauthenticated = a visitor who has not signed in yet), and org: each signed-in workspace resolves its own value, so a flag can be ON in one workspace and OFF in another and each gets its own row with an org_id. A bare lookup returns one row per (scope, org), so read every row rather than the first one, and pass scope and/or org_id to narrow. On builds that report it, rows also carry timestamp, the device clock when that row was written, which tells an older row from a newer one. Use list_feature_flags or search_feature_flags first if you are not sure of the exact key.",
635
635
  inputSchema: {
636
636
  type: "object",
637
637
  properties: {
638
638
  key: { type: "string", description: "Exact flag key, e.g. 'android_some_flag'." },
639
639
  scope: { type: "string", description: "Optional. 'authenticated' (signed-in user) or 'unauthenticated' (visitor). Omit to get rows for every scope that exists." },
640
+ org_id: { type: "string", description: "Optional. Narrow to one signed-in workspace, using the org_id from an earlier row. Omit to get a row per org." },
640
641
  },
641
642
  required: ["key"],
642
643
  },
@@ -0,0 +1,15 @@
1
+ import type { DashboardScreenCapabilities, DashboardScreenController } from "./dashboard-screen.js";
2
+ /** Android's dashboard capture implementation, isolated around the adb/ffmpeg pipeline. */
3
+ export declare class AndroidDashboardScreenController implements DashboardScreenController {
4
+ capabilities(): DashboardScreenCapabilities;
5
+ refreshCapabilities(): Promise<void>;
6
+ captureScreenshot(): Promise<Buffer | null>;
7
+ startRecording(): Promise<string | null>;
8
+ stopRecording(): Promise<string | null>;
9
+ isRecording(): boolean;
10
+ redetect(): Promise<string>;
11
+ reset(): void;
12
+ resetDetection(): void;
13
+ resolveRecording(file: string): string | null;
14
+ registerCleanup(): void;
15
+ }
@@ -0,0 +1,48 @@
1
+ import { captureScreenshot, detectDisplay, displayNote, getLive, reapLiveIfIdle, refreshScreenCapabilities, registerScreenCleanup, resetScreenDetection, resetScreenState, screenCapabilities, startLive, startRecording, stopRecording, } from "./screen.js";
2
+ import { recordingPath } from "./screen-artifacts.js";
3
+ /** Android's dashboard capture implementation, isolated around the adb/ffmpeg pipeline. */
4
+ export class AndroidDashboardScreenController {
5
+ capabilities() {
6
+ return screenCapabilities();
7
+ }
8
+ refreshCapabilities() {
9
+ return refreshScreenCapabilities();
10
+ }
11
+ async captureScreenshot() {
12
+ await detectDisplay();
13
+ return captureScreenshot();
14
+ }
15
+ async startRecording() {
16
+ await detectDisplay();
17
+ if (!startLive(20))
18
+ return null;
19
+ return startRecording();
20
+ }
21
+ async stopRecording() {
22
+ const recording = await stopRecording();
23
+ // A recording can outlive the last live viewer. Once it stops, nothing should retain the
24
+ // adb screenrecord/ffmpeg pipeline in that case.
25
+ reapLiveIfIdle();
26
+ return recording;
27
+ }
28
+ isRecording() {
29
+ return getLive()?.recording !== null && getLive()?.recording !== undefined;
30
+ }
31
+ async redetect() {
32
+ resetScreenState();
33
+ await detectDisplay();
34
+ return displayNote();
35
+ }
36
+ reset() {
37
+ resetScreenState();
38
+ }
39
+ resetDetection() {
40
+ resetScreenDetection();
41
+ }
42
+ resolveRecording(file) {
43
+ return recordingPath(file);
44
+ }
45
+ registerCleanup() {
46
+ registerScreenCleanup();
47
+ }
48
+ }
@@ -33,6 +33,7 @@ export declare function parseAdbDevicesOutput(raw: string): {
33
33
  }[];
34
34
  export declare class AndroidTransport implements DeviceTransport {
35
35
  readonly platform = "android";
36
+ readonly supportsRadarHttpTools = true;
36
37
  readonly supportsLocalFileAccess = true;
37
38
  readonly supportsDeviceDashboard = true;
38
39
  private portForwarded;
@@ -160,6 +160,8 @@ export function parseAdbDevicesOutput(raw) {
160
160
  }
161
161
  export class AndroidTransport {
162
162
  platform = "android";
163
+ // The Android debug build serves Radar's HTTP API through the adb-forwarded local socket.
164
+ supportsRadarHttpTools = true;
163
165
  // adb reaches the app's databases and shared prefs through run-as, so the DB and prefs tools
164
166
  // (which shell to adb themselves) are cleared to run.
165
167
  supportsLocalFileAccess = true;
@@ -0,0 +1,35 @@
1
+ import type { DeviceTransport } from "./transport.js";
2
+ export interface DashboardScreenCapabilities {
3
+ screenshot: boolean;
4
+ liveCast: boolean;
5
+ snapshotCast: boolean;
6
+ recording: boolean;
7
+ ffmpeg: boolean;
8
+ scrcpy: boolean;
9
+ installHint: string | null;
10
+ platform: string;
11
+ }
12
+ /**
13
+ * Shared screen contract used by the dashboard. Platform implementations own every capture
14
+ * command and recording lifecycle detail; HTTP routes only enforce consent and serialize results.
15
+ */
16
+ export interface DashboardScreenController {
17
+ capabilities(): DashboardScreenCapabilities;
18
+ refreshCapabilities(): Promise<void>;
19
+ captureScreenshot(): Promise<Buffer | null>;
20
+ startRecording(): Promise<string | null>;
21
+ stopRecording(): Promise<string | null>;
22
+ isRecording(): boolean;
23
+ redetect(): Promise<string>;
24
+ reset(): void;
25
+ /**
26
+ * The safe subset of reset(): drop cached detection/capability state so the next capture
27
+ * re-detects, WITHOUT stopping recordings or deleting artifacts. This is what a same-device
28
+ * re-arm needs; reset() is reserved for real session boundaries (device swap, first enable
29
+ * of the process).
30
+ */
31
+ resetDetection(): void;
32
+ resolveRecording(file: string): string | null;
33
+ registerCleanup(): void;
34
+ }
35
+ export declare function createDashboardScreenController(transport: DeviceTransport): DashboardScreenController;
@@ -0,0 +1,12 @@
1
+ import { AndroidDashboardScreenController } from "./android-dashboard-screen.js";
2
+ import { IosDashboardScreenController } from "./ios-dashboard-screen.js";
3
+ export function createDashboardScreenController(transport) {
4
+ switch (transport.platform) {
5
+ case "android":
6
+ return new AndroidDashboardScreenController();
7
+ case "ios":
8
+ return new IosDashboardScreenController(transport);
9
+ default:
10
+ throw new Error(`Screen capture is not supported for platform: ${transport.platform}`);
11
+ }
12
+ }
@@ -0,0 +1,32 @@
1
+ import type { DashboardScreenCapabilities, DashboardScreenController } from "./dashboard-screen.js";
2
+ import type { DeviceTransport } from "./transport.js";
3
+ export interface IosRecordingHandle {
4
+ readonly started: Promise<void>;
5
+ isRunning(): boolean;
6
+ stop(): Promise<void>;
7
+ kill(): void;
8
+ }
9
+ export type IosRecordingStarter = (simulatorUdid: string, outputPath: string) => IosRecordingHandle;
10
+ /** Start simctl's open-ended recorder and expose its readiness/finalization lifecycle. */
11
+ export declare function startIosSimulatorRecording(simulatorUdid: string, outputPath: string): IosRecordingHandle;
12
+ /** iOS Simulator's dashboard capture implementation, isolated around simctl. */
13
+ export declare class IosDashboardScreenController implements DashboardScreenController {
14
+ private readonly transport;
15
+ private readonly startSimulatorRecording;
16
+ private recording;
17
+ private cleanupRegistered;
18
+ private caps;
19
+ constructor(transport: DeviceTransport, startSimulatorRecording?: IosRecordingStarter);
20
+ capabilities(): DashboardScreenCapabilities;
21
+ refreshCapabilities(): Promise<void>;
22
+ private buildCaps;
23
+ captureScreenshot(): Promise<Buffer | null>;
24
+ startRecording(): Promise<string | null>;
25
+ stopRecording(): Promise<string | null>;
26
+ isRecording(): boolean;
27
+ redetect(): Promise<string>;
28
+ reset(): void;
29
+ resetDetection(): void;
30
+ resolveRecording(file: string): string | null;
31
+ registerCleanup(): void;
32
+ }