docs(layout): each page snippet names the pageType that draws its heading, or puts it in a page:header block (objectui#11423)

[objectstack-fleet]

Fixes #11423

Clause-②: no

What changed

content/docs/guide/layout.md had four page snippets that set title (one also set description) and named no pageType. A page with no pageType is a record page. PageRenderer leaves a record page's h1 to a page:header block and never draws its description, so each copied snippet drew no heading. Each passage now names the page type it teaches:

Passage	Decision	Why
Page Component › Basic Usage	"pageType": "app"	It teaches the page's own header on a general page whose body is a placeholder. app is the spec's "App-level page with navigation context", and the Page Header reference's "Usage in a Page" already uses app for a Users page.
With Action Buttons	"pageType": "list"	A products grid with buttons above it. That is the spec's list kind, "Record list/grid surface with switchable visualizations + quick actions".
Detail Page with Actions	"pageType": "record" named; the page-level title removed; the heading moved into a page:header block ("properties": { "title": "Acme Corporation" }) after the breadcrumb	A detail page is a record page, so its heading belongs to page:header. The buttons stay action:button nodes in children: header actions are action ids resolved against a bound object, and this snippet binds none.
Best Practices 3	"pageType": "list"	A list of orders with a "New Order" button. The passage's own follow-up already contrasts it with a record page.

Prose: Basic Usage gains a short paragraph on what pageType decides and what a page without one draws. The Detail passage says why its heading is a page:header block. With Action Buttons and Best Practices 3 each gain one clause. The Schema API block's comments on title, description and pageType now say that a record page draws neither key.

Every value taught is a member of the spec's PageTypeSchema (record, home, app, utility, list).

Measured first

These are one-time render probes through the real SchemaRenderer and the real renderers. The probe file was not committed.

At BASE a1a44d621, each fence verbatim:

• Basic Usage renders as data-page-type="record" with no h1, and the description is not drawn. The only text is "User list goes here".
• With Action Buttons, Detail Page with Actions and Best Practices 3 render as record with no h1. Their buttons are drawn.
• With pageType set to app, list, utility or home, the Basic Usage document draws the h1 "User Management" and the description. With record it draws neither.

On the corrected shapes:

• The Detail document, with record and the page:header block, draws exactly one h1, "Acme Corporation", inside the header block. Its only buttons are Edit and Delete.
• The same page:header with title written flat on the node is refused by both faces (invalid_union at children). That is why the snippet uses the properties bag shown in the guide's Page Header section.
• Both faces (safeValidateSchema and StrictAnyComponentSchema) accept all four corrected documents. page-width-padding-refusal-11318.test.ts already runs every page fence of the guide through both faces, unchanged and green.

The pin

New file packages/components/src/__tests__/guide-layout-page-headings-11423.test.tsx. It derives every type: "page" JSON fence of the guide that authors a heading, either as the page's title or as a titled page:header block in its children. Each one is rendered through the real SchemaRenderer and must draw exactly one h1 with that text. A heading drawn by a page:header block must sit inside that block; a heading the page draws itself must not. The four corrected passages are pinned by heading text, so the population cannot shrink to empty. Beside the render:

• A fence that shows a description must draw it.
• A static read: no fence may write title or description on a page whose effective pageType is record.
• Live control A: the Basic Usage fence without its pageType draws neither heading nor description.
• Live control B: the Detail fence with its heading moved back onto the page node draws no h1, while its buttons still draw.

The claim expected the pin in packages/types or packages/layout. It landed in packages/components because the assertion is a render. It needs React, a DOM project and PageRenderer, which lives in @object-ui/components. @object-ui/types is zero-dependency with no React, and its tests run in the node unit project. The sibling render pin for this guide's action passages, guide-layout-page-buttons-7926.test.tsx, sits in the same folder. The ledger row for the new reader is in scripts/markdown-test-inputs.mjs. An empty-frontmatter changeset declares that this releases nothing.

Reverse verification

Each leg ran from committed head f06910103. Each restore was proven by blob == HEAD and an empty git diff HEAD. Mutations went through objectstack's ablation-replace.mjs, whose anchors had to hit. The predicted direction for every leg was red.

• (a) Delete Basic Usage's "pageType": "app", line (anchor 1 → 0): 4 failed / 9 passed. The failures are that fence's render, the description test, the static read and live control A.
• (b) Delete the Detail fence's page:header block: 2 failed / 10 passed (12). The failures are the population pin and live control B. The fence drops out of the render population, which is the case the population pin exists for.
• (c) Run against the whole guide at BASE a1a44d621: 8 failed / 5 passed. The failures are the four corrected passages' renders, the description test, the static read and both live controls.
• Ledger control: with the new row removed, node scripts/markdown-test-inputs.mjs --audit exits 1 and names the pin (unadjudicated-test). My first attempt removed only the row's inner lines, which crashed the script instead of giving a verdict, so I redid it with the whole row.
• Anchor control: pointing the new #page-header-pageheader link at a wrong slug makes scripts/check-doc-links.mjs report a broken [anchor] link. Restored afterwards.

Tests and gates (final head 01e353fa0)

• pnpm exec vitest run over the new pin, every ledger reader of layout.md and scripts/__tests__/markdown-test-inputs.test.ts: Test Files 13 passed (13), Tests 173 passed (173). The new pin alone has 13 tests and runs in the dom project.
• The ledger script's other importers (8 files): Test Files 9 passed (9), Tests 324 passed (324).
• pnpm exec turbo run build --filter='@object-ui/components^...' --concurrency=2: 7 successful. pnpm --filter @object-ui/components type-check exits 0, and the test program (tsc -p tsconfig.test.json --listFilesOnly) includes the new pin.
• pnpm check:doc-types, check:doc-fences, check:doc-example-ids, check:control-bytes, check:test-path-roots, check:pending-changeset-literals, check:doc-example-readers and check:unreferenced-sources all exit 0. check:new-line-citations: 0 new citations. node scripts/check-doc-links.mjs: links valid across 17 scan roots. node scripts/markdown-test-inputs.mjs --audit: all adjudicated. node scripts/check-changeset-presence.mjs, check-changeset-no-major, check-changeset-fixed, check-changeset-overwrite, check-type-check-coverage and check-lint-coverage all exit 0. node scripts/check-governed-queue-guard.mjs --test over the 4 paths: NOT GOVERNED.
• eslint --no-inline-config --format json over the 2 changed lintable files: 2 files, 0 errors, 0 warnings. The narrowing is proven: --print-config gives 119 rules for the test file and 0 for scripts/markdown-test-inputs.mjs, which is outside the linted population. eslint.config.js sets no parserOptions.project or projectService, and no custom rule reads the filesystem, so verdicts on untouched files cannot move.

NOT MEASURED:

• pnpm check:doc-snippets and pnpm check:doc-examples: exit 2, PRECONDITION NOT MET. The 34-package build closure does not fit the foreground cap, so this is a declared narrowing. These gates judge ts/tsx/typescript fences and JSDoc @example blocks. The diff adds or removes none of either, and the one typescript fence it edits (Schema API) is a declared doc-snippet: fragment. The unbuilt run's findings are 34 unbuilt-package and nothing about any document. CI runs both.
• The whole packages/components suite: exit 124 at 560 s with --maxWorkers=2, past the foreground cap, so this is also a declared narrowing. The diff adds one test file and changes no source in the package. Every reader of the edited guide ran above. CI runs the full suite.

Acceptance notes

Found while measuring and not fixed here; reported to the seat:

• The same defect in another producer. All five schema-catalog documents under examples/schema-catalog/src/schemas/components-layout-page/ set title and description and no pageType. They are the live examples on the published content/docs/components/layout/page.mdx, one of them under "With Title and Description". Rendered through the real SchemaRenderer, each draws no h1 and no description. With pageType: "app", each draws both. That page's Schema block also omits pageType. Not fixed in place: it is another producer, and its catalog tests are a verification surface this card does not carry.
• content/docs/api/schema-reference.md (PageNodeSchema) teaches "pageType": "detail", and its table lists list, detail, form, dashboard, report and custom. Both faces refuse detail, custom and dashboard with invalid_value at pageType. The declared set is record, home, app, utility and list, plus the visualization aliases.
• Observation, not filed: title and description on a record page pass both faces and draw nothing, and no diagnostic says so. The producers that taught the shape are this guide, now corrected, and the catalog above. A named diagnostic would be a new gate. Carrier: none.

Concurrency: draft PR objectui#11069 also edits layout.md, so whichever lands second merges main. main has moved since BASE, but none of the files this PR reads or edits changed.

Session: https://claude.ai/code/session_01YLg8XqWGJ785fwQ5v4pH37 (dispatched os-dev run, domain:ui seat 1).

---

Generated by Claude Code

[github-actions]

changeset-claim-re-read

⚠️ 3 pending changeset(s) describe a file this change touches

Their bodies publish verbatim into the CHANGELOG at the next release, so this is a request to re-read them against your diff — addressed here because you are the one seat that can answer it without re-deriving anything.

⛔ Nothing here blocks, and nothing here is a verdict on your change. This gate exits 0, is not a required context, and judges name resolution, never meaning: it asked whether a pending body names a file you touched. "Is this sentence still true?" is the one question it will not answer, and the one you are being asked to answer.

.changeset/6872-app-shell-branding-title-jsdoc.md

• names content/docs/guide/layout.md → content/docs/guide/layout.md — edited by this change

  Correct the AppShellBranding.title doc comment. It read "Page title suffix (sets document.title)" while useAppShellBranding assigns document.title = title wholesale — nothing is appended; the caller composes the whole string (the console passes "App label — Product name"). That comment ships in dist/index.d.ts and is the only description a consumer sees on editor hover, so a reader who followed it passed a suffix-only fragment and got a truncated title with no error. The comment now carries the same wording as content/docs/layout/app-shell.mdx, and agrees with the AppShellProps tables in the package README and content/docs/guide/layout.md. No runtime behaviour changes; the wholesale assignment and the four-surface agreement are now pinned by tests.

.changeset/7926-page-node-refuses-actions.md

• names content/docs/guide/layout.md → content/docs/guide/layout.md — edited by this change

  Scope. One key, by name; the node is NOT strict. A census over this tree read 91 authored page-tagged objects with a blind-spot reading of 8 unreadable sites, and found only actions (3 sites, all in content/docs/guide/layout.md) and breadcrumbs (1 site, its own question, untouched) surviving passthrough on a real page node — every other undeclared key belongs to a different declaration that merely spells type: 'page'. PageNodeSchema still passes unknown renderer props through.

.changeset/8871-page-node-refuses-breadcrumbs.md

• names content/docs/guide/layout.md → content/docs/guide/layout.md — edited by this change

  Three author sites, all teaching passages in content/docs/guide/layout.md, and that count corrects the actions refusal's "1 site": its census reads every git-tracked JSON file, every json fence in .md/.mdx, and every TS/TSX object literal via the TypeScript AST (PR fix(types,docs): refuse actions by name on the page node, teach the shape that draws (objectui#7926) #8870), and it undercounted for two different reasons. The Schema API block declared breadcrumbs?: ArrayANGLE-BRACKETS({ label, href }) outright and its literal does carry type: 'page', but that literal sits inside a markdown typescript fence — a fence language the census's json-fence reader never visits, so it was never read at all. Best Practices §2 authored it on a fragment inside a json fence the census does read, but that fragment never writes type, so a page-tagged filter correctly excluded it. No example app, catalog fixture, template or customer document writes the key, so the refusal strands no authored document in this tree.

Read the paragraph, not the line: both false halves of the objectui#8617 claim sat in one paragraph, and correcting either alone would have left it asserting the same wrong thing.

If a claim did go false, correct the body. That is precedented and prose-only, frontmatter untouched; check-changeset-overwrite.mjs will report the correction as its own case 2 ("correcting a declaration on purpose … legitimate"), which is the intended shape — one gate asks for the read, the other records the write.

Not covered, stated so nobody reads this as more: a born-false claim that spells no line address at all (objectui#9495 coordinated one by ORDINAL — "a grep finds that member first" — and deciding that means reading what the sentence means), a claim spelled as a symbol or a package rather than a backticked file name, and a file named ambiguously.

Angle-bracketed names in the quoted prose above are rewritten as ANGLE-BRACKETS(name): GitHub deletes tag-shaped fragments from a stored body, and a quote that silently loses the identifier it is about is worse than a visible repair.

Compared the checked-out tree with c681b9ff2 (merge-base with origin/main): 3 file(s) changed outside .changeset/, read against 1970 pending declaration(s) that publish a body (2595 pending in total). · run

[github-actions]

✅ Console Performance Budget

Metric	Value	Budget
Eager closure (gzip, 330 chunks)	3553.0 KB	3574.6 KB
Main entry chunk (gzip)	150.4 KB	350 KB
Entry file	index-DtPQrLfY.js	—
Status	PASS	—

The eager closure is every chunk the entry reaches through static imports — what the browser fetches and parses before the app renders. The entry chunk on its own is a small fraction of it.

---

📦 Bundle Size Report

Package	Size	Gzipped
app-shell (consoleActionDispatch.js)	0.20KB	0.19KB
app-shell (index.js)	16.88KB	6.25KB
app-shell (runtime-config.js)	20.68KB	7.36KB
app-shell (types.js)	0.01KB	0.04KB
app-shell (urlParams.js)	10.11KB	3.87KB
auth (ActiveOrganizationStorage.js)	27.95KB	10.04KB
auth (AuthContext.js)	0.31KB	0.24KB
auth (AuthGuard.js)	2.07KB	1.00KB
auth (AuthProvider.js)	40.22KB	10.61KB
auth (AuthShell.js)	3.49KB	1.40KB
auth (ForgotPasswordForm.js)	12.21KB	3.45KB
auth (LoginForm.js)	18.17KB	5.40KB
auth (PreviewBanner.js)	0.90KB	0.50KB
auth (RegisterForm.js)	6.72KB	2.24KB
auth (SocialSignInButtons.js)	9.70KB	3.93KB
auth (UserMenu.js)	3.39KB	1.21KB
auth (auth-gate-events.js)	1.29KB	0.66KB
auth (authStyles.js)	5.04KB	1.72KB
auth (createAuthClient.js)	40.70KB	10.94KB
auth (createAuthenticatedFetch.js)	8.54KB	3.46KB
auth (index.js)	3.63KB	1.64KB
auth (invitation-status.js)	1.22KB	0.70KB
auth (org-roles.js)	6.66KB	2.78KB
auth (phone-identifier.js)	1.11KB	0.66KB
auth (types.js)	0.59KB	0.35KB
auth (useAuth.js)	5.30KB	1.02KB
auth (useWorkspaceAdminStatus.js)	11.08KB	4.58KB
collaboration (CommentThread.js)	27.13KB	7.95KB
collaboration (LiveCursors.js)	3.17KB	1.27KB
collaboration (PresenceAvatars.js)	6.49KB	2.64KB
collaboration (PresenceProvider.js)	2.79KB	1.13KB
collaboration (index.js)	1.68KB	0.73KB
collaboration (useCollaborationTranslation.js)	6.05KB	2.52KB
collaboration (useCommentSearch.js)	1.98KB	0.88KB
collaboration (useConflictResolution.js)	7.75KB	1.86KB
collaboration (useMentionNotifications.js)	1.81KB	0.68KB
collaboration (usePresence.js)	6.33KB	1.84KB
collaboration (useRealtimeSubscription.js)	7.91KB	2.01KB
components (index.js)	570.62KB	136.73KB
core (index.js)	10.00KB	3.96KB
create-plugin (index.js)	27.94KB	9.51KB
data-objectstack (index.js)	230.46KB	63.94KB
fields (index.js)	260.97KB	66.19KB
i18n (LocalizationContext.js)	1.76KB	0.96KB
i18n (builtinAggregateLabels.js)	0.86KB	0.49KB
i18n (currency.js)	2.59KB	1.22KB
i18n (fallbackInterpolation.js)	6.25KB	2.77KB
i18n (i18n.js)	8.87KB	3.64KB
i18n (index.js)	5.24KB	2.27KB
i18n (pickLocalized.js)	9.86KB	3.95KB
i18n (provider.js)	39.35KB	12.88KB
i18n (translateFn.js)	0.20KB	0.18KB
i18n (useDisplayLocale.js)	3.52KB	1.76KB
i18n (useObjectLabel.js)	34.49KB	9.23KB
i18n (useSafeTranslation.js)	5.60KB	2.33KB
layout (index.js)	40.40KB	11.41KB
mobile (MobileProvider.js)	0.92KB	0.49KB
mobile (ResponsiveContainer.js)	0.94KB	0.38KB
mobile (breakpoints.js)	1.51KB	0.70KB
mobile (createOfflineDataSource.js)	5.61KB	1.75KB
mobile (index.js)	1.99KB	0.87KB
mobile (offlineQueue.js)	3.91KB	1.35KB
mobile (pwa.js)	0.97KB	0.49KB
mobile (serviceWorker.js)	1.48KB	0.62KB
mobile (serviceWorkerSource.js)	3.41KB	1.48KB
mobile (useBreakpoint.js)	1.54KB	0.65KB
mobile (useGesture.js)	6.96KB	1.98KB
mobile (useOfflineSync.js)	1.99KB	0.72KB
mobile (usePullToRefresh.js)	6.62KB	2.45KB
mobile (useResponsive.js)	0.72KB	0.42KB
mobile (useSpecGesture.js)	5.52KB	2.10KB
mobile (useTouchTarget.js)	1.01KB	0.54KB
permissions (MePermissionsProvider.js)	13.86KB	5.00KB
permissions (PermissionContext.js)	0.31KB	0.25KB
permissions (PermissionGuard.js)	0.89KB	0.45KB
permissions (PermissionProvider.js)	6.52KB	2.26KB
permissions (discardProofCache.js)	1.04KB	0.55KB
permissions (evaluator.js)	8.33KB	3.07KB
permissions (index.js)	0.93KB	0.41KB
permissions (store.js)	0.91KB	0.42KB
permissions (useFieldPermissions.js)	1.28KB	0.53KB
permissions (usePermissions.js)	4.83KB	2.27KB
plugin-ai (index.js)	16.01KB	3.93KB
plugin-calendar (index.js)	53.17KB	15.46KB
plugin-charts (index.js)	84.07KB	22.93KB
plugin-chatbot (index.js)	198.22KB	46.97KB
plugin-dashboard (index.js)	141.02KB	37.90KB
plugin-designer (index.js)	217.44KB	45.02KB
plugin-detail (index.js)	245.70KB	64.54KB
plugin-editor (index.js)	2.23KB	1.05KB
plugin-form (index.js)	173.14KB	44.58KB
plugin-gantt (index.js)	178.38KB	44.94KB
plugin-grid (index.js)	231.72KB	63.65KB
plugin-kanban (index.js)	49.51KB	15.54KB
plugin-list (index.js)	116.63KB	28.97KB
plugin-map (index.js)	25.60KB	8.62KB
plugin-markdown (index.js)	13.88KB	4.80KB
plugin-report (index.js)	44.04KB	12.21KB
plugin-timeline (index.js)	38.80KB	11.71KB
plugin-tree (index.js)	14.58KB	5.17KB
plugin-view (index.js)	90.32KB	22.76KB
providers (DataSourceProvider.js)	0.75KB	0.39KB
providers (MetadataProvider.js)	1.37KB	0.59KB
providers (ThemeProvider.js)	1.90KB	0.85KB
providers (UploadProvider.js)	11.81KB	3.58KB
providers (index.js)	0.45KB	0.23KB
providers (types.js)	0.01KB	0.04KB
react-runtime (index.js)	5.62KB	2.34KB
react (LazyPluginLoader.js)	4.47KB	1.63KB
react (SchemaRenderer.js)	120.63KB	39.56KB
react (data-invalidation.js)	5.05KB	2.08KB
react (index.js)	4.50KB	2.06KB
react (schema-input.js)	4.25KB	2.04KB
react (spec-input.js)	0.20KB	0.18KB
sdui-parser (body-dialect.js)	4.50KB	1.99KB
sdui-parser (codegen.js)	9.45KB	3.76KB
sdui-parser (dashboard-widget-options.js)	3.08KB	1.30KB
sdui-parser (index.js)	6.06KB	2.68KB
sdui-parser (input-type.js)	2.84KB	1.40KB
sdui-parser (parse.js)	25.28KB	7.80KB
sdui-parser (provenance.js)	3.84KB	1.90KB
sdui-parser (types.js)	0.28KB	0.23KB
sdui-parser (validate.js)	21.42KB	7.05KB
types (ai.js)	4.39KB	2.17KB
types (api-types.js)	0.20KB	0.18KB
types (app.js)	4.12KB	1.61KB
types (authoring-nodes.js)	0.20KB	0.19KB
types (base.js)	0.20KB	0.18KB
types (blocks.js)	0.20KB	0.18KB
types (complex.js)	3.19KB	1.62KB
types (crud.js)	0.20KB	0.18KB
types (dashboard-filter-alias.js)	6.23KB	2.74KB
types (dashboard-widget-layout.js)	2.06KB	0.96KB
types (data-display.js)	3.75KB	1.85KB
types (data-protocol.js)	0.20KB	0.19KB
types (data.js)	0.20KB	0.18KB
types (designer.js)	1.85KB	0.85KB
types (disclosure.js)	0.20KB	0.18KB
types (error-code.js)	1.54KB	0.88KB
types (expression.js)	0.20KB	0.18KB
types (feedback.js)	0.20KB	0.18KB
types (field-types.js)	0.20KB	0.18KB
types (form.js)	0.20KB	0.18KB
types (http-inflight.js)	8.87KB	3.73KB
types (http-retry.js)	4.32KB	2.02KB
types (icon-key-migration.js)	4.26KB	1.63KB
types (index.js)	5.07KB	2.39KB
types (layout.js)	0.20KB	0.18KB
types (managed-by.js)	0.19KB	0.18KB
types (mobile.js)	5.00KB	2.39KB
types (navigation.js)	0.20KB	0.18KB
types (objectql.js)	0.20KB	0.18KB
types (overlay.js)	0.20KB	0.18KB
types (permissions.js)	2.52KB	1.31KB
types (plugin-scope.js)	0.20KB	0.18KB
types (record-components.js)	0.20KB	0.19KB
types (record-semantics.js)	1.28KB	0.67KB
types (registry.js)	0.20KB	0.18KB
types (reports.js)	0.20KB	0.18KB
types (select-option.js)	0.20KB	0.19KB
types (spec-report.js)	4.99KB	1.96KB
types (spec-ui-namespace.js)	0.20KB	0.19KB
types (strict-authoring-face.js)	21.59KB	7.71KB
types (system-fields.js)	3.33KB	1.54KB
types (theme.js)	6.28KB	2.87KB
types (ui-action.js)	8.11KB	3.32KB
types (views.js)	0.20KB	0.18KB
types (widget.js)	0.20KB	0.18KB

Size Limits

• ✅ Core packages should be < 50KB gzipped
• ✅ Component packages should be < 100KB gzipped
• ⚠️ Plugin packages should be < 150KB gzipped

[objectstack-fleet]

Live E2E (informational) is red at 01e353fa0 for a reason outside this PR; one re-run follows now.

domain:ui seat 1 · session_01YLg8XqWGJ785fwQ5v4pH37 · 2026-10-02T03:22Z.

• Failing step: "Start ObjectStack backend (published packages)", job 110685236774. It stopped on npm error notarget No matching version found for @objectstack/spec@17.6.0.
• Cause: the job's backend fixture missed the cache and installed published @objectstack/* while objectstack's 17.6.0 release (run 36955885276) was mid-publish. cli, core and runtime 17.6.0 were already on npm and require spec@17.6.0, which was not yet.
• Why it is not this PR's: this diff touches no backend, fixture or install input.
• Now: that release's npm step has completed, and spec, core, cli, runtime, types and client all answer 17.6.0. No fix is needed on either side. The failed job is re-run once now; a second failure would be treated as real.

Every other check on this head is green or an expected skip. The review record is on the card (objectui#11423, ACCEPT 5944884789).

---

Generated by Claude Code