From e2ae91538fabb2d794db05db1551e5441e7ea5f9 Mon Sep 17 00:00:00 2001 From: Brian Love Date: Tue, 17 Nov 2026 17:22:26 -0800 Subject: [PATCH 1/2] feat(react): show a placeholder while generated UI props are still undefined Angular gives every registry entry a default readiness fallback: defineAngularRegistry pairs each component with DefaultFallbackComponent, and render-element mounts that fallback while any resolved prop is undefined (or a schema fails), latching once the real component mounts, per element and per repeat row. A2UI catalogs get the same treatment, so components that arrive before updateDataModel shimmer instead of rendering empty labels. React only gated explicit { kind: 'readiness' } entries, so plain components and the whole a2uiBasicCatalog() mounted at once with undefined props. RenderSpec now applies Angular's rule by default: a registered component waits behind RenderPendingFallback (GenerativeUiSkeleton markup) while any resolved prop is undefined, then mounts and stays mounted for that element. A readiness entry keeps its own predicate and shows the tree's placeholder when it has no fallback, as Angular does with fallback ?? DefaultFallbackComponent. The unknown-type `fallback` is not gated. `pendingFallback` customizes the placeholder; `null` restores the previous immediate mounting. A per-entry opt-out is a readiness entry whose isReady always returns true. A2UI: the basic catalog's inputs (TextField, CheckBox, ChoicePicker, DateTimeInput, Slider) wait on every prop except their own `value`, so an unseeded field the person fills in is not stuck on the placeholder, which Angular's literal rule would do. A2uiSurface and A2uiMessageSurfaces take `pendingFallback`; with null the surface uses an ungated catalog. Chat's generativeUi options forward `pendingFallback` too. A ready-on-first-render readiness gate now starts admitted, so the real view renders once instead of twice. Element lifecycle events are unchanged: an element reports `mounted` once when its placeholder first renders, as Angular reports it from ngOnInit. Co-Authored-By: Claude Opus 5.5 --- .../a2ui/getting-started/introduction.mdx | 2 + .../docs/react/render/guides/lifecycle.mdx | 2 +- .../docs/react/render/guides/registry.mdx | 21 ++ .../react/src/dashboard-views.spec.tsx | 3 +- .../react/src/dashboard-views.spec.tsx | 3 +- libs/react/src/a2ui/catalog/choices.spec.tsx | 2 +- libs/react/src/a2ui/catalog/index.ts | 40 +++- libs/react/src/a2ui/message-surfaces.spec.tsx | 6 +- libs/react/src/a2ui/message-surfaces.tsx | 7 +- libs/react/src/a2ui/readiness.spec.tsx | 80 ++++++++ libs/react/src/a2ui/styles.css | 63 ++++++ libs/react/src/a2ui/surface.tsx | 26 ++- libs/react/src/a2ui/surface.type-test.tsx | 15 +- libs/react/src/chat/generative-ui.tsx | 6 + .../chat/message-list-interactive-ui.spec.tsx | 20 +- .../src/render/computed-functions.spec.tsx | 4 +- .../src/render/default-readiness.spec.tsx | 186 ++++++++++++++++++ libs/react/src/render/index.ts | 1 + libs/react/src/render/pending-fallback.tsx | 24 +++ libs/react/src/render/readiness.spec.tsx | 42 +++- libs/react/src/render/readiness.tsx | 29 +-- libs/react/src/render/render-spec.spec.tsx | 9 +- libs/react/src/render/render-spec.tsx | 47 ++++- libs/react/src/render/render.type-test.ts | 6 +- libs/react/src/render/seeded-state.spec.tsx | 7 +- libs/react/src/render/types.ts | 8 + scripts/react-parity/dispositions.json | 20 ++ scripts/react-parity/verify-packages.mjs | 2 +- scripts/react-parity/verify-packages.spec.mjs | 8 +- 29 files changed, 637 insertions(+), 52 deletions(-) create mode 100644 libs/react/src/a2ui/readiness.spec.tsx create mode 100644 libs/react/src/render/default-readiness.spec.tsx create mode 100644 libs/react/src/render/pending-fallback.tsx diff --git a/apps/website/content/docs/react/a2ui/getting-started/introduction.mdx b/apps/website/content/docs/react/a2ui/getting-started/introduction.mdx index 329f1eab2..762150ddd 100644 --- a/apps/website/content/docs/react/a2ui/getting-started/introduction.mdx +++ b/apps/website/content/docs/react/a2ui/getting-started/introduction.mdx @@ -13,6 +13,8 @@ The native React APIs on this page are experimental, private source-build packag The server sends a surface description and data-model updates. React retains the received surface, while form controls hold the traveler’s current edits. Search, Select, and Modify send intentional actions; typing does not start another agent run. The example admits a fixed flight-form profile rather than every possible A2UI component. +When components arrive before the data model, `A2uiSurface` shows a placeholder for each component whose data-bound props have no value yet, then mounts it once they do. An input's own `value` may stay unset, so an empty field the traveler fills in still appears. Pass `pendingFallback` to change the placeholder, or `null` to mount every component at once. + The [React conversation walkthrough](/docs/react/langgraph/concepts/conversation-turns) connects this capability to requests, tools, UI state, and saved history. ## Start a conversation diff --git a/apps/website/content/docs/react/render/guides/lifecycle.mdx b/apps/website/content/docs/react/render/guides/lifecycle.mdx index e07090f1c..383ad2899 100644 --- a/apps/website/content/docs/react/render/guides/lifecycle.mdx +++ b/apps/website/content/docs/react/render/guides/lifecycle.mdx @@ -21,7 +21,7 @@ These protections do not validate your application schema. Admit untrusted view Use stable element keys and registry component identities across updates. Container views must place the provided `children` where they belong. [Repeat loops](/docs/react/render/guides/repeat-loops) need meaningful unique identities when items can reorder. -A readiness registry entry can defer its component until its synchronous predicate accepts the props. Follow the [registry guide](/docs/react/render/guides/registry) for that mounted-view boundary. Readiness is presentation admission, not a network completion signal. +A registered component waits behind `RenderPendingFallback` while any resolved prop is undefined, and a readiness registry entry can defer its component until its synchronous predicate accepts the props. Follow the [registry guide](/docs/react/render/guides/registry) for that mounted-view boundary. Readiness is presentation admission, not a network completion signal. ## Retire owned work diff --git a/apps/website/content/docs/react/render/guides/registry.mdx b/apps/website/content/docs/react/render/guides/registry.mdx index 03fd86c34..987e85723 100644 --- a/apps/website/content/docs/react/render/guides/registry.mdx +++ b/apps/website/content/docs/react/render/guides/registry.mdx @@ -22,6 +22,27 @@ export const tripViews: ReactRenderRegistry = { }; ~~~ +## Wait for bound props + +As in the Angular renderer, a registered component does not mount while any of its resolved props is `undefined`, such as a `$state` binding whose path has not arrived. RenderSpec shows `RenderPendingFallback` in its place, a labelled shimmer card that uses the generative UI skeleton classes. Once every prop has a value, the component mounts and stays mounted for that element, even if a value later goes missing. Each repeat row waits on its own props. + +Pass a component as `pendingFallback` to show something else, or pass `null` to mount every component at once. To let one component mount with undefined props, register it as a readiness entry whose predicate always accepts: + +~~~tsx +import type { ReactRenderRegistry } from '@threadplane/react/render'; + +export const views: ReactRenderRegistry = { + Heading: ({ props }) =>

{String(props['text'] ?? '')}

, + Note: { + kind: 'readiness', + component: ({ props }) =>

{String(props['text'] ?? '')}

, + isReady: () => true, + }, +}; +~~~ + +A readiness entry decides with its own predicate. Without its own `fallback`, it shows the tree's `pendingFallback`. The element reports `mounted` to `onEvent` once, when the placeholder first renders, which matches the Angular renderer. + The [React conversation walkthrough](/docs/react/langgraph/concepts/conversation-turns) connects this capability to requests, tools, UI state, and saved history. ## Try each registry mode diff --git a/cockpit/ag-ui/json-render/react/src/dashboard-views.spec.tsx b/cockpit/ag-ui/json-render/react/src/dashboard-views.spec.tsx index c2384e1c7..23267d36a 100644 --- a/cockpit/ag-ui/json-render/react/src/dashboard-views.spec.tsx +++ b/cockpit/ag-ui/json-render/react/src/dashboard-views.spec.tsx @@ -255,7 +255,8 @@ it('updates the same retained layout from latest shared state without mutating t }); it('distinguishes unavailable data from valid empty lists and zero values', () => { const view = render(); - expect(screen.getAllByText('Waiting for dashboard data…')).toHaveLength(4); + // RenderSpec holds each view behind its placeholder until the bound data arrives. + expect(screen.getAllByText('Building UI…')).toHaveLength(4); view.rerender( { const view = render(); - expect(screen.getAllByText('Waiting for dashboard data…')).toHaveLength(4); + // RenderSpec holds each view behind its placeholder until the bound data arrives. + expect(screen.getAllByText('Building UI…')).toHaveLength(4); view.rerender( { }); it('maps min and max to the native bounds in the same format', () => { - const { element } = input({ min: '2026-03-01T00:00:00', max: { path: '/latest' } }, '2026-03-04'); + const { element } = input({ min: '2026-03-01T00:00:00' }, '2026-03-04'); expect([element.min, element.max]).toEqual(['2026-03-01', '']); cleanup(); const surfaces = store( diff --git a/libs/react/src/a2ui/catalog/index.ts b/libs/react/src/a2ui/catalog/index.ts index 57ae25f61..d07f3818d 100644 --- a/libs/react/src/a2ui/catalog/index.ts +++ b/libs/react/src/a2ui/catalog/index.ts @@ -1,4 +1,7 @@ -import type { ReactRenderRegistry } from '../../render/index.js'; +import type { + ReactRenderRegistry, + RenderReadinessEntry, +} from '../../render/index.js'; import { A2uiAudioPlayer } from './audio-player.js'; import { A2uiButton } from './button.js'; import { A2uiCard } from './card.js'; @@ -18,7 +21,22 @@ import { A2uiText } from './text.js'; import { A2uiTextField } from './text-field.js'; import { A2uiVideo } from './video.js'; -const CATALOG: ReactRenderRegistry = Object.freeze({ +/** + * An input waits, like every other component, while a prop such as its label + * has not arrived; its `value` alone may stay undefined, because the person + * fills an unseeded field. + */ +const ready: RenderReadinessEntry['isReady'] = (props) => + Object.entries(props).every( + ([key, value]) => key === 'value' || value !== undefined + ); +const input = ( + component: RenderReadinessEntry['component'] +): RenderReadinessEntry => + Object.freeze({ kind: 'readiness', component, isReady: ready }); + +/** Every basic component, mounted at once, for a surface whose `pendingFallback` is null. */ +const EAGER: ReactRenderRegistry = Object.freeze({ AudioPlayer: A2uiAudioPlayer, Button: A2uiButton, Card: A2uiCard, @@ -39,12 +57,28 @@ const CATALOG: ReactRenderRegistry = Object.freeze({ Video: A2uiVideo, }); +const CATALOG: ReactRenderRegistry = Object.freeze({ + ...EAGER, + CheckBox: input(A2uiCheckBox), + ChoicePicker: input(A2uiChoicePicker), + DateTimeInput: input(A2uiDateTimeInput), + Slider: input(A2uiSlider), + TextField: input(A2uiTextField), +}); + /** * The A2UI basic catalog: Text, Image, Icon, Video, AudioPlayer, Row, Column, * List, Card, Divider, Tabs, Modal, TextField, CheckBox, ChoicePicker, * DateTimeInput, Slider and Button. Inputs write to the surface's store when `A2uiSurface` is given one; - * a Button hands its event action to the surface's `onAction`. + * a Button hands its event action to the surface's `onAction`. A component + * shows a placeholder while a data-bound prop has no value yet, except an + * input's own `value`. */ export function a2uiBasicCatalog(): ReactRenderRegistry { return CATALOG; } + +/** The basic catalog without any wait, so every component mounts at once. */ +export function a2uiEagerCatalog(): ReactRenderRegistry { + return EAGER; +} diff --git a/libs/react/src/a2ui/message-surfaces.spec.tsx b/libs/react/src/a2ui/message-surfaces.spec.tsx index c0d6f3cad..850a1ec7a 100644 --- a/libs/react/src/a2ui/message-surfaces.spec.tsx +++ b/libs/react/src/a2ui/message-surfaces.spec.tsx @@ -158,8 +158,12 @@ describe('A2uiMessageSurfaces', () => { expect(view.queryByRole('status')).not.toBeNull(); expect(surfaceIds(view.container)).toEqual([]); view.rerender(); - expect(view.queryByRole('status')).toBeNull(); expect(surfaceIds(view.container)).toEqual(['trip']); + // The surface is live; only its Text bound to /title waits for the data model. + expect(view.getByRole('status').closest('.a2ui-surface')).not.toBeNull(); + view.rerender(); + expect(view.queryByRole('status')).toBeNull(); + expect(view.container.textContent).toContain('Lyon'); }); it('renders nothing for a finished message with no surface', () => { diff --git a/libs/react/src/a2ui/message-surfaces.tsx b/libs/react/src/a2ui/message-surfaces.tsx index e697d65ac..6b0b11576 100644 --- a/libs/react/src/a2ui/message-surfaces.tsx +++ b/libs/react/src/a2ui/message-surfaces.tsx @@ -25,7 +25,12 @@ export interface A2uiMessageContent { export interface A2uiMessageSurfacesProps extends Pick< A2uiSurfaceProps, - 'onAction' | 'onValidationError' | 'functions' | 'catalog' | 'className' + | 'onAction' + | 'onValidationError' + | 'functions' + | 'catalog' + | 'pendingFallback' + | 'className' > { readonly content: A2uiMessageContent; } diff --git a/libs/react/src/a2ui/readiness.spec.tsx b/libs/react/src/a2ui/readiness.spec.tsx new file mode 100644 index 000000000..3e82786d1 --- /dev/null +++ b/libs/react/src/a2ui/readiness.spec.tsx @@ -0,0 +1,80 @@ +import { cleanup, render } from '@testing-library/react'; +import { afterEach, describe, expect, it } from 'vitest'; +import type { A2uiSurfaceSnapshot } from '@threadplane/content/a2ui'; +import type { RenderViewProps } from '../render/index'; +import { A2uiSurface } from './index'; + +afterEach(cleanup); + +type Component = A2uiSurfaceSnapshot['components'][number]; +const surface = ( + components: readonly Component[], + dataModel: A2uiSurfaceSnapshot['dataModel'] = {} +): A2uiSurfaceSnapshot => ({ + surfaceId: 's1', + catalogId: 'basic', + components, + dataModel, +}); +const components: readonly Component[] = [ + { id: 'root', component: 'Column', children: ['title', 'guest'] }, + { id: 'title', component: 'Text', text: { path: '/title' } }, + { + id: 'guest', + component: 'TextField', + label: { path: '/guestLabel' }, + value: { path: '/guest' }, + }, +]; + +describe('A2uiSurface readiness', () => { + it('shows placeholders for components that arrive before the data model, then mounts them', () => { + const view = render(); + const pending = view.getAllByRole('status'); + expect(pending).toHaveLength(2); + expect(pending.every((el) => el.closest('.a2ui-surface'))).toBe(true); + expect(view.queryByRole('textbox')).toBeNull(); + + // The input value is never seeded: the person fills it in. + view.rerender( + + ); + expect(view.queryByRole('status')).toBeNull(); + expect(view.container.textContent).toContain('Lyon trip'); + expect((view.getByLabelText('Guest') as HTMLInputElement).value).toBe(''); + }); + + it('keeps a mounted component when its data later goes missing', () => { + const view = render( + + ); + const field = view.getByRole('textbox'); + view.rerender(); + expect(view.queryByRole('status')).toBeNull(); + expect(view.getByRole('textbox')).toBe(field); + }); + + it('takes a custom pendingFallback, or null to mount at once', () => { + const Pending = ({ elementKey }: RenderViewProps) => ( +

waiting

+ ); + const view = render( + + ); + expect( + [...view.container.querySelectorAll('[data-pending]')].map((el) => + el.getAttribute('data-pending') + ) + ).toEqual(['title', 'guest']); + cleanup(); + const eager = render( + + ); + expect(eager.queryByRole('status')).toBeNull(); + expect(eager.getByRole('textbox')).toBeTruthy(); + }); +}); diff --git a/libs/react/src/a2ui/styles.css b/libs/react/src/a2ui/styles.css index 43fabd734..6308be85d 100644 --- a/libs/react/src/a2ui/styles.css +++ b/libs/react/src/a2ui/styles.css @@ -541,6 +541,63 @@ .a2ui-unsupported { display: contents; } +/* RenderPendingFallback: a component whose data-bound props have not arrived. */ +.a2ui-surface .tp-render-pending { + display: block; + box-sizing: border-box; + inline-size: 100%; + min-inline-size: 0; + padding: var(--a2ui-spacing-3); + border: 1px solid var(--a2ui-outline); + border-radius: var(--a2ui-shape-medium); + background: var(--a2ui-surface-variant); + color: var(--a2ui-on-surface-variant); + font-size: var(--a2ui-typography-label-size); +} +.a2ui-surface .tp-render-pending .tp-genui-skeleton__label { + display: block; + margin-block-end: var(--a2ui-spacing-2); +} +.a2ui-surface .tp-render-pending .tp-genui-skeleton__rows { + display: flex; + flex-direction: column; + gap: var(--a2ui-spacing-2); +} +.a2ui-surface .tp-render-pending .tp-genui-skeleton__row { + display: block; + block-size: 0.625rem; + border-radius: var(--a2ui-shape-extra-small); + background: linear-gradient( + 90deg, + color-mix(in srgb, currentColor 22%, transparent) 0%, + color-mix(in srgb, currentColor 10%, transparent) 50%, + color-mix(in srgb, currentColor 22%, transparent) 100% + ); + background-size: 200% 100%; + animation: a2ui-pending-shimmer 1.4s ease-in-out infinite; +} +.a2ui-surface .tp-render-pending .tp-genui-skeleton__row:nth-child(1) { + inline-size: 70%; +} +.a2ui-surface .tp-render-pending .tp-genui-skeleton__row:nth-child(2) { + inline-size: 90%; +} +.a2ui-surface .tp-render-pending .tp-genui-skeleton__row:nth-child(3) { + inline-size: 50%; +} +@keyframes a2ui-pending-shimmer { + 0% { + background-position: 200% 0; + } + 100% { + background-position: -200% 0; + } +} +@media (prefers-reduced-motion: reduce) { + .a2ui-surface .tp-render-pending .tp-genui-skeleton__row { + animation: none; + } +} @media (forced-colors: active) { .a2ui-card, .a2ui-divider--horizontal { @@ -555,6 +612,12 @@ .a2ui-modal { border-color: CanvasText; } + .a2ui-surface .tp-render-pending { + border-color: CanvasText; + } + .a2ui-surface .tp-render-pending .tp-genui-skeleton__row { + background: GrayText; + } .a2ui-tf__input, .a2ui-dti__input, .a2ui-cp__filter { diff --git a/libs/react/src/a2ui/surface.tsx b/libs/react/src/a2ui/surface.tsx index 99fef827a..0b0664a0f 100644 --- a/libs/react/src/a2ui/surface.tsx +++ b/libs/react/src/a2ui/surface.tsx @@ -11,8 +11,12 @@ import { type A2uiSurfaceSnapshot, type A2uiValue, } from '@threadplane/content/a2ui'; -import { RenderSpec, type ReactRenderRegistry } from '../render/index.js'; -import { a2uiBasicCatalog } from './catalog/index.js'; +import { + RenderSpec, + type ReactRenderRegistry, + type RenderSpecProps, +} from '../render/index.js'; +import { a2uiBasicCatalog, a2uiEagerCatalog } from './catalog/index.js'; import { A2uiDefaultFallback } from './default-fallback.js'; import { A2uiActionContext, @@ -137,6 +141,13 @@ export interface A2uiSurfaceProps { }; /** Components by A2UI name. Defaults to `a2uiBasicCatalog()`; keep it stable. */ readonly catalog?: ReactRenderRegistry; + /** + * Shown in place of a component while a data-bound prop has no value yet, + * such as components that arrive before the data model. Defaults to + * `RenderPendingFallback`; `null` mounts every component of the default + * catalog at once. A readiness entry in your own `catalog` still decides. + */ + readonly pendingFallback?: RenderSpecProps['pendingFallback']; readonly className?: string; } @@ -149,7 +160,9 @@ export interface A2uiSurfaceProps { * show their messages until they pass. A Button whose own `checks` fail is * disabled. A Button with a function-call action runs it here, through * `functions` or the built-in `openUrl`, without consulting `checks` on - * inputs. Function-call props show their current value. A component the + * inputs. Function-call props show their current value. A component whose + * data-bound props have not arrived shows `pendingFallback` until they do, + * then stays mounted; an input's own `value` may stay unset. A component the * catalog lacks keeps its children. A child template is stamped once per * item of its list; inputs, checks and actions inside it work on that item. * The surface's `theme` sets the accent colour from a hex `primaryColor` and @@ -162,6 +175,7 @@ export function A2uiSurface({ onValidationError, functions, catalog, + pendingFallback, className, }: A2uiSurfaceProps) { const { spec, state, sources } = useMemo( @@ -276,9 +290,13 @@ export function A2uiSurface({ diff --git a/libs/react/src/a2ui/surface.type-test.tsx b/libs/react/src/a2ui/surface.type-test.tsx index de3bfc5a1..3030457bf 100644 --- a/libs/react/src/a2ui/surface.type-test.tsx +++ b/libs/react/src/a2ui/surface.type-test.tsx @@ -5,9 +5,12 @@ import type { A2uiValidationErrorMessage, A2uiValue, } from '@threadplane/content/a2ui'; -import type { ReactNode } from 'react'; +import type { ComponentType, ReactNode } from 'react'; import type { MessageA2uiContent } from '../chat/index.js'; -import type { ReactRenderRegistry } from '../render/index.js'; +import type { + ReactRenderRegistry, + RenderViewProps, +} from '../render/index.js'; import { A2uiMessageSurfaces, A2uiSurface, @@ -40,6 +43,7 @@ export type PropsContract = Assert< }) => void; }; readonly catalog?: ReactRenderRegistry; + readonly pendingFallback?: ComponentType | null; readonly className?: string; } > @@ -150,7 +154,12 @@ export type MessageSurfacesPropsContract = Assert< { [K in keyof A2uiMessageSurfacesProps]: A2uiMessageSurfacesProps[K] }, { readonly content: A2uiMessageContent } & Pick< A2uiSurfaceProps, - 'onAction' | 'onValidationError' | 'functions' | 'catalog' | 'className' + | 'onAction' + | 'onValidationError' + | 'functions' + | 'catalog' + | 'pendingFallback' + | 'className' > extends infer T ? { [K in keyof T]: T[K] } : never diff --git a/libs/react/src/chat/generative-ui.tsx b/libs/react/src/chat/generative-ui.tsx index 006707ed2..fad7c0cec 100644 --- a/libs/react/src/chat/generative-ui.tsx +++ b/libs/react/src/chat/generative-ui.tsx @@ -74,6 +74,11 @@ export interface MessageGenerativeUi { readonly functions?: ReactRenderFunctions; /** Rendered for a spec component the registry lacks; see `RenderSpecProps.fallback`. */ readonly fallback?: ComponentType; + /** + * Shown in place of a spec element while a bound prop has no value yet; see + * `RenderSpecProps.pendingFallback`. `null` mounts every element at once. + */ + readonly pendingFallback?: ComponentType | null; /** * Actions a spec's `on` bindings may run; see `RenderSpecProps.handlers`. A * binding that names an action missing here does nothing. Setting this @@ -314,6 +319,7 @@ function SpecSurface({ registry: options.registry, functions: options.functions, fallback: options.fallback, + pendingFallback: options.pendingFallback, loading: streaming, }; return ( diff --git a/libs/react/src/chat/message-list-interactive-ui.spec.tsx b/libs/react/src/chat/message-list-interactive-ui.spec.tsx index f1a52bf12..e5dd16ab9 100644 --- a/libs/react/src/chat/message-list-interactive-ui.spec.tsx +++ b/libs/react/src/chat/message-list-interactive-ui.spec.tsx @@ -194,12 +194,30 @@ describe('MessageList generativeUi interaction', () => { const view = render( ); - expect(echoes(view.container)).toEqual(['']); + // Bound props wait for the state, behind the render placeholder. + expect(echoes(view.container)).toEqual([]); + expect(view.container.querySelector('.tp-render-pending')).not.toBeNull(); view.rerender(); + expect(view.container.querySelector('.tp-render-pending')).toBeNull(); expect(echoes(view.container)).toEqual(['Ada']); fireEvent.change(view.getByRole('textbox', { name: 'Guest' }), { target: { value: 'Grace' }, }); expect(echoes(view.container)).toEqual(['Grace']); }); + + it('mounts bound elements at once with pendingFallback null', () => { + const content = createMessageContent(); + const rows = content.project( + snapshot([assistant(FORM.slice(0, FORM.indexOf(',"state"')), 'a', true)]) + ); + const options: MessageGenerativeUi = { + registry, + handlers: {}, + pendingFallback: null, + }; + const view = render(); + expect(echoes(view.container)).toEqual(['']); + expect(view.container.querySelector('.tp-render-pending')).toBeNull(); + }); }); diff --git a/libs/react/src/render/computed-functions.spec.tsx b/libs/react/src/render/computed-functions.spec.tsx index 566ac12d9..8f0e9d35e 100644 --- a/libs/react/src/render/computed-functions.spec.tsx +++ b/libs/react/src/render/computed-functions.spec.tsx @@ -221,7 +221,9 @@ describe('RenderSpec computed functions', () => { {...{ functions: {} }} /> ); - expect(view.container.querySelector('p')?.textContent).toBe(''); + // An unknown function resolves to undefined, so the element waits. + expect(view.container.querySelector('p')).toBeNull(); + expect(view.getByRole('status')).toBeTruthy(); } ); diff --git a/libs/react/src/render/default-readiness.spec.tsx b/libs/react/src/render/default-readiness.spec.tsx new file mode 100644 index 000000000..9f2b0f08e --- /dev/null +++ b/libs/react/src/render/default-readiness.spec.tsx @@ -0,0 +1,186 @@ +import { cleanup, render } from '@testing-library/react'; +import { afterEach, describe, expect, it } from 'vitest'; +import { + RenderPendingFallback, + RenderSpec, + type ReactRenderRegistry, + type RenderEvent, + type RenderSpecData, + type RenderViewProps, +} from './index'; + +afterEach(cleanup); + +const Label = ({ props }: RenderViewProps) => ( +

{String(props['text'])}

+); +const Box = ({ children }: RenderViewProps) =>
{children}
; +const bound: RenderSpecData = { + root: 'label', + elements: { + label: { type: 'Label', props: { text: { $state: '/title' } } }, + }, +}; + +describe('default readiness', () => { + it('shows the default placeholder while a bound prop is undefined, then the component', () => { + const view = render( + + ); + expect(view.queryByTestId('label')).toBeNull(); + const status = view.getByRole('status'); + expect(status.className).toContain('tp-genui-skeleton'); + expect(status.textContent).toContain('Building UI'); + view.rerender( + + ); + expect(view.queryByRole('status')).toBeNull(); + expect(view.getByTestId('label').textContent).toBe('Lyon'); + }); + + it('latches: a ready element never returns to the placeholder', () => { + const view = render( + + ); + const label = view.getByTestId('label'); + view.rerender(); + expect(view.queryByRole('status')).toBeNull(); + expect(view.getByTestId('label')).toBe(label); + expect(label.textContent).toBe('undefined'); + }); + + it('mounts an element with only literal or defined props at once', () => { + const spec: RenderSpecData = { + root: 'label', + elements: { label: { type: 'Label', props: { text: 'Plain' } } }, + }; + const view = render(); + expect(view.queryByRole('status')).toBeNull(); + expect(view.getByTestId('label').textContent).toBe('Plain'); + }); + + it('gates each repeat row on its own props and latches per row', () => { + const spec: RenderSpecData = { + root: 'rows', + elements: { + rows: { + type: 'Box', + props: {}, + children: ['row'], + repeat: { statePath: '/rows', key: 'id' }, + }, + row: { type: 'Label', props: { text: { $item: 'text' } } }, + }, + }; + const registry = { Box, Label } satisfies ReactRenderRegistry; + const view = render( + + ); + expect(view.getAllByTestId('label').map((el) => el.textContent)).toEqual([ + 'A', + ]); + expect(view.getAllByRole('status')).toHaveLength(1); + view.rerender( + + ); + expect(view.queryByRole('status')).toBeNull(); + expect(view.getAllByTestId('label').map((el) => el.textContent)).toEqual([ + 'undefined', + 'B', + ]); + }); + + it('uses a custom pendingFallback with the pending view props', () => { + const Pending = ({ elementKey, props }: RenderViewProps) => ( +

+ waiting {elementKey} {String('text' in props)} +

+ ); + const view = render( + + ); + expect(view.getByText('waiting label true')).toBeTruthy(); + expect(view.queryByRole('status')).toBeNull(); + }); + + it('opts out for the tree with pendingFallback null', () => { + const view = render( + + ); + expect(view.queryByRole('status')).toBeNull(); + expect(view.getByTestId('label').textContent).toBe('undefined'); + }); + + it('opts out for one entry with a readiness entry that is always ready', () => { + const registry = { + Label: { kind: 'readiness', component: Label, isReady: () => true }, + } satisfies ReactRenderRegistry; + const view = render( + + ); + expect(view.queryByRole('status')).toBeNull(); + expect(view.getByTestId('label').textContent).toBe('undefined'); + }); + + it('does not gate the fallback for unknown types', () => { + const spec: RenderSpecData = { + root: 'x', + elements: { x: { type: 'Unknown', props: { text: { $state: '/t' } } } }, + }; + const view = render( + + ); + expect(view.getByTestId('label').textContent).toBe('undefined'); + }); + + it('reports the element mounted once, while the placeholder shows, as Angular does', () => { + const events: RenderEvent[] = []; + const view = render( + events.push(event)} + /> + ); + view.rerender( + events.push(event)} + /> + ); + const mounts = events.filter( + (event) => + event.type === 'lifecycle' && + event.scope === 'element' && + event.event === 'mounted' + ); + expect(mounts).toHaveLength(1); + expect(view.getByTestId('label').textContent).toBe('Lyon'); + }); + + it('exports the default placeholder for reuse', () => { + const view = render(); + expect(view.getByRole('status').textContent).toContain('Building UI'); + }); +}); diff --git a/libs/react/src/render/index.ts b/libs/react/src/render/index.ts index 680fddc6a..3afbece6b 100644 --- a/libs/react/src/render/index.ts +++ b/libs/react/src/render/index.ts @@ -1,5 +1,6 @@ 'use client'; export { RenderSpec } from './render-spec.js'; +export { RenderPendingFallback } from './pending-fallback.js'; export { RenderDevtools } from './devtools.js'; export type { RenderDevtoolsProps } from './devtools.js'; export { createRenderLifecycle } from './lifecycle.js'; diff --git a/libs/react/src/render/pending-fallback.tsx b/libs/react/src/render/pending-fallback.tsx new file mode 100644 index 000000000..994140dee --- /dev/null +++ b/libs/react/src/render/pending-fallback.tsx @@ -0,0 +1,24 @@ +import type { ComponentType } from 'react'; +import type { RenderViewProps } from './types.js'; + +/** + * The placeholder `RenderSpec` shows in place of a registered element while any + * of its resolved props is still undefined. It uses the `GenerativeUiSkeleton` + * markup and classes, so the chat and A2UI stylesheets style it. Pass your own + * component as `RenderSpec`'s `pendingFallback` to replace it. + */ +export const RenderPendingFallback: ComponentType = () => ( +
+ Building UI… +
+); diff --git a/libs/react/src/render/readiness.spec.tsx b/libs/react/src/render/readiness.spec.tsx index a1f42583f..1a641b85a 100644 --- a/libs/react/src/render/readiness.spec.tsx +++ b/libs/react/src/render/readiness.spec.tsx @@ -108,10 +108,17 @@ function node(value?: string) { } function mount( initial: RenderReadinessEntry = entry(), - state: NonNullable = node('ready') + state: NonNullable = node('ready'), + // `null` turns off the default wait for direct components. + pendingFallback?: null ) { const view = render( - + ); return { ...view, @@ -120,7 +127,12 @@ function mount( nextState = node() ) { view.rerender( - + ); }, }; @@ -133,7 +145,7 @@ function edit(view: ReturnType) { describe('readiness contracts', () => { it.each(['function', 'memo', 'forwardRef'])( - 'keeps direct %s views immediate with undefined props', + 'keeps direct %s views immediate with undefined props when pendingFallback is null', (kind) => { const Component = kind === 'memo' @@ -145,7 +157,7 @@ describe('readiness contracts', () => { )) : Input; - const view = mount(entry()); + const view = mount(entry(), node('ready'), null); view.update(Component); expect(view.getByText('undefined')).toBeTruthy(); expect(view.getByRole('textbox')).toBeTruthy(); @@ -251,7 +263,7 @@ describe('readiness contracts', () => { ) ).toThrow(error); }); - it('uses null for absent pending fallback and reserves top fallback for unknown types', () => { + it('uses the tree placeholder for absent pending fallback, null when turned off, and reserves top fallback for unknown types', () => { const top = vi.fn(() =>

unknown

); const view = render( { fallback={top} /> ); + expect(view.getByRole('status').textContent).toContain('Building UI'); + view.rerender( + + ); expect(view.container.textContent).toBe(''); expect(top).not.toHaveBeenCalled(); view.rerender(); @@ -270,7 +292,11 @@ describe('readiness contracts', () => { const Component = memo(Input); Object.setPrototypeOf(Component, { kind: 'readiness' }); const view = render( - + ); expect(view.getByRole('textbox')).toBeTruthy(); }); @@ -407,7 +433,7 @@ describe('readiness contracts', () => { }); it('resets descriptor lifetime across direct component dispatch', () => { const config = entry(); - const view = mount(config); + const view = mount(config, node('ready'), null); const old = edit(view); view.update(Input); expect(view.getByRole('textbox')).not.toBe(old); diff --git a/libs/react/src/render/readiness.tsx b/libs/react/src/render/readiness.tsx index aae661078..bc88baa63 100644 --- a/libs/react/src/render/readiness.tsx +++ b/libs/react/src/render/readiness.tsx @@ -24,6 +24,20 @@ function sameContract(left: Contract, right: Contract): boolean { ); } +function admit( + entry: RenderReadinessEntry, + props: RenderViewProps['props'] +): boolean { + if (typeof entry.isReady !== 'function') + throw new TypeError('Render readiness isReady must be a function.'); + const result = entry.isReady(props); + if (typeof result !== 'boolean') + throw new TypeError( + 'Render readiness isReady must return a synchronous boolean.' + ); + return result; +} + /** A gate is unmounted by the renderer's normal missing/hidden/direct paths. */ export function ReadinessGate({ entry, @@ -39,24 +53,17 @@ export function ReadinessGate({ component: entry.component, isReady: entry.isReady, }; + // A first render that is ready starts admitted, so the real view renders once + // rather than again from the layout effect. An abandoned mount discards it. const [committed, setCommitted] = useState(() => ({ contract, generation: 0, - mounted: false, + mounted: admit(entry, view.props), })); const unchanged = sameContract(committed.contract, contract); const generation = committed.generation + (unchanged ? 0 : 1); let ready = unchanged && committed.mounted; - if (!ready) { - if (typeof entry.isReady !== 'function') - throw new TypeError('Render readiness isReady must be a function.'); - const result = entry.isReady(view.props); - if (typeof result !== 'boolean') - throw new TypeError( - 'Render readiness isReady must return a synchronous boolean.' - ); - ready = result; - } + if (!ready) ready = admit(entry, view.props); // Only a successful commit of this subtree records admission. Suspended or // abandoned candidates cannot latch; a committed pending contract retires A. useLayoutEffect(() => { diff --git a/libs/react/src/render/render-spec.spec.tsx b/libs/react/src/render/render-spec.spec.tsx index 5abf78147..f7ee1cc39 100644 --- a/libs/react/src/render/render-spec.spec.tsx +++ b/libs/react/src/render/render-spec.spec.tsx @@ -352,7 +352,14 @@ describe('RenderSpec', () => { }, }; const before = JSON.stringify({ state, spec }); - render(); + render( + + ); if (!captured) throw new Error('Capture view did not render'); expect(captured.props['missing']).toBeUndefined(); const payload = captured.props['payload'] as { diff --git a/libs/react/src/render/render-spec.tsx b/libs/react/src/render/render-spec.tsx index a46bf2648..a262a5421 100644 --- a/libs/react/src/render/render-spec.tsx +++ b/libs/react/src/render/render-spec.tsx @@ -26,6 +26,7 @@ import type { import { ownRenderValue } from './values.js'; import { ownRenderFunctions } from './functions.js'; import { ReadinessGate } from './readiness.js'; +import { RenderPendingFallback } from './pending-fallback.js'; import { RenderDevtoolsMark, RenderDevtoolsScope } from './devtools.js'; import type { RenderReadinessEntry, @@ -42,8 +43,12 @@ const EMPTY_STATE = Object.freeze({}); const NO_STORE = Object.freeze({}); const noSubscription = () => () => undefined; declare const process: { readonly env: { readonly NODE_ENV?: string } }; +/** The default admission: every resolved prop has a value, as in Angular's renderer. */ +const allPropsDefined: RenderReadinessEntry['isReady'] = (props) => + Object.values(props).every((value) => value !== undefined); interface ElementProps extends Pick { + readonly pendingFallback: RenderSpecProps['pendingFallback']; readonly spec: NonNullable; readonly elementKey: string; readonly context: PropResolutionContext; @@ -74,6 +79,7 @@ function Element({ registry, loading, fallback, + pendingFallback, context, ancestors, interaction, @@ -89,10 +95,10 @@ function Element({ ) ) return null; - const entry = - (Object.hasOwn(registry, element.type) - ? registry[element.type] - : undefined) ?? fallback; + const registered = Object.hasOwn(registry, element.type) + ? registry[element.type] + : undefined; + const entry = registered ?? fallback; if (!entry) return null; const rawProps = ownRenderValue(element.props, true) as Record< string, @@ -117,6 +123,7 @@ function Element({ registry={registry} loading={loading} fallback={fallback} + pendingFallback={pendingFallback} context={childContext} ancestors={nextAncestors} interaction={interaction} @@ -178,16 +185,40 @@ function Element({ }, }; const Component = entry as Exclude; + // As in Angular, a registered component waits while any resolved prop is + // undefined, and a readiness entry without its own fallback shows the tree's + // placeholder. `pendingFallback={null}` turns both off. The unknown-type + // `fallback` is not a registry entry and mounts at once. + const placeholder = + pendingFallback === null + ? undefined + : pendingFallback ?? RenderPendingFallback; + const own = + Object.hasOwn(entry, 'kind') && + (entry as RenderReadinessEntry).kind === 'readiness' + ? (entry as RenderReadinessEntry) + : undefined; + const gate: RenderReadinessEntry | undefined = own + ? own.fallback !== undefined || placeholder === undefined + ? own + : { ...own, fallback: placeholder } + : registered !== undefined && placeholder !== undefined + ? { + kind: 'readiness', + component: Component, + isReady: allPropsDefined, + fallback: placeholder, + } + : undefined; return ( - {Object.hasOwn(entry, 'kind') && - (entry as RenderReadinessEntry).kind === 'readiness' ? ( + {gate !== undefined ? ( @@ -238,6 +269,7 @@ export function RenderSpec({ functions, loading, fallback, + pendingFallback, handlers, onEvent, }: RenderSpecProps) { @@ -299,6 +331,7 @@ export function RenderSpec({ registry={registry} loading={loading} fallback={fallback} + pendingFallback={pendingFallback} context={{ stateModel, functions: ownRenderFunctions(functions) }} ancestors={new Set()} interaction={interaction} diff --git a/libs/react/src/render/render.type-test.ts b/libs/react/src/render/render.type-test.ts index 484868b25..eee43960e 100644 --- a/libs/react/src/render/render.type-test.ts +++ b/libs/react/src/render/render.type-test.ts @@ -13,7 +13,7 @@ import type { RenderStore, } from './index.js'; import type { RenderState } from '@threadplane/content/render-state'; -import { RenderSpec } from './index.js'; +import { RenderPendingFallback, RenderSpec } from './index.js'; import type { Json } from '@threadplane/content/json'; const spec = { @@ -34,6 +34,10 @@ const functions: ReactRenderFunctions = { uppercase: ({ value }) => String(value).toUpperCase(), }; RenderSpec({ spec, registry, functions }); +RenderSpec({ spec, registry, pendingFallback: RenderPendingFallback }); +RenderSpec({ spec, registry, pendingFallback: null }); +// @ts-expect-error pendingFallback is a component or null, not an element. +RenderSpec({ spec, registry, pendingFallback: 'Loading' }); export function computedContracts( args: Readonly>, diff --git a/libs/react/src/render/seeded-state.spec.tsx b/libs/react/src/render/seeded-state.spec.tsx index 72379e57d..52800d55a 100644 --- a/libs/react/src/render/seeded-state.spec.tsx +++ b/libs/react/src/render/seeded-state.spec.tsx @@ -94,7 +94,8 @@ describe('RenderSpec state carried by the spec', () => { it('seeds the store when state first appears in a later spec', () => { const view = render(); - expect(field(view).readOnly).toBe(true); + // The field waits for its bound value. + expect(view.queryByRole('textbox', { name: 'Name' })).toBeNull(); view.rerender( ); @@ -103,7 +104,9 @@ describe('RenderSpec state carried by the spec', () => { }); it('stays read-only for a spec without state', () => { - const view = render(); + const view = render( + + ); expect(field(view).value).toBe(''); expect(field(view).readOnly).toBe(true); }); diff --git a/libs/react/src/render/types.ts b/libs/react/src/render/types.ts index 2daee7367..208e59eee 100644 --- a/libs/react/src/render/types.ts +++ b/libs/react/src/render/types.ts @@ -131,7 +131,15 @@ interface RenderSpecBaseProps { readonly registry: ReactRenderRegistry; readonly functions?: ReactRenderFunctions; readonly loading?: boolean; + /** Renders an element whose type the registry does not name. Without it, such elements are left out. */ readonly fallback?: ComponentType; + /** + * Shown in place of a registered component while any of the element's resolved props is + * undefined, such as a state path that has not arrived. Once the props resolve, the component + * mounts and stays mounted for that element. Defaults to `RenderPendingFallback`; `null` mounts + * every component at once. A readiness entry decides for itself and uses its own `fallback`. + */ + readonly pendingFallback?: ComponentType | null; /** Actions the spec's `on` bindings may run. Without them, events do nothing. */ readonly handlers?: ReactRenderHandlers; /** Notified when an action runs, the store changes, or a view reports a result. */ diff --git a/scripts/react-parity/dispositions.json b/scripts/react-parity/dispositions.json index 0987ec8a6..debc2e423 100644 --- a/scripts/react-parity/dispositions.json +++ b/scripts/react-parity/dispositions.json @@ -19415,6 +19415,26 @@ "treatment": "react", "status": "in-progress", "note": "Turns RenderSpec lifecycle, stateChange and handler events into first-mount, mount-count and latest-activity timings, the React counterpart of Angular RENDER_LIFECYCLE." + }, + { + "id": "export:libs/react/src/render/index.ts#RenderPendingFallback", + "taskIds": [ + "T20", + "T24" + ], + "treatment": "react", + "status": "in-progress", + "note": "Default placeholder RenderSpec shows while a registered element has an undefined resolved prop, the React counterpart of Angular DefaultFallbackComponent and A2uiDefaultFallbackComponent. Uses the GenerativeUiSkeleton markup." + }, + { + "id": "source:libs/react/src/render/pending-fallback.tsx", + "taskIds": [ + "T20", + "T24" + ], + "treatment": "react", + "status": "in-progress", + "note": "RenderPendingFallback: the default readiness placeholder for every registered component, mirroring Angular defineAngularRegistry's DefaultFallbackComponent." } ] } diff --git a/scripts/react-parity/verify-packages.mjs b/scripts/react-parity/verify-packages.mjs index 588e0b402..0efa1dec8 100644 --- a/scripts/react-parity/verify-packages.mjs +++ b/scripts/react-parity/verify-packages.mjs @@ -521,7 +521,7 @@ const SUPPORTED_EXPORTS = { ], 'react/debug': ['ChatDebug', 'StateDiff', 'useAgentDevtools'], 'react/markdown': ['Markdown', 'MarkdownComponentsProvider', 'MarkdownCopyButton'], - 'react/render': ['RenderSpec', 'createRenderLifecycle', 'RenderDevtools'], + 'react/render': ['RenderSpec', 'createRenderLifecycle', 'RenderDevtools', 'RenderPendingFallback'], 'react/a2ui': ['A2uiSurface', 'a2uiBasicCatalog', 'useA2uiSurfaceWriter', 'A2uiMessageSurfaces', 'a2uiClientCapabilities'], 'content/messages': ['createMessageContent', 'deriveDomain', 'deriveSourceType', 'deriveMonogram', 'monogramHue', 'formatPublished', 'monogramColor', 'citationTypeMeta', 'citationTypeLabel', 'citationSourceVisual'], 'content/json': ['createJson'], diff --git a/scripts/react-parity/verify-packages.spec.mjs b/scripts/react-parity/verify-packages.spec.mjs index fc10c7659..b8cdc4584 100644 --- a/scripts/react-parity/verify-packages.spec.mjs +++ b/scripts/react-parity/verify-packages.spec.mjs @@ -1086,7 +1086,7 @@ test('React chat requires its real supported export', () => { assert.throws(() => packageVerifier.assertSupportedExports('react/chat', { ...supported, isTyping: forwarded }), /isTyping/); assert.throws(() => packageVerifier.assertSupportedExports('core', { completeDelivery: forwarded }), /completeDelivery/); }); -test('React render requires exactly the RenderSpec, lifecycle recorder and RenderDevtools runtime exports', () => { +test('React render requires exactly the RenderSpec, lifecycle recorder, RenderDevtools and RenderPendingFallback runtime exports', () => { const RenderSpec = () => null; const createRenderLifecycle = () => ({}); assert.throws(() => packageVerifier.assertSupportedExports('react/a2ui', {}), /A2uiSurface/); @@ -1100,8 +1100,10 @@ test('React render requires exactly the RenderSpec, lifecycle recorder and Rende assert.throws(() => packageVerifier.assertSupportedExports('react/render', {}), /RenderSpec/); assert.throws(() => packageVerifier.assertSupportedExports('react/render', { RenderSpec }), /createRenderLifecycle/); assert.throws(() => packageVerifier.assertSupportedExports('react/render', { RenderSpec, createRenderLifecycle }), /RenderDevtools/); - assert.doesNotThrow(() => packageVerifier.assertSupportedExports('react/render', { RenderSpec, createRenderLifecycle, RenderDevtools })); - assert.throws(() => packageVerifier.assertSupportedExports('react/render', { RenderSpec, createRenderLifecycle, RenderDevtools, createStateStore: () => ({}) }), /unexpected/); + const RenderPendingFallback = () => null; + assert.throws(() => packageVerifier.assertSupportedExports('react/render', { RenderSpec, createRenderLifecycle, RenderDevtools }), /RenderPendingFallback/); + assert.doesNotThrow(() => packageVerifier.assertSupportedExports('react/render', { RenderSpec, createRenderLifecycle, RenderDevtools, RenderPendingFallback })); + assert.throws(() => packageVerifier.assertSupportedExports('react/render', { RenderSpec, createRenderLifecycle, RenderDevtools, RenderPendingFallback, createStateStore: () => ({}) }), /unexpected/); }); test('headless framework root rejects the render adapter and engine', () => { assert.throws(() => packageVerifier.assertHeadlessInputs({ 'node_modules/@threadplane/react/src/render/render-spec.js': {} }), /render/i); From fe3b08511b528e16b3e9c9dc4c22f4afbf87e532 Mon Sep 17 00:00:00 2001 From: Brian Love Date: Tue, 17 Nov 2026 18:57:05 -0800 Subject: [PATCH 2/2] test(react): keep the readiness package proof under the default placeholder RenderSpec now shows RenderPendingFallback while a registered component has an undefined resolved prop. The installed readiness proof registered memo and forwardRef components directly with an unresolved $state binding and expected them to render with undefined, so it timed out waiting for them. The direct exotic spec now renders with pendingFallback={null}, the documented opt-out, keeping its intent: memo and forwardRef components register directly and receive undefined props. A second tree renders the same unresolved binding without the opt-out and asserts the default placeholder appears and the component is withheld. The null-fallback steps assert that a readiness entry without its own fallback shows the tree placeholder. The plain consumer's A2uiSurfaceProps and A2uiMessageSurfacesProps exact-type contracts include the new pendingFallback prop. Co-Authored-By: Claude Opus 5.5 --- .../react-parity/react-readiness/README.md | 2 +- .../react-parity/react-readiness/react.tsx | 36 +++++++++++++++---- scripts/react-parity/verify-packages.mjs | 4 +-- .../react-parity/verify-react-readiness.mjs | 28 +++++++++++++-- 4 files changed, 57 insertions(+), 13 deletions(-) diff --git a/fixtures/react-parity/react-readiness/README.md b/fixtures/react-parity/react-readiness/README.md index bb406ff7c..9ad309177 100644 --- a/fixtures/react-parity/react-readiness/README.md +++ b/fixtures/react-parity/react-readiness/README.md @@ -4,4 +4,4 @@ Private, bounded development StrictMode fixture for the actual application-owned Run `node scripts/react-parity/verify-react-readiness.mjs --retain NEW_DIRECTORY` after fresh core, content, and React builds. The runner installs exactly those three local artifacts using the existing `react-render` profile and current root lock. Strict installed type checking uses `skipLibCheck:false`. Vite builds without workspace configuration or environment files and records all module inputs separately from modules with executed bytes. Installed parser dependencies are legitimate; parser execution is excluded from this proof. -The browser checks literal state and command counts, actual DOM identity and edited local inputs, pending children and null fallback, committed admission followed by missing data, contract replacement, remounts, direct memo/forwardRef undefined values, stable repeated keys, and a real suspended candidate cancelled before admission commits. Each browser step and screenshot is retained with installed/type/emitted/source hashes, the root lock fingerprint, and owned process/profile/socket cleanup receipts. This fixture does not claim full renderer parity, SSR, schema validation, forms, or backend integration. +The browser checks literal state and command counts, actual DOM identity and edited local inputs, pending children and an absent fallback that shows the default placeholder, committed admission followed by missing data, contract replacement, remounts, direct memo/forwardRef undefined values under `pendingFallback={null}`, the default placeholder for an unresolved binding without that opt-out, stable repeated keys, and a real suspended candidate cancelled before admission commits. Each browser step and screenshot is retained with installed/type/emitted/source hashes, the root lock fingerprint, and owned process/profile/socket cleanup receipts. This fixture does not claim full renderer parity, SSR, schema validation, forms, or backend integration. diff --git a/fixtures/react-parity/react-readiness/react.tsx b/fixtures/react-parity/react-readiness/react.tsx index 70b6519bd..1b69b56b3 100644 --- a/fixtures/react-parity/react-readiness/react.tsx +++ b/fixtures/react-parity/react-readiness/react.tsx @@ -140,6 +140,17 @@ const directRegistry: ReactRenderRegistry = { Memo: DirectMemo, Forward: DirectForward, }; +// The same unresolved binding without the opt-out: the default placeholder stands in. +function DefaultWaitReal() { + return

Mounted too early

; +} +const defaultWaitSpec: RenderSpecData = { + root: 'wait', + elements: { + wait: { type: 'Wait', props: { absent: { $state: '/missing' } } }, + }, +}; +const defaultWaitRegistry: ReactRenderRegistry = { Wait: DefaultWaitReal }; const rowSpec: RenderSpecData = { root: 'rows', elements: { @@ -184,18 +195,29 @@ function App() { return ( <>

{descriptor}

- +
+ +
+ {/* Direct exotic components receive undefined props only with the documented opt-out. */} +
+ +
); diff --git a/scripts/react-parity/verify-packages.mjs b/scripts/react-parity/verify-packages.mjs index 0efa1dec8..f4aae9161 100644 --- a/scripts/react-parity/verify-packages.mjs +++ b/scripts/react-parity/verify-packages.mjs @@ -246,11 +246,11 @@ export type CitationSourceVisualFunctionContract = CitationDisplayAssert = (() => T extends A ? 1 : 2) extends (() => T extends B ? 1 : 2) ? true : false; type A2uiAssert = T; -export type A2uiSurfacePropsContract = A2uiAssert void; readonly onValidationError?: (error: import('@threadplane/content/a2ui').A2uiValidationErrorMessage) => void; readonly functions?: { readonly [name: string]: (args: { readonly [name: string]: import('@threadplane/content/a2ui').A2uiValue }) => void }; readonly catalog?: import('@threadplane/react/render').ReactRenderRegistry; readonly className?: string }>>; +export type A2uiSurfacePropsContract = A2uiAssert void; readonly onValidationError?: (error: import('@threadplane/content/a2ui').A2uiValidationErrorMessage) => void; readonly functions?: { readonly [name: string]: (args: { readonly [name: string]: import('@threadplane/content/a2ui').A2uiValue }) => void }; readonly catalog?: import('@threadplane/react/render').ReactRenderRegistry; readonly pendingFallback?: import('react').ComponentType | null; readonly className?: string }>>; export type A2uiSurfaceParameterContract = A2uiAssert[0], import('@threadplane/react/a2ui').A2uiSurfaceProps>>; export type A2uiMessageContentContract = A2uiAssert>; export type A2uiMessageSurfacesParameterContract = A2uiAssert[0], import('@threadplane/react/a2ui').A2uiMessageSurfacesProps>>; -export type A2uiMessageSurfacesPropsContract = A2uiAssert>; +export type A2uiMessageSurfacesPropsContract = A2uiAssert>; export type A2uiSurfaceWriterContract = A2uiAssert void }>>; export type A2uiSurfacesSetValueContract = A2uiAssert boolean>>; export type A2uiCreateActionMessageContract = A2uiAssert import('@threadplane/content/a2ui').A2uiActionMessage | null>>; diff --git a/scripts/react-parity/verify-react-readiness.mjs b/scripts/react-parity/verify-react-readiness.mjs index c737a2e09..e508f67f2 100644 --- a/scripts/react-parity/verify-react-readiness.mjs +++ b/scripts/react-parity/verify-react-readiness.mjs @@ -447,13 +447,25 @@ export async function verifyReadinessBrowser( })) assert.equal(await view.getAttribute(attr), expected, attr); } - if (visible) + if (visible) { for (const name of ['direct-memo', 'direct-forward']) assert.equal( await page.getByTestId(name).textContent(), 'undefined', - 'Direct exotic component preserves undefined' + 'Direct exotic component preserves undefined with pendingFallback null' ); + const wait = page.getByTestId('default-wait'); + assert.equal( + await wait.locator('.tp-render-pending[role="status"]').count(), + 1, + 'Default placeholder stands in for an unresolved binding' + ); + assert.equal( + await page.getByTestId('default-wait-real').count(), + 0, + 'Default wait withholds the component' + ); + } }; const screenshot = async (action, index) => { if (directory) @@ -599,8 +611,18 @@ export async function verifyReadinessBrowser( if (action === 'Missing while hidden') current = { real: false }; if (action === 'Show pending') current = { real: false, pending: true, value: null }; - if (['Null fallback', 'Remount pending'].includes(action)) + if (['Null fallback', 'Remount pending'].includes(action)) { current = { real: false }; + // A readiness entry without its own fallback shows the tree's default placeholder. + assert.equal( + await page + .getByTestId('main-tree') + .locator('.tp-render-pending[role="status"]') + .count(), + 1, + 'Absent readiness fallback uses the default placeholder' + ); + } if (action === 'Ready after remount') { current = { real: true,