docs(blocks,plugins): compile nineteen plaintext-fenced TypeScript snippets (#5867 batch 4)

[yinlianghui-tw]

Part of #5867

Batch 4 of N, taking the two groups batch 3's handback named as the only unblocked ones: plugins and blocks. All readings below are at branch head 4430ac30d, and every heavy run went through the container's shared verify lock.

What this changes

19 fences re-fenced from ```plaintext to ```ts across 7 whole pages — content/docs/blocks/block-schema.mdx (10) and six content/docs/plugins/*.mdx (9: charts 1, editor 1, form 2, grid 2, markdown 1, view 2) — so check-doc-snippet-types compiles them.

Triage's classifier is the one applied, unwidened: a plaintext block whose first line starts with import / export / interface / type X = / const x: T is code. Genuinely-prose blocks on the same pages are left alone — 12 of them survive across the batch pages, including block-schema.mdx's slotContent illustration, which opens with a comment and would not parse.

No FRAGMENT_MARKER was declared. The gate, UNGATED_DOCS and the ledger are untouched; scripts/ is not in the diff.

The defects compiling them found, all fixed rather than marked

All on block-schema.mdx; the six plugins pages compiled untouched, as batch 2's probe 2 predicted.

block	what was wrong	fix
Block Slots	BlockSlot.defaultContent is typed SchemaNode, never imported	import SchemaNode
Complete Example	annotates BlockSchema, never imported	import BlockSchema
Marketplace Example	annotates BlockLibrarySchema, never imported	import BlockLibrarySchema
Block Library	references heroBlock, defined in a different block on the page	declare const heroBlock: BlockSchema
Block Editor	references cardBlock, defined in a different block on the page	declare const cardBlock: BlockSchema
Runtime Validation	validates myBlock, the reader's own value	declare const myBlock: unknown

declare const is this repo's existing idiom for a value a snippet does not define — seven prior uses across components/basic/icon.mdx, guide/notifications.md and guide/troubleshooting.md.

The defect that only appeared once the first fix landed

Resolving BlockLibrarySchema un-masked one the unresolved name had been suppressing. Both Marketplace Example listings carried:

schema: { /* block schema */ },

While BlockLibrarySchema was TS2304, its annotation degraded to any and the member was never checked. With the import in place the gate reddened it as TS2741: Property 'type' is missing in type '{}' but required in type 'BlockSchema' — BlockLibraryItem.schema is a required BlockSchema, and an empty object is not one. Both now carry a real minimal block schema naming the listing they belong to. This is the #5044 class exactly: a block teaching a shape the types reject, under a gate that reported the page as covered.

Verification

Gate, before and after, on the built tree:

reading	before (133e2ea1e)	after (4430ac30d)
blocks to compile	206	225 (+19 = exactly the batch)
diagnostics	0	0
declared fragments	111	111 (unmoved)
covered documents	178	178 (set did not shrink)
ungated	44	44 (none newly ungated)
covered docs holding a ts/tsx block	63	64

The gate's own verdict line after: Every covered documentation snippet compiles against the built types. The --build-filter closure is byte-identical before and after.

Other gates, exit codes captured before any pipe, quoting each gate's own verdict line:

• check:doc-types exit=0 — Every documented component type is registered.
• docs:check-links exit=0 — Links are valid across 15 scan roots.
• check:control-bytes exit=0 — OK (scanned 5081 tracked text file(s); skipped 85 binary)

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

Lint, narrowed and the narrowing measured: the diff is 7 .mdx files plus one .changeset/*.md. ESLint's own configuration reports every one of them as File ignored because no matching configuration was supplied — eslint.config.js matches only **/*.{ts,tsx}, and type-aware linting is not enabled, so this diff cannot move the verdict on any untouched file. File count read from --format json: 2 probed, 2 ignored, 0 errors.

Render check

pnpm site:build green. The reader-visible half is measured against a rebuilt baseline rather than asserted: the site was rebuilt with content/docs reverted to the pre-batch commit, counted, then restored under a trap.

block-schema.mdx renders as literal <pre> blocks, so its count is exact:

	before	after
rendered blocks with shiki token spans	0	10
rendered blocks with none	11	1
shiki keyword spans	0	52

Ten blocks moved from unstyled to tokenised — the page's whole share of the batch — and the one surviving prose block still carries zero token spans.

The six plugins pages render most blocks through the RSC flight payload, so the same before/after counter was run on both representations, reading keyword spans:

page	before	after	delta	converted
plugin-charts	10	13	+3	1
plugin-editor	5	8	+3	1
plugin-form	7	12	+5	2
plugin-grid	16	21	+5	2
plugin-markdown	8	11	+3	1
plugin-view	50	55	+5	2
plugin-dashboard (control, untouched)	0	0	0	0

Build note, unrelated to this diff and identical to batches 1–3: the site build needs @object-ui/plugin-gantt and @object-ui/plugin-map built first, both outside the gate's --build-filter closure.

Scope selection was measured, not eyeballed

All 22 candidate blocks across all 8 candidate files were re-fenced in a throwaway probe, the mutation proved on disk first (per-file plaintext counts dropped to their expected values; git diff --stat showed 22 insertions / 22 deletions), the tree rebuilt, the gate run, and the tree restored under trap … EXIT INT TERM using git checkout HEAD -- on the two directories, never the bare form. The probe read Covered blocks: 339 — 228 to compile (206 + 22, so every re-fence landed in the population) and named exactly one file this batch then excluded.

Excluded, with a measured reason

content/docs/plugins/plugin-dashboard.mdx — 3 blocks, whole file left as plaintext. Its TypeScript Support block fails the syntax phase (TS1109 on widgets: [...], an English ellipsis at expression position), which #6122 already records. Measuring behind that failure found more than #6122 knew: the block also imports DashboardSchema and MetricCardSchema, and neither name exists anywhere — not on @object-ui/plugin-dashboard's built export surface, not in @object-ui/types, not declared in any packages/*/src. The syntax failure had been masking both. Reported on #6122 rather than filed fresh, because that card already owns this file's defect record and is in flight; the comment there also points at #5015 / PR #5069, which settled the identical fabricated-name defect in this package's README and pins the correct form, so the file needs no new ruling.

The 7 blocks in 6 UNGATED_DOCS pages were not re-fenced and should not be: those documents are not compiled at all, so re-fencing moves blocks-to-compile by zero. Left alone deliberately, not overlooked.

Population, re-derived

146 blocks / 102 files on origin/main 133e2ea1e, reproducing batch 3's reading exactly. Widening the derivation's fence-language set to text and plain moves it to 147/103 and surfaces one block the whole lane has been blind to — filed as #6135, unassigned, with the file it names blocked on #6122.

Remainder after this batch: 110 blocks / 85 files, handed back on the card in batch 3's shape.

---

Generated by Claude Code

[yinlianghui-tw]

PM: ACCEPT — batch 4, and two findings that change how the rest of this card gets planned

	before	after	required
blocks to compile	206	225	+19 = exactly the batch size ✅
diagnostics	0	0	✅
declared fragments	111	111	unmoved — no marker ✅
covered / ungated	178 / 44	178 / 44	⛔ neither moved ✅

⚠️ The un-masking finding is the most important thing in this report

An unresolved type name (TS2304) degrades its annotation to any, which suppresses every member check under it — so the diagnostic count a probe reports for a block with an ambient-name failure is a LOWER BOUND, and fixing the name can make the block redden harder rather than go green.

You did not merely state it — you hit it. Resolving BlockLibrarySchema un-masked two schema: { /* block schema */ } literals that had been invisible: while the annotation was TS2304 it degraded to any and the member was never checked; with the import in place, TS2741, because BlockLibraryItem.schema is a required BlockSchema. That is the #5044 class in its purest form — a defect hidden behind another defect.

And the consequence for planning is real: batch 2's probe 2 counted 34 SchemaNode and 10 ComponentSchema ambient-name failures across the components group and characterised them as "fixed in-batch with one import line". Right about the import, wrong about it being the whole fix. The components group — 71 files, the largest remaining prize — must budget for a second round of diagnostics after the imports land. I am carrying that into its dispatch order; without it, a dev would size that batch from a number that is structurally a floor.

That correction is worth more than the 19 blocks.

#6135 — the lane's population has a blind spot, and it is in every handback so far

Deriving the population from plaintext fences only means a TS block fenced text or plain is invisible to it. Widening only the fence-language set — triage's classifier untouched — moves the population 146/102 → 147/103 and surfaces components/form/file-upload.mdx:27, a text-fenced block opening interface FileUploadSchema { that passes the classifier unmodified.

So every batch's handback arithmetic, including this one's, shares the gap. That is exactly the right thing to file rather than absorb, and your framing is right: this is a fifth reading on the axis the card already names, not a new axis. A-then-C is the sensible route — treat text/plain as synonyms now, then let the deferred fence-language guard pin the allowed spellings, since nothing today stops a sixth spelling reopening it.

Correctly not fixed here: the file is in the components group, blocked on #6122.

The probe validated both lists, not just one

The one file it named as a syntax failure is exactly the one file you excluded, and the 6 semantic failures are exactly the block-schema.mdx defects you fixed. Both the exclusion list and the fix list are measured against the same run. Batch 3 set that bar; this matches it.

The render check goes further than any prior batch: measured against a rebuilt baseline (revert content/docs, prove on disk, rebuild, re-run the identical counter, restore under a trap) rather than compared against remembered numbers. And you handled the two rendering modes honestly — block-schema.mdx renders literal pre blocks so its count is exact (0 → 10 tokenised, 11 → 1 untokenised, 52 keyword spans), while the plugins pages render through the RSC flight payload, so you reported keyword-span deltas per page and showed they match three tokens per import line. Control: plugin-dashboard.mdx, untouched, reads 0 before and after.

Using declare const for cross-block references is right, and citing the seven prior uses across icon.mdx and two guide pages is what makes it the repo's idiom rather than your invention.

On plugin-dashboard.mdx — reported, not filed, and the reasoning is correct

You routed it to #6122 (which already owns that file's defect record and is in flight) rather than opening a fresh card, and established it needs no new ruling: #5015 / PR #5069 settled the identical defect in the identical package's README, and README.md:386 carries the answer — the package ships components, not schema types. The docs page is the same content one file over, simply not swept at the time.

Finding the landed precedent instead of asking for a decision is the difference between a blocker and a work item.

Remainder

plugins has 3 blocks left (the excluded plugin-dashboard.mdx), blocks is clear. The unblocked surface is now nearly exhausted — what remains is gated on #6132 (components, 71 files), #6121 (core), #6131 (layout), #6126 (fields), and #6135's population question. Three of those five are with the maintainer.

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

---

Generated by Claude Code