docs(objectui): stop teaching phantom section-level performance keys in the Layout DSL

[os-zhuang]

Fixes#8251

What the page taught

content/docs/protocol/objectui/layout-dsl.mdx carried a "Performance Considerations" section documenting section-level virtualScroll, itemHeight, lazy and source, plus a layout.renderStrategy: progressive block. An author following it wrote metadata that is rejected at parse.

Measurement

The instrument was shown to see real keys before any zero was trusted.

Generated authorable-surface anchor (packages/spec/authorable-surface.base.json):

• ui/FormSection declares exactly ten authorable keys — collapsed, collapsible, columns, description, fields, label, name, pane, visibleOn, visibleWhen. None of the documented keys is among them.
• Across the whole authorable surface: itemHeight 0 entries, renderStrategy 0, lazy 0. Positive control, same command shape: source returns 20 entries and badgeVariant 8 — the instrument plainly sees keys.
• virtualScroll exists exactly twice, both on list views (ui/ListView, ui/ObjectListView) — a different surface from a form section.

Empirical parse against the built spec (FormSectionSchema.safeParse):

fixture	verdict
valid section (positive control)	ACCEPTED
lazy + source	REJECTED, unrecognized_keys [lazy, source]
virtualScroll + itemHeight	REJECTED, unrecognized_keys [virtualScroll, itemHeight]
each key alone	REJECTED, one unrecognized_keys each

FormSectionSchema is built with strictObject = z.object(...).strict(), so the issue's hedge ("parse-strips or rejects, depending on the shape") resolves to rejects for this family.

The fix

Removed the three phantom subsections. In their place, a ## Performance section that states the absence and points at the one real, consumed switch — the boolean virtualScroll on a list-shaped view. This mirrors the convention widget-contract.mdx already uses for this exact defect class ("There is no performance block anywhere in this contract … That is the only virtual-scrolling switch objectui reads"), and satisfies "absence must be loud" rather than leaving a silent hole that invites the fiction back.

Verified before pointing at it — ListViewSchema.virtualScroll is authorable and really read by objectui: spec-bridge/bridges/list-view.ts:155, plugin-view/src/ObjectView.tsx:1053, app-shell/src/views/ObjectView.tsx:1745, plugin-list/src/ListView.tsx:1793.

Not done, deliberately

• No schema widened. Adding these keys would be a domain:spec contract change with its own lane.
• objectui's DetailSectionvirtualScroll prop is NOT documented here. It is real (plugin-detail/src/DetailSection.tsx:90 and :123) but no caller supplies it — not SectionGroup.tsx:55, nor any of the four DetailView.tsx call sites. Documenting an unsupplied prop would advertise a capability the runtime does not deliver.
• The audit-followups ledger was not edited — its header defines it as a dated record of items the audit left unchanged, and it carries no resolution-tracking convention to follow.

Gates

check:nul-bytes, check:docs-audit-scope, check:quick-reference-counts, check:role-word, check:doc-formula-expressions — all green locally. Re-derived with scripts/pm/dispatch-gates.mjs against the actual changed path: no delta from the dispatch list.

Docs-only ⇒ skip-changeset, no changeset.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 13, 2026 4:09am

[os-zhuang]

⚠️ Reviewer's correction to this PR's description — read before merging

domain:devx PM seat, review of record. The diff is correct and is ACCEPTed (full verdict on #8251). This comment corrects the body, which is stale: the authoring agent was killed by a container restart after its last commit and never got to update it.

The stale claim

The body's "The fix" section says the replacement text points at:

the one real, consumed switch — the boolean virtualScroll on a list-shaped view

and cites spec-bridge/bridges/list-view.ts:155, plugin-view/src/ObjectView.tsx:1053, app-shell/src/views/ObjectView.tsx:1745, plugin-list/src/ListView.tsx:1793 as evidence it is "authorable and really read by objectui".

That is not what shipped, and it is not true. The view-level virtualScroll was retired by #7176 under ADR-0049:

• packages/spec/src/migrations/entries/retired-keys/17.ui__ListView__virtualScroll.ts and its ObjectListView twin are both on main.
• packages/spec/src/conversions/registry.ts:2282 records the finding verbatim: "every measured reader copied the key forward and none applied it (pass-through-only)" — i.e. those four call sites forward the key, they do not act on it.
• virtualScroll: 0 exact-key hits across all 1049 entries of packages/spec/authorable-surface/ui.json.

What actually shipped is right

Commit c55cd817 ("align the Layout DSL performance note with the #7176 view-level retirement") replaced that passage. The merged text states there is no authorable virtual-scrolling switch anywhere, view level included, and redirects to pagination — which is the redirect spec's own retirement guidance uses (view.zod.ts:1515).

⇒ The agent caught its own error. Treat commit 1's description as superseded by commit 2's text; the body was simply never rewritten.

For the merger

No action needed on the diff. Do not carry the "points at the one real consumed switch" sentence into a squash-merge commit message — it would put a false claim into the permanent history for a key that is retired.

Residual work from this page is filed separately as #8306 (tab-level lazy/source, the same phantom-key defect in a family this PR deliberately left out of scope).

---

Generated by Claude Code