@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/Markdown/modules/softBreaks.spec.md

@@ -1,137 +0,0 @@
----
-schema_version: 3
-template_version: 2
-kind: module
-id: module:Markdown/softBreaks
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-09-22
-owners: [cixzhang]
-review_triggers: [public-api, behavior]
-verified_by:
-  [
-    packages/core/src/Markdown/plugins/softBreaks.test.tsx,
-    apps/storybook/.storybook/Markdown.remarkPlugins.test.ts,
-    apps/sandbox/src/app/(fullscreen)/pages/markdown-perf/benchmarkProfiles.test.ts,
-  ]
-parent_component: component:Markdown
-references: [spec:AST-036/DEC-1, spec:AST-036/DEC-11]
----
-
-# Markdown soft-breaks module contract
-
-## Contract at a glance
-
-| Area            | Contract                                                                                                                                                                                                                           |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | `markdownSoftBreaksPlugin` is one durable first-party plugin value exported from `@astryxdesign/core/Markdown/plugins`.                                                                                                            |
-| Behavior        | Each soft LF, CRLF, or lone CR line ending in eligible phrasing becomes a canonical Markdown `break` node, matching the real plugin through Astryx's adapter.                                                                      |
-| End-user impact | Readers see author-intended line wrapping without requiring two trailing spaces, while protected content remains literal and copyable.                                                                                             |
-| Builder impact  | Builders opt in by adding one value to `plugins`; there are no settings or renderer slots.                                                                                                                                         |
-| Compatibility   | Additive and opt-in; omitted and empty plugin lists preserve the released parser, DOM, accessibility, and streaming behavior.                                                                                                      |
-| Review checks   | Reject missing link-label parity with `remark-breaks`, matching inside code, images, citations, math, or extension nodes; source preprocessing; a custom renderer; or behavior that diverges between complete and streaming input. |
-| Governing rules | [`spec:AST-036` FR1–FR17, FR21–FR24, FR36, FR38, FR40](../../../../../docs/specs/AST-036/spec.md); [`component:Markdown` FR12–FR16, FR21](../Markdown.spec.md).                                                                    |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Builders who receive prose with meaningful single line endings should be able to
-render those endings as breaks without rewriting source or changing Markdown's
-parser. The plugin is deliberately fixed: one stable behavior makes it easy to
-recognize, benchmark, and replace with an adapted `remark-breaks` transform.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: additive and opt-in
-- Migration decision: `spec:AST-036/DEC-11`
-
-## Ownership boundary
-
-**Owns**
-
-- The exported plugin value and its stable plugin name.
-- Converting eligible soft line endings to built-in `break` nodes.
-- Complete, streaming, SSR, Storybook parity, and browser-performance evidence.
-
-**Does not own / non-goals**
-
-- Parsing or rendering a new extension node.
-- Opaque line endings inside inline/fenced code, images, citations, math, or extension nodes.
-- CSS white-space behavior or source preprocessing.
-- Hard breaks already authored with Markdown's two-space or backslash syntax.
-
-## Public API and concepts
-
-| Concept                    | Closed values or states                                          | Meaning                                                               | Default             | Owner                        | Stability |
-| -------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------- | ---------------------------- | --------- |
-| `markdownSoftBreaksPlugin` | one `MarkdownPluginEntry<never>`                                 | Converts eligible soft endings through the public transform protocol. | absent              | `module:Markdown/softBreaks` | stable    |
-| Eligible ending            | LF, CRLF, or lone CR inside phrasing text, including link labels | Replaced by one built-in `break` node.                                | literal soft ending | `module:Markdown/softBreaks` | stable    |
-| Opaque context             | code, image, citation, math, or extension content                | Remains byte-for-byte content rather than becoming a break.           | protected           | `component:Markdown`         | stable    |
-
-## Behavioral contract
-
-| ID  | Invariant                                                                                                                                   | Basis                     |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
-| FR1 | Every eligible LF, CRLF, or lone CR ending becomes exactly one canonical `break` node.                                                      | `spec:AST-036` FR1, FR9   |
-| FR2 | The plugin uses only `createMarkdownPlugin()` and the public immutable transform contract and introduces no extension node or renderer.     | `spec:AST-036` FR1, FR40  |
-| FR3 | Link-label prose transforms for `remark-breaks` parity; inline and fenced code, images, citations, math, and extension nodes remain opaque. | `spec:AST-036` FR7, FR15  |
-| FR4 | Omitted or empty plugin lists preserve the released soft-ending behavior.                                                                   | `spec:AST-036` FR2, FR3   |
-| FR5 | Every streamed prefix is deterministic and the final streamed tree equals complete parsing of the same source.                              | `spec:AST-036` FR13, FR36 |
-| FR6 | Source with no newline returns the original tree without allocating replacement nodes.                                                      | `spec:AST-036` FR21, FR23 |
-| FR7 | Native output matches an adapted `remark-breaks` transform for the supported Astryx subset.                                                 | `spec:AST-036` FR20, FR40 |
-
-## Accessibility contract
-
-- **AR1 — reading order stays source order.** A break adds no focus target and
-  does not move text between semantic containers.
-- **AR2 — link meaning stays intact.** Link destinations and accessible names
-  retain their source text while visual line breaks match `remark-breaks`.
-
-## Design relationships
-
-Soft breaks add no anatomy or styling. Existing Markdown paragraph and break
-rendering remains authoritative.
-
-## Parent and system relationships
-
-- `component:Markdown` owns parsing, protected contexts, rendering, and fallback.
-- `spec:AST-036` owns the plugin protocol and first-party parity requirement.
-- `module:Markdown/remark` owns the adapted `remark-breaks` comparison path.
-
-## Content boundary
-
-This module recognizes only LF, CRLF, and lone CR characters already present in
-eligible canonical phrasing text. It does not inspect or persist document content
-outside the transform invocation.
-
-## Verification map
-
-| Contract    | Verification                                                               | Representative states                                                                                  | Failure expectation                                                                                    |
-| ----------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
-| FR1–FR4     | `softBreaks.test.tsx` AST and SSR fixtures                                 | LF, CRLF, lone CR, prose, emphasis, multiline link, inline code, fence, authored hard break, no plugin | Extra, missing, opaque-context, doubled-hard-break, or default-path break fails.                       |
-| FR5         | `softBreaks.test.tsx` prefix sequence                                      | before, at, and after a streamed line ending                                                           | Oscillation or final mismatch fails.                                                                   |
-| FR6         | `softBreaks.test.tsx` identity coverage and Markdown Perf no-claim profile | no newline                                                                                             | Allocating a changed tree for absent source fails.                                                     |
-| FR7         | Storybook native/adapted parity story                                      | prose, emphasis, multiline link, protected code                                                        | DOM divergence fails.                                                                                  |
-| Performance | Markdown Performance paired empty/plugin runs for the soft-break workload  | no, sparse, and dense claims; complete and streaming modes                                             | Different source between a pair, missing baseline delta, or missing density control blocks acceptance. |
-
-## Decision log
-
-### DEC-1 — Ship one fixed plugin value
-
-**Reference:** `module:Markdown/softBreaks/DEC-1`
-**Decider:** `cixzhang`, `2026-09-22`
-
-Soft breaks have one established meaning and need no product-specific data or
-presentation. A fixed value keeps the API smaller than a factory whose options
-would not change behavior.
-
-Rejected: source preprocessing; a boolean on Markdown; a renderer callback; a
-factory with no meaningful configuration.
-
-## Open questions
-
-None.

package/src/Markdown/modules/sourceLines.spec.md

@@ -1,162 +0,0 @@
----
-schema_version: 3
-template_version: 4
-kind: module
-id: module:Markdown/sourceLines
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-09
-owners: [cixzhang]
-review_triggers: [public-api, behavior]
-verified_by: [packages/core/src/Markdown/plugins/sourceLines.test.tsx]
-parent_component: component:Markdown
-references: [spec:AST-036/DEC-1, spec:AST-036/DEC-11, component:Markdown/DEC-2]
----
-
-# Markdown source-lines module contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                   |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `markdownSourceLinesPlugin` is one fixed first-party plugin value exported from `@astryxdesign/core/Markdown/plugins`. With it installed, `components` block renderers receive an optional `sourceLines` prop.             |
-| Behavior                | Each block Markdown renders, nested blocks included, carries `data-source-line` and `data-source-line-end`: the 1-based, inclusive source lines it was parsed from. Inline elements carry none.                            |
-| End-user impact         | Readers of a host's line-addressed features (find, highlights, review comments) get results that point at the exact Markdown lines, including inside lists and quotes. Without the plugin nothing changes.                 |
-| Builder impact          | Builders opt in by adding one value to `plugins`. A builder with a custom block renderer places the received `sourceLines` on its own element; a plugin block renderer reads lines from its node's `position`.             |
-| Compatibility/readiness | Additive and opt-in. Omitted or empty plugin lists keep the released AST, DOM, parse cost, and streaming reuse.                                                                                                            |
-| Review checks           | Reject a Markdown prop, stamps on inline elements, line work without the plugin, a wrapper element Markdown adds around custom or plugin output, lines that disagree between full and streaming parses, or offsets in DOM. |
-| Governing rules         | [`spec:AST-036` FR3, FR9, FR15, FR40](../../../../../docs/specs/AST-036/spec.md); [`component:Markdown` FR3, FR12, FR15](../Markdown.spec.md).                                                                             |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-A host that maps something in the rendered document back to its Markdown source
-(a selection, a search hit, a diff hunk, a comment anchor) needs to know which
-source lines each rendered block came from. Lines are the unit because diffs,
-blame, and edits address lines, and because a block nested in a list item or a
-quote has lines but no contiguous character range. The module gives every block
-Markdown renders its lines, so a host builds those features as plugins and host
-code instead of forking the renderer.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: additive and opt-in
-- Migration decision: `module:Markdown/sourceLines/DEC-1`
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The exported plugin value and its stable plugin name.
-- The `data-source-line` and `data-source-line-end` attributes on blocks
-  Markdown renders, and the `sourceLines` prop given to `components` block
-  renderers, while the plugin is installed.
-- Line numbers on the canonical `position` of source-backed block nodes,
-  nested blocks included, while the plugin is installed.
-- Complete, streaming, and server-render evidence for those lines.
-
-**Does not own / non-goals**
-
-- Aggregate plugin protocol, ordering, and composition — owned by
-  `component:Markdown` and `spec:AST-036`.
-- Mapping a DOM selection or search hit to lines, highlighting, or any other
-  host feature built on the stamps — owned by the product callsite.
-- Line or column positions on inline nodes, table rows, or table cells.
-- Character offsets in the DOM, and the released `range` projection —
-  `parseMarkdown(source, {sourceRanges: true})` keeps its released behavior.
-- Elements a custom renderer or plugin renderer owns; Markdown adds no wrapper
-  to place stamps on them.
-
-## Public API and concepts
-
-| Concept                     | Closed values or states                                                                                                       | Meaning                                                                                  | Default | Owner                         | Stability |
-| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------- | ----------------------------- | --------- |
-| `markdownSourceLinesPlugin` | one `MarkdownPluginEntry<never>`                                                                                              | Turns on source lines for the Markdown, parser, or Outline call it is passed to.         | absent  | `module:Markdown/sourceLines` | stable    |
-| Source lines                | `{start, end}`: 1-based, inclusive line numbers into the string the parser received                                           | The lines a block's own source occupies, from its first line to its last non-blank line. | none    | `module:Markdown/sourceLines` | stable    |
-| Stamped block               | Heading, Paragraph, List item, Code block, Blockquote, Table, Divider, and block Image on the default path                    | Carries `data-source-line="<start>"` and `data-source-line-end="<end>"`.                 | none    | `module:Markdown/sourceLines` | stable    |
-| `sourceLines` prop          | `{start: number, end: number}` on the `heading`, `paragraph`, `code`, `blockquote`, `hr`, `image`, and block `math` renderers | The replaced block's source lines, for the renderer to place on its own element.         | absent  | `module:Markdown/sourceLines` | stable    |
-
-## Behavioral contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                              | Basis                        | Draft review state |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | ------------------ |
-| FR1 | With the plugin installed, every stamped block, at any nesting depth, carries `data-source-line` and `data-source-line-end` with its source lines as base-10 integers. Inline elements, table rows, and table cells carry neither attribute.                                                                                                                                                           | host line-addressed features | settled            |
-| FR2 | Line numbers count LF and CRLF line endings in the exact string the parser received, including lines a native frontmatter block occupies, so line 1 is the first line of that string.                                                                                                                                                                                                                  | `spec:AST-036` FR9           | settled            |
-| FR3 | A block's lines span from its first source line to its last non-blank source line, including its own container markers (`>`, list markers), lazy continuation lines, and a code fence's opening and closing lines.                                                                                                                                                                                     | `component:Markdown` FR23    | settled            |
-| FR4 | A supplied `components` block renderer receives `sourceLines` and owns whether and where its element carries the attributes. Markdown adds no wrapper element and does not impose the attributes on the replacement. `sourceLines` is absent for inline math (`display: 'inline'`) and for images in phrasing content, because neither is a block.                                                     | `component:Markdown` FR3     | settled            |
-| FR5 | Source-backed block nodes in the canonical tree, extension blocks and a semantic-fence proposal's node included, carry `line` on `position.start` and `position.end`, so a plugin block renderer and a transform read lines from the node.                                                                                                                                                             | `spec:AST-036` FR9           | settled            |
-| FR6 | Streaming converges to the lines a full parse of the same text yields at every chunk boundary, and a settled block keeps its lines and its rendered element as more text arrives.                                                                                                                                                                                                                      | `spec:AST-036` FR15, FR21    | settled            |
-| FR7 | Without the plugin, the canonical tree carries no `line`, the DOM carries no source-line attribute, `components` renderers receive no `sourceLines`, and parsing does no line work. With it, source lines come from the positions of the single parse Markdown already runs: the plugin adds no parse pass and no per-block re-tokenizing, and no position or line work runs when it is not installed. | `spec:AST-036` FR2, FR3      | settled            |
-| FR8 | The plugin introduces no extension node, renderer, element, theme target, or source change, and composes with every other plugin in any order.                                                                                                                                                                                                                                                         | `spec:AST-036` FR40, DEC-11  | settled            |
-
-### Transformation and precedence order
-
-- **ORD1 — Lines are parse output.** Core authors them while parsing;
-  transforms observe the lines on source-backed nodes and cannot
-  author, shift, or forge them (`spec:AST-036` FR11). A node a transform creates
-  has no position and its rendered block carries no stamp.
-
-### Performance and resources
-
-- **PR1 — Bounded cost.** Line work is recorded during the existing parse and
-  stays within `spec:AST-036` FR23's first-party helper budget for one helper, in
-  complete and streaming modes. Streaming with the plugin reuses settled blocks
-  exactly as streaming without it.
-
-## Accessibility contract
-
-- **AR1 — Data attributes only.** The stamps add no role, name, focus target, or
-  text, and do not change reading order.
-
-## Design relationships
-
-The module adds no anatomy, styling, or theme target.
-
-## Parent and system relationships
-
-- `component:Markdown` owns parsing, rendering, `components` seams, and fallback.
-- `spec:AST-036` owns the plugin protocol, canonical `position`, and first-party
-  plugin rules; DEC-11 permits the internal seam this module uses because this
-  record owns the result and the empty pipeline is unchanged.
-
-## Verification map
-
-| Contract    | Verification                                        | Representative states                                                                                                | Mutation or failure expectation                                                                                        |
-| ----------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| FR1–FR3     | `sourceLines.test.tsx` DOM and AST fixtures         | every stamped block kind; nested list and quote blocks; lazy continuation; CRLF; frontmatter; inline emphasis; table | A missing, shifted, or inline stamp fails.                                                                             |
-| FR4–FR5     | `sourceLines.test.tsx` renderer fixtures            | each `components` block renderer; a plugin block renderer; a claimed semantic fence                                  | A renderer without `sourceLines`, a Markdown-added wrapper, or a node without lines fails.                             |
-| FR6         | `sourceLines.test.tsx` every-character streaming    | top-level, nested, and fenced blocks split at each character                                                         | A streamed line differing from the full parse, or a remounted settled block, fails.                                    |
-| FR7–FR8     | `sourceLines.test.tsx` and existing Markdown suites | plugin omitted, empty list, plugin with heading links and soft breaks                                                | Any line, attribute, or prop without the plugin, a changed default DOM, or a second parse pass with the plugin, fails. |
-| Performance | Markdown performance paired empty/plugin runs       | complete and streaming modes                                                                                         | Exceeding the one-helper budget or losing settled-block reuse blocks acceptance.                                       |
-
-## Decision log
-
-### DEC-1 — Source lines ship as one fixed plugin value
-
-**Reference:** `module:Markdown/sourceLines/DEC-1`
-**Decider:** `cixzhang`, `2026-10-09`
-
-A host feature that needs source lines installs a plugin, as every other
-Markdown feature does, and the plugin has one meaning with nothing to
-configure. Markdown stamps the blocks it renders and hands the lines to the
-renderers that replace its blocks, because those are the only elements it owns;
-a host or plugin renderer places them on its own element. Lines rather than
-offsets reach the DOM because nested blocks have no contiguous range.
-
-Rejected: a boolean prop on Markdown; giving every renderer positions on the default path, which costs every caller; a plugin DOM hook, which `spec:AST-036` excludes.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This record does not duplicate consumer signatures or examples, parent parsing or
-rendering mechanics, host features built on the stamps, or current audit results.
-It links to their canonical owners.

package/src/MetadataList/MetadataList.spec.md

@@ -1,187 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:MetadataList
-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]
-verified_by:
-  [
-    packages/core/src/MetadataList/MetadataList.test.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-    .github/visual-baseline/manifest.json,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [architecture:component-theming-surface, architecture:public-component-api]
-contributing: []
-system_specs: [spec:AST-009]
----
-
-# MetadataList component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                           |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `children` (MetadataListItem entries), `columns`, `label` (`position`, `width`), `maxNumOfItems`, `orientation`, `title`, root `BaseProps`, `ref`. |
-| Behavior                | A description list of label and value pairs in one column, several columns, or a wrapping row, with an optional show more and show less toggle.    |
-| End-user impact         | People scan labelled facts in a predictable grid, and assistive technology reads each label with its value.                                        |
-| Builder impact          | None; the record describes shipped behavior.                                                                                                       |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes.                                                                         |
-| Review checks           | Reject a list that is not a `dl`, a toggle without its expanded state or controlled list, an unlocalized toggle label, or overridable reflection.  |
-| Governing rules         | `architecture:public-component-api` INV5–INV8; `architecture:component-theming-surface`; WCAG 2.2 SC 1.3.1 and 4.1.2.                              |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-MetadataList presents read-only key and value facts as a description list. It
-owns the arrangement of its entries, the label placement it passes to them, and
-the optional disclosure that collapses a long list; callers own the facts.
-
-Consumer syntax and examples belong in `MetadataList.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes` — one column, vertical, labels at the
-  start, no collapse.
-- Compatibility class: records shipped behavior; no public prop, default, DOM,
-  target, or styling output changes.
-- Controlled/uncontrolled behavior: the expanded state of the disclosure is
-  uncontrolled.
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The root, its `metadata-list` target, the optional title, the `dl`, and
-  the show more and show less toggle.
-- Column layout, orientation, and the label position and width its entries
-  read.
-
-**Does not own / non-goals**
-
-- Each entry's label and value markup — owned by `component:MetadataListItem`.
-- The facts shown and their formatting — owned by the caller.
-- Editable fields — owned by form components.
-
-## Public concepts
-
-| Concept        | Closed values or states            | Meaning                                                                                                   | Availability by variant/orientation/state            | Default                                                  | Owner                    | Stability | Invalid-value behavior                                              |
-| -------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------- | ------------------------ | --------- | ------------------------------------------------------------------- |
-| Columns        | `single`; `multi`; positive number | One column, auto-filling columns, or exactly N columns.                                                   | Vertical only                                        | `single`                                                 | `component:MetadataList` | Stable    | 1 acts as `single`; a number below 1 falls to the `multi` template. |
-| Orientation    | `vertical`; `horizontal`           | A grid of entries, or one wrapping row of stacked entries.                                                | Always                                               | `vertical`                                               | `component:MetadataList` | Stable    | Closed union; rejected by types.                                    |
-| Label position | `start`; `top`                     | Label beside its value, or stacked above it.                                                              | Vertical only                                        | `top` for `multi` or a number above 1, otherwise `start` | `component:MetadataList` | Stable    | Horizontal always stacks.                                           |
-| Label width    | number (px); CSS length string     | The label track's width; on `multi` it replaces the auto-fill grid with one label and value pair per row. | Vertical with start labels, at one column or `multi` | content width                                            | `component:MetadataList` | Stable    | —                                                                   |
-| Collapse       | positive number; unset             | Entries shown before a show more toggle.                                                                  | Vertical only                                        | unset                                                    | `component:MetadataList` | Stable    | Ignored when horizontal.                                            |
-| Title          | ReactNode; unset                   | Content shown above the list.                                                                             | Always                                               | unset                                                    | `component:MetadataList` | Stable    | —                                                                   |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Basis                                                                   |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| FR1 | MetadataList renders a root `div` carrying the `metadata-list` target, which reflects `columns` and `orientation`, holding the optional title, a `dl` of the entries, and, when the list collapses, a toggle button. The title renders above the list with a `--spacing-3` gap as plain content; it is not a heading and does not name the list.                                                                                                                                                                                                                                                                                                                                          | Current source and tests                                                |
-| FR2 | Vertical, one column with start labels is a two-track grid (label `auto`, value `minmax(0, 1fr)`) with `--spacing-2` row and `--spacing-4` column gaps and baseline alignment; a label `width` replaces the label track, and on `multi` with start labels a `width` replaces the auto-fill grid with the same two tracks. One column with top labels is a single track with a `--spacing-3` gap. `multi` auto-fills 280px-minimum columns with a `--spacing-4` gap. A number N above 1 makes exactly N columns, each `1fr` with top labels or a label `auto` and value `minmax(0, 1fr)` pair with start labels, ignoring a label `width`; a number below 1 falls to the `multi` template. | Current source and tests                                                |
-| FR3 | Label position defaults to `top` for `multi` or a number above 1 and to `start` otherwise (including a number below 1), and a caller `position` wins. Horizontal orientation lays entries in one wrapping row with a `--spacing-4` gap, stacks every label above its value, and ignores `columns` and `maxNumOfItems`.                                                                                                                                                                                                                                                                                                                                                                    | Current source and tests                                                |
-| FR4 | When vertical and the entries exceed `maxNumOfItems`, only the first `maxNumOfItems` render, followed by a native button labelled with the localized "Show more", with `aria-expanded="false"` and `aria-controls` naming the `dl`. Activating it renders every entry and switches to "Show less" with `aria-expanded="true"`; activating it again collapses. Focus stays on the button.                                                                                                                                                                                                                                                                                                  | Current source and tests; `architecture:public-component-api`           |
-| FR5 | `ref`, DOM, data, ARIA, and event props, `xstyle`, `className`, and `style` reach or compose on the root; the reflected `data-columns` and `data-orientation` replace a caller's values.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Current source and tests; `architecture:public-component-api` INV5–INV8 |
-
-### Allowed variation
-
-- **AV1 — Facts.** Any MetadataListItem content may fill the list.
-- **AV2 — Title.** Any ReactNode, including a caller's heading, may be the
-  title.
-
-### Representative states
-
-| State      | Required invariant                                                   | Allowed variation |
-| ---------- | -------------------------------------------------------------------- | ----------------- |
-| One column | Label and value tracks; labels at the start.                         | Label width.      |
-| N columns  | Exactly N columns; labels on top by default.                         | N.                |
-| Horizontal | One wrapping row; labels stacked; no toggle.                         | —                 |
-| Collapsed  | First `maxNumOfItems` entries; "Show more"; `aria-expanded="false"`. | Locale.           |
-| Expanded   | Every entry; "Show less"; `aria-expanded="true"`.                    | Locale.           |
-
-### Transformation and precedence order
-
-- **ORD1 — Label position.** Horizontal → top; otherwise caller `position` →
-  `top` for `multi` or a number above 1 → `start`.
-- **ORD2 — Columns.** Horizontal → no grid; N above 1 → exactly N columns (N tracks with top labels, N label and value pairs with start labels); a
-  start-label `width` → that label track; otherwise the static template.
-
-### Performance and resources
-
-- **PR1 — Local state only.** MetadataList holds one expanded flag and one
-  generated id, and adds no listener, observer, timer, or measurement.
-
-## Accessibility contract
-
-- **AR1 — Description list semantics.** Entries are `dt` and `dd` pairs inside
-  one `dl`, so assistive technology reads each label with its value
-  (WCAG 2.2 SC 1.3.1).
-- **AR2 — Disclosure state.** The toggle is a native button exposing its
-  expanded state and the list it controls (WCAG 2.2 SC 4.1.2).
-- **AR3 — Localized labels.** The toggle's text comes from the translation
-  catalog, never assembled in the component.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                          | Representation authority     | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------- | ---------------------------- | -------------- | ------------------ |
-| Title            | Optional content above the list.            | Current source and docs      | Supporting     | FR1                |
-| Label            | The key of each entry.                      | `component:MetadataListItem` | Supporting     | FR2, FR3           |
-| Metadata         | The value of each entry.                    | `component:MetadataListItem` | Prominent      | FR2, FR3           |
-| Disclosure       | Show more or show less in the accent color. | Current source and docs      | Supporting     | FR4                |
-
-Theming: the root carries the `metadata-list` target, which reflects `columns`
-and `orientation`, and each entry carries the `metadata-list-item` target
-(`component:MetadataListItem`). `MetadataList.doc.mjs` names no root anatomy
-part for the `metadata-list` target, so no anatomy-theming block is declared
-here; the Title, value cell, and Disclosure carry no target.
-
-## Family and system relationships
-
-- `component:MetadataListItem` owns entry markup and reads the label position
-  this record resolves.
-- `architecture:component-theming-surface` owns target and anatomy mapping.
-- `architecture:public-component-api` owns caller-input routing; FR5 applies
-  it.
-- `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        | `MetadataList.test.tsx` description-list, `dl`, and title tests; stable visual baselines `core-metadatalist--basic` (neutral and probe themes) | Items; title                                               | A missing `dl`, `dt`, or `dd`, or a missing title, fails; a changed default layout comes back changed for review. Gap: no accessibility-tree check proves the term and definition pairing (`spec:AST-009` FR3).                                                                                                                   | `audit:MetadataList/a11y`     |
-| FR2, ORD2       | `MetadataList.test.tsx` numeric-column and label-width tests                                                                                   | N columns with top and start labels; `multi`; custom width | A wrong inline grid template for N columns or a label width, or a `repeat(` inline template for `multi`, fails. Gap: the static one-column and `multi` templates and the gaps have no unit check beyond the default baseline. No test covers a width beside N columns with start labels, a width on `multi`, or a number below 1. | `audit:MetadataList/layout`   |
-| FR3, ORD1       | `MetadataList.test.tsx` orientation and default-position tests                                                                                 | Horizontal; omitted position; `columns={2}`                | A horizontal list without stacked labels or with a toggle, or a wrong default position, fails. No test covers `multi`'s top-label default or a number below 1's start-label default.                                                                                                                                              | `audit:MetadataList/layout`   |
-| FR4, AR2, AR3   | `MetadataList.test.tsx` show more, toggle, and localization tests                                                                              | Collapsed; expanded; French catalog                        | A missing toggle, hidden entries that render, a toggle that does not expand and collapse, or English text under a French catalog fails. Gap: no test asserts `aria-expanded`, `aria-controls`, or that focus stays on the button.                                                                                                 | `audit:MetadataList/behavior` |
-| FR5             | `MetadataList.test.tsx` root pass-through, event, and owned-metadata tests                                                                     | `aria-label`, `id`, data; click; colliding reflection      | A dropped attribute or handler, or a caller `data-columns` or `data-orientation` that wins, fails. Gap: no test covers `ref`, `className`, `style`, or the `xstyle` merge order.                                                                                                                                                  | `audit:MetadataList/api`      |
-| PR1             | Source review                                                                                                                                  | Every state                                                | Gap: no automated check fails if MetadataList adds a listener, timer, or measurement.                                                                                                                                                                                                                                             | `audit:MetadataList/behavior` |
-| Theming targets | `themingTargets.test.ts`                                                                                                                       | Root and item targets                                      | A renamed or undocumented target fails. Gap: no check fails if the side-by-side `dt` loses the `metadata-list-item` target.                                                                                                                                                                                                       | `audit:MetadataList/theming`  |
-
-## Decision log
-
-None recorded. The record describes shipped behavior.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables/examples, current audit
-results, implementation steps, or entry markup. It links to their owners.