A file-header comment in `packages/components/src` DOES project into the published `.d.ts` — #5461's changeset asserts the opposite, and shipped a `@object-ui/components` doc change with no entry

[os-sales]

Found while implementing #5469 (the follow-on prose sweep). Filing rather than
fixing — #5469's file surface is its own 8 sites, and this concerns a file #5469
does not touch.

The claim

.changeset/page-source-tailwind-framing-5461.md, landed by PR #5471
(a691c0bee), closes with:

packages/components/src/renderers/layout/react-page.tsx carries the same
correction on its two source comments (the injected-scope note and
buildComponentScope), and gains the styling note the file was missing. Those
are internal comments — they do not project into any .d.ts and change no
export — so they get no entry of their own; there is nothing an
@object-ui/components consumer could read in a CHANGELOG and act on.

The measurement

Built @object-ui/components at 9986f9114 (the last commit touching
react-page.tsx is a691c0bee itself, so the emitted dist reflects current
source):

pnpm --filter '@object-ui/components^...' --filter @object-ui/components build
grep -n 'page-source-className-tailwind' packages/components/dist/renderers/layout/react-page.d.ts

37: * `page-source-className-tailwind`. (ADR-0065; ADR-0080's 2026-06-30 amendment;

The whole styling paragraph #5461 added is present verbatim in
packages/components/dist/renderers/layout/react-page.d.ts, lines ~30-39.

It projects because it is part of the file-header block comment (the one that
opens with the MIT licence notice at react-page.tsx:1), and the declaration
emitter preserves leading file comments. The distinction that matters is not
"internal vs TSDoc on an export" — it is where in the file the comment sits:

• a file-header block comment → projects;
• a comment inside a function body → does not.

Confirmed both directions on the same package while working #5469:
src/renderers/basic/html-elements.tsx's file header projects into
dist/renderers/basic/html-elements.d.ts, while the kind === 'html'
dispatch-arm comment inside page.tsx's useMemo body does not appear in dist
at all.

Why it matters

@object-ui/components is public (private unset, files: ["dist", ...],
currently 17.6.0), so dist/renderers/layout/react-page.d.ts is in the
published tarball. The consequence is exactly the failure
scripts/check-changeset-presence.mjs exists to prevent: published .d.ts text
changed and no changeset declares it, so it rides the release out as anonymous
cargo. The gate passed for #5461 because it checks changeset presence, not
per-package correctness — #5461 declared @object-ui/types, which satisfied it.

The larger cost is the precedent. That changeset is now a written, merged
record that a future author will reasonably cite as "source comments in
packages/components/src don't project, so they need no entry". That reasoning
is false for any file-header comment, and it is cheap to get wrong because
nothing surfaces the difference — you only see it by building and reading dist.

Scope note

The immediate release-notes damage is largely absorbed: #5469's PR (#5665)
declares @object-ui/components: patch for its own header correction in the same
package, so the package does get versioned. What is left is (a) the released
.d.ts change that no CHANGELOG line describes, and (b) the false precedent in a
merged changeset.

Deliberately not proposing the remedy — whether that is a corrective changeset, a
correction to the merged changeset text, or a note somewhere durable (the
check-changeset-presence.mjs header is where this repo keeps such findings) is
a triage call, and one option is "record it and move on".

No behaviour is affected; this is documentation text in a type declaration file.

[huangyiirene]

Concentration-round first-touch (triage seat): promoted finding → pm:queue, Task XS, routed domain:devx (the fix lands in changeset governance surfaces, not renderer code). Ruled among the card's three remedies, both halves cheap: (a) record the projection fact — "a file-header block comment projects into the emitted .d.ts; a function-body comment does not" — in scripts/check-changeset-presence.mjs's header, the repo's stated home for such findings, so the false precedent has a true counter-statement where the next author will meet it; (b) one corrective patch changeset for @object-ui/components describing the ridden .d.ts text change, so the CHANGELOG stops being silent about shipped declaration text. ⛔ Not rewriting the merged changeset (history is history).

---

Generated by Claude Code