@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/Outline/Outline.spec.md

@@ -1,258 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:Outline
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-31
-owners: [cixzhang]
-review_triggers:
-  [public-api, behavior, layout, theming, accessibility, interaction]
-verified_by:
-  [
-    packages/core/src/Outline/Outline.test.tsx,
-    packages/core/src/Outline/OutlineFocus.a11y.chromium.spec.ts,
-    packages/core/src/theme/themingTargets.test.ts,
-    .github/visual-baseline/manifest.json,
-    scripts/check-knowledge.mjs,
-  ]
-modules: [module:Outline/parseOutlineFromMarkdown]
-families: []
-design_specs: [design:reduced-motion]
-architecture:
-  [
-    architecture:component-theming-surface,
-    architecture:interaction-modality,
-    architecture:public-component-api,
-  ]
-contributing: []
-system_specs: [spec:AST-009, spec:AST-020]
----
-
-# Outline component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                    |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `items`, `activeId`, `onActiveIdChange`, `label`, `density`, `onNavigateStart`, `onNavigateEnd`, `offset`, `scrollContainerRef`, `hasScrollOnClick`, root `BaseProps`, `ref`.                                               |
-| Behavior                | A labelled navigation list of same-page heading links with keyboard movement, a scroll-tracked current heading, and a sliding indicator.                                                                                    |
-| End-user impact         | People see where they are in a long page and jump to any heading by pointer or keyboard, landing below a fixed header.                                                                                                      |
-| Builder impact          | A builder's explicit `aria-label` is meant to name the navigation; today `label` or the localized default replaces it (FR1 gap).                                                                                            |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Five implementation gaps are listed under Current-state impact.                                                                                  |
-| Review checks           | Reject a link left out of the Tab order or arrow-key movement added without a named exception, a dead link for a missing target, a callback that fires twice, or a lost focus outline.                                      |
-| Governing rules         | `architecture:interaction-modality`; `architecture:component-theming-surface`; `architecture:public-component-api` INV5–INV8; `spec:AST-020` FR15; `design:reduced-motion` DR1–DR3; WCAG 2.2 SC 1.3.1, 2.1.1, 2.4.3, 2.4.7. |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Outline presents same-page heading navigation: heading links with labels, a
-vertical indicator track, and a sliding active indicator that follows the
-heading the reader is on. The document owns the headings.
-
-Consumer syntax and examples belong in `Outline.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes` — localized "Table of contents" label,
-  default density, no offset, the nearest scrollable ancestor (else the window)
-  as the scroll root, smooth scroll on click.
-- Compatibility class: records shipped behavior; no public prop, default, DOM,
-  target, or styling output changes.
-- Controlled/uncontrolled behavior: the current heading is controlled with
-  `activeId` and `onActiveIdChange`, or uncontrolled and tracked from scroll.
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **Caller `aria-label` replaced (FR1).** Caller props spread before the
-  component's `aria-label`, so a caller `aria-label` is replaced by `label` or
-  the localized default; only the `label` prop names the navigation, where
-  `architecture:public-component-api` INV5 lets a caller's explicit input
-  reach the element.
-- **Focus stays on the Outline after navigating (FR4).** Activating a link
-  scrolls to the section but leaves focus on the link, so the next Tab moves
-  past the Outline, usually back toward the top of the content, instead of
-  into the chosen section, where a native in-page link moves the sequential
-  focus starting point (WCAG 2.2 SC 2.4.3).
-- **The indicator slides under reduced motion (FR6).** The indicator's move
-  and resize transition has no reduced-motion branch, where
-  `design:reduced-motion` DR1–DR3 have it change at once on a fine pointer and
-  cross-fade in 200 ms or less on a coarse one.
-- **One roving Tab stop instead of a Tab stop per link (FR3).** Keyboard users
-  reach only the current heading's link with Tab and move between links with
-  arrow, Home, and End keys, where `spec:AST-020` FR15 keeps a list of
-  independently focusable links in the normal Tab order and adds no such keys
-  without a named exception. Tests pin today's model.
-- **Navigation scrolls smoothly under reduced motion (FR4).** Following a link
-  always smooth-scrolls to the heading, where `design:reduced-motion` DR1–DR3
-  have a scroll the component starts land at once on a fine pointer and
-  cross-fade in 200 ms or less on a coarse one.
-
-## Ownership boundary
-
-**Owns**
-
-- The navigation landmark and its `outline` target, the list, the heading
-  links and their `outline-item` target, the labels, the indicator track, and
-  the active indicator and its `outline-indicator` target.
-- Keyboard focus within the list, scroll tracking, click and keyboard
-  navigation, and the navigate callbacks.
-
-**Does not own / non-goals**
-
-- The destination headings and their content — owned by the document or
-  product callsite.
-- Building `items` from markdown — owned by
-  `module:Outline/parseOutlineFromMarkdown`.
-
-## Public concepts
-
-| Concept         | Closed values or states                            | Meaning                                                                                                                                    | Availability by variant/orientation/state | Default                                | Owner               | Stability | Invalid-value behavior           |
-| --------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- | -------------------------------------- | ------------------- | --------- | -------------------------------- |
-| Items           | `{id, label, level}` list                          | The headings, in order, with heading level 1–6.                                                                                            | Always                                    | —                                      | caller              | Stable    | Levels clamp to four indents.    |
-| Current heading | controlled `activeId`; scroll-tracked              | The heading marked current.                                                                                                                | Always                                    | scroll-tracked                         | `component:Outline` | Stable    | —                                |
-| Label           | string                                             | The navigation's accessible name.                                                                                                          | Always                                    | localized default                      | `component:Outline` | Stable    | —                                |
-| Density         | `default`; `compact`                               | Link padding.                                                                                                                              | Always                                    | `default`                              | `component:Outline` | Stable    | Closed union; rejected by types. |
-| Scroll scope    | `offset`; `scrollContainerRef`; `hasScrollOnClick` | Activation line and landing offset; the scrolled container (else the nearest scrollable ancestor, else the window); whether clicks scroll. | Always                                    | 0; nearest scrollable ancestor; `true` | `component:Outline` | Stable    | —                                |
-| Navigate events | `onNavigateStart`; `onNavigateEnd`                 | Fired when a link navigation starts and when its scroll settles.                                                                           | Always                                    | none                                   | caller              | Stable    | —                                |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Basis                                                                   |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| FR1 | Outline renders a `nav` carrying the `outline` target, which reflects `density`, named by `label` or the localized "Table of contents", holding a `ul` (`role="list"`) of `li` items, each with a link to `#<id>` whose label truncates with an ellipsis, then an `aria-hidden` indicator track and an `aria-hidden` active indicator. A caller's explicit `aria-label` reaches the `nav` (`architecture:public-component-api` INV5). Implementation gap: the component's `aria-label` replaces it (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and tests                                                |
-| FR2 | Each link carries the `outline-item` target, which reflects `level` and, for the current heading, `active`; the current link has `aria-current="location"`, primary text color, and semibold weight. Heading levels 1 and 2 share the first indent, and levels 3, 4, and 5–6 take the second, third, and fourth.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and tests                                                |
-| FR3 | Each link is in the normal Tab order, and Outline adds no arrow, Home, or End movement between links unless this record names an exception (`spec:AST-020` FR15); Tab leaves the list after its last link. Implementation gap: today the list is one roving Tab stop, seated on the current heading (the first link when none is current, none when empty) and following it unless focus is inside the list, with ArrowDown and ArrowUp moving real DOM focus between links and Home and End jumping to the first and last (Current-state impact; OQ1).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Current source and tests; `spec:AST-020` FR15; WCAG 2.2 SC 2.1.1        |
-| FR4 | A click, Enter, or Space on a link whose target exists pushes `#<id>` to history and smoothly scrolls to the heading: at `offset` 0 every scrollable ancestor, the window included, scrolls the heading to the top; with a non-zero `offset` only the scroll root (`scrollContainerRef`, else the nearest scrollable ancestor, else the window) scrolls, landing `offset` pixels plus the heading's own scroll margin below its top; `onNavigateStart` fires when the navigation starts and `onNavigateEnd` exactly once when the scroll settles or the reader interrupts it with a manual scroll, falling back to a timeout when no scroll end arrives; a second navigation ends the first at once, and `onNavigateEnd` does not fire after Outline unmounts mid-scroll. Under reduced motion the navigation scroll does not travel: it lands at once on a fine pointer (`design:reduced-motion` DR3) and cross-fades in 200 ms or less on a coarse pointer (DR2). With `hasScrollOnClick={false}` nothing scrolls: the hash is pushed, the heading marked current, and `onNavigateEnd` fires at once. A click or Enter on a missing target, or any modifier chord, is left to the browser; Space on a missing target does nothing. Following a link moves the sequential focus starting point to the destination, as a native in-page link does (WCAG 2.2 SC 2.4.3). Implementation gaps: the scroll is smooth under reduced motion too; and focus stays on the Outline link, so the next Tab continues after the Outline instead of inside the chosen section (Current-state impact). | Current source and tests                                                |
-| FR5 | Uncontrolled, the current heading follows the reader's scroll position in the scroll root (`scrollContainerRef`, else the nearest scrollable ancestor, else the window), using an activation line shifted by `offset` and each heading's own scroll margin; the first heading is current before any heading passes the line, and the last heading is current once the scroll root reaches its end; a click marks its heading current once the scroll settles. Uncontrolled, `onActiveIdChange` reports each change of the current heading, from scroll or a click; controlled, the Outline does not track scroll, `activeId` decides, and `onActiveIdChange` reports the heading a click selects. Keyboard focus movement and the component's own navigation scroll are not treated as manual scrolling.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Current source and tests                                                |
-| FR6 | The active indicator is a 2px `--color-icon-primary` bar over a 2px `--color-border` track at the inline start, positioned against the current link with CSS anchor positioning and moving with a fast standard transition. Under reduced motion the indicator does not travel: on a fine pointer it changes at once (`design:reduced-motion` DR3), and on a coarse pointer it cross-fades in 200 ms or less (DR2). Implementation gap: the transition has no reduced-motion branch, so the indicator still slides (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and tests                                                |
-| FR7 | The keyboard-focused link shows the shared focus outline in every supported context.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Current source; browser evidence; `architecture:interaction-modality`   |
-| FR8 | `ref`, DOM, data, and event props, `xstyle`, `className`, and `style` reach or compose on the `nav`; `data-testid` reaches it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Current source and tests; `architecture:public-component-api` INV5–INV8 |
-
-### Allowed variation
-
-- **AV1 — Headings.** Heading count, labels, levels, and the current heading
-  vary without changing the anatomy.
-- **AV2 — Density.** Default and compact density use the same anatomy and
-  targets.
-
-### Representative states
-
-| State                  | Required invariant                                                                                                               | Allowed variation |
-| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
-| Uncontrolled scrolling | The current heading follows scroll; `onActiveIdChange` reports it.                                                               | Offset.           |
-| Controlled             | `activeId` decides; clicks report through `onActiveIdChange`.                                                                    | —                 |
-| Keyboard               | Tab visits each link; Enter and Space navigate; no arrow, Home, or End movement (today a single roving stop with them, FR3 gap). | —                 |
-| Missing target         | A click or Enter behaves as a plain link; Space does nothing; no callbacks.                                                      | —                 |
-| Empty                  | Track and indicator render; no links and so no tab stop.                                                                         | —                 |
-
-### Transformation and precedence order
-
-- **ORD1 — Current heading.** Controlled `activeId` → scroll position.
-- **ORD2 — Activation.** Modifier chord, or a click or Enter on a missing
-  target → browser default; Space on a missing target → nothing; otherwise push
-  the hash, scroll, and fire the callbacks.
-
-### Performance and resources
-
-- **PR1 — Scroll tracking.** While uncontrolled, Outline listens to scroll on
-  its scroll root while mounted; navigation waits for scroll end with a timeout
-  fallback; Outline installs the shared press controller.
-
-## Accessibility contract
-
-- **AR1 — Navigation landmark.** The `nav` is named by a caller's explicit
-  `aria-label`, else by `label` or the localized default (FR1 gap), and the list
-  and items keep list semantics (WCAG 2.2 SC 1.3.1).
-- **AR2 — Current location.** The current link exposes
-  `aria-current="location"`; the indicator and track are hidden from assistive
-  technology.
-- **AR3 — Links in Tab order with real focus.** Every link takes keyboard focus
-  through the normal Tab order and keeps real DOM focus, not
-  `aria-activedescendant` (`spec:AST-020` FR15). Implementation gap: today one
-  roving Tab stop with arrow, Home, and End keys (FR3).
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                           | Representation authority | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------------------------ | ------------------------ | -------------- | ------------------ |
-| Outline          | Groups heading navigation and the indicator.                 | Current source and docs  | Supporting     | FR1                |
-| Heading link     | Navigates to one heading and carries level and active state. | Current source and docs  | Prominent      | FR2–FR4            |
-| Label            | Heading text inside its link, truncated with an ellipsis.    | Current source and docs  | Prominent      | FR1, FR2           |
-| Indicator track  | The vertical rule behind the active marker.                  | Current source and docs  | Supporting     | FR6                |
-| Active indicator | The marker aligned to the current link.                      | Current source and docs  | Supporting     | FR6                |
-
-The Label sits inside the `outline-item` target and inherits its text
-treatment. The Indicator track's target exposure is unsettled (OQ2).
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Outline": {"target": "outline"},
-  "Heading link": {"target": "outline-item"},
-  "Label": {"inherits": "outline-item"},
-  "Indicator track": {
-    "none": {
-      "reason": "unsettled: No current public target reaches this part"
-    }
-  },
-  "Active indicator": {"target": "outline-indicator"}
-}
-```
-
-## Family and system relationships
-
-- `module:Outline/parseOutlineFromMarkdown` builds `items` from markdown.
-- `architecture:interaction-modality` owns focus indication; FR7 applies it.
-- `architecture:component-theming-surface` owns target mapping, inherited
-  parts, and unsettled dispositions.
-- `architecture:public-component-api` owns caller-input routing; FR1 records
-  the `aria-label` gap and FR8 applies the rest.
-- `spec:AST-009` owns accessibility-tree evidence; the verification map names
-  its gap.
-
-## Verification map
-
-| Contract            | Verification                                                                                                                                     | Representative states                                                                                                                   | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                                                        | Audit section            |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
-| FR1, AR1            | `Outline.test.tsx` labelled-nav, default-label, class, and track tests; stable visual baselines `core-outline--basic` (neutral and probe themes) | Items; default label; track and indicator                                                                                               | A missing `nav` name, link, or indicator, or a lost `outline` class, fails; a changed default outline comes back changed for review. Gap: the track test matches any `aria-hidden` element, so a missing track passes; no test covers the Label wrapper or its truncation, or a caller `aria-label`; and no accessibility-tree check proves the landmark name (`spec:AST-009` FR3).                                                                    | `audit:Outline/a11y`     |
-| FR2, AR2            | `Outline.test.tsx` controlled `aria-current`, item class, and active-anchor tests                                                                | Controlled current; active ordering                                                                                                     | A missing `aria-current`, `outline-item` class, active class, or `data-level`, or an active link after the indicator, fails. Gap: the level indents have no unit check.                                                                                                                                                                                                                                                                                | `audit:Outline/theming`  |
-| FR3, AR3            | `Outline.test.tsx` keyboard suite                                                                                                                | One tab stop; real focus; seat on current; follow current; no yank; arrows; Home and End; Tab; one and zero items                       | More than one tab stop, `aria-activedescendant` use, a tab stop off the current heading, a stop that moves while focus is inside, or a broken arrow, Home, End, or Tab path fails. Known gap: these tests pin today's single roving stop and arrow keys, the FR3 gap, rather than the per-link Tab order FR3 requires; no test covers that order.                                                                                                      | `audit:Outline/keyboard` |
-| FR4, ORD2           | `Outline.test.tsx` navigate-callback and scroll-scoping suites                                                                                   | Click, Enter, Space; settle; timeout; double settle; interruption; missing target; modifier; `hasScrollOnClick={false}`; offset landing | A navigation that does not scroll, a callback that fires zero or twice, or a missing target or modifier chord that is intercepted fails. No test covers where focus goes after navigating. No test covers the reduced-motion navigation scroll. No test covers a second navigation ending the first, `onNavigateEnd` not firing after an unmount mid-scroll, or Space on a missing target. No test checks the hash push after a successful navigation. | `audit:Outline/behavior` |
-| FR5, ORD1           | `Outline.test.tsx` scroll-tracking, controlled, offset, scroll-margin, and scoped-container tests                                                | Uncontrolled scroll; controlled API; offset; scroll margin; container; keyboard and own scroll                                          | A current heading that ignores the offset or scroll margin, tracks the wrong container, or treats keyboard focus or its own scroll as manual fails. No test dispatches a `scroll` event, so the scroll-event path of tracking has no check.                                                                                                                                                                                                            | `audit:Outline/behavior` |
-| FR6                 | `Outline.test.tsx` indicator tests                                                                                                               | Indicator present; active anchor order                                                                                                  | A missing indicator fails (a missing track does not; see FR1). Gap: indicator position, size, color, and motion have no automated check beyond the baselines. No test covers the reduced-motion outcome.                                                                                                                                                                                                                                               | `audit:Outline/design`   |
-| FR7                 | `OutlineFocus.a11y.chromium.spec.ts`                                                                                                             | Every supported context                                                                                                                 | A focused link without a visible outline fails in Chromium.                                                                                                                                                                                                                                                                                                                                                                                            | `audit:Outline/a11y`     |
-| FR8                 | `Outline.test.tsx` class tests; source review                                                                                                    | Caller class                                                                                                                            | Gap: no test covers `ref`, DOM props, `style`, or the `xstyle` merge order.                                                                                                                                                                                                                                                                                                                                                                            | `audit:Outline/api`      |
-| PR1                 | `Outline.test.tsx` settle tests; source review                                                                                                   | Settle and fallback                                                                                                                     | A callback after the fallback and scroll end both elapse fails. Gap: listener cleanup has no check.                                                                                                                                                                                                                                                                                                                                                    | `audit:Outline/behavior` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                    | Canonical anatomy and current targets                                                                                                   | Missing, extra, or stale mappings fail repository validation.                                                                                                                                                                                                                                                                                                                                                                                          | `audit:Outline/theming`  |
-
-## Decision log
-
-None recorded. The record describes shipped behavior.
-
-## Open questions
-
-- **OQ1 — Should Outline adopt a named `spec:AST-020` FR15 exception: one Tab
-  stop for a long heading list, with arrow, Home, and End movement?**
-  (`human-api`) Adopting it would make today's model the contract: a long
-  heading list costs one Tab stop, and keyboard users move inside it with the
-  arrow keys, which Tab-only screen reader users may not discover. Without it,
-  FR3's per-link Tab order stands and today's model stays the gap.
-- **OQ2 — Should Indicator track gain a stable public theming target?**
-  (`human-api`) Target exposure is unsettled; the current lack of reachability
-  does not decide the answer.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables/examples, current audit
-results, implementation steps, or system rules. It links to their owners.

package/src/Outline/modules/parseOutlineFromMarkdown.spec.md

@@ -1,150 +0,0 @@
----
-schema_version: 3
-template_version: 1
-kind: module
-id: module:Outline/parseOutlineFromMarkdown
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-03
-owners: [cixzhang]
-review_triggers: [public-api, behavior]
-verified_by: [packages/core/src/Outline/parseOutlineFromMarkdown.test.ts]
-parent_component: component:Outline
-references:
-  [
-    architecture:public-component-api,
-    component:Markdown,
-    module:Markdown/headingLinks,
-    spec:AST-036,
-  ]
----
-
-# parseOutlineFromMarkdown module contract
-
-## Intent
-
-`parseOutlineFromMarkdown` and `useOutlineFromMarkdown` derive same-document
-heading navigation from the same Markdown parse configuration, ordered immutable
-transforms, text projection, and collision allocator used by the rendered document.
-This focused module owns that utility behavior without deciding the Outline
-component's anatomy or theming.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: additive parser options; calls without plugins preserve
-  released labels, levels, IDs, and return types
-- Migration decision: `spec:AST-036`
-
-## Ownership boundary
-
-**Owns**
-
-- Deriving ordered `OutlineItem` values from Markdown headings.
-- Accepting the same parser-affecting options and ordered plugin list as Markdown.
-- Applying the same validated immutable transforms before selecting headings.
-- Using the same extension text projection and collision-safe slug allocation as
-  Markdown heading rendering.
-
-**Does not own / non-goals**
-
-- Outline component structure, active state, targets, layout, or theming.
-- Plugin rendering, block-extension navigation entries, or renderer-derived text.
-- A second parser, plugin registry, or independent heading-ID policy.
-
-## Public API and concepts
-
-`parseOutlineFromMarkdown(source, options?)` performs direct derivation.
-`useOutlineFromMarkdown(source, options?)` memoizes the same derivation for React
-callers. `options.plugins` uses the canonical opaque Markdown plugin entries. The
-same ordered transforms run before heading selection; inline extension-node `toText`
-projections then contribute to heading labels and IDs. When the same first-party
-entry is installed on both surfaces, this module consumes the projection owned by
-`module:Markdown/headingLinks`; it does not copy that module's options or behavior.
-
-## Behavioral contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                             | Basis                           | Acceptance and implementation state |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------------- |
-| FR1 | Both utilities accept the same Markdown parser options and ordered plugin list as the rendered Markdown document.                                                                                                                                                                                                                                                                     | `spec:AST-036` FR13, FR16       | current implementation              |
-| FR2 | Both utilities apply the same validated immutable transforms before selecting headings, without allowing renderer output to affect identity.                                                                                                                                                                                                                                          | `spec:AST-036` FR13, FR16       | current implementation              |
-| FR3 | Plugin-enabled labels and IDs use the same extension `toText` projection, slugger, and cross-base collision allocator as Markdown, producing unique matching targets.                                                                                                                                                                                                                 | `spec:AST-036` FR16             | current implementation              |
-| FR4 | An extension node never creates an Outline entry of its own. Outline selection stays root-only; when `module:Markdown/headingLinks` is installed, this module consumes its separately owned identity projection without restating or modifying that contract. A container never restarts or independently scopes the selected projection. It never emits nested Outline entries here. | `module:Markdown/headingLinks`  | current implementation              |
-| FR5 | Omitting plugins and passing an empty list preserve released heading selection, labels, levels, IDs, return type, and memoization behavior.                                                                                                                                                                                                                                           | `spec:AST-036` FR2              | current implementation              |
-| FR6 | The hook memoizes against source and every parse-affecting or transform-affecting option so changed configuration cannot return stale headings.                                                                                                                                                                                                                                       | `component:Markdown` FR15–FR16  | current implementation              |
-| FR7 | A transform that removes a heading removes its Outline entry, and a transform that inserts a synthetic heading adds one, in both surfaces identically. Source-backed heading depth cannot change, so an entry's level always matches the rendered heading.                                                                                                                            | `spec:AST-036` FR26             | current implementation              |
-| FR8 | When a plugin fails, derivation uses the same last valid root the rendered document uses, so labels, levels, and IDs still agree. Failures are reported through the shared diagnostic channel; this module adds no failure mode, fallback, or throw of its own.                                                                                                                       | `spec:AST-036` FR12, FR29       | current implementation              |
-| FR9 | Derivation runs on the canonical tree through the shared parse path and requires no DOM, renderer, client boundary, or second parser. Because transforms are idempotent under streaming, an outline derived from a growing source prefix converges rather than oscillates.                                                                                                            | `spec:AST-036` FR32, FR33, FR36 | current implementation              |
-
-### Transformation and precedence order
-
-Markdown parse configuration → ordered immutable transforms → heading nodes →
-shared perceivable-text projection → selected heading projection → root-heading
-selection → Outline items.
-
-### Performance and resources
-
-- The hook recomputes only when source or parser/transform configuration changes.
-- Renderer output does not enter heading identity.
-- No DOM, renderer mount, registry, Remark runtime, or optional plugin resource is
-  required.
-
-## Accessibility contract
-
-Each derived label is the same perceivable heading text used for Markdown identity,
-and each derived ID targets the matching rendered heading. This module adds no
-interaction or ARIA behavior; the Outline component owns navigation presentation.
-
-## Design relationships
-
-No visual representation is owned by this parser utility.
-
-## Parent and system relationships
-
-- `component:Markdown` owns aggregate parsing, heading rendering, and the generic
-  shared-projection invocation seam.
-- `module:Markdown/headingLinks` owns its optional projection; this module consumes
-  it while retaining root-only Outline selection.
-- `spec:AST-036` owns the canonical plugin protocol and cross-surface parity.
-- `component:Outline` owns presentation, anatomy, and theming.
-
-## Verification map
-
-| Contract | Verification                                                                                        | Representative states                                                                                                              | Mutation or failure expectation                                                                                                                           |
-| -------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1–FR6  | Outline parser tests, plugin transform parity tests, heading-links module tests, and Core typecheck | omitted/empty/installed plugin lists; selected projection changes; transformed and formatted root headings; root/nested containers | A transform is skipped, a root label/ID diverges from Markdown, nested headings enter Outline, selected projection goes stale, or default output changes. |
-| FR7–FR9  | Heading insert/remove parity, failure parity, and streaming derivation                              | headings removed with/without sections; inserted synthetic headings; failing transform; growing source prefix; server derivation   | Outline/document disagreement, divergent fallback, a throw, stale IDs, or streamed oscillation.                                                           |
-
-## Decision log
-
-### DEC-1 — Markdown owns heading identity; Outline projects it
-
-**Reference:** `module:Outline/parseOutlineFromMarkdown/DEC-1`
-**Decider:** cixzhang, 2026-09-15
-
-Outline utilities consume Markdown's parse configuration, ordered transforms, text
-projection, and collision allocator rather than defining a second heading-identity
-system. This keeps labels and link targets aligned without coupling plugin renderer
-output to navigation identity.
-
-### DEC-2 — One traversal survives containers and heading edits
-
-**Reference:** `module:Outline/parseOutlineFromMarkdown/DEC-2`
-**Decider:** cixzhang, 2026-09-16
-
-Extension containers hold ordinary Markdown but do not select a second identity system. Markdown and this module consume the same projection chosen by the installed plugin list, so Outline never links to a root heading Markdown did not identify. The Outline result remains root-only, and an extension node is never an Outline entry.
-
-Transforms may remove and insert headings, so Outline follows the rendered document rather than source: a dropped root heading disappears, an inserted root heading appears, and immutable source-backed depth keeps levels aligned. Both surfaces run the same pipeline rather than independent rules.
-
-Rejected: a container-only traversal exception; extension nodes as Outline entries; source-only derivation; module-local plugin failure fallback.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate plugin protocol details, Markdown parser mechanics,
-consumer examples, or the Outline component's anatomy and theming contract.