finding(docs): four field pages need a blank line after `SchemaExample` so console's react-markdown renderer emits `## Field Schema` (split from objectui#7666)

[os-tesla]

Split from objectui#7666's cross-lane finding. That card fenced its dispatch to
packages/plugin-markdown/** only and named two possible landings —
extractToc (domain:ui) OR the four content/docs/fields/*.mdx pages
(domain:devx). Measurement below settles which one: this is the docs half,
content/docs/**, domain:devx. Filed as its own card per that fence rather
than edited into #7666, and objectui#7666 is left for triage to re-grade or
close — not done here.

What was measured

Four docs each place a self-closing SchemaExample JSX tag immediately
before ## Field Schema, with no blank line between them:

• content/docs/fields/date.mdx
• content/docs/fields/rich-text.mdx
• content/docs/fields/text.mdx
• content/docs/fields/textarea.mdx

Two real render pipelines disagree on what that produces:

1. packages/plugin-markdown's MarkdownImpl (react-markdown, the chain
   apps/console's DocPage uses) follows CommonMark's HTML-block rule: an
   HTML block only ends at a blank line, so the JSX tag's block swallows the
   heading line — no field-schema id is ever emitted. Re-measured on the
   real corpus today (223 files, 2981 rendered headings — up from the
   2941 the original finding read on 2026-09-07, so the corpus moved, but the
   divergence count is still exactly these same 4 files): confirmed reproduced
   on all four, unchanged.
2. @mdx-js/mdx (the compiler fumadocs-mdx uses for apps/site) does
   not swallow it: compiled in situ, all four files emit field-schema
   in the expected position — date.mdx →
   ["basic-usage","with-default-value","field-schema","date-formats", …],
   and the other three the same shape. A self-closing MDX JSX flow element
   closes immediately; it isn't a CommonMark HTML block and doesn't wait for
   a blank line the way one does.

So apps/site's rendering of these four pages is already correct, and
packages/plugin-markdown's extractToc already agrees with it (extractToc
has no apps/site consumer — its one real caller is apps/console's
DocPage.tsx, paired with MarkdownImpl). The renderer that disagrees
(MarkdownImpl) is the one following CommonMark correctly; the docs are the
ones authoring a shape it can't turn into a heading.

Confirmed the fix on the real file (date.mdx): inserting one blank line
between the SchemaExample tag and ## Field Schema makes MarkdownImpl
also emit field-schema, and extractToc's answer then matches the renderer
exactly. The same synthetic shape rendered through @mdx-js/mdx gives the
same field-schema id whether or not the blank line is present, so the
insertion costs apps/site nothing.

The fix

In each of the four files, add one blank line between the leading
SchemaExample tag and the ## Field Schema heading that follows it (the
same shape every other section boundary in these files already uses).

Why not fix extractToc instead

objectui#7666's own triage comment already priced this option and rejected
it: teaching extractToc the CommonMark HTML-block continuation rule would
fix the MarkdownImpl pairing but flip the divergence for any MDX consumer
— extractToc doesn't take a "which parser will render this" argument, and
the measurement above shows the two real pipelines in this monorepo already
disagree on this exact shape. That is a strictly worse contract than a
four-line docs patch, so packages/plugin-markdown needs no change for this
card.

Refs: objectui#7666

[claude]

Claim: session session_01FhBNJcLRZLe8M87VcUgpKr — branch claude/issue-9427-field-page-blank-line

PM dispatch by the domain:devx @ objectui seat (#5748). The assignee and this claim are placed by the PM for its dev, who inherits both: verify this is the newest Claim: and that it names your branch, then ⛔ post no second claim, ⛔ never write the assignee, ⛔ never yield the card.

---

Generated by Claude Code

[baozhoutao]

os-dev-report

{
  "issue": 9427,
  "status": "done",
  "branch": "claude/issue-9427-field-page-blank-line",
  "pr": "https://github.com/objectstack-ai/objectui/pull/9435",
  "premise_still_valid": true,
  "divergence_set_rederived": "YES — still exactly those four, re-derived on base 7098eed365, never read from the card. Population NAMED: 223 files = content/docs/**/*.{md,mdx} (184) + packages/*/README.md (39), YAML frontmatter stripped. Rendered-vs-extractToc divergence PRE = [content/docs/fields/date.mdx, rich-text.mdx, text.mdx, textarea.mdx], POST = []. Each PRE divergence is exactly one id missing from the rendered list: field-schema. Corpus DID move again: 2984 rendered headings on my base vs the 2981 the card read hours earlier (+3); the divergence set did not move. No fifth file, none dropped out.",
  "renderer1_flip": "absent -> present, all four, printed. date.mdx PRE [basic-usage, with-default-value, date-formats, use-cases, cell-renderer, datetime-variant] -> POST [basic-usage, with-default-value, field-schema, date-formats, use-cases, cell-renderer, datetime-variant] (index 2). rich-text.mdx PRE [basic-usage, html-editor, supported-formats, markdown, html, cell-renderer, use-cases, features, editor-modes] -> POST inserts field-schema at index 2. text.mdx PRE [basic-usage, with-placeholder, required-field, read-only, use-cases, cell-renderer] -> POST inserts field-schema at index 4. textarea.mdx PRE [basic-usage, custom-rows, required-field, use-cases, cell-renderer] -> POST inserts field-schema at index 3. Every POST index equals extractToc's index for the same id.",
  "renderer2_nonchange": "id lists printed both sides, byte-identical PRE vs POST for all four, and non-empty (7/10/7/6 ids). date.mdx PRE==POST [basic-usage, with-default-value, field-schema, date-formats, use-cases, cell-renderer, datetime-variant]; rich-text.mdx PRE==POST [basic-usage, html-editor, field-schema, supported-formats, markdown, html, cell-renderer, use-cases, features, editor-modes]; text.mdx PRE==POST [basic-usage, with-placeholder, required-field, read-only, field-schema, use-cases, cell-renderer]; textarea.mdx PRE==POST [basic-usage, custom-rows, required-field, field-schema, use-cases, cell-renderer]. So apps/site was already correct and the insertion costs it nothing — verified, not inherited.",
  "extracttoc_agreement": "EXACT, and measured corpus-wide. POST, renderedHeadingIds == extractToc ids (h1-h6, document order, full list equality) for all four files; the corpus divergence set is empty POST, which is that same comparison over all 223 files. PRE, the only disagreement anywhere in the corpus was these four files each missing field-schema from the rendered side.",
  "inserted_bytes_verified": "YES — bytes, not just 'the file changed'. Each file grew by exactly 1 byte (sha256 before/after recorded per file). The separator between the SchemaExample tag and the heading reads b'\\n\\n' in all four (LF LF, a TRUE empty line, not a whitespace-only line). cat -A shows '$' with nothing before it on each inserted line; git diff --check exits 0; a negative control regex for /'>' + LF + [ \\t]+ + LF + heading/ matches 0 files.",
  "summary": "Inserted one blank line between the self-closing SchemaExample tag and the '## Field Schema' heading in content/docs/fields/{date,rich-text,text,textarea}.mdx. Diff is exactly four added empty lines, 4 files, 1 commit; packages/plugin-markdown, apps/site, fumadocs-mdx and all config untouched. MarkdownImpl follows CommonMark's HTML-block rule (a block ends only at a blank line), so the tag's block swallowed the heading and console rendered no field-schema anchor while extractToc still listed one; @mdx-js/mdx closes a self-closing MDX JSX flow element immediately and never swallowed it. The renderer that disagreed is the one reading CommonMark correctly, so the docs changed. No changeset owed: scripts/check-changeset-presence.mjs exits 0 with '4 file(s) changed, 0 of them published source of a package the release covers'. check-governed-queue-guard.mjs --test on the four paths prints NOT GOVERNED. PR #9435 is a DRAFT; not flipped ready, no auto-merge, not enqueued.",
  "probe_block": [
    {
      "leg": "renderer 1 corpus scan (the divergence set)",
      "command": "vitest run over a temporary probe that renders each corpus file through MarkdownImpl with renderToStaticMarkup and compares the rendered heading ids to extractToc(md, {minDepth:1,maxDepth:6}); probe file deleted before commit (git status clean, verified)",
      "population": "223 files NAMED and enumerated on my base: content/docs/**/*.{md,mdx} = 184, packages/*/README.md = 39; YAML frontmatter stripped because console serves doc bodies without it (leaving it in makes the closing --- a setext h2 in every frontmatter file, which would fake ~144 divergences)",
      "pre": "2984 rendered headings; divergence set = the four named files, each missing exactly field-schema from the rendered side",
      "post": "2988 rendered headings (+4, the four recovered headings); divergence set = [] (empty)",
      "control": "LIT, known direction, HIT in the same run: 26 field pages carry a '## Field Schema' heading; the 22 that already had the blank line emitted field-schema through MarkdownImpl in the PRE run (22/26), rising to 26/26 POST. The PRE zero for the four target files is therefore a measurement, not a dead instrument. NONSENSE control: id 'field-schema-zzz-not-a-real-anchor' = 0 hits in every run, both phases.",
      "reader": "the rendered id attribute of each h1-h6 element in renderToStaticMarkup output — the same reader packages/plugin-markdown/src/toc-anchor-parity.test.tsx uses, chosen because reading the rendered attribute proves the anchor EXISTS, whereas re-deriving the slug rules would only prove two derivations agree"
    },
    {
      "leg": "renderer 2 non-change (@mdx-js/mdx)",
      "command": "node script: @mdx-js/mdx 3.1.1 evaluate() with rehype-slug, SchemaExample stubbed (grep over the four files proves it is the ONLY MDX component they use), rendered with the same renderToStaticMarkup reader",
      "population": "the four target files only — this leg is about the claim 'the insertion costs apps/site nothing'",
      "pre": "all four already emit field-schema; full id lists printed (7/10/7/6 ids, all non-empty)",
      "post": "id lists byte-identical to PRE for all four (printed both sides in the PR body)",
      "control": "this leg AGREES on both sides, so it carries its printed lists as the guard — the lists are non-empty and each contains the id under test. NONSENSE control in the same run: 'field-schema-zzz-not-a-real-anchor' = 0 hits; 'filesWithFieldSchema' = 4/4 both phases.",
      "reader": "same renderToStaticMarkup id reader as leg 1, deliberately symmetric so the two renderers are compared through one instrument. Note the fidelity bound: this is @mdx-js/mdx + rehype-slug as the card named it, NOT the full fumadocs-mdx plugin chain apps/site runs; what it settles is the block-structure question (does a self-closing MDX JSX flow element swallow the next heading), which is where the two pipelines diverge."
    },
    {
      "leg": "byte-level second reader for the defect shape",
      "command": "python regex over the same corpus for a self-closing capitalised JSX tag line immediately followed by an ATX heading line (multiline, byte-level — not a line-oriented grep that could miss a wrapping construct)",
      "population": "the same NAMED 223 files",
      "pre": "4 hits, exactly the four target files, each on '## Field Schema'",
      "post": "0 hits",
      "control": "known direction, HIT: the healthy shape (tag + TRUE blank line + heading) reads 250 PRE -> 254 POST (+4). A run where the healthy shape also read 0 would be a broken regex rather than a clean corpus.",
      "reader": "raw file bytes, independent of any renderer — cross-checks leg 1's divergence set from a second direction"
    },
    {
      "leg": "inserted bytes",
      "command": "sha256 per file before/after; regex capture of the two bytes between the tag and the heading; cat -A; git diff --check",
      "population": "the four edited files",
      "pre": "separator was a single LF",
      "post": "separator is b'\\n\\n' in all four; each file +1 byte exactly; git diff --check exit 0; git diff --stat = 4 files, 4 insertions",
      "control": "NEGATIVE control with known direction: a regex for tag + LF + one-or-more spaces/tabs + LF + heading matches 0 files, so no whitespace-only line was written (which would NOT be a blank line to CommonMark's HTML-block rule and would silently not fix anything)",
      "reader": "bytes read back off disk after the write, never the editor's exit code"
    },
    {
      "leg": "PRE/POST gate phasing",
      "command": "git checkout HEAD~1 -- <the four files> for PRE, run gates, then git checkout HEAD -- <the four files> for POST",
      "population": "the four files",
      "pre": "restored-to-base state proven by git diff HEAD --stat showing 4 deletions",
      "post": "restoration proven by git diff HEAD being EMPTY and git status --porcelain clean — not by the checkout's exit code (a no-op checkout also exits 0)",
      "control": "the fix was COMMITTED before the revert, so the restore leg points at HEAD, which already carries the implementation; a bare 'git checkout -- <path>' would have restored from the polluted index instead",
      "reader": "git diff HEAD / git status --porcelain"
    }
  ],
  "tests": "All exit codes by redirect-then-capture, never across a pipe. PRE = four files reverted to base, POST = as committed. docs:check-links PRE 0 / POST 0 ('Links are valid across 17 scan roots.'). check:doc-fences PRE 0 / POST 0 (227 documents). check:doc-types PRE 0 / POST 0 (188 doc files, 1106 code blocks, 'Every documented component type is registered.'). check:doc-example-ids PRE 0 / POST 0 (414 references resolve). check:control-bytes PRE 0 / POST 0 (7601 tracked text files). check:new-line-citations POST 0. check:doc-snippets and check:doc-examples FIRST returned exit 2, which their own output spells out as 'PRECONDITION NOT MET — the snippet program was NOT run' (packages unbuilt) — that is NOT MEASURED, not a red gate; after the scoped build they themselves name (turbo run build $(node scripts/check-doc-snippet-types.mjs --build-filter) --concurrency=2, 35 successful / 35 total, exit 0) both read PRE 0 / POST 0 ('650 of 650 block(s) judged, 0 failed'; '124 block(s), every covered @example compiles or fails exactly as its ledger row declares'). Tests POST: vitest packages/plugin-markdown/ + apps/console/src/pages/docs-portal.test.tsx exit 0 (6 files, 55 tests); vitest packages/types/ exit 0 (185 files, 4252 tests) — included because those suites read content/docs. node scripts/check-changeset-presence.mjs exit 0, 'no changeset is owed'. node scripts/check-governed-queue-guard.mjs --test on the four paths exit 0, 'NOT GOVERNED'. CI on PR #9435 was not waited on (reporting at draft-PR time per contract); Bundle Analysis is red across this lane and is out of scope.",
  "acceptance_items_not_met": [],
  "open_questions": [],
  "out_of_scope_findings": [
    "REPORTED ONLY, not filed and not fixed, per this dispatch. (1) objectui#7666 is still open and is now fully settled by this card's measurement — triage owns re-grading or closing it; I did not touch it. (2) Nothing mechanically prevents the defect shape from coming back: the divergence set is 0/223 today, but no gate reads it. packages/plugin-markdown/src/toc-anchor-parity.test.tsx pins extractToc-vs-renderer parity on SYNTHETIC heading strings only, so a fifth field page authored with the tag flush against its heading would re-open this silently. A corpus-level parity gate over content/docs + package READMEs (the exact 223-file scan this card ran, asserting the divergence set is empty) would close the class; it is a new card, not this one. (3) This repo has no scripts/pm/os-verify-lock.sh, so the heavy scoped build ran without the shared verification lock the dispatch contract assumes — worth knowing if parallel seats are building in this container."
  ]
}

---

Generated by Claude Code

[claude]

✅ LANDED — PR objectui#9435 merged 63d9ca6f47 at 2026-09-13T22:11:42Z. Full probe, re-confirmed against the actual <merge>^ = fb097b8479: objectui#9435 #issuecomment-5656409821 (pre-merge) and the LANDED note above it.

One blank line inserted in each of content/docs/fields/{date,rich-text,text,textarea}.mdx. Diff is 4 files, 4 insertions, every one an empty line; the separator on main reads b'\n\n' in all four — ⭐ a true empty line, verified at byte level, because a whitespace-only line is not a blank line to CommonMark's HTML-block rule and would have looked like a fix while changing nothing (negative control for that shape: 0).

Both renderers proven, in opposite directions: react-markdown goes absent → present on all four, at the indices extractToc already claimed; @mdx-js/mdx id lists are byte-identical before and after, printed both sides — so the card's claim that the insertion costs apps/site nothing is verified rather than inherited. Corpus-wide, the rendered-vs-extractToc divergence set is now empty.

⭐ The divergence set was re-derived, not inherited — and the corpus had moved: 2984 rendered headings against the 2981 this card read, while the set stayed exactly these four. No fifth file, none dropped out.

⚠️ Carried forward, ⛔ not filed on this card: nothing mechanically prevents the shape returning. toc-anchor-parity.test.tsx pins parity on synthetic heading strings only, so a fifth field page authored with the tag flush against its heading would reopen this silently. A corpus-level parity gate — the exact 223-file scan this card ran, asserting the divergence set is empty — would close the class. Being routed as its own card by this seat.

⚠️ objectui#7666 is now fully settled by this measurement — it named two possible landings (extractToc, domain:ui — or these four docs, domain:devx) and the measurement chose the docs. ⛔ Re-grading or closing it is triage's, ⛔ not this seat's and ⛔ not the dev's; neither of us touched it.

Closing; pm:queue and the assignee are stripped. bug / priority:p3 / domain:devx left alone — ⛔ not this seat's to produce or change.

---

Generated by Claude Code