@multiplatform.one/frappe 7.7.0 → 7.7.1

package/dist/jsx/useLiveQuery.native.js

@@ -27,8 +27,8 @@ __export(useLiveQuery_exports, {
   useLiveQuery: () => useLiveQuery
 });
 module.exports = __toCommonJS(useLiveQuery_exports);
+var import_platform = require("@multiplatform.one/platform");
 var import_react_db = require("@tanstack/react-db");
-const import_meta = {};
 var SSR_LIVE_QUERY_RESULT = Object.freeze({
   state: void 0,
   data: void 0,
@@ -41,14 +41,7 @@ var SSR_LIVE_QUERY_RESULT = Object.freeze({
   isCleanedUp: false,
   isEnabled: true
 });
-var IS_SSR = function () {
-  try {
-    var _env;
-    return ((_env = import_meta.env) === null || _env === void 0 ? void 0 : _env.SSR) === true;
-  } catch (unused) {
-    return false;
-  }
-}();
+var IS_SSR = import_platform.isServer;
 var useLiveQuery = function useLiveQuery2() {
   for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
     args[_key] = arguments[_key];

package/dist/jsx/useLiveQuery.native.js.map

@@ -1 +1 @@
-{"version":3,"names":["__defProp","Object","defineProperty","__getOwnPropDesc","getOwnPropertyDescriptor","__getOwnPropNames","getOwnPropertyNames","__hasOwnProp","prototype","hasOwnProperty","__export","target","all","name","get","enumerable","__copyProps","to","from","except","desc","key","call","__toCommonJS","mod","value","useLiveQuery_exports","useLiveQuery","module","exports","import_react_db","require"],"sources":["../../src/useLiveQuery.ts"],"sourcesContent":[null],"mappings":"AAAA,YAAS;;AAOT,IAAAA,SAAM,GAAAC,MAAA,CAAAC,cAA+B;AAAO,IAC1CC,gBAAO,GAAAF,MAAA,CAAAG,wBAAA;AAAA,IACPC,iBAAM,GAAAJ,MAAA,CAAAK,mBAAA;AAAA,IACNC,YAAY,GAAAN,MAAA,CAAAO,SAAA,CAAAC,cAAA;AAAA,IACZC,QAAQ,GAAAA,CAAAC,MAAA,EAAAC,GAAA;EACR,SAAAC,IAAW,IAAAD,GAAA,EACXZ,SAAS,CAAAW,MAAA,EAAAE,IAAA;IAAAC,GAAA,EAAAF,GAAA,CAAAC,IAAA;IAAAE,UAAA;EAAA;AAAA;AACD,IACRC,WAAS,GAAAA,CAAAC,EAAA,EAAAC,IAAA,EAAAC,MAAA,EAAAC,IAAA;EACT,IAAAF,IAAA,WAAaA,IAAA,wBAAAA,IAAA;IACb,SAAWG,GAAA,IAAAhB,iBAAA,CAAAa,IAAA,GACZ,KAAAX,YAAA,CAAAe,IAAA,CAAAL,EAAA,EAAAI,GAAA,KAAAA,GAAA,KAAAF,MAAA,EAcKnB,SAAmB,CAAAiB,EAAA,EAAMI,GAAA;MAAAP,GAAA,EAAAA,CAAA,KAAAI,IAAA,CAAAG,GAAA;MAAAN,UAAA,IAAAK,IAAA,GAAAjB,gBAAA,CAAAe,IAAA,EAAAG,GAAA,MAAAD,IAAA,CAAAL;IAAA;EAC7B;EACE,OAAAE,EAAQ;AAAsE;AAE9E,IAAAM,YAAO,GAAAC,GAAA,IAAAR,WAAA,CAAAhB,SAAA;EAAAyB,KAAA;AAAA,IAAAD,GAAA;AAAA,IACTE,oBAAA;AACFhB,QAAG,CAAAgB,oBAAA;EAeIC,YAAM,EAAAA,CAAA,KAAyCA;AACpD;AAEAC,MAAA,CAAAC,OAAQ,GAAAN,YAAwD,CAAAG,oBAAI;AACtE,IAAAI,eAAA,GAAAC,OAAA","ignoreList":[]}
+{"version":3,"names":["__defProp","Object","defineProperty","__getOwnPropDesc","getOwnPropertyDescriptor","__getOwnPropNames","getOwnPropertyNames","__hasOwnProp","prototype","hasOwnProperty","__export","target","all","name","get","enumerable","__copyProps","to","from","except","desc","key","call","__toCommonJS","mod","value","useLiveQuery_exports"],"sources":["../../src/useLiveQuery.ts"],"sourcesContent":[null],"mappings":"AAAA,YAAS;;AACT,IAAAA,SAAS,GAAAC,MAAA,CAAAC,cAAgB;AAOzB,IAAAC,gBAAM,GAAAF,MAAA,CAAwBG,wBAAc;AAAA,IAC1CC,iBAAO,GAAAJ,MAAA,CAAAK,mBAAA;AAAA,IACPC,YAAM,GAAAN,MAAA,CAAAO,SAAA,CAAAC,cAAA;AAAA,IACNC,QAAA,GAAYA,CAAAC,MAAA,EAAAC,GAAA;EACZ,SAAQC,IAAA,IAAAD,GAAA,EACRZ,SAAW,CAAAW,MAAA,EAAAE,IAAA;IAAAC,GAAA,EAAAF,GAAA,CAAAC,IAAA;IAAAE,UAAA;EAAA;AAAA;AACF,IACTC,WAAQ,GAAAA,CAAAC,EAAA,EAAAC,IAAA,EAAAC,MAAA,EAAAC,IAAA;EACR,IAAAF,IAAA,IAAS,OAAAA,IAAA,wBAAAA,IAAA;IACT,SAAAG,GAAa,IAAAhB,iBAAA,CAAAa,IAAA,GACb,KAAAX,YAAW,CAAAe,IAAA,CAAAL,EAAA,EAAAI,GAAA,KAAAA,GAAA,KAAAF,MAAA,EACZnB,SAAA,CAAAiB,EAAA,EAAAI,GAAA;MAAAP,GAAA,EAAAA,CAAA,KAAAI,IAAA,CAAAG,GAAA;MAAAN,UAAA,IAAAK,IAAA,GAAAjB,gBAAA,CAAAe,IAAA,EAAAG,GAAA,MAAAD,IAAA,CAAAL;IAAA;EAoBD;EAeO,OAAME,EAAA;AACX;AAEA,IAAAM,YAAQ,GAAAC,GAAA,IAAqDR,WAAO,CAAAhB,SAAA;EAAAyB,KAAA;AAAA,IAAAD,GAAA;AACtE,IAAAE,oBAAA","ignoreList":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/frappe",
-  "version": "7.7.0",
+  "version": "7.7.1",
   "description": "frappe client for multiplatform.one ecosystem",
   "keywords": [
     "auth",
@@ -66,7 +66,7 @@
     "@tanstack/react-pacer": "0.22.0",
     "broadcast-channel": "^7.3.0",
     "socket.io-client": "^4.8.3",
-    "@multiplatform.one/store": "7.7.0"
+    "@multiplatform.one/store": "7.7.1"
   },
   "devDependencies": {
     "@tamagui/build": "2.7.6",
@@ -76,15 +76,16 @@
     "@types/lodash.startcase": "^4.4.9",
     "@vitejs/plugin-react": "^6.0.1",
     "react": "19.2.5",
+    "tamagui": "2.7.6",
     "typescript": "~5.9.3",
     "vitest": "^4.1.5",
-    "@multiplatform.one/config": "7.7.0",
-    "@multiplatform.one/platform": "7.7.0",
-    "@multiplatform.one/test-utils": "7.7.0"
+    "@multiplatform.one/platform": "7.7.1",
+    "@multiplatform.one/test-utils": "7.7.1",
+    "@multiplatform.one/config": "7.7.1"
   },
   "peerDependencies": {
     "react": "^19.1.0",
-    "@multiplatform.one/platform": "^7.7.0"
+    "@multiplatform.one/platform": "^7.7.1"
   },
   "engines": {
     "node": ">=6.0.0"

package/src/devtools/FrappeDevtoolsPanel.spec.tsx

@@ -0,0 +1,270 @@
+/**
+ * FrappeDevtoolsPanel contract specs.
+ *
+ * The panel is plain DOM inside the TanStack Devtools shell, so its whole
+ * contract is: read SyncModule.__debug(), repaint on every subscribeStore
+ * emit, and paint the palette the shell's theme prop names. Nothing here
+ * touches the sync engine — a stub SyncModule exposing just those two members
+ * is the entire surface the panel consumes, which keeps the spec hermetic and
+ * lets a test drive the panel into states a live engine reaches only by
+ * timing (a stale checkpoint, a failed mutation, a lost socket).
+ */
+import { cleanup, fireEvent, render, screen, act } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { SyncModule } from "../sync";
+import type { FrappeDebugState } from "../sync/types";
+import { Operation, Status } from "../sync/types";
+import { themes } from "./theme";
+import { FrappeDevtoolsPanel } from "./FrappeDevtoolsPanel";
+
+afterEach(cleanup);
+
+function emptyDebugState(): FrappeDebugState {
+  return {
+    subscriptions: [],
+    normalizedCache: { size: 0, doctypes: [] },
+    mutationJournal: { pending: [], confirmed: [], failed: [] },
+    connection: { socketConnected: false, isLeader: false, isOnline: true },
+  };
+}
+
+function populatedDebugState(): FrappeDebugState {
+  return {
+    subscriptions: [
+      {
+        id: "sub-todo",
+        query: { doctype: "ToDo" } as FrappeDebugState["subscriptions"][number]["query"],
+        docCount: 8,
+        tombstoneCount: 1,
+        checkpoint: new Date().toISOString(),
+      },
+      {
+        id: "sub-note",
+        query: { doctype: "Note" } as FrappeDebugState["subscriptions"][number]["query"],
+        docCount: 3,
+        tombstoneCount: 0,
+      },
+    ],
+    normalizedCache: {
+      size: 11,
+      doctypes: [
+        { doctype: "ToDo", count: 8 },
+        { doctype: "Note", count: 3 },
+      ],
+    },
+    mutationJournal: {
+      pending: [
+        {
+          id: "m-pending",
+          operation: Operation.Update,
+          doctype: "ToDo",
+          docname: "TODO-HANGS",
+          status: Status.Pending,
+          createdAt: Date.now(),
+          retryCount: 0,
+        },
+      ],
+      confirmed: [
+        {
+          id: "m-confirmed",
+          operation: Operation.Update,
+          doctype: "ToDo",
+          docname: "TODO-0001",
+          status: Status.Confirmed,
+          createdAt: Date.now(),
+          retryCount: 0,
+        },
+      ],
+      failed: [
+        {
+          id: "m-failed",
+          operation: Operation.Update,
+          doctype: "ToDo",
+          docname: "TODO-REJECTS",
+          status: Status.Failed,
+          createdAt: Date.now(),
+          retryCount: 2,
+          error: "ValidationError: TODO-REJECTS is locked",
+        },
+      ],
+    },
+    connection: { socketConnected: true, isLeader: true, isOnline: true },
+  };
+}
+
+/**
+ * A SyncModule stub with only what the panel calls. `emit()` drives the
+ * subscribeStore listener the way the real store does on every write.
+ */
+function stubSyncModule(initial: FrappeDebugState) {
+  let state = initial;
+  const listeners = new Set<() => void>();
+  const unsubscribe = vi.fn();
+  const module = {
+    __debug: vi.fn(() => state),
+    subscribeStore: vi.fn((listener: () => void) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+        unsubscribe();
+      };
+    }),
+  } as unknown as SyncModule;
+  return {
+    module,
+    unsubscribe,
+    set(next: FrappeDebugState) {
+      state = next;
+      act(() => {
+        for (const listener of listeners) listener();
+      });
+    },
+    listenerCount: () => listeners.size,
+  };
+}
+
+describe("FrappeDevtoolsPanel reads __debug()", () => {
+  it("paints the subscriptions the debug snapshot names", () => {
+    const stub = stubSyncModule(populatedDebugState());
+    const { container } = render(
+      <FrappeDevtoolsPanel syncModule={stub.module} devtoolsTheme="light" />,
+    );
+    expect(stub.module.__debug).toHaveBeenCalled();
+    expect(container.textContent).toContain("ToDo");
+    expect(container.textContent).toContain("Note");
+  });
+
+  it("an empty snapshot still paints the shell, not a blank div", () => {
+    const stub = stubSyncModule(emptyDebugState());
+    const { container } = render(
+      <FrappeDevtoolsPanel syncModule={stub.module} devtoolsTheme="light" />,
+    );
+    expect(container.firstElementChild).toBeTruthy();
+    expect(container.textContent).toContain("Pages");
+    expect(container.textContent).toContain("Cache");
+    expect(container.textContent).toContain("Mutations");
+  });
+
+  it("with no subscription selected the Pages tab asks for one", () => {
+    const stub = stubSyncModule(populatedDebugState());
+    const { container } = render(
+      <FrappeDevtoolsPanel syncModule={stub.module} devtoolsTheme="light" />,
+    );
+    expect(container.textContent).toContain("Select a subscription");
+  });
+});
+
+describe("FrappeDevtoolsPanel repaints on store emits", () => {
+  it("subscribes once and re-reads __debug() on every emit", () => {
+    const stub = stubSyncModule(emptyDebugState());
+    render(<FrappeDevtoolsPanel syncModule={stub.module} devtoolsTheme="light" />);
+    expect(stub.listenerCount()).toBe(1);
+    const before = (stub.module.__debug as ReturnType<typeof vi.fn>).mock.calls.length;
+    stub.set(populatedDebugState());
+    expect((stub.module.__debug as ReturnType<typeof vi.fn>).mock.calls.length).toBeGreaterThan(
+      before,
+    );
+  });
+
+  it("a subscription that appears after mount reaches the sidebar", () => {
+    const stub = stubSyncModule(emptyDebugState());
+    const { container } = render(
+      <FrappeDevtoolsPanel syncModule={stub.module} devtoolsTheme="light" />,
+    );
+    expect(container.textContent).not.toContain("Note");
+    stub.set(populatedDebugState());
+    expect(container.textContent).toContain("Note");
+  });
+
+  it("unsubscribes from the store on unmount", () => {
+    const stub = stubSyncModule(emptyDebugState());
+    const { unmount } = render(
+      <FrappeDevtoolsPanel syncModule={stub.module} devtoolsTheme="light" />,
+    );
+    expect(stub.listenerCount()).toBe(1);
+    unmount();
+    expect(stub.listenerCount()).toBe(0);
+    expect(stub.unsubscribe).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("FrappeDevtoolsPanel tabs", () => {
+  it("the Cache tab lists the cached doctypes and their counts", () => {
+    const stub = stubSyncModule(populatedDebugState());
+    const { container } = render(
+      <FrappeDevtoolsPanel syncModule={stub.module} devtoolsTheme="light" />,
+    );
+    fireEvent.click(screen.getByText("Cache"));
+    expect(container.textContent).toContain("ToDo");
+    expect(container.textContent).toContain("8");
+  });
+
+  it("the Mutations tab lists every journal state under All", () => {
+    const stub = stubSyncModule(populatedDebugState());
+    const { container } = render(
+      <FrappeDevtoolsPanel syncModule={stub.module} devtoolsTheme="light" />,
+    );
+    fireEvent.click(screen.getByText("Mutations"));
+    expect(container.textContent).toContain("TODO-HANGS");
+    expect(container.textContent).toContain("TODO-0001");
+    expect(container.textContent).toContain("TODO-REJECTS");
+    expect(container.textContent).toContain("Failed (1)");
+  });
+
+  it("a failed entry keeps its error message collapsed until the row is clicked", () => {
+    const stub = stubSyncModule(populatedDebugState());
+    const { container } = render(
+      <FrappeDevtoolsPanel syncModule={stub.module} devtoolsTheme="light" />,
+    );
+    fireEvent.click(screen.getByText("Mutations"));
+    expect(container.textContent).not.toContain("locked");
+    fireEvent.click(screen.getByText("TODO-REJECTS"));
+    expect(container.textContent).toContain("locked");
+  });
+
+  it("the Failed filter drops the pending and confirmed rows", () => {
+    const stub = stubSyncModule(populatedDebugState());
+    const { container } = render(
+      <FrappeDevtoolsPanel syncModule={stub.module} devtoolsTheme="light" />,
+    );
+    fireEvent.click(screen.getByText("Mutations"));
+    fireEvent.click(screen.getByText("Failed (1)"));
+    expect(container.textContent).toContain("TODO-REJECTS");
+    expect(container.textContent).not.toContain("TODO-HANGS");
+    expect(container.textContent).not.toContain("TODO-0001");
+  });
+
+  it("selecting a subscription moves the Pages tab off the placeholder", () => {
+    const stub = stubSyncModule(populatedDebugState());
+    const { container } = render(
+      <FrappeDevtoolsPanel syncModule={stub.module} devtoolsTheme="light" />,
+    );
+    fireEvent.click(screen.getByText("ToDo"));
+    expect(container.textContent).not.toContain("Select a subscription");
+  });
+});
+
+describe("FrappeDevtoolsPanel theme prop", () => {
+  it("light and dark paint different backgrounds, and each is its palette's bg", () => {
+    const light = render(
+      <FrappeDevtoolsPanel
+        syncModule={stubSyncModule(emptyDebugState()).module}
+        devtoolsTheme="light"
+      />,
+    );
+    const lightBg = (light.container.firstElementChild as HTMLElement).style.backgroundColor;
+    cleanup();
+    const dark = render(
+      <FrappeDevtoolsPanel
+        syncModule={stubSyncModule(emptyDebugState()).module}
+        devtoolsTheme="dark"
+      />,
+    );
+    const darkBg = (dark.container.firstElementChild as HTMLElement).style.backgroundColor;
+    expect(lightBg).not.toBe(darkBg);
+    expect(lightBg).toBeTruthy();
+    expect(darkBg).toBeTruthy();
+    // The panel owns its own palette (devtools/theme.ts); it never reads the app knobs.
+    expect(Object.keys(themes)).toEqual(["light", "dark"]);
+  });
+});

package/src/devtools/FrappeDevtoolsPanel.stories.tsx

@@ -0,0 +1,233 @@
+import { useEffect, useState } from "react";
+import { Button, isWeb, Text, XStack, YStack } from "tamagui";
+import {
+  HANGING_TODO,
+  REJECTED_TODO,
+  type ToDo,
+  type ToDoStatus,
+  toDoFixtureData,
+  useSeededJournal,
+  useStoryConfig,
+} from "../../tests/storyFixtures";
+import { useFrappeCollection } from "../frappeReact";
+import type { SyncModule } from "../sync";
+import type { FrappeDebugState } from "../sync/types";
+import { useLiveQuery } from "../useLiveQuery";
+import { FrappeDevtoolsPanel } from "./FrappeDevtoolsPanel";
+
+export default {
+  title: "Frappe/FrappeDevtoolsPanel",
+  component: FrappeDevtoolsPanel,
+  tags: ["!test"],
+  parameters: {
+    status: { type: "stable" },
+    docs: {
+      description: {
+        component:
+          "The Frappe tab of the TanStack Devtools shell: subscriptions in the sidebar, Pages / Cache / Mutations tabs and a stats bar, all read from SyncModule.__debug() and refreshed on every store emit. Plain DOM with its own light and dark palette (devtools/theme.ts), so it follows the shell's theme prop, never the app knobs. Stories are network-hermetic (G-15/D-05): the SyncModule runs over an InMemoryFixtureProvider, one ToDo subscription is opened through useFrappeCollection, and two scripted documents put a Pending and a Failed entry in the journal next to a Confirmed one. Nothing is fetched. On native the panel has no DOM to render into, so the story prints the same debug counts as text.",
+      },
+    },
+  },
+  argTypes: {
+    devtoolsTheme: { control: "radio", options: ["light", "dark"] },
+  },
+};
+
+type DevtoolsTheme = "light" | "dark";
+
+function useDebugState(syncModule: SyncModule | undefined): FrappeDebugState | undefined {
+  const [state, setState] = useState<FrappeDebugState | undefined>(undefined);
+  useEffect(() => {
+    if (!syncModule) return;
+    setState(syncModule.__debug());
+    return syncModule.subscribeStore(() => setState(syncModule.__debug()));
+  }, [syncModule]);
+  return state;
+}
+
+/** What the panel would show, as text, for platforms without a DOM. */
+function DebugSummary({ syncModule }: { syncModule: SyncModule }) {
+  const state = useDebugState(syncModule);
+  if (!state) return null;
+  const { subscriptions, normalizedCache, mutationJournal } = state;
+  return (
+    <YStack gap="$1" data-testid="devtools-summary">
+      <Text fontSize="$2">
+        subscriptions {subscriptions.length}
+        {subscriptions.map((sub) => ` · ${sub.query.doctype} (${sub.docCount} docs)`).join("")}
+      </Text>
+      <Text fontSize="$2">
+        cache {normalizedCache.size} docs
+        {normalizedCache.doctypes.map((d) => ` · ${d.doctype} ${d.count}`).join("")}
+      </Text>
+      <Text fontSize="$2">
+        mutations pending {mutationJournal.pending.length} · confirmed{" "}
+        {mutationJournal.confirmed.length} · failed {mutationJournal.failed.length}
+      </Text>
+    </YStack>
+  );
+}
+
+function PanelFrame({
+  syncModule,
+  devtoolsTheme,
+  height = 440,
+}: {
+  syncModule: SyncModule;
+  devtoolsTheme: DevtoolsTheme;
+  height?: number;
+}) {
+  if (!isWeb) {
+    return (
+      <YStack gap="$2">
+        <Text fontSize="$2" color="$color10">
+          FrappeDevtoolsPanel is plain DOM inside the TanStack Devtools shell, which only exists on
+          web. The SyncModule behind it is live here too:
+        </Text>
+        <DebugSummary syncModule={syncModule} />
+      </YStack>
+    );
+  }
+  return (
+    <div
+      data-testid="devtools-panel-host"
+      style={{
+        height,
+        borderRadius: 6,
+        overflow: "hidden",
+        border: "1px solid rgba(128, 128, 128, 0.35)",
+      }}
+    >
+      <FrappeDevtoolsPanel syncModule={syncModule} devtoolsTheme={devtoolsTheme} />
+    </div>
+  );
+}
+
+interface HostProps {
+  devtoolsTheme: DevtoolsTheme;
+  /** Open the ToDo subscription (a sidebar row and cached documents). */
+  subscribe?: boolean;
+  /** Seed one Confirmed, one Pending and one Failed journal entry once the subscription is ready. */
+  seed?: boolean;
+}
+
+function PanelHost({ devtoolsTheme, subscribe = true, seed = true }: HostProps) {
+  const config = useStoryConfig(toDoFixtureData());
+  const collection = useFrappeCollection<ToDo>(subscribe ? config : undefined, "ToDo");
+  const { isReady } = useLiveQuery(
+    (q) => (collection ? q.from({ todo: collection }) : null),
+    [collection],
+  );
+  const syncModule = useSeededJournal(config, Boolean(isReady), seed);
+  if (!syncModule) {
+    return (
+      <Text fontSize="$2">
+        No SyncModule: getFrappeSyncModule() returns undefined during server rendering.
+      </Text>
+    );
+  }
+  return <PanelFrame syncModule={syncModule} devtoolsTheme={devtoolsTheme} />;
+}
+
+const nextStatus: Record<ToDoStatus, ToDoStatus> = {
+  Open: "Working",
+  Working: "Completed",
+  Completed: "Open",
+  Cancelled: "Open",
+};
+
+function swallow(tx: { isPersisted: { promise: Promise<unknown> } }) {
+  // A rejected write is reported by the journal, not by an unhandled rejection.
+  tx.isPersisted.promise.catch(() => {});
+}
+
+/** Drives the collection from buttons so the panel's tabs move while you watch. */
+function InteractiveHost() {
+  const config = useStoryConfig(toDoFixtureData(5));
+  const collection = useFrappeCollection<ToDo>(config, "ToDo");
+  const { data, isReady } = useLiveQuery(
+    (q) => (collection ? q.from({ todo: collection }) : null),
+    [collection],
+  );
+  const syncModule = useSeededJournal(config, Boolean(isReady), false);
+  const [devtoolsTheme, setDevtoolsTheme] = useState<DevtoolsTheme>("light");
+  const [inserted, setInserted] = useState(0);
+  const rows = (data as ToDo[] | undefined) ?? [];
+
+  const update = (name: string) => {
+    const row = rows.find((r) => r.name === name);
+    if (!collection || !row) return;
+    swallow(
+      collection.update(name, (draft) => {
+        draft.status = nextStatus[row.status];
+      }),
+    );
+  };
+  const insert = () => {
+    if (!collection) return;
+    const n = inserted + 1;
+    setInserted(n);
+    swallow(
+      collection.insert({
+        name: `TODO-NEW-${String(n).padStart(3, "0")}`,
+        doctype: "ToDo",
+        description: `Added from the story (#${n})`,
+        status: "Open",
+        priority: "Medium",
+        date: "2026-09-05",
+        modified: "2026-09-05 12:00:00",
+      }),
+    );
+  };
+  const removeLast = () => {
+    const last = rows[rows.length - 1];
+    if (!collection || !last) return;
+    swallow(collection.delete(last.name));
+  };
+
+  if (!syncModule) return null;
+  return (
+    <YStack gap="$3">
+      <XStack gap="$2" flexWrap="wrap">
+        <Button size="$2" onPress={() => update("TODO-0002")} disabled={!isReady}>
+          Update TODO-0002 (confirms)
+        </Button>
+        <Button size="$2" onPress={() => update(HANGING_TODO)} disabled={!isReady}>
+          Update {HANGING_TODO} (stays pending)
+        </Button>
+        <Button size="$2" onPress={() => update(REJECTED_TODO)} disabled={!isReady}>
+          Update {REJECTED_TODO} (fails)
+        </Button>
+        <Button size="$2" onPress={insert} disabled={!isReady}>
+          Insert
+        </Button>
+        <Button size="$2" onPress={removeLast} disabled={!rows.length}>
+          Delete last
+        </Button>
+        <Button
+          size="$2"
+          onPress={() => setDevtoolsTheme((t) => (t === "light" ? "dark" : "light"))}
+        >
+          Theme: {devtoolsTheme}
+        </Button>
+      </XStack>
+      <Text fontSize="$2" color="$color10" data-testid="interactive-rows">
+        {rows.map((r) => `${r.name}=${r.status}`).join(" · ") || "no rows yet"}
+      </Text>
+      <PanelFrame syncModule={syncModule} devtoolsTheme={devtoolsTheme} height={400} />
+    </YStack>
+  );
+}
+
+/** One subscription, cached documents, and Confirmed + Pending + Failed journal entries, light palette. */
+export const Main = () => <PanelHost devtoolsTheme="light" />;
+Main.storyName = "Main";
+
+/** Same state under the shell's dark theme prop. */
+export const Dark = () => <PanelHost devtoolsTheme="dark" />;
+
+/** A SyncModule nobody has subscribed through yet: empty sidebar, empty cache, empty journal. */
+export const Empty = () => <PanelHost devtoolsTheme="light" subscribe={false} seed={false} />;
+
+/** Buttons drive inserts, updates and deletes through the collection; watch the tabs move. */
+export const Interactive = () => <InteractiveHost />;

package/src/devtools/plugin.spec.tsx

@@ -0,0 +1,91 @@
+/**
+ * frappeDevtoolsPlugin contract specs (MPO-8).
+ *
+ * The plugin is the whole surface the TanStack Devtools shell sees: an id and
+ * a name for the tab strip, and a render(hostElement, { theme }) the shell
+ * calls when the tab opens. What renders is FrappeDevtoolsPanel bound to the
+ * SyncModule the factory closed over — so the contract worth pinning is the
+ * binding, not the panel's paint, which FrappeDevtoolsPanel.spec.tsx owns.
+ */
+import { cleanup, render } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { SyncModule } from "../sync";
+import type { FrappeDebugState } from "../sync/types";
+import { FrappeDevtoolsPanel } from "./FrappeDevtoolsPanel";
+import { frappeDevtoolsPlugin } from "./plugin";
+
+afterEach(cleanup);
+
+function stubSyncModule(label: string) {
+  const state: FrappeDebugState = {
+    subscriptions: [
+      {
+        id: `sub-${label}`,
+        query: { doctype: label } as FrappeDebugState["subscriptions"][number]["query"],
+        docCount: 1,
+        tombstoneCount: 0,
+      },
+    ],
+    normalizedCache: { size: 1, doctypes: [{ doctype: label, count: 1 }] },
+    mutationJournal: { pending: [], confirmed: [], failed: [] },
+    connection: { socketConnected: false, isLeader: false, isOnline: true },
+  };
+  return {
+    __debug: vi.fn(() => state),
+    subscribeStore: vi.fn(() => () => {}),
+  } as unknown as SyncModule;
+}
+
+describe("frappeDevtoolsPlugin identity", () => {
+  it("is the id and name the shell lists in its tab strip", () => {
+    const plugin = frappeDevtoolsPlugin(stubSyncModule("ToDo"));
+    expect(plugin.id).toBe("frappe");
+    expect(plugin.name).toBe("Frappe");
+    expect(typeof plugin.render).toBe("function");
+  });
+
+  it("the identity does not change with the SyncModule it wraps", () => {
+    const a = frappeDevtoolsPlugin(stubSyncModule("ToDo"));
+    const b = frappeDevtoolsPlugin(stubSyncModule("Note"));
+    expect(a.id).toBe(b.id);
+    expect(a.name).toBe(b.name);
+  });
+});
+
+describe("frappeDevtoolsPlugin render()", () => {
+  it("returns the panel element bound to the module the factory closed over", () => {
+    const syncModule = stubSyncModule("ToDo");
+    const plugin = frappeDevtoolsPlugin(syncModule);
+    const element = plugin.render(document.createElement("div"), { theme: "light" });
+    expect(element.type).toBe(FrappeDevtoolsPanel);
+    expect(element.props.syncModule).toBe(syncModule);
+  });
+
+  it("forwards the shell's theme prop straight through, both ways", () => {
+    const plugin = frappeDevtoolsPlugin(stubSyncModule("ToDo"));
+    const host = document.createElement("div");
+    expect(plugin.render(host, { theme: "light" }).props.devtoolsTheme).toBe("light");
+    expect(plugin.render(host, { theme: "dark" }).props.devtoolsTheme).toBe("dark");
+  });
+
+  it("the returned element actually mounts and paints that module's state", () => {
+    const plugin = frappeDevtoolsPlugin(stubSyncModule("Sales Invoice"));
+    const { container } = render(plugin.render(document.createElement("div"), { theme: "light" }));
+    expect(container.textContent).toContain("Sales Invoice");
+  });
+
+  it("render() does not write into the host element itself — the shell mounts what it returns", () => {
+    const plugin = frappeDevtoolsPlugin(stubSyncModule("ToDo"));
+    const host = document.createElement("div");
+    plugin.render(host, { theme: "light" });
+    expect(host.childElementCount).toBe(0);
+  });
+
+  it("two renders of one plugin stay bound to the same module", () => {
+    const syncModule = stubSyncModule("ToDo");
+    const plugin = frappeDevtoolsPlugin(syncModule);
+    const host = document.createElement("div");
+    expect(plugin.render(host, { theme: "light" }).props.syncModule).toBe(syncModule);
+    expect(plugin.render(host, { theme: "dark" }).props.syncModule).toBe(syncModule);
+  });
+});