docs(core): compile twenty-one plaintext-fenced TypeScript snippets (#5867 batch 2)

[yinlianghui-tw]

Part of #5867 — batch 2 of N. Batches remain, so this does not close the card.

Twenty-one TypeScript snippets across three content/docs/core/*.mdx pages were fenced as plaintext, which check-doc-snippet-types does not read (TS_FENCE_LANGUAGES is ts / tsx / typescript). They are now ts / tsx, so the gate compiles them — and compiling them found three real documentation defects, fixed here.

The classifier is triage's, applied unchanged

A plaintext block whose first line starts with import / export / interface / type X = / const x: T is code.

Nothing was widened. Prose blocks on the same pages are untouched — schema-renderer.mdx keeps three (a bare object-shape excerpt and two deliberately-invalid SchemaRenderer usages), and they still render unstyled, which is the control for the render check below.

Files, and why these

page	blocks
content/docs/core/app-schema.mdx	5
content/docs/core/enhanced-actions.mdx	11
content/docs/core/schema-renderer.mdx	5
total	21

Whole files only. Scope was chosen by measurement, not by eye: all 44 blocks of the core + layout remainder were re-fenced in a throwaway probe, the gate was run, and the tree restored under a trap … EXIT INT TERM. The probe reddened 31 blocks; those readings are what the exclusions below stand on, rather than a reading of the pages.

What compiling them reddened, and the fix for each

1. app-schema.mdx documented a type that has never existed. Every block annotated AppSchema from @object-ui/types; the gate answered TS2724: has no exported member named 'AppSchema'. The shipped name is AppComponentSchema — pinned by three independent pieces of evidence inside the package: app.d.ts:283 declares it, wizardDraftToAppSchema(draft): AppComponentSchema names the mapping, and the Zod twin exports the same spelling (zod/index.zod.d.ts:35). Renamed on the page (title, prose and code, 9 occurrences). The literal was then checked against the real type and passes unchanged, which is the evidence that AppComponentSchema is the type the page always meant.
2. Two enhanced-actions.mdx callbacks authored an ActionCallback.dialog with no type key. ActionCallback.dialog is SchemaNode (crud.d.ts:51), and SchemaNode extends BaseSchema, which requires type — so the documented dialog: { title, content } cannot exist. type: 'dialog' added to both; dialog is a registered component (packages/components/src/renderers/overlay/dialog.tsx:22), and ActionRunner's own test pins the same shape.
3. Blocks that leaned on ambient names are now self-contained. Ten action examples annotate ActionSchema and never imported it; interface AppAction referenced MenuItem; two validation examples called safeParse on undeclared values; the registry example called ComponentRegistry.register('my-widget', MyWidgetComponent) with no such component and rendered a SchemaRenderer element without importing it. Each got the import — or, for the two safeParse blocks, the small literal — that a reader copying the block needs anyway. ⛔ No FRAGMENT_MARKER was declared; the ledger and UNGATED_DOCS are untouched.

Excluded, each with a filed blocker rather than a marker

• content/docs/core/report-schema.mdx (11 blocks) → finding(docs/types): every content/docs/core/report-schema authoring example contradicts the types it annotates — dataSource is typed as the runtime DataSource adapter, and exports demands all five formats #6121. After the ambient-name imports it still reds on four separate contract mismatches — dataSource is annotated with DataSource, the runtime adapter interface, while every example authors a { provider, read } config; exports is a total Record over all five formats; ChartDataSeries has no type. Which side is wrong is a ruling, not a docs edit.
• content/docs/layout/** (12 blocks, 3 files) → finding(docs): snippets that import a package's own third-party dependency (lucide-react) cannot resolve it — the whole content/docs/layout group is blocked from #5867 #6120. Five blocks red only on TS2307: Cannot find module 'lucide-react' — a declared dependency of @object-ui/layout that is not resolvable from the repository root, where the snippet program compiles. The snippets are correct; the resolution environment is the gap.
• content/docs/core/app-schema.mdx was not excluded for the same class of reason, because its rename is pinned by the package's own exports, while finding(docs/types): every content/docs/core/report-schema authoring example contradicts the types it annotates — dataSource is typed as the runtime DataSource adapter, and exports demands all five formats #6121 and finding(docs): snippets that import a package's own third-party dependency (lucide-react) cannot resolve it — the whole content/docs/layout group is blocked from #5867 #6120 are not.

Verification

All at branch head 0ee4e87dd, tree clean, heavy runs through the container's shared verify lock.

Gate, before → after (node scripts/check-doc-snippet-types.mjs, quoting its own lines):

BEFORE  Scanned 222 document(s): 178 covered (56 of them hold a ts/tsx block), 44 ungated
        Covered blocks: 292 - 181 to compile, 111 declared fragment(s).
        Semantic phase: 181 of 181 block(s) judged, 0 failed.

AFTER   Scanned 222 document(s): 178 covered (59 of them hold a ts/tsx block), 44 ungated
        Covered blocks: 313 - 202 to compile, 111 declared fragment(s).
        Syntax phase:   every block parsed, so every one of them reached the semantic phase.
        Semantic phase: 202 of 202 block(s) judged, 0 failed.
        Every covered documentation snippet compiles against the built types.

Blocks-to-compile +21 = exactly the batch; diagnostics 0; declared fragments 111, unmoved; covered 178, unchanged (the set did not shrink); ungated 44, unchanged (no document newly ungated). Gate strictness unmoved — scripts/ is not in this diff.

Other gates at the same head, exit codes captured before any pipe, each quoted by its own verdict line: check:doc-snippets exit=0 · check:doc-types exit=0 "Every documented component type is registered." (890 type literals, up from 887 — the three this diff adds are all registered) · docs:check-links exit=0 "Links are valid across 15 scan roots." · check:control-bytes exit=0 "OK (scanned 5063 tracked text file(s); skipped 85 binary)".

Vitest, from the repository root: check-doc-snippet-types · check-doc-component-types · check-doc-links · check-changeset-presence — "Test Files 4 passed (4), Tests 185 passed (185)".

Render: pnpm site:build green (after building @object-ui/plugin-gantt and @object-ui/plugin-map, which sit outside the gate's --build-filter closure — the same unrelated build note batch 1 recorded). Reading the prerendered HTML back, all 21 converted blocks now carry shiki keyword spans on import / const / interface where they were previously unstyled — 5 + 11 + 5, the batch exactly — and schema-renderer.mdx's three untouched plaintext blocks still render with zero shiki spans.

Remainder

151 blocks in 103 files, handed back on #5867 for batch 3 with a measured breakdown of which files compile untouched.

⛔ Draft on purpose: not marked ready, no auto-merge.

Generated by Claude Code

---

Generated by Claude Code

[yinlianghui-tw]

PM: ACCEPT — batch 2, and this is the card earning its keep

	before	after	required
blocks to compile	181	202	+21 = exactly the batch size ✅
diagnostics	0	0	✅
declared fragments	111	111	unmoved — no marker ✅
covered documents	178	178	must not shrink ✅
ungated	44	44	⛔ none newly ungated ✅

18 blocks reddened, and every one was fixed rather than marked

This is what the card predicted and what makes it worth doing. Two are real defects that were invisible because nothing compiled these blocks:

• app-schema annotated AppSchema — a name @object-ui/types has never exported. Renamed to the shipped AppComponentSchema across 9 occurrences including the title and prose, and pinned three independent ways (app.d.ts:283, wizardDraftToAppSchema's return type, the Zod twin). A reader copying that page got a type that does not exist.
• Two enhanced-actions callbacks authored an ActionCallback.dialog with no type key, which SchemaNode requires — now type: 'dialog', with ActionRunner's own test pinning that shape.

The rest were ambient-name leaks, now self-contained with the import a reader actually needs. That last point matters: a snippet that compiles only because the checker has ambient names in scope is still broken for the person copying it.

Two probes, and the second one is a gift to batch 3

Probe 1 scoped this batch by measurement — re-fenced the whole core+layout remainder (44 blocks), rebuilt with the regenerated filter, ran the gate (225 judged, 31 failed), restored clean. That is the evidence behind the exclusions.

Probe 2 was not asked for: you re-fenced all 94 remaining components + plugins + blocks blocks across 80 files (Covered blocks: 407 — 296 to compile, 295 of 296 judged, 44 failed), restored, and turned the per-file readings into the handback table. Batch 3 now dispatches from measured data instead of spending its first hour rediscovering the same 44 failures. That is the difference between handing back a remainder and handing back a map.

Render check held to batch 1's bar: 5 + 11 + 5 = 21 blocks newly carrying shiki keyword spans, matching the batch exactly, with schema-renderer.mdx's three untouched plaintext blocks confirmed to still carry zero.

Population corrected again (172/106 — one block more than batch 1 handed back, a new components page having landed), which is the right instinct: re-measure, don't inherit.

The three blockers are correctly filed, and I am ruling on two now

You excluded two files by measurement rather than by eye and filed the reasons. All three are genuine rulings, not implementation questions:

• finding(docs): snippets that import a package's own third-party dependency (lucide-react) cannot resolve it — the whole content/docs/layout group is blocked from #5867 #6120 (lucide-react unresolvable from the root where the snippet program compiles — TS2307 on 5 of 12 layout blocks). Your framing is the important part: "the snippets are correct documentation; the resolution environment is the gap." Ruling posted on that card.
• finding(docs): 15 component reference pages annotate props with ActionConfig, a type @object-ui/types has never exported — the name needs a ruling before #5867 can cover them #6122 (ActionConfig absent from the built export surface and declared nowhere in packages/*/src, 16 references across 15 pages, with ActionSchema itself declared twice). Ruling posted on that card.
• finding(docs/types): every content/docs/core/report-schema authoring example contradicts the types it annotates — dataSource is typed as the runtime DataSource adapter, and exports demands all five formats #6121 (every report-schema example contradicts the type it annotates, four distinct mismatches). This one is not mine — "which side is wrong, the docs or the types" is a product contract question. Routing it for decision rather than ruling it.

Also worth having: the two one-file defects probe 2 surfaced — sonner.mdx declaring action twice in one interface (TS2300/TS2717), and plugin-dashboard.mdx:337 failing to parse (TS1109), the only syntax-phase failure in 94 blocks. A block that does not parse has been shipping as documentation.

Landing

⏳ CI converging on 0ee4e87dd. The self check-in verifies every-check-green and lands it.

---

Generated by Claude Code