docs(fields): compile seventeen plaintext-fenced TypeScript snippets (#5867 batch 3)

[yinlianghui-tw]

Part of #5867

Batch 3 of N. Re-fences 17 TypeScript blocks across 10 whole content/docs/fields pages from plaintext to ts, so check-doc-snippet-types compiles them against the built types, and fixes the two blocks that reddened as a result.

All measurements at branch head d6378e44e, tree clean at run time; every heavy run through the container's shared verify lock.

Population, re-derived on today's origin/main (133e2ea1e)

146 blocks across 102 files — down from batch 2's handback of 151/103. PR #6119 (card #6107) landed in between and converted four fields blocks itself (27 → 23), and one components page moved (72 → 71). Derived with the gate's ownlistDocuments and UNGATED_DOCS, plus triage's classifier applied to plaintext fences.

What this batch takes, and why

content/docs/fields — the only group PM's batch-3 order left unblocked, components (#6122) and layout (#6120) being in flight with other devs.

Scope chosen by measurement: all 23 classifier-matching fences across the 13 fields pages were re-fenced in a throwaway probe, the closure rebuilt, the gate run, and the tree restored under a trap ... EXIT INT TERM. The mutation was proved on disk before the run — per-file plaintext fence counts dropped to their expected values, git diff --stat showed 23 insertions / 23 deletions — and git status --porcelain was empty after the restore.

That probe measured 229 blocks to compile (206 + 23) with 1 syntax and 4 semantic failures across 5 files. The 10 files with no failure, plus the 2 whose failures are fixable in scope, are this batch.

taken	blocks
file, formula, grid, rich-text, select, summary, user, vector — compile untouched	13
image, lookup — compile after the two fixes below	4
total	17

The two documentation defects compiling these found

Both are the #5044 class: a page teaching a name against a type that does not accept it, under a gate that reported the file as covered.

• image.mdx annotated ImageFieldSchema.value with FileMetadata, a name @object-ui/types does not export. It was deliberately renamed to UploadedFileMetadata (objectstack#4115) precisely because the spec's same-named type is a different shape — the storage layer's file record, not the field-value payload; re-exporting the spec's would have deleted url. The page now imports and annotates UploadedFileMetadata.
• lookup.mdx referenced DataSource without importing it. DataSourceis exported from @object-ui/types; the import is now there, which is also what a reader copying the block needs. (LookupOption, referenced beside it, is declared inside the same block and needed nothing.)

No other block body was edited. No FRAGMENT_MARKER was declared. The gate, UNGATED_DOCS and the ledger are untouched — scripts/ is not in this diff, so gate strictness is unmoved.

Gate counts, before and after

	before	after	delta
covered documents	178	178	unchanged — set did not shrink
of them holding a ts/tsx block	63	70	+7
ungated	44	44	unchanged — no document newly ungated
covered blocks	317	334
blocks to compile	206	223	+17 = exactly the batch
declared fragments	111	111	unmoved
diagnostics	0	0

Verbatim after: Semantic phase: 223 of 223 block(s) judged, 0 failed. / Every covered documentation snippet compiles against the built types.

Other gates, at the same head

Exit codes captured before any pipe; each gate's own verdict line quoted.

• 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).

Render check

pnpm site:build green (556 static pages). Reading the prerendered HTML back from apps/site/.next/server/app/docs/fields/*.html, counting pre blocks that contain a shiki keyword-coloured span:

page	ts fences @origin/main	ts fences @Head	highlighted blocks rendered
file, formula, image, lookup, rich-text, select, user	0	2 each	2 each
grid, summary, vector	1 each	2 each	2 each

Rendered highlighted blocks equal the ts fence count on every page, and the fence total moves 3 → 20 = +17, the batch exactly.

Control, on the same pages: unhighlighted rendered blocks equal the remaining plaintext fences everywhere — image 3/3, lookup 2/2, grid 8/8, summary 5/5 — and the untouched prose blocks on date (1/1) and percent (1/1) still carry zero keyword spans.

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

Excluded by measurement, with blockers filed

Three fields pages (6 blocks) red for reasons that need a ruling rather than an edit, so the whole file is excluded in each case rather than marked:

• finding(docs): two content/docs/fields snippets depend on identifiers the snippet program cannot resolve — a fabricated db handle and an undeclared ajv — each needs a ruling before #5867 can cover them #6126 — auto-number.mdx leans on a fabricated ambient db handle (TS2304 + TS7006), and object.mdx imports ajv, which is resolvable from neither the repo root nor any workspace package.json (TS2307).
• finding(docs): content/docs/fields/location.mdx welds a JSX element and a bare metadata object literal into one fence, so it parses as neither ts nor tsx #6127 — location.mdx welds a JSX element and a bare metadata object literal into one fence; measured to fail under bothts (2 diagnostics) and tsx (5), so no fence language fixes it.

Remainder for batch 4

146 measured, 17 taken — 129 blocks in 92 files remain:

group	blocks	files	state
content/docs/components/**	71	71	blocked on #6122
content/docs/layout/**	12	3	blocked on #6120
content/docs/plugins/**	12	7	triaged by batch 2's probe 2
content/docs/core/**	11	1	blocked on #6121
content/docs/blocks/**	10	1	triaged by batch 2's probe 2
content/docs/fields/**	6	3	blocked on #6126, #6127
named in UNGATED_DOCS — adds zero to the compile population	7	6	leave

The 7 blocks in 6 UNGATED_DOCS pages were not re-fenced: the document is not compiled at all, so re-fencing them moves blocks-to-compile by zero and the "+N = batch size" check does not apply. They are left alone deliberately, not overlooked.

Docs only — the changeset carries empty frontmatter and publishes nothing.

Generated by Claude Code

---

Generated by Claude Code

[yinlianghui-tw]

PM: ACCEPT — batch 3

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

The image.mdx fix is the one worth reading

ImageFieldSchema.value was annotated FileMetadata — a name @object-ui/types does not export, and deliberately so: objectstack#4115 renamed it to UploadedFileMetadata because the spec's same-named type is the storage layer's file record, a different shape whose re-export would have deleted url.

So the naive fix — re-export FileMetadata to make the docs compile — would have silently broken the field's payload contract. You found the rename's reason, not just the rename. That is the difference between correcting a symbol and understanding why it moved.

The probe closed the loop on its own exclusions

Re-fencing all 23 fields fences, then reading the gate's failures: the 5 reddening files it named are exactly the 3 you excluded plus the 2 you fixed. That is the exclusion list validated against the measurement rather than asserted alongside it — no file was excluded on a hunch, and none was quietly missed.

The render check is the tightest yet: ts-fence total across the 10 pages moves 3 → 20 (+17, the batch exactly), and the unhighlighted rendered blocks equal the remaining plaintext fences on every page (image 3/3, lookup 2/2, grid 8/8, summary 5/5), with the untouched prose blocks on date.mdx and percent.mdx still at zero keyword spans. Both directions, per page.

Population re-derived again and the drift explained rather than absorbed: 146/102, five fewer than batch 2 handed back, because #6119 itself converted four fields blocks (27 → 23) and a components page moved. Knowing why a number changed is what makes the next handback trustworthy.

Rulings posted on both blockers

Both are genuine rulings, correctly filed rather than guessed:

• finding(docs): content/docs/fields/location.mdx welds a JSX element and a bare metadata object literal into one fence, so it parses as neither ts nor tsx #6127 (location.mdx fails under both fence languages — 2 syntactic diagnostics as ts, 5 as tsx) — ruled: split the fence. Your supplementary measurement is what makes that safe; without it, "switch it to tsx" is the obvious wrong answer.
• finding(docs): two content/docs/fields snippets depend on identifiers the snippet program cannot resolve — a fabricated db handle and an undeclared ajv — each needs a ruling before #5867 can cover them #6126 (auto-number.mdx's ambient db handle; object.mdx's unresolvable ajv) — ruled: narrow both to ObjectUI's own contract. Your framing decided it: "making it compile would mean the renderer's docs minting a backend contract it does not own."

And you were right to separate object.mdx from #6120 rather than folding them: #6120's lucide-reactis declared by a package and merely does not resolve from the root; nothing in this repo depends on ajv at all. Different shapes, different answers — and your note that object.mdx should follow #6120's route if one emerges, rather than grow a second answer, is exactly the right hedge.

On the file.mdx observation — agreed, and I am not acting on it

You declined to touch it because the block compiles and editing a green block is scope creep. Correct. Recording the reasoning so it is not rediscovered: file.mdx declares a localinterface FileMetadata whose shape matches the shipped UploadedFileMetadata, so it is a valid self-contained illustration — but it uses the very name objectstack#4115 renamed off, one page away from image.mdx now importing the real export. A reader moving between the two could reasonably conclude FileMetadata is importable. Low cost, real, and not this batch's business.

Batch 4

Your remainder table makes it dispatchable without re-derivation: 129 blocks / 92 files, with plugins (12/7) and blocks (10/1) the only unblocked groups — a clean batch of up to 22, both already triaged by batch 2's probe 2. components (71 files, the largest prize) unblocks when #6122 lands; layout when #6120 does. Both are in flight now.

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

---

Generated by Claude Code