@astryxdesign/core 0.7.4 → 0.7.5-canary.031a639

package/src/List/List.spec.md

@@ -26,22 +26,31 @@ architecture:
   [architecture:container-padding, architecture:public-component-api]
 contributing: [contributing:api-conventions]
 system_specs:
-  [spec:AST-002/DEC-1, spec:AST-002/DEC-2, spec:AST-017/FR4, spec:AST-057/FR9]
+  [
+    spec:AST-107,
+    spec:AST-002/DEC-1,
+    spec:AST-002/DEC-2,
+    spec:AST-017/FR4,
+    spec:AST-057/FR9,
+    spec:AST-094,
+    spec:AST-103,
+    spec:AST-105,
+  ]
 ---
 
 # List component contract
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                              |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | Optional `edge?: 'padded' \| 'flush' \| 'outset' \| 'bleed'`, default `'padded'`. Deprecated `edgeCompensation?: 'inline'` resolves to `'outset'`.                                                    |
-| Behavior                | One edge treatment applies to every ListItem row and decides where row content and row paint sit relative to the list's edges and the host's padding.                                                 |
-| End-user impact         | Row text can share the line of the list header and a heading above, with row paint stopping at the text, reaching into the host padding, or reaching the host edges.                                  |
-| Builder impact          | One choice per list. `flush` works anywhere; `outset` and `bleed` act only inside a host that publishes container padding.                                                                            |
-| Compatibility/readiness | Additive; omission keeps current geometry; `edgeCompensation` keeps working with a codemod to `edge`.                                                                                                 |
-| Review checks           | Reject header movement, row paint past the host's padding edge, duplicated padding values, physical-edge logic, automatic opt-in, a ListItem-level prop, or a second prop that can contradict `edge`. |
-| Governing rules         | `architecture:container-padding/INV3`, `INV9–INV11`; `spec:AST-002/DEC-1–DEC-2`; `spec:AST-017/FR4`; `spec:AST-057/FR9`.                                                                              |
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | Optional `edge?: 'padded' \| 'flush' \| 'outset' \| 'bleed'`, default `'padded'`. Deprecated `edgeCompensation?: 'inline'` resolves to `'outset'`. Optional `reorderable` takes the object `createReorderable` returns, and ListItem's `itemKey` identifies each row (`spec:AST-103`). Optional `animatedLayout` takes the handle `useAnimatedLayout` returns (`spec:AST-105`).                                                                                                                               |
+| Behavior                | One edge treatment applies to every ListItem row and decides where row content and row paint sit relative to the list's edges and the host's padding. With `reorderable`, rows reorder by dragging a handle or through reorder mode (`spec:AST-103` FR3, FR4). Under a coarse pointer a row's press follows the cell profile (`spec:AST-094` FR11); with `animatedLayout`, row updates animate (`spec:AST-105`). A row menu opens from the row's own `<li>` on the context request (FR13).                    |
+| End-user impact         | Row text can share the line of the list header and a heading above, with row paint stopping at the text, reaching into the host padding, or reaching the host edges. Touch users get a 44 px row target (FR10) and the cell press (FR11); with `animatedLayout`, row updates animate for every pointer (FR12). A row with a menu opens it by a long press, a right click, or Shift+F10, or through its More actions button (FR13).                                                                            |
+| Builder impact          | One `edge` choice per list. `flush` works anywhere; `outset` and `bleed` act only inside a host that publishes container padding. Passing an `animatedLayout` handle is one new choice, and a row menu is the other: the caller passes a ListItem's ref to `useContextMenu` (FR13), and who draws a plain row's More actions button is open (OQ2); and rows animate only with an `itemKey`; the touch target and press need none.                                                                             |
+| Compatibility/readiness | Additive; omission keeps current geometry; `edgeCompensation` keeps working with a codemod to `edge`. `reorderable` and `itemKey` are additive and stable, specified and not implemented yet; without them nothing changes. `animatedLayout` is additive and specified, not implemented yet. The touch target (FR10) and the press's compositor release (FR11) are specified, not implemented yet, and change nothing under a fine pointer. Row menus (FR13) are additive and specified, not implemented yet. |
+| Review checks           | Reject header movement, row paint past the host's padding edge, duplicated padding values, physical-edge logic, automatic opt-in, a ListItem-level edge prop, or a second prop that can contradict `edge`.                                                                                                                                                                                                                                                                                                    |
+| Governing rules         | `architecture:container-padding/INV3`, `INV9–INV11`; `spec:AST-002/DEC-1–DEC-2`; `spec:AST-017/FR4`; `spec:AST-057/FR9`. `spec:AST-103`. `spec:AST-094` FR4, FR5, FR11, FR13; `spec:AST-105` FR1–FR5. `spec:AST-107` FR8 (row menus).                                                                                                                                                                                                                                                                         |
 
 This table is a review projection; the body below is authoritative.
 
@@ -82,6 +91,12 @@ Consumer migration instructions belong in consumer docs and release notes.
 - Keeping the optional header in place for every treatment.
 - The relationship between row geometry and Item's density- and theme-aware
   inline inset.
+- Its rows' 44 px touch target under a coarse pointer (FR10).
+- Its rows' press paint under a coarse pointer (FR11).
+- Its rows' update motion with an `animatedLayout` handle: entering, exiting,
+  and crossing (FR12).
+- Its rows' menus attaching to the row's own `<li>` (FR13); the More actions
+  button, focus return, and a plain row's press paint are open (OQ2).
 
 **Does not own / non-goals**
 
@@ -93,24 +108,30 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Public concepts
 
-| Concept                        | Closed values or states              | Meaning                                                                                 | Availability by variant/orientation/state                                                | Default  | Owner            | Stability  | Invalid-value behavior                       |
-| ------------------------------ | ------------------------------------ | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------- | ---------------- | ---------- | -------------------------------------------- |
-| Edge treatment                 | `padded`, `flush`, `outset`, `bleed` | Where row content and row paint sit relative to the list's edges and the host's padding | Every density, marker style, and divider setting; `outset` and `bleed` read host padding | `padded` | `component:List` | accepted   | Other values are rejected by the public type |
-| Edge compensation (deprecated) | omitted, `inline`                    | Same as `edge="outset"`                                                                 | As `outset`                                                                              | omitted  | `component:List` | deprecated | Other values are rejected by the public type |
+| Concept                        | Closed values or states              | Meaning                                                                                                                                          | Availability by variant/orientation/state                                                | Default  | Owner            | Stability  | Invalid-value behavior                       |
+| ------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | -------- | ---------------- | ---------- | -------------------------------------------- |
+| Edge treatment                 | `padded`, `flush`, `outset`, `bleed` | Where row content and row paint sit relative to the list's edges and the host's padding                                                          | Every density, marker style, and divider setting; `outset` and `bleed` read host padding | `padded` | `component:List` | accepted   | Other values are rejected by the public type |
+| Edge compensation (deprecated) | omitted, `inline`                    | Same as `edge="outset"`                                                                                                                          | As `outset`                                                                              | omitted  | `component:List` | deprecated | Other values are rejected by the public type |
+| Animated layout                | absent, a `useAnimatedLayout` handle | Inserted, removed, and moved rows animate, and the rows after a change glide to their new places (FR12)                                          | Every density, marker style, edge treatment, and divider setting                         | absent   | `spec:AST-105`   | accepted   | Other values are rejected by the public type |
+| Reordering                     | absent, a `createReorderable` object | Rows can be reordered by handle, keyboard, and assistive technology; `onReorder` receives the moved row's key and its new index (`spec:AST-103`) | Every density, marker style, edge treatment, and divider setting                         | absent   | `spec:AST-103`   | accepted   | Other values are rejected by the public type |
 
 ## Behavioral and layout contract
 
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Basis                                                                                    | Status                                                |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| FR1 | List MUST own `edge` and apply one treatment to every ListItem row, interactive or not; ListItem MUST NOT expose a parallel public prop. A defined `edge` MUST win over `edgeCompensation`, and `edgeCompensation="inline"` with `edge` undefined MUST resolve to `outset`.                                                                                                                                                                                                                                                                                                                                                                                                     | `component:List/DEC-1`, `component:List/DEC-3`                                           | Accepted contract                                     |
-| FR2 | `padded` MUST preserve current header, list, and row geometry. No treatment MAY move the header or change row block padding, gap, markers, start and end content, semantics, or hit target relative to the row box.                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Owner direction                                                                          | Accepted contract                                     |
-| FR3 | `flush` MUST resolve each row's inline inset to zero through the private source that supplies Item's applied inline padding, so row content and row paint share the list's inline edges. It reads no host padding. A theme override of row inline padding takes precedence over the zero (FR7).                                                                                                                                                                                                                                                                                                                                                                                 | `component:List/DEC-3`                                                                   | Accepted contract                                     |
-| FR4 | `outset` MUST place each row so it reaches past the host content line by the smaller of its own inline inset and the matching host inset, per logical edge, keeping its inset inside. Content reaches the host line when the host inset is at least the row inset.                                                                                                                                                                                                                                                                                                                                                                                                              | `architecture:container-padding/INV9–INV10`; `component:List/DEC-2`                      | Accepted contract                                     |
-| FR5 | `bleed` MUST place each row so it reaches the host's padding edge on each logical edge, with square corners. Row content sits on the host content line, or at the row's own inset from its edge when the host inset is smaller. A theme override of row inline padding sets the content's inset instead (FR7).                                                                                                                                                                                                                                                                                                                                                                  | `architecture:container-padding/INV3`; `component:List/DEC-4`                            | Accepted contract                                     |
-| FR6 | Missing or reset host inset MUST resolve to zero, so `outset` and `bleed` place content as `padded` does outside a padded host. No row paint MAY reach past the host's padding edge.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `architecture:container-padding/INV6`, `INV9`                                            | Accepted contract                                     |
-| FR7 | Each row's retained inset MUST come from the same private density- and theme-derived source as Item's applied inline padding. A theme `item.paddingInline` override takes precedence over every treatment's row padding, as it does over density. A consumer override of row padding through `xstyle`, `className`, or `style` is outside the alignment guarantee.                                                                                                                                                                                                                                                                                                              | Shared two-owner geometry contract                                                       | Accepted contract                                     |
-| FR8 | `outset` and `bleed` are valid only under a host state whose published inline inset matches its applied padding: a visually neutral host, such as a Layout region with explicit padding or a padded ScrollableArea, or the content area of a Card, Section (any variant), Dialog, or BottomSheet. Those hosts bound their padding with a border, background, or clip; FR6 keeps row paint inside the padding edge, so it never covers the border or changes the host's outline. Automatic LayoutContent/LayoutPanel states with a known publication mismatch are not eligible until that gap is fixed, and Drawer's content area is not admitted until it has its own evidence. | `architecture:container-padding/INV8–INV11`; real-browser evidence in each admitted host | Accepted contract                                     |
-| FR9 | The list element containing the rows MUST clip in the inline axis with `overflow-inline: clip`, never `hidden`. Under `outset` and `bleed` its inline edges MUST reach the host's padding edge, so the clip never cuts resting row paint and a swiped row paints no further than that edge.                                                                                                                                                                                                                                                                                                                                                                                     | `spec:AST-057/FR9`                                                                       | Verified by `List.test.tsx` and real-browser geometry |
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Basis                                                                                    | Status                                                |
+| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| FR1  | List MUST own `edge` and apply one treatment to every ListItem row, interactive or not; ListItem MUST NOT expose a parallel public prop. A defined `edge` MUST win over `edgeCompensation`, and `edgeCompensation="inline"` with `edge` undefined MUST resolve to `outset`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `component:List/DEC-1`, `component:List/DEC-3`                                           | Accepted contract                                     |
+| FR2  | `padded` MUST preserve current header, list, and row geometry, apart from FR10's hit target under a coarse pointer. No treatment MAY move the header or change row block padding, gap, markers, start and end content, semantics, or hit target relative to the row box.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Owner direction                                                                          | Accepted contract                                     |
+| FR3  | `flush` MUST resolve each row's inline inset to zero through the private source that supplies Item's applied inline padding, so row content and row paint share the list's inline edges. It reads no host padding. A theme override of row inline padding takes precedence over the zero (FR7).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `component:List/DEC-3`                                                                   | Accepted contract                                     |
+| FR4  | `outset` MUST place each row so it reaches past the host content line by the smaller of its own inline inset and the matching host inset, per logical edge, keeping its inset inside. Content reaches the host line when the host inset is at least the row inset.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `architecture:container-padding/INV9–INV10`; `component:List/DEC-2`                      | Accepted contract                                     |
+| FR5  | `bleed` MUST place each row so it reaches the host's padding edge on each logical edge, with square corners. Row content sits on the host content line, or at the row's own inset from its edge when the host inset is smaller. A theme override of row inline padding sets the content's inset instead (FR7).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `architecture:container-padding/INV3`; `component:List/DEC-4`                            | Accepted contract                                     |
+| FR6  | Missing or reset host inset MUST resolve to zero, so `outset` and `bleed` place content as `padded` does outside a padded host. No row paint MAY reach past the host's padding edge.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `architecture:container-padding/INV6`, `INV9`                                            | Accepted contract                                     |
+| FR7  | Each row's retained inset MUST come from the same private density- and theme-derived source as Item's applied inline padding. A theme `item.paddingInline` override takes precedence over every treatment's row padding, as it does over density. A consumer override of row padding through `xstyle`, `className`, or `style` is outside the alignment guarantee.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Shared two-owner geometry contract                                                       | Accepted contract                                     |
+| FR8  | `outset` and `bleed` are valid only under a host state whose published inline inset matches its applied padding: a visually neutral host, such as a Layout region with explicit padding or a padded ScrollableArea, or the content area of a Card, Section (any variant), Dialog, or BottomSheet. Those hosts bound their padding with a border, background, or clip; FR6 keeps row paint inside the padding edge, so it never covers the border or changes the host's outline. Automatic LayoutContent/LayoutPanel states with a known publication mismatch are not eligible until that gap is fixed, and Drawer's content area is not admitted until it has its own evidence.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `architecture:container-padding/INV8–INV11`; real-browser evidence in each admitted host | Accepted contract                                     |
+| FR9  | The list element containing the rows MUST clip in the inline axis with `overflow-inline: clip`, never `hidden`. Under `outset` and `bleed` its inline edges MUST reach the host's padding edge, so the clip never cuts resting row paint and a swiped row paints no further than that edge.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `spec:AST-057/FR9`                                                                       | Verified by `List.test.tsx` and real-browser geometry |
+| FR10 | Under a coarse primary pointer (`spec:AST-094` FR13), every ListItem row MUST offer a hit target at least 44 px tall, through its padding or an invisible hit area, with no visual change, where its neighbors leave room: the hit area never overlaps a neighboring row's or control's target, and between close neighbors it is clamped to half the gap; row height and geometry stay as they are at every density. A fine pointer keeps today's hit target.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Owner decision, 2026-10-26: no row-height change, a 44 px touch target                   | Accepted contract                                     |
+| FR11 | Under a coarse primary pointer, an interactive row's press MUST follow the cell profile (`spec:AST-094` FR11): it paints the `--color-overlay-pressed` token above the row's background and below its content without adding an element, and its release fades over the press model's release duration and curve on the compositor (`spec:AST-094` FR5). The row's dividers stay drawn while it is pressed, in every theme. At rest the row's paint and stacking are as they were.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `spec:AST-094` FR5, FR11                                                                 | Accepted contract                                     |
+| FR12 | List MUST take an `animatedLayout` handle (`spec:AST-105` FR1) and report each row inserted, removed, or moved between renders. With a handle, an inserted row enters, a removed row collapses in place, inert and hidden from assistive technology until it is gone, and a row crossing rows moving the other way rides above them on the list's surface, while the rows after a change glide to their new places (`spec:AST-105` FR3), all starting on one frame on the shared motion role (`spec:AST-105` FR4). Without a handle the list changes at once (`spec:AST-105` FR2). A row's identity is its `itemKey` (`spec:AST-103` DEC-4); a row without one changes at once.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `spec:AST-105` FR1–FR5; `spec:AST-103` DEC-4                                             | Accepted contract                                     |
+| FR13 | A row menu on a ListItem attaches to the row's own `<li>`, keeping `ul > li` with no wrapper element: the caller passes the ListItem's ref to `useContextMenu` (`spec:AST-107` FR8), with no ListItem prop of its own; the whole row is its hit area, it opens on the context request (a long press, a right click, or Shift+F10), under a finger, the row takes the press paint (FR11; on a plain row, part of OQ2) and lifts as the menu grows from it, `useContextMenu` lifting the element it is attached to (`spec:AST-094` FR31, FR33), while a mouse, the keyboard, and `presentation: 'popover'` open the released menu without the lift (`spec:AST-094` FR41), and focus returns to the row's focus target when the menu closes. A row that is already focusable (`onClick` or `href`) takes Shift+F10 and the context-menu key directly, and a row with an `interactiveRef` takes them on that element; neither shows a "More actions" button; a row with none of these shows a visible "More actions" button named with the row's label, such as "More actions for Inbox", its keyboard and screen-reader path to the menu. When a menu opens, focus moves into it; when it closes, focus returns to the row's focus target, or to the "More actions" button on a row that shows one. Who moves focus there, since `useContextMenu` returns focus to the `<li>`, which takes none, is part of OQ2. A reorderable row always has its handle (`spec:AST-103` FR3), so when it also has a row menu, a hold on the handle picks the row up and a hold anywhere else on the row opens the menu. | Owner decision, 2026-10-26; `spec:AST-107` FR8                                           | Accepted contract                                     |
 
 ### Allowed variation
 
@@ -121,6 +142,8 @@ Consumer migration instructions belong in consumer docs and release notes.
   resolves independently.
 - Labels, descriptions, markers, start/end content, interactivity, and selection
   may vary without changing the collection-wide treatment.
+- Under a coarse primary pointer, a row's hit target grows toward 44 px where
+  its neighbors leave room (FR10); row geometry and appearance are unchanged.
 
 ### Representative states
 
@@ -133,6 +156,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | `outset` or `bleed`, host inset smaller than row inset | Row paint stops at the host's padding edge; content keeps the row inset.               | Either logical edge independently.  |
 | `outset` or `bleed`, no host inset                     | Content placed as `padded`; `bleed` rows are square.                                   | Standalone lists and overlays.      |
 | LTR or RTL                                             | Logical start/end mapping follows direction.                                           | Writing direction.                  |
+| `animatedLayout`, rows change                          | Staying rows move to their new places; a removed row collapses; new rows fade in.      | Reduced motion: the role's policy.  |
 
 ### Transformation and precedence order
 
@@ -151,6 +175,9 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 - **PR1 — CSS geometry only.** Every treatment MUST add no measurement, observer,
   listener, state, Effect, or render pass. Deprecation warnings are dev-only.
+- **PR2 — Motion only where it applies.** FR11 adds no listener, observer,
+  measurement, or animation under a fine pointer, and FR12 measures rows only
+  with a handle. Every motion runs on transform and opacity.
 
 ## Accessibility contract
 
@@ -175,20 +202,36 @@ Consumer migration instructions belong in consumer docs and release notes.
 - `architecture:public-component-api`, `spec:AST-002`, and `spec:AST-017` own
   public API admission and the deprecation lifecycle.
 - Item remains the implementation owner of row padding and interaction paint;
-  List owns only the collection-level treatment and row placement.
+  List owns the collection-level treatment, row placement, and its rows' own
+  entering, exiting, and crossing (FR12).
 - `spec:AST-057` owns swipe actions on `Item` and the rule that the element
   containing swipe-capable rows clips in the inline axis; List carries that clip
   (FR9) and `ListItem` passes `swipeActions` and `swipeBehavior` through to
   `Item` unchanged.
+- `spec:AST-094` owns the touch presentation gate (FR13), the press model
+  (FR11), and motion roles (FR4); FR10 and FR11 apply the gate and the press
+  model to list rows, and FR12's motion plays an FR4 role.
+- `spec:AST-105` owns the animated layout handle and its shared motion; List
+  adopts it for row updates (FR12).
+- `spec:AST-103` owns reordering. List is its first adopter: it
+  takes the `reorderable` object, a row's key is its `ListItem`'s `itemKey`
+  and its position is its index, and the
+  handle is the one element reordering adds to a row, at its trailing edge
+  (`spec:AST-103` FR5).
 
 ## Verification map
 
-| Contract                  | Verification                                                 | Representative states                                                                                                                                                                                                                                                                                                                | Mutation or failure expectation                                                                                                                                      | Audit section       |
-| ------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
-| FR1–FR7, FR9              | List, Item, and theme-registry tests                         | every treatment; all densities; static and interactive rows; header; deprecated alias alone and with `edge`; ListItem outside a List                                                                                                                                                                                                 | Removing context propagation, using one host edge for both inline edges, zeroing padding without the shared inset source, or dropping the list's reach or clip fails | `audit:List/layout` |
-| FR2–FR6, FR8–FR9, AR1–AR2 | Real-browser List geometry evidence                          | each treatment in a Card at two paddings, a Section, an inline Dialog with and without Layout, a BottomSheet, a padded ScrollableArea scrolling vertically and in both axes, a LayoutContent with explicit padding, and standalone; header and dividers; LTR/RTL; hovered and selected rows; a swiped row under `outset` and `bleed` | Header movement, content off the expected line, paint past the host's padding edge, clipped resting paint, or a changed row box fails                                | `audit:List/visual` |
-| Migration                 | `astryx upgrade` codemod tests                               | static, aliased, already-migrated, dynamic, and computed-`edge` callsites; a second run                                                                                                                                                                                                                                              | A dynamic value or a computed `edge` rewritten, a static one missed, or a second run that changes output fails                                                       | `audit:List/docs`   |
-| Documentation             | `List.doc.mjs`, Storybook, and `scripts/check-knowledge.mjs` | public prop, values, default, deprecation, and representative composition                                                                                                                                                                                                                                                            | Missing or stale contract, docs, or example fails                                                                                                                    | `audit:List/docs`   |
+| Contract                  | Verification                                                                             | Representative states                                                                                                                                                                                                                                                                                                                | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                   | Audit section       |
+| ------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
+| FR1–FR7, FR9              | List, Item, and theme-registry tests                                                     | every treatment; all densities; static and interactive rows; header; deprecated alias alone and with `edge`; ListItem outside a List                                                                                                                                                                                                 | Removing context propagation, using one host edge for both inline edges, zeroing padding without the shared inset source, or dropping the list's reach or clip fails                                                                                                                                                                                                                              | `audit:List/layout` |
+| FR2–FR6, FR8–FR9, AR1–AR2 | Real-browser List geometry evidence                                                      | each treatment in a Card at two paddings, a Section, an inline Dialog with and without Layout, a BottomSheet, a padded ScrollableArea scrolling vertically and in both axes, a LayoutContent with explicit padding, and standalone; header and dividers; LTR/RTL; hovered and selected rows; a swiped row under `outset` and `bleed` | Header movement, content off the expected line, paint past the host's padding edge, clipped resting paint, or a changed row box fails                                                                                                                                                                                                                                                             | `audit:List/visual` |
+| FR10                      | List tests of the touch hit target and real-browser hit-testing                          | every density; a row with a description; compact rows packed closer than 44 px; a row with an end control; a coarse and a fine pointer; a theme row padding                                                                                                                                                                          | A coarse-pointer row whose target stays at its box where its neighbors leave room, a target that reaches a neighboring row's or control's target, a changed row box, or a changed fine-pointer target fails                                                                                                                                                                                       | `audit:List/layout` |
+| FR11                      | Item press-layer tests and real-browser pixel evidence                                   | press, hold, and release; a release while the main thread is blocked; a mouse; a pressed row between two divided rows                                                                                                                                                                                                                | A release that stops while script runs, an element added for the press, a divider hidden during a press, or paint or stacking changed at rest fails                                                                                                                                                                                                                                               | `audit:List/visual` |
+| FR12                      | List update-motion tests and real-browser frame evidence                                 | an insert, a removal, and a reorder, with and without a handle; reduced motion; a mouse                                                                                                                                                                                                                                              | A staying row that jumps with a handle, motion without one, a collapsing removed row that takes focus, pointer input or an accessibility-tree node, a removed row left after its collapse ends, or layout or paint per frame fails                                                                                                                                                                | `audit:List/visual` |
+| Migration                 | `astryx upgrade` codemod tests                                                           | static, aliased, already-migrated, dynamic, and computed-`edge` callsites; a second run                                                                                                                                                                                                                                              | A dynamic value or a computed `edge` rewritten, a static one missed, or a second run that changes output fails                                                                                                                                                                                                                                                                                    | `audit:List/docs`   |
+| Documentation             | `List.doc.mjs`, Storybook, and `scripts/check-knowledge.mjs`                             | public prop, values, default, deprecation, and representative composition                                                                                                                                                                                                                                                            | Missing or stale contract, docs, or example fails                                                                                                                                                                                                                                                                                                                                                 | `audit:List/docs`   |
+| FR13                      | List tests and real-browser tests of a row menu with a mouse, a finger, and the keyboard | a plain row, a row with `onClick`, a row with `href`; a right click, a long press, Shift+F10, the context-menu key; close by Escape and by choice; a finger's hold, a mouse's right click, the keyboard, and `presentation: 'popover'`                                                                                               | A wrapper element around the `<li>`, a row a context request does not open, focus left in a closed menu or not returned to the row or its button, a plain row without a named "More actions" button, or a focusable row that ignores Shift+F10 fails. A lift or press paint under a mouse, the keyboard, or `presentation: 'popover'`, or a finger's hold on a focusable row without them, fails. | `audit:List/layout` |
+| FR13 reorder              | Real-browser tests with a finger and a mouse on a reorderable row with a menu            | a hold on the handle and on the row body of a reorderable row with a menu                                                                                                                                                                                                                                                            | A handle hold that opens the menu, or a body hold that picks the row up, fails                                                                                                                                                                                                                                                                                                                    | `audit:List/layout` |
 
 ## Decision log
 
@@ -248,7 +291,21 @@ existing list in a container.
 
 ## Open questions
 
-None.
+- **OQ1 — A caller's `::before` through a press.** The press paint takes the
+  row's `::before` while the row is pressed, so a caller's decoration there
+  is hidden for that time: (a) keep that, and document decorating a row with
+  a child; or (b) require the press paint to leave a caller's `::before`
+  intact.
+
+- **OQ2 — Who renders a plain row's More actions button and returns focus.** `useContextMenu`
+  returns `open` and `close` but no trigger, so FR13's More actions button on a
+  row with no `onClick`, `href`, or `interactiveRef` has no owner yet: (a) the
+  caller renders a Button in the row's end content that calls `open`, named
+  with the row's label; (b) ListItem renders it when its ref carries a menu; (c)
+  `useContextMenu` returns the trigger's props. The same answer decides who
+  returns focus to the row's focus target or that button on close, since the
+  hook returns it to the `<li>`, and who paints a plain row's press under a
+  finger's hold, since FR11 paints only an interactive row's press.
 
 ## Content boundary
 

package/src/List/ListItem.doc.mjs

@@ -104,7 +104,7 @@ export const docs = {
     {
       name: 'isSelected',
       type: 'boolean',
-      description: 'Selected state; sets aria-selected on the item.',
+      description: 'Selected state; marks the item as the current one with aria-current="true" (a list item cannot carry aria-selected).',
       default: 'false',
     },
     {
@@ -196,7 +196,7 @@ export const docsZh = {
     {
       name: 'isSelected',
       type: 'boolean',
-      description: '选中状态；在项目上设置 aria-selected。',
+      description: '选中状态；在项目上设置 aria-current="true"，将其标为当前项（列表项不能使用 aria-selected）。',
       default: 'false',
     },
     {
@@ -236,6 +236,6 @@ export const docsDense = {
       'Link target attribute, only when href provided. target="_blank" auto-adds noopener noreferrer.',
     rel: 'Link relationship tokens. noopener noreferrer are merged for target="_blank".',
     isDisabled: 'Disabled state; sets aria-disabled.',
-    isSelected: 'Selected state; sets aria-selected.',
+    isSelected: 'Selected state; sets aria-current="true".',
   },
 };

package/src/Markdown/Markdown.codeLanguages.test.tsx

@@ -0,0 +1,137 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Markdown.codeLanguages.test.tsx
+ * @input Markdown, CodeBlock language modules, createCodeLanguage
+ * @output Markdown FR30 evidence: a fence naming a value in `codeLanguages`
+ *   renders with it, ahead of a built-in; a later entry wins; a
+ *   `diff-<identifier>` fence takes the diff layer over it; a custom `code`
+ *   renderer keeps receiving the fence word
+ * @position Markdown FR30 evidence
+ */
+
+import {render} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {createCodeLanguage} from '../CodeBlock/grammar';
+import {objectiveC} from '../CodeBlock/languages/objective-c';
+import {thrift} from '../CodeBlock/languages/thrift';
+import {Markdown} from './Markdown';
+
+const THRIFT = 'struct User {\n  1: required string name;\n}';
+
+function keywordTexts(root: ParentNode): string[] {
+  return Array.from(root.querySelectorAll('.astryx-token-keyword')).map(
+    node => node.textContent ?? '',
+  );
+}
+
+describe('Markdown codeLanguages (Markdown FR30)', () => {
+  const fence = '```thrift\n' + THRIFT + '\n```';
+
+  it('paints a fence naming a listed value, and only then', () => {
+    const unlisted = render(<Markdown>{fence}</Markdown>);
+    expect(keywordTexts(unlisted.container)).toEqual([]);
+    const listed = render(
+      <Markdown codeLanguages={[thrift]}>{fence}</Markdown>,
+    );
+    // jsdom has no CSS Custom Highlight API, so CodeBlock falls back to spans.
+    expect(keywordTexts(listed.container)).toContain('struct');
+  });
+
+  it('labels a matched fence with the value name, not the fence word', () => {
+    const fence = '```objc\n@interface A : NSObject\n@end\n```';
+    const {container} = render(
+      <Markdown codeLanguages={[objectiveC]}>{fence}</Markdown>,
+    );
+    expect(container.textContent).toContain('objective-c');
+    expect(container.querySelector('pre')?.getAttribute('data-language')).toBe(
+      'objective-c',
+    );
+  });
+
+  it('lets a later entry win a shared identifier', () => {
+    const mine = createCodeLanguage({
+      name: 'thrift',
+      identifiers: ['thrift'],
+      tokenize: () => [{type: 'string', start: 0, end: 6}],
+    });
+    const {container} = render(
+      <Markdown codeLanguages={[thrift, mine]}>{fence}</Markdown>,
+    );
+    expect(keywordTexts(container)).toEqual([]);
+    expect(container.querySelector('.astryx-token-string')?.textContent).toBe(
+      'struct',
+    );
+  });
+
+  it('lets a listed value claim a built-in identifier', () => {
+    const myTs = createCodeLanguage({
+      name: 'ts',
+      identifiers: ['ts'],
+      tokenize: () => [{type: 'string', start: 0, end: 5}],
+    });
+    const fenceTs = '```ts\nconst a = 1;\n```';
+    const builtIn = render(<Markdown>{fenceTs}</Markdown>);
+    expect(keywordTexts(builtIn.container)).toContain('const');
+    const listed = render(
+      <Markdown codeLanguages={[myTs]}>{fenceTs}</Markdown>,
+    );
+    expect(keywordTexts(listed.container)).toEqual([]);
+    expect(
+      listed.container.querySelector('.astryx-token-string')?.textContent,
+    ).toBe('const');
+  });
+
+  it('takes the diff layer over a listed value for a diff-<identifier> fence', () => {
+    const diff = '```diff-thrift\n+struct User {}\n```';
+    const {container} = render(
+      <Markdown codeLanguages={[thrift]}>{diff}</Markdown>,
+    );
+    expect(keywordTexts(container)).toContain('struct');
+    expect(container.querySelector('[data-diff="added"]')).not.toBeNull();
+  });
+
+  it('does not re-render the document when an inline list names the same values', () => {
+    // An inline plugin's render runs each time Markdown renders its blocks.
+    let renders = 0;
+    const counting = [
+      {
+        pattern: /marker/g,
+        render: () => {
+          renders++;
+          return 'marker';
+        },
+      },
+    ];
+    const doc = 'A marker here.\n\n' + fence;
+    const {rerender} = render(
+      <Markdown codeLanguages={[thrift]} inlinePlugins={counting}>
+        {doc}
+      </Markdown>,
+    );
+    const first = renders;
+    rerender(
+      <Markdown codeLanguages={[thrift]} inlinePlugins={counting}>
+        {doc}
+      </Markdown>,
+    );
+    expect(renders).toBe(first);
+  });
+
+  it('keeps a custom code renderer receiving the fence word', () => {
+    const seen: unknown[] = [];
+    render(
+      <Markdown
+        codeLanguages={[thrift]}
+        components={{
+          code: ({language}) => {
+            seen.push(language);
+            return null;
+          },
+        }}>
+        {fence}
+      </Markdown>,
+    );
+    expect(seen).toEqual(['thrift']);
+  });
+});

package/src/Markdown/Markdown.doc.mjs

@@ -159,6 +159,12 @@ export const docs = {
       description:
         "Opt-in autolinking of bare URLs and emails. 'gfm' applies GitHub-Flavored Markdown autolink-literal rules: bare https?://..., www...., <scheme:url>, <email>, and user@host all become links. Trailing sentence punctuation and unbalanced trailing close-parens are excluded; matches inside code spans, code blocks, existing links, and image alt text are skipped. Default behavior (option unset) is unchanged.",
     },
+    {
+      name: 'codeLanguages',
+      type: 'ReadonlyArray<CodeLanguage>',
+      description:
+        "CodeBlock language values a fence may name, each imported on its own (e.g. graphql from @astryxdesign/core/CodeBlock/languages/graphql) or made with createCodeLanguage. A fence whose language word is one of a listed value's identifiers renders with it, ahead of a built-in; a diff-<identifier> fence takes the diff layer over it; a later entry wins. Pass the same list to RichTextEditor or RichTextView so read and edit match.",
+    },
     {
       name: 'components',
       type: 'MarkdownComponents',
@@ -686,6 +692,12 @@ export const docsZh = {
       description:
         "可选的裸 URL 和电子邮箱自动链接。设为 'gfm' 启用 GitHub Flavored Markdown 自动链接规则：裸 https?://、www.、<scheme:url>、<email> 以及 user@host 都会变成链接。末尾句末标点和不平衡的末尾右括号会被排除；代码块、现有链接和图片替代文本内部的匹配会被跳过。默认为关闭。",
     },
+    {
+      name: 'codeLanguages',
+      type: 'ReadonlyArray<CodeLanguage>',
+      description:
+        '代码块可以命名的 CodeBlock 语言值，每个单独导入（例如从 @astryxdesign/core/CodeBlock/languages/graphql 导入 graphql），或用 createCodeLanguage 创建。语言词属于所列值标识符的代码块用该值渲染，优先于内置语言；后列出的条目优先。',
+    },
     {
       name: 'components',
       type: 'MarkdownComponents',

package/src/Markdown/Markdown.fr23.bench.ts

@@ -16,7 +16,9 @@
  * then nine alternating paired rounds averaging 20 iterations a side,
  * reported as the median of the nine paired ratios — against the omitted
  * baseline, for a stable list and a recreated equivalent one. Each ratio
- * comes from one sample, never a selection by the fastest baseline.
+ * comes from one sample, never a selection by the fastest baseline. Windows
+ * are timed on the main thread's CPU clock, so V8's background threads do not
+ * bill their work to whichever side happens to be running.
  *
  * The harness retries a fresh process only when the A/A control is invalid.
  * A helper-overhead failure is never retried to obtain a passing sample.

package/src/Markdown/Markdown.fr23.perf.test.ts

@@ -19,7 +19,7 @@
  * The timed region inside each process is the spec's protocol, unsmoothed:
  * ten untimed warmups, then one median of nine alternating paired rounds,
  * for a stable plugin list and a recreated equivalent one, against the
- * omitted baseline. A first attempt within budget on both paths certifies
+ * omitted baseline, timed on the main thread's CPU clock. A first attempt within budget on both paths certifies
  * them. Otherwise up to nine fresh-process attempts decide each path on its
  * own: a path fails the unchanged budget when a majority of the nine (five)
  * exceed it, and collection stops as soon as both paths are decided.
@@ -27,10 +27,15 @@
 
 import {execFileSync} from 'node:child_process';
 import {mkdtempSync, rmSync, writeFileSync} from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
+import {Worker} from 'node:worker_threads';
 import {afterAll, describe, expect, it} from 'vitest';
-import {measureMarkdownPairedRatio} from './Markdown.fr23.sampling';
+import {
+  mainThreadCpuTime,
+  measureMarkdownPairedRatio,
+} from './Markdown.fr23.sampling';
 
 interface BenchmarkResult {
   readonly sections: number;
@@ -160,11 +165,17 @@ function runSettledBenchmark(sections: number): BenchmarkResult {
   return measured;
 }
 
+/**
+ * The ratios depend on the processor, so each line names it: a runner on a
+ * different CPU model shows up in the log rather than as an unexplained shift.
+ */
+const CPU_MODEL = os.cpus()[0]?.model.trim() ?? 'unknown CPU';
+
 function logBenchmarkResult(result: BenchmarkResult, attempt: number): void {
   console.log(
     `  ${result.sections} sections, attempt ${attempt}, FR23 representative set over empty:` +
       ` stable ${result.stable.toFixed(3)}, recreated ${result.recreated.toFixed(3)}` +
-      ` (budget ${FR23_BUDGET}, A/A control ${result.control.toFixed(3)})`,
+      ` (budget ${FR23_BUDGET}, A/A control ${result.control.toFixed(3)}; ${CPU_MODEL})`,
   );
 }
 
@@ -266,6 +277,37 @@ describe('Markdown FR23 helper overhead', () => {
     }
   });
 
+  it("times only the main thread, not V8's or a worker's background threads", async () => {
+    // A worker spins for 300 ms of CPU while this thread sleeps without any.
+    // The process clock counts the worker's time; the sampling clock must not.
+    const flag = new Int32Array(new SharedArrayBuffer(4));
+    const processBefore = process.cpuUsage();
+    const threadBefore = mainThreadCpuTime();
+    const worker = new Worker(
+      `const {workerData} = require('node:worker_threads');
+       const end = Date.now() + 300;
+       while (Date.now() < end) {}
+       Atomics.store(workerData, 0, 1);
+       Atomics.notify(workerData, 0);`,
+      {eval: true, workerData: flag},
+    );
+    // A worker that dies before it finishes must fail the test, not hang it.
+    const deadline = Date.now() + 10_000;
+    while (Atomics.load(flag, 0) === 0) {
+      if (Date.now() > deadline) {
+        await worker.terminate();
+        throw new Error('The CPU-spinning worker did not finish in 10 s');
+      }
+      Atomics.wait(flag, 0, 0, 50);
+    }
+    const thread = mainThreadCpuTime() - threadBefore;
+    const processUsage = process.cpuUsage(processBefore);
+    await worker.terminate();
+    const processTime = processUsage.user + processUsage.system;
+    expect(processTime).toBeGreaterThan(200_000);
+    expect(thread).toBeLessThan(processTime / 4);
+  });
+
   describe('deciding each path from fresh-process attempts', () => {
     const result = (stable: number, recreated: number): BenchmarkResult => ({
       sections: 500,

package/src/Markdown/Markdown.fr23.sampling.ts

@@ -2,13 +2,22 @@
 
 /**
  * @file Markdown.fr23.sampling.ts
- * @input Baseline/candidate callbacks and a microsecond CPU clock
+ * @input Baseline/candidate callbacks and the main thread's microsecond CPU clock
  * @output The FR23 paired-median ratio
  * @position Test-only sampling for Markdown.fr23.bench.ts
  */
 
-function cpuTime(): number {
-  const used = process.cpuUsage();
+/**
+ * CPU time of the calling thread, in microseconds: the time the measured call
+ * holds the JS thread, its own garbage-collection pauses included.
+ *
+ * Not `process.cpuUsage()`, which sums every thread of the process: V8's
+ * concurrent GC and compiler threads run during the timed windows, and their
+ * CPU lands in whichever window is open. At 500 sections that made even the
+ * A/A control (identical work on both sides) vary by up to 13 percent.
+ */
+export function mainThreadCpuTime(): number {
+  const used = process.threadCpuUsage();
   return used.user + used.system;
 }
 
@@ -20,7 +29,7 @@ function median(values: ReadonlyArray<number>): number {
 export function measureMarkdownPairedRatio(
   baseline: () => number,
   candidate: () => number,
-  now: () => number = cpuTime,
+  now: () => number = mainThreadCpuTime,
 ): number {
   let sink = 0;
   const average = (callback: () => number): number => {