fix(sdui): stop the react page's "no adapter yet" fallback churning its provider context (#3000)

Audit of the remaining half of ReactKindPage's scope memo, [schema, adapter].
The schema half was the live bug fixed in #2984; this is the adapter half.

The hosts are fine — both AdapterCtx.Provider call sites pass a stable value
(AdapterProvider from useState, the console preview from a module constant), so
there is no state loss in the shipped app.

One real instance remained, one layer down: `dataSource={adapter ?? {}}` minted a
fresh object every render while the adapter was still null (the window before the
host connects). That is a context value and SchemaRendererProvider memoises on
its identity, so every block inside the page had its schema re-cloned and its
expressions re-run on each render. Now a module constant.

The `adapter` dependency itself must stay, and is now pinned. It looks like the
obvious thing to optimise away, but ReactRunner hands React the same element
object while (code, scope) hold, and React bails out on an identical element
reference — so recompiling is the ONLY path by which a new adapter reaches the
blocks inside the page. Verified by removing it: every block stays pinned to the
first adapter forever, with no error, just a dead data source.
react-page-adapter.test.tsx pins both directions.

Docs: the react-pages guide now states the host-side requirement — an adapter
constructed inline on every render resets every react page on every render.

Author: os-zhuang

.changeset/react-page-adapter-identity.md

@@ -0,0 +1,34 @@
+---
+"@object-ui/components": patch
+---
+
+fix(sdui): the react page's "no adapter yet" fallback stops churning its provider context
+
+Audit of the remaining half of `ReactKindPage`'s scope memo, `[schema, adapter]`.
+The `schema` half was the live bug fixed in objectui#2984; this is the adapter
+half.
+
+**The hosts are fine.** Both `AdapterCtx.Provider` call sites pass a stable
+value — `AdapterProvider` from `useState`, the console preview from a module
+constant — so there is no state loss in the shipped app.
+
+**One real instance remained**, one layer down: `<SchemaRendererProvider
+dataSource={adapter ?? {}}>` minted a fresh object on every render while the
+adapter was still null (the window before the host connects). That is a context
+value, and `SchemaRendererProvider` memoises on its identity, so every block
+inside the page had its schema re-cloned and its expressions re-run on each
+render of the page. Now a module constant, like the `SchemaRenderer` fallback
+it mirrors.
+
+**The `adapter` dependency itself must stay**, and is now pinned. It looks like
+the obvious thing to optimise away — it is the last remaining trigger that can
+recompile a page and cost its `useState`. But `ReactRunner` hands React the same
+element object while `(code, scope)` hold, and React bails out on an identical
+element reference, so the page subtree never re-renders on its own: recompiling
+is the *only* path by which a new adapter reaches the blocks inside the page.
+Removing the dependency strands every block on the first adapter forever — no
+error, just a dead data source. `react-page-adapter.test.tsx` pins both
+directions, so the tradeoff cannot be quietly re-litigated.
+
+Docs: the react-pages guide now states the host-side requirement — an adapter
+constructed inline on every render resets every react page on every render.

content/docs/guide/react-pages.md

@@ -167,8 +167,27 @@ injected — use HTML) or a block outside the public contract (use `Block`).
 ### Page state
 
 A react page keeps its own `useState` across re-renders and across lazy plugin
-loads. Two things reset it, both intentional: a change to `source`, and a change
-to the page's data/variables — the page is genuinely a different page then.
+loads. Three things reset it, all intentional: a change to `source`, a change to
+the page's data/variables, and a **new data source** — the page is genuinely a
+different page then.
+
+That last one is a requirement on the **host**, not the author. The page is
+recompiled when the adapter's *identity* changes, because recompiling is the
+only way the new adapter reaches the blocks inside the page. So a host that
+constructs a new adapter on every render resets every react page on every
+render. Provide it from state or a module constant:
+
+```tsx
+// ❌ new adapter object every render — every react page below loses its state
+<AdapterCtx.Provider value={new ObjectStackAdapter(config)}>
+
+// ✅
+const [adapter, setAdapter] = useState<ObjectStackAdapter | null>(null);
+<AdapterCtx.Provider value={adapter}>
+```
+
+`@object-ui/app-shell`'s `AdapterProvider` already does this correctly; the rule
+matters for custom hosts and preview surfaces.
 
 ## `kind:'html'`
 

packages/components/src/__tests__/react-page-adapter.test.tsx

@@ -0,0 +1,108 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * The adapter reaches a `kind:'react'` page's blocks, and keeps reaching them
+ * when the host swaps it.
+ *
+ * `ReactKindPage` memoises the injected scope on `[schema, adapter]`, and that
+ * `adapter` dependency looks like something to optimise away — it is the one
+ * remaining thing that can recompile the page and cost its `useState`
+ * (objectui#2954). It cannot go.
+ *
+ * `ReactRunner` returns the SAME element object while `(code, scope)` are
+ * unchanged, and React bails out of re-rendering a child whose element is
+ * referentially identical. So the page subtree does not re-render on its own:
+ * recompiling is the ONLY way a new adapter reaches the blocks inside the page.
+ * Drop the dependency (or read the adapter through a ref to "keep the scope
+ * stable") and every block in every react page silently keeps querying through
+ * the dead adapter — no error, just stale or failing data.
+ *
+ * These pin both halves so the tradeoff cannot be quietly re-litigated:
+ * a swapped adapter must reach the blocks, and an unchanged one must not
+ * disturb them.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { render, waitFor } from '@testing-library/react';
+import React from 'react';
+import { ComponentRegistry } from '@object-ui/core';
+import { SchemaRenderer, AdapterCtx } from '@object-ui/react';
+
+/** The dataSource each render of the stand-in block was handed. */
+const seen: unknown[] = [];
+
+const makeAdapter = (id: string) => ({ id, find: async () => [] }) as any;
+
+const SOURCE = `
+function Page() {
+  const [n, setN] = React.useState(0);
+  return (
+    <div>
+      <button data-testid="counter" onClick={() => setN(n + 1)}>{n}</button>
+      <ListView objectName="showcase_project" />
+    </div>
+  );
+}`;
+
+const SCHEMA = { type: 'home', kind: 'react', name: 'adapter_page', source: SOURCE };
+
+beforeAll(async () => {
+  await import('../renderers');
+  ComponentRegistry.register('list-view', (props: any) => {
+    seen.push(props.schema?.dataSource);
+    return <div data-testid="list-view-double" />;
+  });
+}, 30000);
+
+afterAll(() => {
+  ComponentRegistry.unregister('list-view');
+});
+
+function Host({ adapter }: { adapter: any }) {
+  return (
+    <AdapterCtx.Provider value={adapter}>
+      <SchemaRenderer schema={SCHEMA} />
+    </AdapterCtx.Provider>
+  );
+}
+
+describe('kind:\'react\' page ↔ adapter identity', () => {
+  it('hands blocks the new adapter when the host swaps it', async () => {
+    seen.length = 0;
+    const first = makeAdapter('first');
+    const second = makeAdapter('second');
+
+    const { findByTestId, rerender } = render(<Host adapter={first} />);
+    await findByTestId('list-view-double');
+    expect(seen.at(-1)).toBe(first);
+
+    rerender(<Host adapter={second} />);
+
+    // Nothing else re-renders the page subtree — ReactRunner hands React the
+    // same element object while (code, scope) hold, and React bails out on an
+    // identical element reference. Recompiling on the new scope is what carries
+    // the adapter in.
+    await waitFor(() => expect(seen.at(-1)).toBe(second));
+  });
+
+  it('leaves the page alone while the adapter identity holds', async () => {
+    seen.length = 0;
+    const adapter = makeAdapter('stable');
+
+    const { findByTestId, getByTestId, rerender } = render(<Host adapter={adapter} />);
+    const counter = await findByTestId('counter');
+    counter.click();
+    await waitFor(() => expect(getByTestId('counter').textContent).toBe('1'));
+
+    rerender(<Host adapter={adapter} />);
+
+    // The other half of the tradeoff: the same adapter must not recompile, or
+    // the page loses its state on every parent render.
+    expect(getByTestId('counter').textContent).toBe('1');
+    expect(seen.at(-1)).toBe(adapter);
+  });
+});

packages/components/src/renderers/layout/react-page.tsx

@@ -93,6 +93,18 @@ function buildComponentScope(dataSource: unknown): Record<string, React.Componen
   return scope;
 }
 
+/**
+ * Stand-in for "no adapter yet" — the window before the host's AdapterProvider
+ * finishes connecting, and any surface that renders a react page without one.
+ *
+ * A module constant, not an inline `?? {}`: this is a context value, and
+ * SchemaRendererProvider memoises on its identity. A fresh object per render
+ * would break that memo for every block inside the page, re-cloning each
+ * block's schema and re-running its expressions on every render of the page —
+ * the same defect the SchemaRenderer fallback had (objectui#2954).
+ */
+const NO_DATA_SOURCE = {};
+
 function CapabilityDisabledNotice(): React.ReactElement {
   return (
     <div className="m-4 rounded-md border border-amber-400/40 bg-amber-50 p-4 text-sm text-amber-900 dark:bg-amber-950/30 dark:text-amber-200">
@@ -179,7 +191,7 @@ export const ReactKindPage: React.FC<{ schema: any }> = ({ schema }) => {
 
   const { ReactRunner } = runtime;
   return (
-    <SchemaRendererProvider dataSource={adapter ?? {}}>
+    <SchemaRendererProvider dataSource={adapter ?? NO_DATA_SOURCE}>
       <ReactRunner
         code={source}
         scope={scope}