feat(render, chat): development-only render report for the AG-UI DevTools UI tab - #1215

…nd what didn't render (#60)

* docs: UI inspector design and plans (§14.5)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* §14.5 A1: generative-UI surfaces, catalogs and checks (U1–U3)

core/genui/extract.ts reads every A2UI / json-render surface out of a
capture: Threadplane's sentinel text, json-render text, a2ui-partial
custom events (last valid parse wins, a poisoned call stops) and GenUI
tool args over AG-UI and LangGraph; CopilotKit's a2ui-surface activities
in both middleware forms (v0.0.10 a2ui_operations snapshots, v0.0.2
operations deltas + replace:false snapshots) with lifecycle status.
Malformed payloads become findings, never throws.

core/genui/catalog.ts: the exact catalog from RunAgentInput.context
(A2UI_SCHEMA_CONTEXT_DESCRIPTION), a registry catalog for A2, and the
inferred A2UI v0.9 basic catalog (18 components, both basic ids).

core/genui/check.ts: unknown_component, missing_required_prop (exact
only), unresolved_child, orphaned_subtree, no_root, duplicate_id,
catalog_mismatch, each labelled exact or inferred.

Golden fixtures: a slice of Threadplane's stage-replay.json (LangGraph,
158 KB), a CopilotKit capture from the middleware tests' sequences, and
Threadplane json-render/A2UI over AG-UI incl. the cockpit render_spec.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* §14.5 A2: capture Threadplane render reports (U4, U5)

core/signals/render-report.ts validates U4's render report beside the
signals one: exact key sets (the report's and each element's), v 1,
kind 'render', surface/registry names/element keys and types 1-128
chars, at most 500 registry names and 2,000 elements, states mounted |
fallback | unresolved | hidden, own properties only, never throws.
cloneRenderReport copies field by field, one level deeper per element,
bounded by the contract rather than a re-read length.

The threadplane:devtools listener routes each detail by its own kind:
absent is a signals report, 'render' a render report, anything else is
dropped; each is validated, copied and re-checked before posting. The
render report rides its own connectionless arm (kind 'render') through
the inject guard, the relay's field-by-field rebuild and the worker,
which keeps a separate per-tab ring of 500 (eviction counted), paused
with capture, cleared with the buffer, and mirrored as a tail bounded
by count (100) and size (1 MB). Snapshot and append carry renders; the
panel folds them into PanelState.renders (bounded, empty for imports)
and its coalescer now batches render-only appends with signals ones.

Tests at every layer incl. hostile inputs, Threadplane-shaped reports
from cacheplane/threadplane#1215's specs through the validator, and an
e2e page dispatching valid, hostile and signals reports on one event.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* §14.5 A3: the UI tab — generative-UI surfaces, trees and findings (U6)

Surfaces grouped by run, each with its framework, format, status, the
catalog it was checked against and its basis (exact / inferred / none);
a component tree from the root, with what the root cannot reach listed
separately and a reference the surface does not hold shown as such;
each node badged rendered / fallback / not rendered / unknown type. The
states come from the latest Threadplane render report whose surface is
the surface's id (A2UI id, or spec: + root), applied to the most recent
surface with that id — and its registry is passed into inspectGenui
(new per-surface registryFor) so that surface's checks become exact —
else from the wire checks; the tab says which. Findings per surface,
extraction findings per run; selecting a node shows its props and links
its source frame in Timeline. The empty state names what the view lists.

Visual gate: both golden fixtures imported, then the Threadplane one
live with a seeded render report (devtools-live-genui shim), asserting
the cockpit's node states switch to the hook's in both schemes.

Docs: README status, PRIVACY (render report is names and states only),
listing line, spec §14.5 note.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(genui): review fixes

- Linear-time extraction and checks on hostile captures: the partial-JSON
  scanner no longer snapshots the open stack per token (quadratic in depth);
  orphaned-subtree marking walks the surface once; duplicate ids and touched
  surfaces use Sets; no argument spreads (Math.max(...seqs), push(...findings))
  that overflow past ~120k elements; an unstringifiable LangGraph message is
  skipped instead of throwing out of extractSurfaces.
- UI tab: trees are capped at MAX_TREE_DEPTH (64) and marked "deeper levels not
  shown" (a 5,000-deep surface overflowed Preact's render); reachability is
  walked iteratively apart from drawing; the capture is extracted once per model.
- A render report's registry is widened by the types its elements show
  resolving, by long types it cannot carry, and (at the 500-name cap) by every
  wire type it does not call unresolved — no false exact unknown_component.
- Render ring bounded by size as well as count (MAX_RENDER_RING_CHARS, 4 M
  serialized characters) in the worker, its restore, and the panel's copy.
- e2e quiet-page: wait for the worker to report the document loaded
  (readLoadedCapture) instead of racing the relay's capture-loaded message.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(acceptance): the UI inspector against a real Threadplane build

acceptance:threadplane now also renders an A2UI surface and a json-render spec
(each with one unknown type and a child under it) through <a2ui-surface> and
<chat-generative-ui> after a real AG-UI run, and asserts the worker holds the
render reports (unresolved / hidden / mounted) and that the UI tab's model
badges the captured surfaces the same. Builds render and a2ui too when stale.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>