basalt-ui 1.27.0 → 1.29.0

package/src/common/validate.ts

@@ -0,0 +1,94 @@
+/**
+ * Prop validation, in the two shapes basalt actually needs (Blueprint audit §3, isomorphic finding
+ * F-ERR-1).
+ *
+ * The split is the design: a MISUSE that would crash anyway throws immediately with a written
+ * message (`assertRequiredProps`), while a misuse that merely renders something the caller did not
+ * mean warns once in dev and renders on (`useValidateProps`).
+ */
+import { useEffect } from 'react'
+import { isDev } from './is-dev'
+import { requiredProp } from './errors'
+
+/** A check returns the message(s) it has, or nothing. `null`/`undefined` entries are ignored. */
+type CheckResult = string | null | undefined | Array<string | null | undefined>
+
+/**
+ * Module-level so the once-per-message promise survives a re-render, a remount, and a second
+ * instance of the same component. A dev warning is about the CODE, and printing it per render is
+ * how a real warning gets scrolled out of the console. Keyed by `component` + message, so two
+ * different faults in one component both get said.
+ */
+const reported = new Set<string>()
+
+/**
+ * Dev-only prop validation. `console.error`s each message ONCE per `(component, message)` pair, and
+ * is a no-op in production: `isDev()` reads `process.env.NODE_ENV`, which every bundler
+ * constant-folds, so the whole body disappears from a production build.
+ *
+ * **The dedup key is `${component} ${message}`, and nothing else** — not the instance, not the
+ * props. Two instances of one component producing the SAME message say it once between them, which
+ * is the intent (a dev warning is about the code). A caller that wants it said per instance has to
+ * embed the identifying context IN the message — the title, the persist key, the field name — the
+ * way `Section` writes `Section "<title>": …`. A message built from nothing instance-specific is a
+ * message the second faulty call site never gets.
+ *
+ * @example
+ * useValidateProps(
+ *   'Section',
+ *   () => (persistKey !== undefined && !collapsible ? sectionPersistMessage : null),
+ *   [persistKey, collapsible],
+ * )
+ */
+export function useValidateProps(
+  component: string,
+  check: () => CheckResult,
+  deps: unknown[],
+): void {
+  useEffect(() => {
+    if (!isDev()) return
+    const result = check()
+    const messages = Array.isArray(result) ? result : [result]
+    for (const raw of messages) {
+      if (raw === null || raw === undefined) continue
+      const key = `${component} ${raw}`
+      if (reported.has(key)) continue
+      reported.add(key)
+      console.error(raw)
+    }
+    // The deps ARE the caller's contract: this hook cannot know what `check` closes over.
+    // oxlint-disable-next-line react-hooks/exhaustive-deps -- the caller owns the dep list
+  }, deps)
+}
+
+/** Test seam. The once-per-message Set is module state, so a suite has to be able to clear it. */
+export function resetValidatedProps(): void {
+  reported.clear()
+}
+
+/**
+ * THROWS on a missing required prop, in every build, before the component reads into it.
+ *
+ * This is the F-ERR-1 remedy, and the reason it is not dev-gated: the component was going to crash
+ * either way (`undefined is not an object (evaluating 'field.use')`), so the only thing in question
+ * is whether the stack reaching `BasaltErrorBoundary` names the component and the prop. It does
+ * now. A prop that is merely questionable belongs in `useValidateProps`, not here.
+ *
+ * @example
+ * assertRequiredProps('SelectFilter', props, ['field'])
+ */
+export function assertRequiredProps<P extends object>(
+  component: string,
+  props: P,
+  keys: ReadonlyArray<Extract<keyof P, string>>,
+  hints?: Partial<Record<Extract<keyof P, string>, string>>,
+): void {
+  for (const key of keys) {
+    const value = (props as Record<string, unknown>)[key]
+    if (value !== undefined && value !== null) continue
+    const hint = hints?.[key]
+    throw new Error(
+      hint === undefined ? requiredProp(component, key) : requiredProp(component, key, hint),
+    )
+  }
+}

package/src/content/article-layout.module.css

@@ -17,6 +17,11 @@
   grid-template-columns: minmax(0, var(--vx-prose-measure));
 }
 
+/* The literal below MUST equal `BREAKPOINTS.article` (src/tokens/index.ts) — a `@media`
+ * condition is resolved before custom properties exist, so `max-width: var(--x)` is invalid CSS
+ * and a stylesheet with a responsive rule has no choice but to write the number. The token is the
+ * readable half; `article-layout.breakpoint.test.ts` asserts the two agree, the same
+ * "literal must match the token" idiom as `styles.floor.test.ts`. Change both or neither. */
 @media (max-width: 1200px) {
   .root {
     grid-template-columns: minmax(0, var(--vx-prose-measure));
@@ -72,10 +77,12 @@
 .tocRail {
   grid-column: 2;
   position: sticky;
-  /* DESKTOP-only value on purpose (no `< sm` override needed): the rail is already `display: none`
-   * below the 1200px `@media` breakpoint just above, well above the `sm` (48em/768px) breakpoint
-   * that switches BasaltShell's header — and, by extension, this clearance — to its mobile value
-   * (see `content/prose.module.css` for the responsive split; docs/CONTENT-SPEC.md §5). */
+  /* The rail sticks inside whatever scrolls it — `AppShell.Main` in a shell, the document without
+   * one — and NOTHING overhangs that box: the app header and `PageBar` row 2's band are both shell
+   * regions rendered outside the scrollport (`shell/app-main.module.css`). So the offset is
+   * `--vx-space-sticky-header-clearance` and nothing else, which is exactly what that token means
+   * since it stopped carrying a header height (tokens/palette.ts, `deriveSpacing`;
+   * docs/CONTENT-SPEC.md §5). */
   top: var(--vx-space-sticky-header-clearance);
   align-self: start;
 }

package/src/content/callout.tsx

@@ -8,20 +8,25 @@
  *   <p>This endpoint is rate-limited to 60 requests/minute.</p>
  * </Callout>
  */
-import type { CSSProperties, ReactNode } from 'react'
+import type { ReactNode } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
 import classes from './callout.module.css'
 
+/**
+ * One of the five `Tone` forks (`common/props.ts`) — kept as its own type because `info` has no
+ * `Tone` equivalent: `good`/`warn`/`bad` line up with `Tone` exactly, `info` is the extra kind a
+ * callout needs that a status badge does not.
+ */
 export type CalloutKind = 'info' | 'good' | 'warn' | 'bad'
 
-export type CalloutProps = {
+export type CalloutProps = BasaltProps & {
   /** Semantic kind — drives the rail/tint color and the default icon. Default `'info'`. */
   readonly kind?: CalloutKind
   readonly title?: string
   /** Overrides the default per-kind icon. Only rendered alongside a `title`. */
   readonly icon?: ReactNode
   readonly children: ReactNode
-  readonly className?: string
-  readonly style?: CSSProperties
 }
 
 const KIND_CLASS: Record<CalloutKind, string> = {
@@ -80,10 +85,11 @@ const DEFAULT_ICON: Record<CalloutKind, ReactNode> = {
 }
 
 export function Callout({ kind = 'info', title, icon, children, className, style }: CalloutProps) {
-  const rootClass = [classes.root, KIND_CLASS[kind], className].filter(Boolean).join(' ')
-
   return (
-    <div className={rootClass} {...(style !== undefined && { style })}>
+    <div
+      className={cx(classes.root, KIND_CLASS[kind], className)}
+      {...(style !== undefined && { style })}
+    >
       {title !== undefined && (
         <div className={classes.titleRow}>
           <span className={classes.icon}>{icon ?? DEFAULT_ICON[kind]}</span>

package/src/content/guide.tsx

@@ -18,6 +18,8 @@ import type { ReactNode } from 'react'
 import { ActionIcon, Button, Drawer } from '@mantine/core'
 import type { DrawerProps } from '@mantine/core'
 import { useDisclosure } from '@mantine/hooks'
+import type { BasaltProps } from '../common/props'
+import { cx } from '../common/props'
 import classes from './guide.module.css'
 import type { ArticleNavTarget } from './article-layout'
 import { Markdown } from './markdown'
@@ -54,7 +56,7 @@ function GuideGlyph() {
   )
 }
 
-export type GuideDrawerProps = {
+export type GuideDrawerProps = BasaltProps & {
   readonly opened: boolean
   readonly onClose: () => void
   readonly title: string
@@ -78,6 +80,8 @@ export function GuideDrawer({
   fullPageHref,
   renderLink = defaultRenderLink,
   size = 440,
+  className,
+  style,
 }: GuideDrawerProps) {
   return (
     <Drawer
@@ -86,6 +90,8 @@ export function GuideDrawer({
       position="right"
       size={size}
       title={<span className={classes.drawerTitle}>{title}</span>}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     >
       <div className={classes.body}>
         {markdown !== undefined ? (
@@ -111,7 +117,7 @@ export function GuideDrawer({
   )
 }
 
-export type GuideLinkProps = {
+export type GuideLinkProps = BasaltProps & {
   /** Trigger label. Default `'Guide'`. */
   readonly label?: string
   readonly title: string
@@ -131,6 +137,8 @@ export function GuideLink({
   fullPageHref,
   renderLink,
   iconOnly = false,
+  className,
+  style,
 }: GuideLinkProps) {
   const [opened, { open, close }] = useDisclosure(false)
 
@@ -141,9 +149,10 @@ export function GuideLink({
           variant="subtle"
           color="gray"
           size="sm"
-          className={classes.trigger}
+          className={cx(classes.trigger, className)}
           onClick={open}
           aria-label={label}
+          {...(style !== undefined && { style })}
         >
           <GuideGlyph />
         </ActionIcon>
@@ -152,9 +161,10 @@ export function GuideLink({
           variant="subtle"
           color="gray"
           size="compact-xs"
-          className={classes.trigger}
+          className={cx(classes.trigger, className)}
           leftSection={<GuideGlyph />}
           onClick={open}
+          {...(style !== undefined && { style })}
         >
           <span className={classes.triggerLabel}>{label}</span>
         </Button>

package/src/content/heading-anchor.tsx

@@ -19,18 +19,25 @@
  *   <h2 id={id}>Setup<HeadingAnchor id={id} /></h2>
  * </Prose>
  */
+import type { BasaltProps } from '../common/props'
+import { cx } from '../common/props'
 import { CopyAction } from './copy-action'
 import { LinkGlyph } from './glyphs'
 import classes from './prose.module.css'
 
-export type HeadingAnchorProps = {
+export type HeadingAnchorProps = BasaltProps & {
   /** The heading's `id` — the fragment the copied URL points at. */
   readonly id: string
   /** Accessible name for the trigger. */
   readonly label?: string
 }
 
-export function HeadingAnchor({ id, label = 'Copy link to section' }: HeadingAnchorProps) {
+export function HeadingAnchor({
+  id,
+  label = 'Copy link to section',
+  className,
+  style,
+}: HeadingAnchorProps) {
   // Resolved at click time, never at render: the component is SSR-rendered (no `window`), and the
   // live search/pathname is the honest basis for the link a reader is asking to share.
   const resolveUrl = () => {
@@ -41,7 +48,11 @@ export function HeadingAnchor({ id, label = 'Copy link to section' }: HeadingAnc
   // The span owns placement + the hover reveal; CopyAction owns the affordance itself. It also
   // carries `data-heading-anchor`, which `TableOfContents` strips when reading a heading's label.
   return (
-    <span className={classes.headingAnchor} data-heading-anchor>
+    <span
+      className={cx(classes.headingAnchor, className)}
+      data-heading-anchor
+      {...(style !== undefined && { style })}
+    >
       <CopyAction
         value={resolveUrl}
         label="Copy link"

package/src/content/index.ts

@@ -27,6 +27,8 @@ export type { TableOfContentsProps, TocItem } from './toc'
 export { ReadingProgress } from './reading-progress'
 export type { ReadingProgressProps } from './reading-progress'
 
+// `SlugTracker` is a PascalCase utility class, not a component — see its own JSDoc `@remarks`
+// (isomorphic harness finding F-DET-1). `new SlugTracker()`, never `<SlugTracker />`.
 export { headingSlug, readingTime, SlugTracker } from './slug'
 export type { ReadingTime } from './slug'
 

package/src/content/markdown.tsx

@@ -101,10 +101,9 @@ export type MarkdownProps = {
    * default to same-origin `['/']`; `'trusted'` (your own authored content) keeps
    * `['https://', '/']`. An explicit `allowedImagePrefixes` always wins over both.
    *
-   * Default: `'untrusted'` when `streaming` is set, `'trusted'` otherwise. That default only
-   * preserves the pre-1.12 fail-safe — it is NOT the policy. Settledness has nothing to do with
-   * trust: a FINISHED agent message is still model-generated, so any surface rendering agent text
-   * must pin `contentTrust="untrusted"` explicitly rather than lean on `streaming`.
+   * Default: `'trusted'`. Settledness has nothing to do with trust: a FINISHED agent message is
+   * still model-generated, so any surface rendering agent text must pin `contentTrust="untrusted"`
+   * explicitly rather than lean on `streaming`.
    */
   readonly contentTrust?: MarkdownContentTrust
   /**
@@ -394,6 +393,7 @@ const LazyReactMarkdown = lazy(() =>
     })
     .catch(() => ({ default: ({ text }: BridgeProps) => <PlainTextFallback text={text} /> })),
 )
+Object.assign(LazyReactMarkdown, { displayName: 'LazyReactMarkdown' })
 
 // ── Streaming block rendering ──────────────────────────────────────────────────────────────────
 
@@ -443,6 +443,7 @@ function BlockRenderer({
 // Referential stability of `components`/`urlTransform` (both memoized by the caller) is what makes
 // this memo skip re-rendering an unchanged settled block — see the module JSDoc.
 const MemoizedBlock = memo(BlockRenderer)
+MemoizedBlock.displayName = 'MemoizedBlock'
 
 // ── Lazy-loaded remend ─────────────────────────────────────────────────────────────────────────
 
@@ -616,10 +617,7 @@ export function Markdown({
   density = 'article',
   measure,
   streaming = false,
-  // `streaming` as the trust DEFAULT is backward compatibility only (pre-1.12 the image policy was
-  // read straight off `streaming`, so dropping it would silently widen every existing streaming
-  // call site). It is a floor, never the policy — see the prop's JSDoc.
-  contentTrust = streaming ? 'untrusted' : 'trusted',
+  contentTrust = 'trusted',
   components,
   fenceRenderers,
   sanitizeSchema,

package/src/content/prose.module.css

@@ -32,16 +32,18 @@
   margin-bottom: 0;
 }
 
-/* Sticky-header clearance for in-page anchors. One value on every viewport: since the
- * controls waves the AppShell header is `appShellHeaderHeight` (48px) on phones too — the two-row
- * mobile header and its `-mobile` clearance token are gone (docs/CONTROLS-SPEC.md §2.1, law C14).
- * `--basalt-page-bar-h` (a sticky PageBar row 2, published by the shell) is added on top so a
- * heading never lands under the filter row. A `./content` consumer rendering Prose standalone (no
- * BasaltShell) overrides `--vx-space-sticky-header-clearance` itself. */
+/* Anchor clearance. One value on every viewport, and NO chrome height in it: an anchor scroll
+ * happens inside the scrollport, and since `BasaltShell` made `AppShell.Main` that box both the
+ * AppShell header and `PageBar` row 2's band are regions rendered OUTSIDE it
+ * (`shell/app-main.module.css`) — the `--basalt-page-bar-h` term this rule used to add would now
+ * push every heading a band below where it belongs, and an `--app-shell-header-height` term (gone
+ * since the controls waves) would add a header on top of that. What is left is breathing room,
+ * which is precisely what `--vx-space-sticky-header-clearance` means now (tokens/palette.ts). A
+ * `./content` consumer with its OWN fixed chrome above the scrollport overrides that token. */
 .root h2,
 .root h3,
 .root h4 {
-  scroll-margin-top: calc(var(--vx-space-sticky-header-clearance) + var(--basalt-page-bar-h, 0px));
+  scroll-margin-top: var(--vx-space-sticky-header-clearance);
 }
 
 /* Headings share family/weight/color across densities; size + margin differ below. */

package/src/content/reading-progress.tsx

@@ -1,9 +1,14 @@
 /**
  * ReadingProgress — an opt-in, scroll-driven 2px top bar (docs/CONTENT-SPEC.md §3/§7).
  *
- * Progress is how far `target` (default: the whole document) has been scrolled through the
+ * Progress is how far `target` (default: the whole scrollport) has been scrolled through the
  * viewport — 0 at the top of `target`, 1 once its bottom edge has cleared the viewport.
  *
+ * WHICH BOX SCROLLS is resolved, never assumed: inside `BasaltShell` the scroller is
+ * `AppShell.Main` (`shell/app-main.module.css`), where `window.scrollY` is pinned at 0 and a
+ * `scroll` listener on `window` never fires. `scrollParentOf` answers `null` for a shell-less app
+ * and this falls back to the window unchanged.
+ *
  * @example
  * import { ReadingProgress } from 'basalt-ui/content'
  *
@@ -13,35 +18,50 @@
  */
 import type { RefObject } from 'react'
 import { useEffect, useRef, useState } from 'react'
+import type { BasaltProps } from '../common/props'
+import { cx } from '../common/props'
+import { scrollParentOf } from '../common/scroll-parent'
 import classes from './reading-progress.module.css'
 
-export type ReadingProgressProps = {
-  /** The element to track scroll progress through. Default: the whole document. */
+export type ReadingProgressProps = BasaltProps & {
+  /** The element to track scroll progress through. Default: the whole scrollport. */
   readonly target?: RefObject<HTMLElement | null>
 }
 
-function computeProgress(target: HTMLElement | null | undefined): number {
-  const viewport = window.innerHeight
-  const scrollTop = window.scrollY
+/**
+ * `port` is the resolved scrollport, or `null` for "the document scrolls". The only thing that
+ * changes between the two is where the four numbers come from — `target`'s offset is measured
+ * against the SCROLLER's own top edge rather than the viewport's, which for the window case is the
+ * same edge and reduces to the original arithmetic.
+ */
+function computeProgress(target: HTMLElement | null | undefined, port: HTMLElement | null): number {
+  const viewport = port ? port.clientHeight : window.innerHeight
+  const scrollTop = port ? port.scrollTop : window.scrollY
+  const originTop = port ? port.getBoundingClientRect().top : 0
+  const scrollable = port ? port.scrollHeight : document.documentElement.scrollHeight
 
-  const start = target ? target.getBoundingClientRect().top + scrollTop : 0
-  const total = target
-    ? target.offsetHeight - viewport
-    : document.documentElement.scrollHeight - viewport
+  const start = target ? target.getBoundingClientRect().top - originTop + scrollTop : 0
+  const total = target ? target.offsetHeight - viewport : scrollable - viewport
 
   if (total <= 0) return 0
   const ratio = (scrollTop - start) / total
   return Math.min(1, Math.max(0, ratio))
 }
 
-export function ReadingProgress({ target }: ReadingProgressProps = {}) {
+export function ReadingProgress({ target, className, style }: ReadingProgressProps = {}) {
   const [progress, setProgress] = useState(0)
   const frame = useRef<number | null>(null)
+  const rootRef = useRef<HTMLDivElement | null>(null)
 
   useEffect(() => {
+    // The bar itself is a fine probe when there is no `target`: it is mounted inside whatever
+    // region the reader is scrolling, which is the box this is measuring.
+    const port = scrollParentOf(target?.current ?? rootRef.current)
+    const scroller: Window | HTMLElement = port ?? window
+
     const tick = () => {
       frame.current = null
-      setProgress(computeProgress(target?.current))
+      setProgress(computeProgress(target?.current, port))
     }
 
     const onScroll = () => {
@@ -50,17 +70,22 @@ export function ReadingProgress({ target }: ReadingProgressProps = {}) {
     }
 
     tick()
-    window.addEventListener('scroll', onScroll, { passive: true })
+    scroller.addEventListener('scroll', onScroll, { passive: true })
     window.addEventListener('resize', onScroll, { passive: true })
     return () => {
-      window.removeEventListener('scroll', onScroll)
+      scroller.removeEventListener('scroll', onScroll)
       window.removeEventListener('resize', onScroll)
       if (frame.current !== null) cancelAnimationFrame(frame.current)
     }
   }, [target])
 
   return (
-    <div className={classes.root} aria-hidden>
+    <div
+      ref={rootRef}
+      className={cx(classes.root, className)}
+      aria-hidden
+      {...(style !== undefined && { style })}
+    >
       <div className={classes.fill} style={{ transform: `scaleX(${progress})` }} />
     </div>
   )

package/src/content/slug.ts

@@ -28,6 +28,10 @@ export function headingSlug(text: string): string {
  * Dedupes repeated slugs within one document — the second occurrence of a slug gets `-1`, the
  * third `-2`, and so on (matches github-slugger's own collision behavior). Create one instance
  * per document/render pass; it carries no global state.
+ *
+ * @remarks not a component — an ordinary PascalCase utility class on the `content` barrel
+ * (isomorphic harness finding F-DET-1). It carries no `prototype.isReactComponent` marker, so
+ * `new SlugTracker()`, not `<SlugTracker />`.
  */
 export class SlugTracker {
   private readonly counts = new Map<string, number>()

package/src/content/toc.tsx

@@ -6,6 +6,17 @@
  * `headingSlug`/`SlugTracker` when authoring the headings. Sticky positioning is the consumer's
  * job; this component is just the rail.
  *
+ * The spy resolves WHICH BOX SCROLLS (`scrollParentOf`) instead of assuming the window: inside
+ * `BasaltShell` that is `AppShell.Main` (`shell/app-main.module.css`), so both the observer's root
+ * and the bottom-edge arithmetic have to be that element — a window listener there never fires and
+ * a viewport-rooted observer measures the wrong band. `null` means the document scrolls, which is
+ * the shell-less case and behaves exactly as before.
+ *
+ * The active rail item carries `aria-current="location"` (WAI-ARIA APG's own recommendation for a
+ * link set that navigates within one page, rather than `"page"`/`"true"`) — both a genuine a11y fix
+ * (previously `activeId` drove `classes.active` alone, so a screen reader had no signal at all) and
+ * the one DOM-observable hook for `activeId` that does not depend on a CSS Modules class hash.
+ *
  * @example
  * import { TableOfContents, headingSlug } from 'basalt-ui/content'
  *
@@ -18,6 +29,7 @@
 import type { MouseEvent, RefObject } from 'react'
 import { useEffect, useRef, useState } from 'react'
 import { useReducedMotion } from '@mantine/hooks'
+import { scrollParentOf } from '../common/scroll-parent'
 import classes from './toc.module.css'
 
 export type TocItem = {
@@ -79,6 +91,11 @@ export function TableOfContents({
   // Set while a clicked item owns the rail; `resolve` stands down until it's released.
   const pinnedRef = useRef<string | null>(null)
   const releasePinRef = useRef<(() => void) | null>(null)
+  // The rail's own node — the probe `scrollParentOf` walks from when there is no `containerRef`.
+  const navRef = useRef<HTMLElement | null>(null)
+  // The resolved scrollport (`null` = the document), published by the spy effect so the click-pin
+  // release below listens for `scrollend` on the same box the spy is watching.
+  const portRef = useRef<HTMLElement | null>(null)
 
   useEffect(() => {
     return () => releasePinRef.current?.()
@@ -108,6 +125,10 @@ export function TableOfContents({
       .filter((el): el is HTMLElement => el !== null)
     if (elements.length === 0) return
 
+    const port = scrollParentOf(containerRef?.current ?? navRef.current)
+    portRef.current = port
+    const scroller: Window | HTMLElement = port ?? window
+
     const intersecting = new Set<string>()
 
     const resolve = () => {
@@ -118,8 +139,9 @@ export function TableOfContents({
       // Bottom edge: the last sections are usually shorter than the observer's 70% dead zone, so
       // their headings can NEVER reach the activation band — the rail would stall on whichever
       // section last made it in. Once the page bottoms out, the final item is the honest answer.
-      const doc = document.documentElement
-      if (window.innerHeight + window.scrollY >= doc.scrollHeight - 2) {
+      const box = port ?? document.documentElement
+      const seen = port ? port.clientHeight + port.scrollTop : window.innerHeight + window.scrollY
+      if (seen >= box.scrollHeight - 2) {
         const last = elements[elements.length - 1]
         if (last) setActiveId(last.id)
         return
@@ -134,7 +156,9 @@ export function TableOfContents({
       // Nothing intersecting — the last heading already scrolled past, or (above the first one,
       // i.e. at the very top of the article) the first heading, so the rail always marks where the
       // reader actually is instead of showing nothing until the first heading reaches the band.
-      const passed = elements.filter((el) => el.getBoundingClientRect().top < 0)
+      // "Past" is measured against the SCROLLER's top edge, which for the window case is 0.
+      const originTop = port ? port.getBoundingClientRect().top : 0
+      const passed = elements.filter((el) => el.getBoundingClientRect().top < originTop)
       const current = passed[passed.length - 1] ?? elements[0]
       if (current) setActiveId(current.id)
     }
@@ -147,19 +171,22 @@ export function TableOfContents({
         }
         resolve()
       },
-      { rootMargin: '-80px 0px -70% 0px' },
+      // `root: null` IS the viewport — the shell-less case, unchanged. Inside a shell the root has
+      // to be the scrollport or the `-70%` dead zone is measured against a box nothing scrolls.
+      { root: port, rootMargin: '-80px 0px -70% 0px' },
     )
 
     for (const el of elements) observer.observe(el)
     // The observer only fires when an intersection CHANGES; the bottom edge above resolves on
     // scroll position alone, so it needs a scroll signal too. Re-setting the same id is a no-op
     // for React, so this stays free on every frame that doesn't move the rail.
-    window.addEventListener('scroll', resolve, { passive: true })
+    scroller.addEventListener('scroll', resolve, { passive: true })
     return () => {
       observer.disconnect()
-      window.removeEventListener('scroll', resolve)
+      scroller.removeEventListener('scroll', resolve)
+      portRef.current = null
     }
-  }, [resolvedItems])
+  }, [resolvedItems, containerRef])
 
   if (resolvedItems.length === 0) return null
 
@@ -174,15 +201,18 @@ export function TableOfContents({
     setActiveId(id)
     pinnedRef.current = id
 
+    // The same box the spy watches — `scrollend` on `window` never fires for a scroll that happened
+    // inside `AppShell.Main`, which would leave the rail pinned for the full `CLICK_PIN_MAX_MS`.
+    const scroller: Window | HTMLElement = portRef.current ?? window
     let timer: ReturnType<typeof setTimeout> | null = null
     const release = () => {
       pinnedRef.current = null
       if (timer !== null) clearTimeout(timer)
-      window.removeEventListener('scrollend', release)
+      scroller.removeEventListener('scrollend', release)
       releasePinRef.current = null
     }
     timer = setTimeout(release, CLICK_PIN_MAX_MS)
-    window.addEventListener('scrollend', release, { once: true })
+    scroller.addEventListener('scrollend', release, { once: true })
     releasePinRef.current = release
   }
 
@@ -200,7 +230,7 @@ export function TableOfContents({
   const navClass = [classes.root, className].filter(Boolean).join(' ')
 
   return (
-    <nav className={navClass} aria-label={title}>
+    <nav ref={navRef} className={navClass} aria-label={title}>
       <div className={classes.header}>{title}</div>
       <ul className={classes.list}>
         {resolvedItems.map((item) => (
@@ -214,6 +244,13 @@ export function TableOfContents({
               ]
                 .filter(Boolean)
                 .join(' ')}
+              // `classes.active` alone used to be the ONLY signal of which item the spy picked —
+              // both a real a11y gap (nothing here told assistive tech which section is current)
+              // and, incidentally, the reason a consumer/test could not observe `activeId` without
+              // reading CSS. `location` (not `page`/`true`) is the value WAI-ARIA's Authoring
+              // Practices call out BY NAME for exactly this widget: a set of links navigating
+              // within a single page, as opposed to a set of links to different pages.
+              aria-current={activeId === item.id ? 'location' : undefined}
               onClick={handleClick(item.id)}
             >
               {item.label}