docs: list the page heading in the table of contents

[Lisa18289]

The page heading is rendered from the frontmatter, not from the MDX, so getAnchors never saw it. The topmost section of every page — intro, status callout, live example — had no anchor at all, and the table of contents offered no way back to the top.

MdxFileFactory.fromFile now prepends an entry for the page title, and the heading carries the matching id. /releases builds its anchors itself and prepends the same entry.

The slug is the constant top rather than the slugified title: # Color and # Releases already exist as MDX headings and would collide with it. As a bonus, #top is a special case in HTML — if the element is ever missing, the browser still jumps to the top of the page.

The heading gets scroll-margin-top: 100vh rather than the 6rem the MDX headings use. It sits 121px down the document, so a matching offset stopped 25px short and scrolled the page padding away; a full viewport clamps the jump to 0 without a fixed length that needs re-tuning when the header height or page padding changes.

The active entry

Adding an entry above the first section exposed two faults in how the active entry was picked, both pre-existing. It came from an IntersectionObserver watching a band 20–30% down the viewport, and that band answers "which section am I in" badly:

• Its position scales with the viewport. On a 1400px window it spans 280–420px and lands on the first section while the page is still at the top. Previously that section was also the first entry, so the wrong answer looked right.
• It only reports when a heading crosses it. On /releases both anchors sit in the top 274px, so the last callback fires around scrollY 34 and none ever follows — whatever was decided there stuck for the rest of the page.

The active entry is now computed from the scroll position: the last heading that has crossed the line an anchor jump lands on, and the page heading before any has. It recomputes on scroll and resize, so it cannot freeze, and the observer and its fallback branch are gone. This also clears a standing react-hooks/exhaustive-deps warning.

Release headings had no scroll-margin-top at all, so jumping to one put it under the sticky header. They now carry the same 6rem as the MDX headings.

Verified in the browser

• All five pages with a table of contents (01–04 and /releases) show the title as the first, non-indented entry, linking to an id that exists.
• The heading sits 121px down the document at every width from 820px to 1920px.
• Clicking the top entry from scrollY: 4000 lands at 0, and deep-linking …/button#top does too. Clicking a release entry puts its heading 96px down, clear of the 72px header.
• At scrollY: 0 the page heading is active at 900px and 1400px viewport height; on /releases the entry switches to the release at scrollY: 200 and stays there to the bottom of the page.

titleFrom was extracted from getTitle so the factory can build the entry before constructing the MdxFile; its fallback chain is covered by a unit test.

03-patterns/02-codesnippets/multi-upload has no # /## heading at all and now shows a table of contents with a single entry. Accepted as-is; giving that page a heading is content work, not part of this fix.

No release: apps/ is publish-irrelevant per .github/scripts/release-relevance-lib.mjs.

Closes #2876

🤖 Generated with Claude Code

[github-actions]

Coverage Report for ./packages/components/

Status	Category	Percentage	Covered / Total
🔵	Lines	76%	627 / 825
🔵	Statements	75.91%	643 / 847
🔵	Functions	77.95%	145 / 186
🔵	Branches	66.66%	298 / 447

File Coverage

No changed files found.

Generated in workflow #6407 for commit 7e252fa by the Vitest Coverage Report Action

[github-actions]

🚀 Preview Deployment

Preview environments are ready:

Type	URL
docs	pr-2988.docs.review.flow-components.de
storybook	pr-2988.storybook.review.flow-components.de

Images:

• docs: ghcr.io/mittwald/flow/docs:pr-2988
• storybook: ghcr.io/mittwald/flow/storybook:pr-2988