feat(admin-ui): improve the collection API document viewer — shallower expansion, copy/download, later a JSON mode

[58bits]

Background

ApiView renders the whole document payload with shouldExpandNode={allExpanded}:

• packages/host-tanstack-start/src/admin-shell/collections/api.tsx

For documents with rich text, blocks, multiple locales, and populated relations this produces a long tree that is both expensive to mount and hard to scan.

Evidence

Profiled in the admin UI against a seeded docs document on the dev server:

• Page total: 5396 DOM nodes, of which 4182 (78%) belong to .byline-api-viewer.
• The first layout of that freshly mounted tree costs roughly 740 ms in a dev build. Incremental re-layout of the same page afterwards is ~1 ms whether the viewer is displayed or hidden — so the cost is tied to mounting the expanded tree, not to repeated work.

react-json-view-lite does not mount collapsed descendants, so reducing the initial expansion genuinely reduces DOM size rather than just hiding nodes.

Scope

Keep the current tree viewer. Do not switch libraries for this — there is no comparative profile establishing a benefit.

1. Shallower initial expansion. Show document metadata and the first level of content fields; leave deeper structures collapsed. Keep the expansion callback referentially stable so unrelated renders do not reset the reader's choices.
2. Copy JSON / Download JSON. Both operate on the complete loaded document regardless of what is collapsed, and retain the existing locale and populate-depth controls.
3. A lazily loaded, read-only JSON mode (later). CodeMirror is the natural fit — the repo already has a code editor with JSON and read-only support at packages/admin/src/fields/code/code-editor.tsx. It renders only the visible portion plus a margin, and its search extension searches the document rather than relying on browser Find over rendered text.

That existing editor needs adaptation before reuse as an inspector: search and folding configuration, keyboard focus in read-only mode, and reliable document replacement when locale or depth changes. Its current synchronization deliberately ignores external updates while focused, which suits editing but not an inspector.

Known limitation

Shallow expansion helps nested documents. Expanding an array with thousands of entries still renders all of them, so it does not solve every large-payload case.

Success criterion

Less blocking on mount and a faster usable view, with layout still correct. The
console warning disappearing is not the goal on its own — a change that only
stops Chrome attributing the reflow to JavaScript, while the same layout work
still happens at paint, has not improved anything for the reader.

Validation

Check against representative rich-text and populated documents, not a minimal one.

Compare initial navigation before and after with identical data and viewport,
take repeated measurements rather than one sample, and back them with a browser
performance trace. The numbers quoted above are single samples from a dev build and
are indicative only — they are not a baseline anyone should compare against
directly.

Note

This is a usability improvement first. It is also the change most likely to move the [Violation] Forced reflow warning reported on this view, because it reduces the DOM that must be laid out on mount — see the companion issue on the tabs measurement for why the breadcrumb work did not resolve it.

[58bits]

Shallower initial expansion landed

90d714e8 — packages/host-tanstack-start/src/admin-shell/collections/api.tsx now
expands the document root and the level below it and leaves everything deeper
collapsed:

const expandToFirstLevel = (level: number): boolean => level < 2

Declared at module scope, so its identity is stable across renders and a re-render does
not discard what the reader has opened. react-json-view-lite does not mount collapsed
descendants, so this reduces the mounted tree rather than hiding nodes.

Measurement

Two complete production builds served side by side from one session — one on the
existing allExpanded, one on expandToFirstLevel — measured against the same docs
document, the same viewport, and the same navigation path (client-side transition from
the editor to the API view), six samples each.

	allExpanded	level < 2
navigation-to-double-rAF, median	238.0 ms	99.4 ms
largest timed geometry read	~123 ms (119.7–136.9)	~6.7 ms (6.2–7.8)
long tasks per transition	140–157 ms, every sample	none observed
mounted nodes in .byline-api-viewer	4182	96

Every timed read above 3 ms in the allExpanded arm occurred at one call site:
clientWidth on the breadcrumbs element (breadcrumbs.tsx:63). Reducing the viewer's
initial DOM substantially reduced the measured cost at the breadcrumb read.

The view remains usable: document metadata, title and summary render in full, with
content: [ … ] collapsed, and opening that array still works incrementally
(96 → 101 mounted nodes).

Limits of this measurement

One machine, one viewport, one document. Navigation-to-double-requestAnimationFrame is
a proxy for paint, quantised at about 16.7 ms, and tab visibility was confirmed before
and after the run but not recorded per sample, so treat the timings as approximate. The
mounted node count depends on neither, and is the primary evidence here.

Separate observation

A full page load of the API view behaves differently from a client-side transition.
The baseline full load recorded a cheap breadcrumb read (3.7 ms) and a 156 ms long task;
the variant recorded no long task. The forced-reflow warning has only been observed on
the client-side navigation path.

Still outstanding

• Copy JSON / Download JSON over the complete loaded document, independent of what
  is collapsed, retaining the locale and populate-depth controls.
• The lazily loaded, read-only JSON mode (CodeMirror), with the adaptations this
  issue already lists.
• The known limitation stands: expanding an array with thousands of entries still
  renders all of them.

Keeping this issue open for those.