@axonpack/react-native-devtools-tab 0.1.0

package/src/renderer/services/__tests__/remote-receiver.test.ts

@@ -0,0 +1,126 @@
+import { expect, test } from "bun:test";
+
+import type { RemoteOp } from "../../../core/constants/remote-op.const";
+import {
+  createRemoteReceiver,
+  type RemoteNode,
+} from "../remote-receiver.service";
+
+/**
+ * Ops by hand, so these say what an op means rather than what React happens to emit.
+ *
+ * The tree only, with no document anywhere: this side stopped building elements when
+ * react-native-web took that job over, and what it holds now is what the panel's React renders
+ * from. `remote-tree.component` is where that rendering is tested.
+ */
+function receive() {
+  const receiver = createRemoteReceiver();
+
+  return { receiver, apply: (...ops: RemoteOp[]) => receiver.apply(ops) };
+}
+
+/** What is on screen, as a plain object a failed expectation can print in full. */
+
+function shapeOf(node: RemoteNode): unknown {
+  if (node.type === "#text") return node.text;
+  return {
+    type: node.type,
+    props: node.props,
+    children: node.children.map(shapeOf),
+  };
+}
+
+test("a prop that stops being sent is dropped rather than carried as null", () => {
+  const { receiver, apply } = receive();
+
+  apply(
+    { op: "create", id: 1, type: "div", props: { title: "wait", id: "busy" } },
+    { op: "append", parent: 0, child: 1 },
+  );
+  expect(receiver.root.children[0].props).toEqual({
+    title: "wait",
+    id: "busy",
+  });
+
+  // What the sender emits once React drops both props. Carrying the null on would hand React a
+  // `title={null}`, which is a prop that is still there.
+  apply({ op: "update", id: 1, props: { title: null, id: null } });
+
+  expect(receiver.root.children[0].props).toEqual({});
+});
+
+test("an update keeps the props it says nothing about", () => {
+  const { receiver, apply } = receive();
+
+  apply(
+    { op: "create", id: 1, type: "input", props: { value: "ada", id: "who" } },
+    { op: "append", parent: 0, child: 1 },
+    { op: "update", id: 1, props: { value: "grace" } },
+  );
+
+  expect(receiver.root.children[0].props).toEqual({
+    value: "grace",
+    id: "who",
+  });
+});
+
+test("clear empties the screen but keeps the ids", () => {
+  const { receiver, apply } = receive();
+
+  // The order React itself uses on a first commit: it creates the nodes, then clears the container,
+  // then appends. Dropping the ids on clear would throw away the tree being built.
+  apply(
+    { op: "create", id: 1, type: "p", props: {} },
+    { op: "text", id: 2, text: "still here" },
+    { op: "clear" },
+    { op: "append", parent: 0, child: 1 },
+    { op: "append", parent: 1, child: 2 },
+  );
+
+  expect(shapeOf(receiver.root)).toEqual({
+    type: "#root",
+    props: {},
+    children: [{ type: "p", props: {}, children: ["still here"] }],
+  });
+});
+
+test("a node is put where it was asked for, and taken out with its subtree", () => {
+  const { receiver, apply } = receive();
+
+  apply(
+    { op: "create", id: 1, type: "p", props: {} },
+    { op: "create", id: 2, type: "p", props: {} },
+    { op: "create", id: 3, type: "span", props: {} },
+    { op: "append", parent: 0, child: 1 },
+    { op: "append", parent: 0, child: 2 },
+    { op: "append", parent: 2, child: 3 },
+  );
+
+  apply({ op: "insert", parent: 0, child: 2, before: 1 });
+  expect(receiver.root.children.map((node) => node.id)).toEqual([2, 1]);
+
+  apply({ op: "remove", parent: 0, child: 2 });
+  expect(receiver.root.children.map((node) => node.id)).toEqual([1]);
+
+  // The subtree's ids went with it, so a stale op cannot reach a node that is off screen.
+  apply({ op: "append", parent: 0, child: 3 });
+  expect(receiver.root.children.map((node) => node.id)).toEqual([1]);
+});
+
+test("every applied batch is one version, which is what the panel re-renders on", () => {
+  const { receiver, apply } = receive();
+
+  let told = 0;
+  const stop = receiver.subscribe(() => told++);
+
+  const before = receiver.version();
+  apply({ op: "text", id: 1, text: "a" });
+  apply({ op: "retext", id: 1, text: "b" });
+
+  expect(receiver.version()).toBe(before + 2);
+  expect(told).toBe(2);
+
+  stop();
+  apply({ op: "retext", id: 1, text: "c" });
+  expect(told).toBe(2);
+});

package/src/renderer/services/remote-receiver.service.ts

@@ -0,0 +1,150 @@
+import {
+  ROOT,
+  type RemoteOp,
+  type RemoteProps,
+} from "../../core/constants/remote-op.const";
+
+/**
+ * The tree the app's React drew, kept as data for the panel to render.
+ *
+ * This used to build DOM nodes itself, one `document.createElement` per op. It cannot any more: a
+ * tab written with `View` and `Text` arrives as the host elements React Native compiles those to,
+ * and turning `RCTView` into a `div` by hand means reimplementing Yoga's defaults, RN's units and
+ * its text layout. react-native-web already is that, exactly, and it is a browser library, so it
+ * runs here. Handing it a tree means this side holds nodes rather than elements and React does the
+ * building.
+ *
+ * Kept as mutations applied to one tree, as before. React then diffs, so the element under a caret
+ * or a scrolled list survives a render above it for the same reason it did when this patched the
+ * DOM directly.
+ */
+
+export type RemoteNode = {
+  id: number;
+  type: string;
+  props: RemoteProps;
+  children: RemoteNode[];
+  text?: string;
+};
+
+export type RemoteReceiver = {
+  apply: (ops: RemoteOp[]) => void;
+  /** The root's children are what a tab drew. Mutated in place, so read it after a change. */
+  root: RemoteNode;
+  /** Bumped on every applied batch, which is what a `useSyncExternalStore` snapshot can watch. */
+  version: () => number;
+  subscribe: (listener: () => void) => () => void;
+};
+
+export function createRemoteReceiver(): RemoteReceiver {
+  const root: RemoteNode = { id: ROOT, type: "#root", props: {}, children: [] };
+  const nodes = new Map<number, RemoteNode>([[ROOT, root]]);
+  const listeners = new Set<() => void>();
+  let version = 0;
+
+  /** A removed subtree's ids are dropped too, so a later op cannot reach a node that is gone. */
+  const forget = (node: RemoteNode): void => {
+    nodes.delete(node.id);
+    for (const child of node.children) forget(child);
+  };
+
+  return {
+    root,
+    version: () => version,
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
+    apply(ops) {
+      for (const op of ops) {
+        switch (op.op) {
+          case "clear":
+            // Only what is on screen. React sends this partway through the first commit, after it
+            // has already created the nodes it is about to append, so dropping the ids here would
+            // throw away the tree it is in the middle of building.
+            root.children = [];
+            break;
+
+          case "create":
+            nodes.set(op.id, {
+              id: op.id,
+              type: op.type,
+              props: op.props,
+              children: [],
+            });
+            break;
+
+          case "text":
+            nodes.set(op.id, {
+              id: op.id,
+              type: "#text",
+              props: {},
+              children: [],
+              text: op.text,
+            });
+            break;
+
+          case "append": {
+            const parent = nodes.get(op.parent);
+            const child = nodes.get(op.child);
+            if (parent && child) parent.children.push(child);
+            break;
+          }
+
+          case "insert": {
+            const parent = nodes.get(op.parent);
+            const child = nodes.get(op.child);
+            const before = nodes.get(op.before);
+            if (!parent || !child) break;
+            // React reorders by inserting a node it has already placed, so this moves rather than
+            // copies. Leaving the old position alone put the same node on screen twice.
+            const from = parent.children.indexOf(child);
+            if (from >= 0) parent.children.splice(from, 1);
+            const at = before ? parent.children.indexOf(before) : -1;
+            parent.children.splice(
+              at < 0 ? parent.children.length : at,
+              0,
+              child,
+            );
+            break;
+          }
+
+          case "remove": {
+            const parent = nodes.get(op.parent);
+            const child = nodes.get(op.child);
+            if (!parent || !child) break;
+            const at = parent.children.indexOf(child);
+            if (at >= 0) parent.children.splice(at, 1);
+            forget(child);
+            break;
+          }
+
+          case "update": {
+            const node = nodes.get(op.id);
+            if (!node) break;
+            // A prop React dropped arrives as null rather than by absence, so it is deleted here
+            // instead of being handed on as a null the renderer would try to apply.
+            const props = { ...node.props };
+            for (const [key, value] of Object.entries(op.props)) {
+              if (value === null) delete props[key];
+              else props[key] = value;
+            }
+            node.props = props;
+            break;
+          }
+
+          case "retext": {
+            const node = nodes.get(op.id);
+            if (node) node.text = op.text;
+            break;
+          }
+        }
+      }
+
+      version++;
+      for (const listener of listeners) listener();
+    },
+  };
+}

package/src/renderer/start-renderer.ts

@@ -0,0 +1,80 @@
+import { createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+
+import {
+  ACTION,
+  HELLO,
+  MUTATE,
+  REGISTER,
+} from "../core/constants/message.const";
+import type { TabAction, TabMutation } from "../core/constants/message.const";
+import { createPanelChannel } from "../core/services/panel-channel.service";
+import {
+  createTabChannel,
+  type TabChannel,
+} from "../core/services/tab-channel.service";
+import { RemoteTree } from "./components/remote-tree.component";
+import { createRemoteReceiver } from "./services/remote-receiver.service";
+
+/**
+ * Boots the page for one tab.
+ *
+ * Each DevTools tab loads this page with its own id, and the channel is bound to it, so nothing here
+ * has to check who a message was for. Nothing here decides what the tab looks like either: the app's
+ * React does, its bar included, and this builds the elements it asks for.
+ */
+export function startRenderer(
+  tabId: string,
+  container: HTMLElement = document.body,
+): TabChannel {
+  const channel = createTabChannel(createPanelChannel(), tabId);
+  let root: Root | null = null;
+
+  const mount = () => {
+    const receiver = createRemoteReceiver();
+    root?.unmount();
+    root = createRoot(container);
+    root.render(
+      createElement(RemoteTree, {
+        receiver,
+        send: (handler: string, payload: unknown) =>
+          channel.send(ACTION, {
+            action: handler,
+            payload,
+          } satisfies TabAction),
+      }),
+    );
+    return receiver;
+  };
+
+  let remote = mount();
+
+  // A registration arriving now means the app is starting over, so what is drawn belongs to an
+  // engine that is gone, and the component that drew it went with it. Throwing the tree away is only
+  // half of that: the app mounts a tab when it is asked to and nothing asks on its behalf, so asking
+  // again here is what gets it drawn a second time. Without it an app reload left every tab that had
+  // already been opened blank until its page was reloaded too.
+  channel.onMessage(REGISTER, () => {
+    remote = mount();
+    channel.send(HELLO);
+  });
+
+  channel.onMessage(MUTATE, (payload) => {
+    remote.apply((payload as TabMutation).ops);
+  });
+
+  // The app almost always started first, so its registration is already gone. Ask for it rather than
+  // waiting for the next one, which is also what makes reloading this page recover.
+  channel.send(HELLO);
+
+  return channel;
+}
+
+export type {
+  MessageChannel,
+  MessageListener,
+} from "../core/services/message-channel.service";
+
+export { createPanelChannel } from "../core/services/panel-channel.service";
+export { createTabChannel } from "../core/services/tab-channel.service";
+export type { TabChannel } from "../core/services/tab-channel.service";