@rnzeus/heimdall-sdk 0.6.1 → 0.7.1

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.
Files changed (50) hide show
  1. package/README.md +47 -5
  2. package/dist/core/connection/session/constants.d.ts +2 -0
  3. package/dist/core/connection/session/constants.js +9 -2
  4. package/dist/core/connection/socket/capabilities.d.ts +7 -0
  5. package/dist/core/connection/socket/capabilities.js +8 -0
  6. package/dist/core/connection/socket/connect-socket.js +15 -9
  7. package/dist/core/connection/socket/host-lines.d.ts +5 -0
  8. package/dist/core/connection/socket/host-lines.js +16 -0
  9. package/dist/core/connection/socket/host-message.d.ts +12 -0
  10. package/dist/core/connection/socket/host-message.js +62 -0
  11. package/dist/core/connection/socket/index.d.ts +2 -0
  12. package/dist/core/connection/socket/index.js +2 -0
  13. package/dist/core/connection/socket/secure-transport.js +4 -11
  14. package/dist/core/connection/socket/send-event.d.ts +2 -1
  15. package/dist/core/connection/socket/send-event.js +4 -2
  16. package/dist/core/frames/index.d.ts +43 -0
  17. package/dist/core/frames/index.js +140 -0
  18. package/dist/frames/index.d.ts +11 -0
  19. package/dist/frames/index.js +35 -0
  20. package/dist/noop/frames.d.ts +2 -0
  21. package/dist/noop/frames.js +1 -0
  22. package/dist/public/prompt/component.js +3 -3
  23. package/dist/public/prompt/local-network.d.ts +31 -0
  24. package/dist/public/prompt/local-network.js +34 -0
  25. package/dist/public/prompt/theme.d.ts +6 -1
  26. package/dist/public/prompt/theme.js +23 -21
  27. package/dist/public/prompt/ui/action-button.d.ts +2 -1
  28. package/dist/public/prompt/ui/action-button.js +14 -3
  29. package/dist/public/prompt/ui/footer.d.ts +5 -2
  30. package/dist/public/prompt/ui/footer.js +3 -4
  31. package/dist/public/prompt/ui/header.js +2 -2
  32. package/dist/public/prompt/ui/screen-recording.d.ts +8 -0
  33. package/dist/public/prompt/ui/screen-recording.js +40 -0
  34. package/dist/public/prompt/ui/status-line.d.ts +11 -0
  35. package/dist/public/prompt/ui/status-line.js +12 -0
  36. package/dist/public/prompt/use-connect-awaiter.d.ts +3 -2
  37. package/dist/public/prompt/use-connect-awaiter.js +55 -9
  38. package/dist/public/prompt/views/cloud-view.d.ts +3 -1
  39. package/dist/public/prompt/views/cloud-view.js +4 -2
  40. package/dist/public/prompt/views/connected-view.js +2 -1
  41. package/dist/public/prompt/views/manual-view.d.ts +5 -2
  42. package/dist/public/prompt/views/manual-view.js +4 -2
  43. package/dist/version.d.ts +1 -1
  44. package/dist/version.js +1 -1
  45. package/frames/index.d.ts +1 -0
  46. package/frames/index.js +1 -0
  47. package/metro/index.cjs +8 -2
  48. package/noop/frames.d.ts +1 -0
  49. package/noop/frames.js +1 -0
  50. package/package.json +22 -2
package/README.md CHANGED
@@ -7,6 +7,7 @@ React Native client for **Heimdall** — a desktop debug inspector for dev and s
7
7
  - **Zustand** — state snapshots per store, with the action that caused them
8
8
  - **Console** — `console.*`, uncaught JS errors and unhandled promise rejections
9
9
  - **App and device info** — version, build, environment, OS, model
10
+ - **Screenshots** — optional: the screen around a bug, with the taps on it, for bug reports
10
11
 
11
12
  ![Heimdall desktop app: network inspector](https://heimdall.rnzeus.dev/readme/network.png)
12
13
 
@@ -21,6 +22,7 @@ It is built for development and stage builds only and is off by default in produ
21
22
  | `react-native-tcp-socket` | `>=6` | transport |
22
23
  | `react-native-mmkv` | `>=3` | remembers the last connection |
23
24
  | `zustand` | `>=3` | optional, only for the Zustand middleware |
25
+ | [`@rnzeus/heimdall-lens`](https://github.com/rnzeus/heimdall-lens) | `>=0.1` | optional, only for screenshots in bug reports |
24
26
 
25
27
  `react-native-tcp-socket` and `react-native-mmkv` are native modules. With Expo you need a [development build](https://docs.expo.dev/develop/development-builds/introduction/) — Expo Go will not work.
26
28
 
@@ -127,6 +129,31 @@ A report can also start from one event — a request, a log line, a socket frame
127
129
 
128
130
  Trackers are connected in the desktop app (Settings → Integrations); nothing extra is needed in your code. Adapters are open source: [`@rnzeus/heimdall-trackers`](https://github.com/rnzeus/heimdall-trackers).
129
131
 
132
+ ## Screenshots in bug reports
133
+
134
+ A report can show the screen around the bug: what the tester tapped and what they saw after it. Install the native module and turn it on once at startup:
135
+
136
+ ```sh
137
+ yarn add @rnzeus/heimdall-lens
138
+ cd ios && pod install
139
+ ```
140
+
141
+ ```ts
142
+ import { heimdallFrames } from "@rnzeus/heimdall-sdk/frames";
143
+
144
+ heimdallFrames();
145
+ ```
146
+
147
+ - **When.** Capture runs only while Heimdall is connected and screen capture is on in it (Settings → Connection). A screenshot is taken at a tap, once the screen settles after it, and when a report is opened in Heimdall — not on a timer. Scrolls are not recorded.
148
+ - **How.** Android copies the window with `PixelCopy` off the UI thread. iOS records the app's own screen with `ReplayKit` — it asks the tester once; without the permission iOS sends a single snapshot of the app's views when a report asks for it, where forms and video may come out blank. Capture slows down or pauses on its own when the device is busy.
149
+ - **What is in them.** Only your app's window: other apps, notifications and the system UI are not captured. The screenshots are not masked — the mask of a report does not cover what is on the screen.
150
+ - **The tester decides.** The connect prompt has a switch, **Record the screen for bug reports**. Off, the device sends nothing, and the choice is remembered.
151
+ - Screenshots stay in the desktop app's memory for a few minutes and go only into the reports the tester attaches them to.
152
+
153
+ Without `@rnzeus/heimdall-lens` in the app, `heimdallFrames()` does nothing and warns in development.
154
+
155
+ To leave the module out of production builds, together with the SDK, see [Removing the SDK from production builds](#removing-the-sdk-from-production-builds).
156
+
130
157
  ## Without the prompt
131
158
 
132
159
  ```ts
@@ -198,7 +225,7 @@ The cloud only stores accounts, devices and the current address of the desktop.
198
225
 
199
226
  ## Removing the SDK from production builds
200
227
 
201
- This is optional: without it the SDK works as described above. With `enabled: false` the SDK is off, but its code and `react-native-tcp-socket` are still in the build. To leave them out of production builds:
228
+ This is optional: without it the SDK works as described above. With `enabled: false` the SDK is off, but its code and its native modules (`react-native-tcp-socket`, and `@rnzeus/heimdall-lens` if you added it) are still in the build. To leave them out of production builds:
202
229
 
203
230
  **1. Replace the SDK with no-ops in `metro.config.js`:**
204
231
 
@@ -215,24 +242,28 @@ module.exports = withHeimdall(config, {
215
242
  });
216
243
  ```
217
244
 
218
- - `include: false` — `@rnzeus/heimdall-sdk` and `@rnzeus/heimdall-sdk/zustand` are replaced with modules that have the same API and do nothing: `connect` and the other calls are no-ops, `<HeimdallConnectPrompt />` renders nothing, `heimdallZustand` returns your store creator as is. Your code does not change.
245
+ - `include: false` — `@rnzeus/heimdall-sdk`, `@rnzeus/heimdall-sdk/zustand` and `@rnzeus/heimdall-sdk/frames` are replaced with modules that have the same API and do nothing: `connect` and the other calls are no-ops, `<HeimdallConnectPrompt />` renders nothing, `heimdallZustand` returns your store creator as is, `heimdallFrames` does nothing. Your code does not change.
219
246
  - `include: true` — the config is returned unchanged.
220
247
  - The `include` option has no default, so the choice is always explicit. Wrap your final config, after any other wrappers.
221
248
  - Any other runtime import of the SDK, such as `@rnzeus/heimdall-sdk/dist/...`, fails the build with an error that names the file. Type-only imports (`import type`) are fine.
222
249
 
223
- **2. Leave the native module out** in `react-native.config.js`:
250
+ **2. Leave the native modules out** in `react-native.config.js`:
224
251
 
225
252
  ```js
226
253
  const production = process.env.APP_ENV === "production";
227
254
 
228
255
  module.exports = {
229
256
  dependencies: production
230
- ? { "react-native-tcp-socket": { platforms: { ios: null, android: null } } }
257
+ ? {
258
+ "react-native-tcp-socket": { platforms: { ios: null, android: null } },
259
+ // only if you added it for screenshots
260
+ "@rnzeus/heimdall-lens": { platforms: { ios: null, android: null } },
261
+ }
231
262
  : {},
232
263
  };
233
264
  ```
234
265
 
235
- Do this only together with step 1, otherwise the app crashes on the missing native module. The setting applies to the whole `pod install` run, so run `pod install` again without the variable before a dev or stage build. Leave `react-native-mmkv` alone if your app uses it for anything else.
266
+ Do this only together with step 1, otherwise the app crashes on the missing native modules. The setting applies to the whole `pod install` run, so run `pod install` again without the variable before a dev or stage build. Leave `react-native-mmkv` alone if your app uses it for anything else.
236
267
 
237
268
  **Which variable to use.** Both files read environment variables of the build process. Use one that is set for the whole build — usually a variable of your CI job, such as the build stage. Values from `.env` files are not visible here. `APP_ENV` above is only an example.
238
269
 
@@ -242,6 +273,7 @@ A production bundle built this way contains no `heimdall://` strings — only th
242
273
 
243
274
  - Events go **directly** from the app to the Heimdall desktop app over TCP on your network, encrypted with TLS when connected through the cloud. Nothing is sent to us or to any third party.
244
275
  - Headers and bodies are sent **as they are**, including auth tokens; a manual connection carries them unencrypted. Use the SDK in dev and stage builds, and narrow the capture with `allowedHosts` / `ignoreUrls` where needed.
276
+ - Screenshots, when turned on, go the same way and are not masked; see [Screenshots in bug reports](#screenshots-in-bug-reports).
245
277
  - `cloud` is optional and never sees captured traffic — see [Connecting without typing an address](#connecting-without-typing-an-address).
246
278
 
247
279
  ## Testing with Jest
@@ -268,6 +300,16 @@ jest.mock("react-native-tcp-socket", () => ({ createConnection: jest.fn() }));
268
300
 
269
301
  [`example/`](./example) is a minimal React Native app with ready-made network, WebSocket, Zustand and console scenarios.
270
302
 
303
+ ## Heimdall ecosystem
304
+
305
+ | | |
306
+ |---|---|
307
+ | [Heimdall desktop](https://heimdall.rnzeus.dev/download) | the inspector for macOS and Windows |
308
+ | [`@rnzeus/heimdall-sdk`](https://github.com/rnzeus/heimdall-sdk) | React Native client: network, WebSocket, state, console |
309
+ | [`@rnzeus/heimdall-lens`](https://github.com/rnzeus/heimdall-lens) | native screenshots and taps for bug reports |
310
+ | [`@rnzeus/heimdall-protocol`](https://github.com/rnzeus/heimdall-protocol) | messages between the SDK and the desktop app |
311
+ | [`@rnzeus/heimdall-trackers`](https://github.com/rnzeus/heimdall-trackers) | issue tracker adapters for bug reports |
312
+
271
313
  ## License
272
314
 
273
315
  MIT
@@ -5,6 +5,8 @@ export declare const SESSION: {
5
5
  KEY_LAST_PORT: string;
6
6
  KEY_LAST_CHANNEL: string;
7
7
  KEY_LAST_SOURCE: string;
8
+ /** "off" when the tester turned screen recording off on this device */
9
+ KEY_FRAMES_RECORDING: string;
8
10
  };
9
11
  type SessionStorage = {
10
12
  getString(key: string): string | undefined;
@@ -6,12 +6,19 @@ export const SESSION = {
6
6
  KEY_LAST_PORT: "lastPort",
7
7
  KEY_LAST_CHANNEL: "lastChannel",
8
8
  KEY_LAST_SOURCE: "lastSource",
9
+ /** "off" when the tester turned screen recording off on this device */
10
+ KEY_FRAMES_RECORDING: "framesRecording",
9
11
  };
10
12
  function createSessionStorage() {
11
13
  const mmkv = MMKVModule;
12
- // react-native-mmkv v4+
14
+ // react-native-mmkv v4+ renamed delete to remove
13
15
  if (typeof mmkv.createMMKV === "function") {
14
- return mmkv.createMMKV({ id: SESSION.STORAGE_ID });
16
+ const storage = mmkv.createMMKV({ id: SESSION.STORAGE_ID });
17
+ return {
18
+ getString: (key) => storage.getString(key),
19
+ set: (key, value) => storage.set(key, value),
20
+ delete: (key) => storage.remove(key),
21
+ };
15
22
  }
16
23
  // react-native-mmkv v3
17
24
  if (typeof mmkv.MMKV === "function") {
@@ -0,0 +1,7 @@
1
+ import type { HelloCapabilities } from "@rnzeus/heimdall-protocol";
2
+ /** Optional features announced in `hello`; set by the feature when the app turns it on. */
3
+ export declare function setCapability<K extends keyof HelloCapabilities>({ name, value, }: {
4
+ name: K;
5
+ value: HelloCapabilities[K];
6
+ }): void;
7
+ export declare function getCapabilities(): HelloCapabilities | undefined;
@@ -0,0 +1,8 @@
1
+ let capabilities = {};
2
+ /** Optional features announced in `hello`; set by the feature when the app turns it on. */
3
+ export function setCapability({ name, value, }) {
4
+ capabilities = { ...capabilities, [name]: value };
5
+ }
6
+ export function getCapabilities() {
7
+ return Object.keys(capabilities).length > 0 ? capabilities : undefined;
8
+ }
@@ -5,6 +5,9 @@ import { handleSocketLost } from "./handle-socket-lost.js";
5
5
  import { flushEarlyEvents } from "./flush-early-events.js";
6
6
  import { normalizeSocketError } from "./normalize-socket-error.js";
7
7
  import { SOCKET } from "./constants.js";
8
+ import { getCapabilities } from "./capabilities.js";
9
+ import { handleHostLine } from "./host-message.js";
10
+ import { readHostLines } from "./host-lines.js";
8
11
  import { getCurrentSession, setCurrentSession, } from "../session/index.js";
9
12
  import { SDK_VERSION } from "../../../version.js";
10
13
  import { normaliseAppInfo, readDeviceInfo } from "../../system/index.js";
@@ -32,6 +35,9 @@ function buildHello({ session, options, secure, }) {
32
35
  hello.app = app;
33
36
  if (secure)
34
37
  hello.auth = { token: secure.token };
38
+ const capabilities = getCapabilities();
39
+ if (capabilities)
40
+ hello.capabilities = capabilities;
35
41
  return hello;
36
42
  }
37
43
  function fail(message) {
@@ -87,6 +93,7 @@ export function connectSocket(optionsOrSession) {
87
93
  const onPlainConnect = () => {
88
94
  clearTimeout(connectTimeout);
89
95
  setConnected(true);
96
+ readHostLines({ socket: newSocket, onLine: handleHostLine });
90
97
  try {
91
98
  newSocket.write(JSON.stringify(buildHello({ session, options })) + "\r\n");
92
99
  }
@@ -104,21 +111,20 @@ export function connectSocket(optionsOrSession) {
104
111
  fail(CERTIFICATE_MISMATCH);
105
112
  return;
106
113
  }
107
- let pending = "";
114
+ let answered = false;
108
115
  const answerTimeout = setTimeout(() => {
109
116
  if (getSocket() === newSocket && !isConnected())
110
117
  fail(NO_ANSWER);
111
118
  }, HOST_ANSWER_TIMEOUT_MS);
112
- const onData = (data) => {
113
- var _a;
114
- pending += typeof data === "string" ? data : String(data);
115
- const end = pending.indexOf("\r\n");
116
- if (end === -1)
119
+ const onLine = (line) => {
120
+ if (answered) {
121
+ handleHostLine(line);
117
122
  return;
118
- (_a = newSocket.off) === null || _a === void 0 ? void 0 : _a.call(newSocket, "data", onData);
123
+ }
124
+ answered = true;
119
125
  clearTimeout(answerTimeout);
120
126
  clearTimeout(connectTimeout);
121
- const answer = parseHostAnswer(pending.slice(0, end));
127
+ const answer = parseHostAnswer(line);
122
128
  if (!answer) {
123
129
  fail(NO_ANSWER);
124
130
  return;
@@ -130,7 +136,7 @@ export function connectSocket(optionsOrSession) {
130
136
  setConnected(true);
131
137
  flushEarlyEvents();
132
138
  };
133
- newSocket.on("data", onData);
139
+ readHostLines({ socket: newSocket, onLine });
134
140
  try {
135
141
  newSocket.write(JSON.stringify(buildHello({ session, options, secure })) + "\r\n");
136
142
  }
@@ -0,0 +1,5 @@
1
+ /** The host writes one JSON message per line; calls `onLine` for every complete line until unsubscribed. */
2
+ export declare function readHostLines({ socket, onLine, }: {
3
+ socket: any;
4
+ onLine: (line: string) => void;
5
+ }): () => void;
@@ -0,0 +1,16 @@
1
+ /** The host writes one JSON message per line; calls `onLine` for every complete line until unsubscribed. */
2
+ export function readHostLines({ socket, onLine, }) {
3
+ let pending = "";
4
+ const onData = (data) => {
5
+ pending += typeof data === "string" ? data : String(data);
6
+ let end = pending.indexOf("\r\n");
7
+ while (end !== -1) {
8
+ const line = pending.slice(0, end);
9
+ pending = pending.slice(end + 2);
10
+ onLine(line);
11
+ end = pending.indexOf("\r\n");
12
+ }
13
+ };
14
+ socket.on("data", onData);
15
+ return () => { var _a; return (_a = socket.off) === null || _a === void 0 ? void 0 : _a.call(socket, "data", onData); };
16
+ }
@@ -0,0 +1,12 @@
1
+ import type { HostConfigFrames } from "@rnzeus/heimdall-protocol";
2
+ /** A host message of wire version 1, or null when the line is not one. */
3
+ export declare function parseHostMessage(line: string): Record<string, unknown> | null;
4
+ export type HostConfig = {
5
+ frames?: HostConfigFrames;
6
+ };
7
+ export declare function parseHostConfig(line: string): HostConfig | null;
8
+ /** Notified with every `hostConfig` the host sends; the latest one wins. */
9
+ export declare function subscribeHostConfig(listener: (config: HostConfig) => void): () => void;
10
+ /** Notified when the host asks for a frame of the screen now (`captureScreen`). */
11
+ export declare function subscribeCaptureScreen(listener: () => void): () => void;
12
+ export declare function handleHostLine(line: string): void;
@@ -0,0 +1,62 @@
1
+ /** A host message of wire version 1, or null when the line is not one. */
2
+ export function parseHostMessage(line) {
3
+ let json;
4
+ try {
5
+ json = JSON.parse(line);
6
+ }
7
+ catch {
8
+ return null;
9
+ }
10
+ if (!json || typeof json !== "object")
11
+ return null;
12
+ const message = json;
13
+ return typeof message.kind === "string" && message.v === 1 ? message : null;
14
+ }
15
+ const optionalNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
16
+ // Hand-written on purpose, like parseHostAnswer: mirrors the tolerant HostConfigWireMessageV1Schema,
17
+ // unknown sections and fields are ignored.
18
+ export function parseHostConfig(line) {
19
+ const message = parseHostMessage(line);
20
+ if ((message === null || message === void 0 ? void 0 : message.kind) !== "hostConfig")
21
+ return null;
22
+ const { frames } = message;
23
+ if (frames === undefined)
24
+ return {};
25
+ if (!frames || typeof frames !== "object")
26
+ return null;
27
+ const { enabled, fps, maxWidth } = frames;
28
+ if (typeof enabled !== "boolean")
29
+ return null;
30
+ return {
31
+ frames: { enabled, fps: optionalNumber(fps), maxWidth: optionalNumber(maxWidth) },
32
+ };
33
+ }
34
+ const configListeners = new Set();
35
+ /** Notified with every `hostConfig` the host sends; the latest one wins. */
36
+ export function subscribeHostConfig(listener) {
37
+ configListeners.add(listener);
38
+ return () => {
39
+ configListeners.delete(listener);
40
+ };
41
+ }
42
+ const captureListeners = new Set();
43
+ /** Notified when the host asks for a frame of the screen now (`captureScreen`). */
44
+ export function subscribeCaptureScreen(listener) {
45
+ captureListeners.add(listener);
46
+ return () => {
47
+ captureListeners.delete(listener);
48
+ };
49
+ }
50
+ export function handleHostLine(line) {
51
+ var _a;
52
+ const config = parseHostConfig(line);
53
+ if (config) {
54
+ for (const listener of configListeners)
55
+ listener(config);
56
+ return;
57
+ }
58
+ if (((_a = parseHostMessage(line)) === null || _a === void 0 ? void 0 : _a.kind) === "captureScreen") {
59
+ for (const listener of captureListeners)
60
+ listener();
61
+ }
62
+ }
@@ -4,3 +4,5 @@ export * from "./destroy-socket";
4
4
  export * from "./send-event";
5
5
  export * from "./early-buffer";
6
6
  export * from "./state";
7
+ export { setCapability } from "./capabilities";
8
+ export { subscribeCaptureScreen, subscribeHostConfig } from "./host-message";
@@ -4,3 +4,5 @@ export * from "./destroy-socket.js";
4
4
  export * from "./send-event.js";
5
5
  export * from "./early-buffer.js";
6
6
  export * from "./state.js";
7
+ export { setCapability } from "./capabilities.js";
8
+ export { subscribeCaptureScreen, subscribeHostConfig } from "./host-message.js";
@@ -1,3 +1,4 @@
1
+ import { parseHostMessage } from "./host-message.js";
1
2
  const REJECT_REASONS = [
2
3
  "auth",
3
4
  "channel",
@@ -34,18 +35,10 @@ export async function readPeerCertificate(socket) {
34
35
  // Hand-written on purpose: the protocol schemas would pull zod into every consumer app. Mirrors the
35
36
  // tolerant HelloAckWireMessageV1Schema: extra fields are ignored, an unknown reason becomes undefined.
36
37
  export function parseHostAnswer(line) {
37
- let json;
38
- try {
39
- json = JSON.parse(line);
40
- }
41
- catch {
42
- return null;
43
- }
44
- if (!json || typeof json !== "object")
45
- return null;
46
- const { kind, v, status, reason } = json;
47
- if (kind !== "helloAck" || v !== 1)
38
+ const message = parseHostMessage(line);
39
+ if ((message === null || message === void 0 ? void 0 : message.kind) !== "helloAck")
48
40
  return null;
41
+ const { status, reason } = message;
49
42
  if (status === "accepted")
50
43
  return { accepted: true };
51
44
  if (status !== "rejected")
@@ -1,3 +1,4 @@
1
1
  import type { EventWirePayload } from "../../../types";
2
2
  export declare function sendEvent(payload: EventWirePayload): void;
3
- export declare function internalSendNetworkEvent(payload: EventWirePayload): void;
3
+ /** @returns false when the event was not handed to the socket */
4
+ export declare function internalSendNetworkEvent(payload: EventWirePayload): boolean;
@@ -19,12 +19,13 @@ export function sendEvent(payload) {
19
19
  }
20
20
  internalSendNetworkEvent(payload);
21
21
  }
22
+ /** @returns false when the event was not handed to the socket */
22
23
  export function internalSendNetworkEvent(payload) {
23
24
  const currentSession = getCurrentSession();
24
25
  const socket = getSocket();
25
26
  const connected = isConnected();
26
27
  if (!socket || !connected || !currentSession)
27
- return;
28
+ return false;
28
29
  const { options, clientId, sessionId } = currentSession;
29
30
  const message = {
30
31
  kind: "event",
@@ -39,8 +40,9 @@ export function internalSendNetworkEvent(payload) {
39
40
  };
40
41
  try {
41
42
  socket.write(JSON.stringify(message) + "\r\n");
43
+ return true;
42
44
  }
43
45
  catch {
44
- // ignore
46
+ return false;
45
47
  }
46
48
  }
@@ -0,0 +1,43 @@
1
+ import type { FrameSource, FramesCapability, FramesStatusEventPayload, ScreenTapEventPayload } from "@rnzeus/heimdall-protocol";
2
+ type FramesSourceFrame = {
3
+ data: string;
4
+ width: number;
5
+ height: number;
6
+ ts: number;
7
+ source?: FrameSource;
8
+ };
9
+ type FramesSourceTap = Pick<ScreenTapEventPayload, "x" | "y" | "ts" | "kind">;
10
+ type FramesSourceStatus = Pick<FramesStatusEventPayload, "state" | "reason" | "fps" | "deviceClass" | "source">;
11
+ /** A native screen capturer, e.g. @rnzeus/heimdall-lens; the SDK only decides when it runs. */
12
+ export type FramesSource = {
13
+ capability: FramesCapability;
14
+ start: (options: {
15
+ fps: number;
16
+ maxWidth: number;
17
+ allowRecording: boolean;
18
+ }) => void;
19
+ stop: () => void;
20
+ /** one frame of the screen as it is now, also while no loop runs */
21
+ captureNow: (options: {
22
+ maxWidth: number;
23
+ }) => Promise<FramesSourceFrame>;
24
+ subscribe: (handlers: {
25
+ onFrame: (frame: FramesSourceFrame) => void;
26
+ onStatus: (status: FramesSourceStatus) => void;
27
+ onTap: (tap: FramesSourceTap) => void;
28
+ }) => () => void;
29
+ };
30
+ /** What the connect prompt shows: whether this app can capture, the tester's choice and how capture goes. */
31
+ export type FramesRecordingState = {
32
+ isAvailable: boolean;
33
+ /** the tester's choice on this device, kept across launches */
34
+ isAllowed: boolean;
35
+ status: FramesSourceStatus | null;
36
+ };
37
+ export declare function getFramesRecordingState(): FramesRecordingState;
38
+ export declare function subscribeFramesRecording(listener: () => void): () => void;
39
+ /** The tester's choice: off keeps frames off on this device — iOS does not even ask — until turned back on. */
40
+ export declare function setFramesRecordingAllowed(isAllowed: boolean): void;
41
+ /** Announces frames in `hello`; capture runs only while the host asks for it over a live connection. */
42
+ export declare function registerFramesSource(next: FramesSource): void;
43
+ export {};
@@ -0,0 +1,140 @@
1
+ import { generateRandomId } from "../../utils/index.js";
2
+ import { getSocket, internalSendNetworkEvent, isConnected, setCapability, subscribeCaptureScreen, subscribeHostConfig, subscribeSocketState, } from "../connection/index.js";
3
+ import { SESSION, SESSION_STORAGE } from "../connection/session/constants.js";
4
+ let source = null;
5
+ let running = null;
6
+ let unsubscribeSource = null;
7
+ let lastHostFrames;
8
+ const RECORDING_OFF = "off";
9
+ let recordingState = {
10
+ isAvailable: false,
11
+ isAllowed: SESSION_STORAGE.getString(SESSION.KEY_FRAMES_RECORDING) !== RECORDING_OFF,
12
+ status: null,
13
+ };
14
+ const recordingListeners = new Set();
15
+ function updateRecordingState(next) {
16
+ recordingState = { ...recordingState, ...next };
17
+ for (const listener of recordingListeners)
18
+ listener();
19
+ }
20
+ export function getFramesRecordingState() {
21
+ return recordingState;
22
+ }
23
+ export function subscribeFramesRecording(listener) {
24
+ recordingListeners.add(listener);
25
+ return () => {
26
+ recordingListeners.delete(listener);
27
+ };
28
+ }
29
+ /** The tester's choice: off keeps frames off on this device — iOS does not even ask — until turned back on. */
30
+ export function setFramesRecordingAllowed(isAllowed) {
31
+ if (isAllowed)
32
+ SESSION_STORAGE.delete(SESSION.KEY_FRAMES_RECORDING);
33
+ else
34
+ SESSION_STORAGE.set(SESSION.KEY_FRAMES_RECORDING, RECORDING_OFF);
35
+ updateRecordingState({ isAllowed });
36
+ applyFrames(lastHostFrames);
37
+ }
38
+ function sendFrame(frame) {
39
+ var _a;
40
+ // Frames are the first thing to give up: never queued, dropped while the socket is still busy.
41
+ if ((_a = getSocket()) === null || _a === void 0 ? void 0 : _a.writableNeedDrain)
42
+ return;
43
+ sendFrameNow(frame);
44
+ }
45
+ function sendFrameNow(frame) {
46
+ internalSendNetworkEvent({
47
+ type: "screenFrame",
48
+ id: generateRandomId(),
49
+ ts: frame.ts,
50
+ width: frame.width,
51
+ height: frame.height,
52
+ mime: "image/jpeg",
53
+ data: frame.data,
54
+ source: frame.source,
55
+ });
56
+ }
57
+ function sendStatus(status) {
58
+ updateRecordingState({ status });
59
+ internalSendNetworkEvent({
60
+ type: "framesStatus",
61
+ id: generateRandomId(),
62
+ ts: Date.now(),
63
+ state: status.state,
64
+ reason: status.reason,
65
+ fps: status.fps,
66
+ deviceClass: status.deviceClass,
67
+ source: status.source,
68
+ });
69
+ }
70
+ // Taps are tiny and mark where frames were touched, so unlike frames they are never dropped.
71
+ function sendTap(tap) {
72
+ internalSendNetworkEvent({
73
+ type: "screenTap",
74
+ id: generateRandomId(),
75
+ ts: tap.ts,
76
+ x: tap.x,
77
+ y: tap.y,
78
+ kind: tap.kind,
79
+ });
80
+ }
81
+ function stopCapture() {
82
+ if (!source || !running)
83
+ return;
84
+ running = null;
85
+ updateRecordingState({ status: null });
86
+ unsubscribeSource === null || unsubscribeSource === void 0 ? void 0 : unsubscribeSource();
87
+ unsubscribeSource = null;
88
+ source.stop();
89
+ }
90
+ /** The host asks for a rate and width; the SDK never goes above what the app allowed. */
91
+ function applyFrames(frames) {
92
+ var _a, _b;
93
+ lastHostFrames = frames;
94
+ if (!source)
95
+ return;
96
+ if (!(frames === null || frames === void 0 ? void 0 : frames.enabled) || !isConnected()) {
97
+ stopCapture();
98
+ return;
99
+ }
100
+ const { maxFps, maxWidth } = source.capability;
101
+ const next = {
102
+ fps: Math.min((_a = frames.fps) !== null && _a !== void 0 ? _a : maxFps, maxFps),
103
+ maxWidth: Math.min((_b = frames.maxWidth) !== null && _b !== void 0 ? _b : maxWidth, maxWidth),
104
+ allowRecording: recordingState.isAllowed,
105
+ };
106
+ if (running &&
107
+ running.fps === next.fps &&
108
+ running.maxWidth === next.maxWidth &&
109
+ running.allowRecording === next.allowRecording) {
110
+ return;
111
+ }
112
+ stopCapture();
113
+ running = next;
114
+ unsubscribeSource = source.subscribe({ onFrame: sendFrame, onStatus: sendStatus, onTap: sendTap });
115
+ source.start(next);
116
+ }
117
+ /** Announces frames in `hello`; capture runs only while the host asks for it over a live connection. */
118
+ export function registerFramesSource(next) {
119
+ if (source)
120
+ return;
121
+ source = next;
122
+ setCapability({ name: "frames", value: next.capability });
123
+ updateRecordingState({ isAvailable: true });
124
+ subscribeHostConfig((config) => applyFrames(config.frames));
125
+ subscribeCaptureScreen(captureScreen);
126
+ subscribeSocketState(() => {
127
+ if (!isConnected())
128
+ stopCapture();
129
+ });
130
+ }
131
+ /** A bug report opened on the host: the screen as it is now, also while frames are off — not if the tester said no. */
132
+ function captureScreen() {
133
+ var _a;
134
+ if (!source || !isConnected() || !recordingState.isAllowed)
135
+ return;
136
+ source
137
+ .captureNow({ maxWidth: (_a = running === null || running === void 0 ? void 0 : running.maxWidth) !== null && _a !== void 0 ? _a : source.capability.maxWidth })
138
+ .then(sendFrameNow)
139
+ .catch(() => { });
140
+ }
@@ -0,0 +1,11 @@
1
+ export type HeimdallFramesOptions = {
2
+ /** upper bound for the rate the host may ask for; 2 by default */
3
+ maxFps?: number;
4
+ /** upper bound for the frame width in pixels; 480 by default */
5
+ maxWidth?: number;
6
+ };
7
+ /**
8
+ * Lets Heimdall attach the last seconds of the screen to a bug report. Call once at startup; capture
9
+ * runs only while Heimdall is connected and asks for frames. Needs `@rnzeus/heimdall-lens` in the app.
10
+ */
11
+ export declare function heimdallFrames(options?: HeimdallFramesOptions): void;
@@ -0,0 +1,35 @@
1
+ import { addFrameListener, addStatusListener, addTapListener, captureFrame, isFramesAvailable, startFrames, stopFrames, } from "@rnzeus/heimdall-lens";
2
+ import { registerFramesSource } from "../core/frames/index.js";
3
+ const DEFAULT_MAX_FPS = 2;
4
+ const DEFAULT_MAX_WIDTH = 480;
5
+ /**
6
+ * Lets Heimdall attach the last seconds of the screen to a bug report. Call once at startup; capture
7
+ * runs only while Heimdall is connected and asks for frames. Needs `@rnzeus/heimdall-lens` in the app.
8
+ */
9
+ export function heimdallFrames(options = {}) {
10
+ var _a, _b;
11
+ if (!isFramesAvailable()) {
12
+ if (__DEV__) {
13
+ console.warn("[Heimdall] heimdallFrames: @rnzeus/heimdall-lens is not linked, rebuild the app after installing it.");
14
+ }
15
+ return;
16
+ }
17
+ registerFramesSource({
18
+ capability: {
19
+ maxFps: (_a = options.maxFps) !== null && _a !== void 0 ? _a : DEFAULT_MAX_FPS,
20
+ maxWidth: (_b = options.maxWidth) !== null && _b !== void 0 ? _b : DEFAULT_MAX_WIDTH,
21
+ },
22
+ start: ({ fps, maxWidth, allowRecording }) => startFrames({ fps, maxWidth, allowRecording }),
23
+ captureNow: ({ maxWidth }) => captureFrame({ maxWidth }),
24
+ stop: () => {
25
+ stopFrames().catch(() => { });
26
+ },
27
+ subscribe: ({ onFrame, onStatus, onTap }) => {
28
+ const subscriptions = [addFrameListener(onFrame), addStatusListener(onStatus), addTapListener(onTap)];
29
+ return () => {
30
+ for (const subscription of subscriptions)
31
+ subscription.remove();
32
+ };
33
+ },
34
+ });
35
+ }
@@ -0,0 +1,2 @@
1
+ import type * as Sdk from "../frames";
2
+ export declare const heimdallFrames: typeof Sdk.heimdallFrames;
@@ -0,0 +1 @@
1
+ export const heimdallFrames = () => { };