@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

package/src/Layout/LayoutHeader.spec.md

@@ -0,0 +1,193 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:LayoutHeader
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-30
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/Layout/LayoutSlots.test.tsx,
+    packages/core/src/Layout/Layout.test.tsx,
+    packages/core/src/Layout/__tests__/contentWidth.test.tsx,
+    packages/core/src/Layout/__tests__/Layout.a11y.test.tsx,
+    packages/core/src/Layout/__tests__/Layout.a11y.chromium.spec.ts,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: [family:layout-regions]
+design_specs: []
+architecture:
+  [
+    architecture:container-padding,
+    architecture:component-theming-surface,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: [spec:AST-038]
+---
+
+# LayoutHeader component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                  |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `children`, `hasDivider`, `height`, `padding`, `paddingBlockEnd`, `label`, `role`, root `BaseProps`, and a root `ref`.                    |
+| Behavior                | A non-shrinking header region whose inner wrapper applies and publishes the Layout inset and aligns to the Layout's content width.        |
+| End-user impact         | People see a header that keeps its height above scrolling content, with content aligned to the page's readable width.                     |
+| Builder impact          | None; the record describes shipped behavior.                                                                                              |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Two implementation gaps are listed under Current-state impact. |
+| Review checks           | Reject a header that shrinks, a published inset that differs from the applied padding, an inferred landmark, or a lost divider default.   |
+| Governing rules         | `family:layout-regions` FR1, FR4–FR6, FR8; `architecture:container-padding`; `architecture:public-component-api` INV5–INV8.               |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+LayoutHeader is the optional header region a caller places in a Layout's
+`header` slot. It owns the header's size, inset, divider, and caller-supplied
+landmark semantics; the caller owns its content.
+
+Consumer syntax and examples belong in `LayoutHeader.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes` — no divider unless a Layout default says
+  so, automatic inset, no landmark role.
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  target, or styling output changes.
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Caller `data-divider` overrides the reflected divider (FR5).** Caller
+  props spread after the component's `data-divider`, so a caller value replaces
+  it: `data-divider="false"` draws no line yet stops the middle row below
+  from collapsing its spacing, where `architecture:public-component-api` INV5
+  keeps component-owned behavior from being overwritten.
+- **Nested Layouts inherit the collapse (FR3).** When this header has no
+  divider, Layouts nested in the middle row, including inside a Dialog,
+  Drawer, or BottomSheet opened from it, inherit its spacing collapse and sit
+  flush against their own dividers (`family:layout-regions` FR6;
+  `spec:AST-038` FR7).
+
+## Ownership boundary
+
+**Owns**
+
+- The header root, which carries the `layout-header` target that
+  `component:Layout` maps, and its inner padding wrapper.
+- Header height, divider, inset, and caller-supplied role and label.
+
+**Does not own / non-goals**
+
+- Slot placement, the Layout-edge inset, content width, and the divider
+  default — owned by `component:Layout`.
+- Header content and its meaning — owned by the caller.
+
+## Public concepts
+
+| Concept         | Closed values or states               | Meaning                                                                     | Availability by variant/orientation/state | Default                   | Owner                    | Stability | Invalid-value behavior           |
+| --------------- | ------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------- | ------------------------- | ------------------------ | --------- | -------------------------------- |
+| Divider         | `true`, `false`, unset                | Draws a line on the header's block-end edge.                                | Always                                    | Layout default, else none | `component:LayoutHeader` | Stable    | —                                |
+| Height          | number (px); CSS length string; unset | Fixes the header's block size.                                              | Always                                    | content height            | `component:LayoutHeader` | Stable    | —                                |
+| Inset           | spacing step; `0`; unset              | Uniform padding that replaces the automatic inset; `0` is full bleed.       | Always                                    | automatic                 | `component:LayoutHeader` | Stable    | Closed union; rejected by types. |
+| Block-end inset | spacing step; unset                   | Replaces the block-end padding alone.                                       | Always                                    | automatic                 | `component:LayoutHeader` | Stable    | Closed union; rejected by types. |
+| Landmark        | caller `role` and `label`             | Exposes the header as the role the caller names, with that accessible name. | Always                                    | none                      | caller                   | Stable    | —                                |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Basis                                                                                   |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| FR1 | LayoutHeader renders a root `div` carrying the `layout-header` target that does not shrink, around an inner `div` that holds the children, has the Layout's content width as its maximum width, and centers within the root. `height` fixes the root's block size, with numbers as pixels.                                                                                                                                                                                                                                                                                                                                       | Current source and tests                                                                |
+| FR2 | Without `padding`, the inner wrapper's inline and block-start padding is the Layout-edge inset and its block-end padding is the inner inset, where the Layout-edge inset comes from the Layout's `padding`, else the nearest padding container, and the inner inset from the nearest padding container (Card, Section, Dialog, Drawer, or BottomSheet), each spacing step 4 otherwise. A `padding` step replaces all four edges, and `0` removes them. `paddingBlockEnd` replaces the block-end edge alone. The wrapper publishes container-padding values equal to the padding it applies.                                      | Current source and tests; `family:layout-regions` FR4; `architecture:container-padding` |
+| FR3 | A divider draws a 1px solid `--color-border` line on the root's block-end edge and reflects `data-divider="true"`. `hasDivider` decides; when unset, the nearest Layout `defaultHasDividers` in the same layer decides (the default stops at a layer boundary, `spec:AST-038` FR7); otherwise there is no divider. A header without a divider lets the middle row below it collapse its block-start spacing. Implementation gap: Layouts nested in that middle row, including inside a Dialog, Drawer, or BottomSheet opened from it, inherit the collapse (`component:LayoutContent` Current-state impact; `spec:AST-038` FR7). | Current source and tests; `family:layout-regions` FR6                                   |
+| FR4 | `role` and `label` set the root's `role` and `aria-label`; LayoutHeader adds no role of its own.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Current source and tests; `family:layout-regions` FR8                                   |
+| FR5 | `ref` reaches the root. Supported DOM, data, ARIA, and event props reach the root, `xstyle`, `className`, and `style` compose after component styles, and the reflected `data-divider` stays component-owned (`architecture:public-component-api` INV5). Implementation gap: caller props spread after `data-divider`, so a caller `data-divider` replaces the reflected value and changes the neighbouring spacing collapse (Current-state impact).                                                                                                                                                                             | Current source and tests; `architecture:public-component-api` INV5–INV8                 |
+
+### Allowed variation
+
+- **AV1 — Content.** Any caller content may fill the header.
+- **AV2 — Landmark.** The caller chooses whether the header is a landmark and
+  which one.
+
+### Representative states
+
+| State             | Required invariant                                 | Allowed variation |
+| ----------------- | -------------------------------------------------- | ----------------- |
+| Default in Layout | Automatic inset, no divider, no role.              | Content.          |
+| With divider      | Block-end line and `data-divider="true"`.          | —                 |
+| Explicit padding  | Uniform padding, published to children.            | Step.             |
+| `paddingBlockEnd` | Only the block-end edge changes.                   | Step.             |
+| Banner landmark   | `role="banner"` and the caller's name on the root. | Name.             |
+
+### Transformation and precedence order
+
+- **ORD1 — Divider.** `hasDivider` → Layout `defaultHasDividers` → none.
+- **ORD2 — Padding.** `paddingBlockEnd` for block-end → `padding` → the
+  automatic inset.
+
+### Performance and resources
+
+- **PR1 — No external lifecycle.** LayoutHeader reads the divider default from
+  its Layout and adds no listener, observer, timer, or measurement.
+
+## Accessibility contract
+
+- **AR1 — Explicit landmarks only.** The header is a landmark only when the
+  caller supplies `role`, and it is named only by the caller's `label`
+  (`family:layout-regions` FR8).
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                      | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Header           | A fixed header band with an optional block-end divider. | Current source and docs  | Supporting     | FR1–FR3            |
+
+Theming: the root carries the `layout-header` target, which `Layout.doc.mjs`
+declares and `component:Layout` maps. `LayoutHeader.doc.mjs` declares no anatomy
+of its own, so no anatomy-theming block is declared here.
+
+## Family and system relationships
+
+- `family:layout-regions` owns region boundaries, padding replacement, divider
+  spacing, and landmark rules; FR2–FR4 and AR1 apply them.
+- `architecture:container-padding` owns inset publication; FR2 applies it.
+- `component:Layout` owns slot placement, the Layout-edge inset, content
+  width, the divider default, and the `layout-header` target mapping.
+- `architecture:public-component-api` owns caller-input routing; FR5 applies
+  it.
+
+## Verification map
+
+| Contract  | Verification                                                                                                                        | Representative states                                   | Mutation or failure expectation                                                                                                                                                                                                                                                                       | Audit section                      |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
+| FR1       | `LayoutSlots.test.tsx` class, height, and inner-wrapper tests; `contentWidth.test.tsx` LayoutHeader inner-wrapper and divider tests | Default; numeric height                                 | A lost `layout-header` class, a missing pixel height, children placed directly on the root, or a divider off the outer element fails. Gap: the non-shrinking root, the content-width maximum, and centering have no check.                                                                            | `audit:LayoutHeader/layout`        |
+| FR2, ORD2 | `Layout.test.tsx` `paddingBlockEnd` tests                                                                                           | `paddingBlockEnd` alone and with `padding`              | A `paddingBlockEnd` that adds no class, changes more than the block-end edge, or leaves the shared per-edge family fails. Gap: the automatic inset, the `padding` replacement, full bleed, and the published values have no check.                                                                    | `audit:LayoutHeader/layout`        |
+| FR3, ORD1 | `LayoutSlots.test.tsx` and `Layout.test.tsx` divider tests                                                                          | Default; `hasDivider`; Layout default; explicit `false` | A missing or unexpected `data-divider`, an ignored Layout default, or an explicit `false` that loses fails. Gap: the line's paint and the collapsed spacing below a header without a divider have no check. No test covers the default stopping at a layer boundary or the inherited nested collapse. | `audit:LayoutHeader/layout`        |
+| FR4, AR1  | `LayoutSlots.test.tsx` landmark test; `Layout.a11y.test.tsx` and `Layout.a11y.chromium.spec.ts` `header-banner` state               | Caller `banner` role and label                          | A lost role or name fails, including at the accessibility tree. Gap: no test asserts that a header without `role` exposes none.                                                                                                                                                                       | `audit:LayoutHeader/accessibility` |
+| FR5       | `LayoutSlots.test.tsx` ref and className tests                                                                                      | Ref; caller class                                       | A ref on another element or a dropped class fails. Gap: no test covers DOM, data, or event props, `style`, or the `xstyle` merge order. No test covers a caller `data-divider`.                                                                                                                       | `audit:LayoutHeader/api`           |
+| PR1       | Source review                                                                                                                       | Every state                                             | Gap: no automated check fails if LayoutHeader adds a listener, timer, or measurement.                                                                                                                                                                                                                 | `audit:LayoutHeader/behavior`      |
+
+## 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, Layout slot rules, or container-padding
+mechanics. It links to their owners.

package/src/Layout/LayoutHeader.tsx

@@ -23,7 +23,7 @@ import * as stylex from '@stylexjs/stylex';
 import {layoutHeaderMarker} from './layoutEdges.stylex';
 import {LayoutDividerContext} from './LayoutDividerContext';
 import {colorVars, spacingVars} from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import type {SizeValue, SpacingStep} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {

package/src/Layout/LayoutPanel.spec.md

@@ -0,0 +1,194 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:LayoutPanel
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-30
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/Layout/LayoutSlots.test.tsx,
+    packages/core/src/Layout/__tests__/Layout.a11y.test.tsx,
+    packages/core/src/Layout/__tests__/Layout.a11y.chromium.spec.ts,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: [family:layout-regions]
+design_specs: []
+architecture:
+  [
+    architecture:container-padding,
+    architecture:component-theming-surface,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: []
+---
+
+# LayoutPanel component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                        |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `children`, `width`, `resizable`, `hasDivider`, `isScrollable`, `padding`, `label`, `role`, root `BaseProps`, and a root `ref`.                 |
+| Behavior                | A fixed-width side region at logical start or end that scrolls by default, with an optional divider on its content-facing edge.                 |
+| End-user impact         | People see a side panel that keeps its width, scrolls on its own, and mirrors to the other side in right-to-left.                               |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                    |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Two implementation gaps are listed under Current-state impact.       |
+| Review checks           | Reject a divider on the outer edge, a panel that shrinks, an inferred landmark, `width` beating `resizable`, or a further publication mismatch. |
+| Governing rules         | `family:layout-regions` FR1, FR2, FR4–FR8, FR10; `architecture:container-padding`; `architecture:public-component-api` INV5–INV8.               |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+LayoutPanel is the side region a caller places in a Layout's `start` or `end`
+slot. It owns the panel's width, inset, scrolling, divider, and
+caller-supplied landmark semantics; the caller owns its content.
+
+Consumer syntax and examples belong in `LayoutPanel.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes` — no divider, scrollable, automatic
+  inset, content width.
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  target, or styling output changes.
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Published inset differs from applied padding (FR3).** On the automatic
+  path a panel applies the Layout-edge inset on its outer inline edge and on
+  a block edge with no header or footer, but publishes the inner inset on
+  every edge. A full-bleed child then lines up against a value that differs
+  from the padding the panel applies, where `architecture:container-padding`
+  has a region publish its applied padding.
+- **Two divider owners can paint one boundary (FR4).** A panel with
+  `hasDivider` beside a ResizeHandle that draws the same line paints the
+  boundary twice; nothing prevents it, so callers keep `hasDivider={false}`
+  when the ResizeHandle owns the line (`family:layout-regions` FR5).
+
+## Ownership boundary
+
+**Owns**
+
+- The panel root, which carries the `layout-panel` target that
+  `component:Layout` maps.
+- Panel width, inset, scrolling, divider, and caller-supplied role and label.
+
+**Does not own / non-goals**
+
+- Slot placement and the Layout-edge inset — owned by `component:Layout`.
+- Resize interaction and the resize handle — owned by useResizable and
+  ResizeHandle (`family:layout-regions` FR10).
+- Panel content and its meaning — owned by the caller.
+
+## Public concepts
+
+| Concept   | Closed values or states               | Meaning                                                                    | Availability by variant/orientation/state | Default       | Owner                   | Stability | Invalid-value behavior           |
+| --------- | ------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------- | ------------- | ----------------------- | --------- | -------------------------------- |
+| Width     | number (px); CSS length string; unset | The panel's inline size.                                                   | Always                                    | content width | `component:LayoutPanel` | Stable    | —                                |
+| Resizable | the value from useResizable           | Supplies a resizable width that wins over `width`.                         | Always                                    | none          | `component:LayoutPanel` | Stable    | —                                |
+| Divider   | `true`, `false`                       | Draws a line on the panel's content-facing edge.                           | Start or end slot                         | `false`       | `component:LayoutPanel` | Stable    | —                                |
+| Scrolling | `true`, `false`                       | Scrolls overflow, or clips it.                                             | Always                                    | `true`        | `component:LayoutPanel` | Stable    | —                                |
+| Inset     | spacing step; `0`; unset              | Uniform padding that replaces the automatic inset; `0` is full bleed.      | Always                                    | automatic     | `component:LayoutPanel` | Stable    | Closed union; rejected by types. |
+| Landmark  | caller `role` and `label`             | Exposes the panel as the role the caller names, with that accessible name. | Always                                    | none          | caller                  | Stable    | —                                |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Basis                                                                         |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| FR1 | LayoutPanel renders one `div` carrying the `layout-panel` target that does not shrink and holds the children directly. `width` sets its inline size, with numbers as pixels; a `resizable` value's size wins over `width`. It scrolls overflow by default; `isScrollable={false}` clips it.                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests; `family:layout-regions` FR7, FR10                   |
+| FR2 | In the `start` slot the panel's content-facing edge is its inline end; in the `end` slot it is its inline start; both follow writing direction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Current source and tests; `family:layout-regions` FR2                         |
+| FR3 | Without `padding`, the panel's outer inline edge has the Layout-edge inset, a block edge with no header or footer beside it has the Layout-edge inset, and other edges have the inner inset, where the Layout-edge inset comes from the Layout's `padding`, else the nearest padding container, and the inner inset from the nearest padding container (Card, Section, Dialog, Drawer, or BottomSheet), each spacing step 4 otherwise. A `padding` step replaces all four edges, and `0` removes them. The panel publishes container-padding values equal to the padding it applies. Implementation gap: on the automatic path it publishes the inner inset on every edge (Current-state impact). | Current source; `family:layout-regions` FR4; `architecture:container-padding` |
+| FR4 | `hasDivider` draws a 1px solid `--color-border` line on the content-facing edge; LayoutPanel does not read a Layout divider default. Without a divider and with the automatic inset, the panel overlaps the content area by the inner inset so the two share one gap. One boundary has one divider owner (`family:layout-regions` FR5). Implementation gap: nothing prevents a panel divider and an adjacent ResizeHandle line from both painting (Current-state impact).                                                                                                                                                                                                                         | Current source and docs; `family:layout-regions` FR5, FR6                     |
+| FR5 | `role` and `label` set the root's `role` and `aria-label`; LayoutPanel adds no role of its own.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Current source and tests; `family:layout-regions` FR8                         |
+| FR6 | `ref` reaches the root. Supported DOM, data, ARIA, and event props reach the root after the component's own attributes; `xstyle`, `className`, and `style` compose after component styles.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests; `architecture:public-component-api` INV5–INV8       |
+
+### Allowed variation
+
+- **AV1 — Content.** Any caller content may fill the panel.
+- **AV2 — Position.** The caller places the panel at start, end, or both.
+
+### Representative states
+
+| State               | Required invariant                                     | Allowed variation |
+| ------------------- | ------------------------------------------------------ | ----------------- |
+| Start panel         | Divider and shared gap on the inline-end edge.         | Width.            |
+| End panel           | Divider and shared gap on the inline-start edge.       | Width.            |
+| Right-to-left       | Start and end mirror.                                  | —                 |
+| Resizable           | The resizable size sets the width.                     | Size.             |
+| Navigation landmark | `role="navigation"` and the caller's name on the root. | Name.             |
+
+### Transformation and precedence order
+
+- **ORD1 — Width.** `resizable` size → `width` → content width.
+- **ORD2 — Padding.** `padding` → automatic inset per edge.
+
+### Performance and resources
+
+- **PR1 — No external lifecycle.** LayoutPanel reads its slot and which slots
+  its Layout fills, and adds no listener, observer, timer, or measurement of
+  its own.
+
+## Accessibility contract
+
+- **AR1 — Explicit landmarks only.** The panel is a landmark only when the
+  caller supplies `role`, named only by the caller's `label`
+  (`family:layout-regions` FR8).
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                           | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------ | ------------------------ | -------------- | ------------------ |
+| Panel            | A fixed side region with an optional content-facing divider. | Current source and docs  | Supporting     | FR1–FR4            |
+
+Theming: the root carries the `layout-panel` target, which `Layout.doc.mjs`
+declares and `component:Layout` maps. `LayoutPanel.doc.mjs` declares no anatomy
+of its own, so no anatomy-theming block is declared here.
+
+## Family and system relationships
+
+- `family:layout-regions` owns region direction, padding replacement,
+  boundary ownership, divider spacing, scrolling, landmarks, and resize
+  delegation; FR1–FR5 and AR1 apply them.
+- `architecture:container-padding` owns inset publication; FR3 applies it and
+  records the gap.
+- `component:Layout` owns slot placement, the Layout-edge inset, and the
+  `layout-panel` target mapping.
+
+## Verification map
+
+| Contract  | Verification                                                                                                                                                | Representative states                             | Mutation or failure expectation                                                                                                                                                                                                                                                                          | Audit section                     |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| FR1, ORD1 | `LayoutSlots.test.tsx` class, width, and resizable tests                                                                                                    | Numeric and string width; resizable               | A lost `layout-panel` class, a missing width, or `width` beating `resizable` fails. Gap: the non-shrinking root, scrolling, and `isScrollable={false}` have no check. No requirement or check covers how a keyboard user reaches a scrolling panel's overflow when the panel holds no focusable content. | `audit:LayoutPanel/layout`        |
+| FR2       | `LayoutSlots.test.tsx` start- and end-slot tests; `Layout.a11y.chromium.spec.ts` `start-end-navigation-rtl` state                                           | Start and end panels; right-to-left               | A panel that fails to render in either slot fails. Gap: no check asserts which edge carries the divider or the shared gap, or the mirrored placement.                                                                                                                                                    | `audit:LayoutPanel/layout`        |
+| FR3, ORD2 | Source review                                                                                                                                               | Automatic, explicit, and zero padding             | Gap: no test covers the automatic per-edge inset, the `padding` replacement, full bleed, or the published values.                                                                                                                                                                                        | `audit:LayoutPanel/layout`        |
+| FR4       | Source review                                                                                                                                               | `hasDivider`; no divider                          | Gap: no test covers the divider line, the shared gap, or a panel divider beside a ResizeHandle.                                                                                                                                                                                                          | `audit:LayoutPanel/layout`        |
+| FR5, AR1  | `LayoutSlots.test.tsx` landmark test; `Layout.a11y.test.tsx` and `Layout.a11y.chromium.spec.ts` `start-end-navigation-rtl` and `nested-panel-region` states | Caller `navigation` and `region` roles and labels | A lost role or name fails, including at the accessibility tree. Gap: no test asserts that a panel without `role` exposes none.                                                                                                                                                                           | `audit:LayoutPanel/accessibility` |
+| FR6       | `LayoutSlots.test.tsx` ref and className tests                                                                                                              | Ref; caller class                                 | A ref on another element or a dropped class fails. Gap: no test covers `style`, DOM, data, or event props, or the `xstyle` merge order.                                                                                                                                                                  | `audit:LayoutPanel/api`           |
+| PR1       | Source review                                                                                                                                               | Every state                                       | Gap: no automated check fails if LayoutPanel adds a listener, timer, or measurement.                                                                                                                                                                                                                     | `audit:LayoutPanel/behavior`      |
+
+## 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, Layout slot rules, resize interaction, or
+container-padding mechanics. It links to their owners.

package/src/Layout/__tests__/Layout.a11y.chromium.spec.ts

@@ -93,15 +93,27 @@ async function runState(
   });
 }
 
-test('every Landmark expectation is exercised by at least one Layout state', async ({
-  page,
-}) => {
-  const cdp = await page.context().newCDPSession(page);
+// Checking coverage runs every state again, which on a loaded runner nears
+// the per-test timeout as one test. It runs as one serial part per state,
+// sharing their results, then one check over all of them.
+test.describe('every Landmark expectation is exercised by at least one Layout state', () => {
+  test.describe.configure({mode: 'serial'});
   const results: BindingResult[] = [];
+
   for (const state of LAYOUT_LANDMARK_A11Y_STATES) {
-    results.push(await runState(page, cdp, state));
+    test(`runs ${state.id}`, async ({page}) => {
+      const cdp = await page.context().newCDPSession(page);
+      results.push(await runState(page, cdp, state));
+    });
   }
-  expect(neverExercised(results)).toEqual([]);
+
+  test('no expectation is left unexercised', () => {
+    // Every part ran in this worker; this test alone proves nothing.
+    expect(results.map(result => result.state).sort()).toEqual(
+      LAYOUT_LANDMARK_A11Y_STATES.map(state => state.id).sort(),
+    );
+    expect(neverExercised(results)).toEqual([]);
+  });
 });
 
 for (const state of LAYOUT_LANDMARK_A11Y_STATES) {

package/src/Lightbox/Lightbox.test.tsx

@@ -132,6 +132,24 @@ describe('Lightbox', () => {
     expect(onOpenChange).toHaveBeenCalledWith(false);
   });
 
+  it('ignores a cancel that bubbles up from inside it', () => {
+    const onOpenChange = vi.fn();
+    render(
+      <Lightbox
+        isOpen={true}
+        onOpenChange={onOpenChange}
+        media={{src: '/photo.jpg', alt: 'Photo'}}
+      />,
+    );
+    // Only a close request fired at the <dialog> itself dismisses; a bubbling
+    // `cancel` from a control inside (a dismissed file picker) does not.
+    const inside = document.querySelector('dialog button')!;
+    const fromInside = new Event('cancel', {bubbles: true, cancelable: true});
+    inside.dispatchEvent(fromInside);
+    expect(onOpenChange).not.toHaveBeenCalled();
+    expect(fromInside.defaultPrevented).toBe(false);
+  });
+
   it('calls onOpenChange(false) on Escape via cancel event', () => {
     const onOpenChange = vi.fn();
     render(

package/src/Lightbox/Lightbox.tsx

@@ -459,6 +459,11 @@ export function Lightbox({
   // only, and never while an IME composition is in progress.
   const handleCancel = useCallback(
     (e: React.SyntheticEvent) => {
+      // A cancel that bubbles up from inside (a dismissed file picker) is not
+      // a close request; the platform's is fired at the dialog itself.
+      if (e.target !== e.currentTarget) {
+        return;
+      }
       e.preventDefault();
       if (!shouldDismissOnCloseRequest()) {
         return;

package/src/Lightbox/LightboxViewport.a11y.browser.spec.ts

@@ -57,11 +57,15 @@ test('the viewer is as tall as the dynamic viewport, so a toolbar never covers i
       }
     };
     for (const sheet of Array.from(document.styleSheets)) {
-      try {
-        walk(sheet.cssRules);
-      } catch {
-        // A cross-origin stylesheet's rules are unreadable and not ours.
+      // A cross-origin stylesheet's rules are unreadable, and not ours: skip
+      // only such a sheet, so any other error still fails the proof.
+      if (
+        sheet.href != null &&
+        new URL(sheet.href, document.baseURI).origin !== location.origin
+      ) {
+        continue;
       }
+      walk(sheet.cssRules);
     }
     return {heights, supported: CSS.supports('height', '100dvh')};
   });

package/src/Link/Link.spec.md

@@ -16,6 +16,7 @@ verified_by:
     packages/core/src/Link/__tests__/Link.a11y.test.tsx,
     packages/core/src/Link/__tests__/Link.a11y.chromium.spec.ts,
     packages/core/src/Link/__tests__/Link.navigation.a11y.chromium.spec.ts,
+    packages/core/src/Link/__tests__/Link.truncation.a11y.chromium.spec.ts,
   ]
 modules: []
 families: [family:navigation-destinations]
@@ -107,7 +108,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | FR3  | An external Link that is not rendered as a button shows a trailing extra-small external-link icon that inherits the root's color, followed by visually hidden new-tab text: `newTabLabel`, else the localized default.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Current source and tests                                                                          |
 | FR4  | A destination reaches the link component only through the shared navigation rule; a rejected destination renders an inert anchor and never invokes a router.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `family:navigation-destinations` FR1–FR6; `spec:AST-005`                                          |
 | FR5  | A disabled Link stays focusable with `aria-disabled="true"`, never navigates, and never runs `onClick`. The disabled anchor form omits `href`, `target`, and `rel`, takes a Tab stop, and skips the custom link component. In every form, clicks are cancelled and stopped, Enter and Space are suppressed, other keys reach the caller's `onKeyDown`, and the Link paints at half opacity with no pointer events and no press paint. A focused Link that becomes disabled MUST keep focus and expose the change on that element (`spec:AST-085` FR4, FR5), and a caller `aria-disabled`, `role`, or `tabIndex` MUST NOT replace the disabled exposure (`architecture:public-component-api` INV5). Implementation gap: caller props spread after Link's own, so a caller `aria-disabled`, `role`, or `tabIndex` overrides them. Implementation gap: an enabled link renders through the safe link component and a disabled one as a plain anchor (or a `<button>` when it has `onClick`), so a focused link that becomes disabled (or re-enabled) is replaced and focus falls to the page. | `spec:AST-085` FR1, FR2, FR4, FR5; `family:navigation-destinations` FR7; current tests            |
-| FR6  | Children render inside Text with `type` (default `body`), `size`, `weight`, `color` (default `accent`), `display` (default `inline`), and `maxLines` (default `0`). The root inherits font family, size, weight, and line height and lays content out with a small gap; `isStandalone` sets the body size and leading on the root. A Link inside a Text with `maxLines` MUST truncate with that text. Implementation gap: the root is `inline-flex`, so an ancestor Text clamp does not truncate it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests                                                                          |
+| FR6  | Children render inside Text with `type` (default `body`), `size`, `weight`, `color` (default `accent`), `display` (default `inline`), and `maxLines` (default `0`). The root inherits font family, size, weight, and line height and lays content out with a small gap; with `maxLines` above 0 it stops at its container, so its Text truncates inside a constrained line; `isStandalone` sets the body size and leading on the root. A Link inside a Text with `maxLines` MUST truncate with that text. Implementation gap: the root is `inline-flex`, so an ancestor Text clamp does not truncate it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Current source and tests                                                                          |
 | FR7  | The root paints the chosen color for the six built-in colors, which the underline and the external icon take; the label's color comes from Text (FR6). On hover-capable pointers an enabled Link underlines on hover, and for `primary`, `secondary`, and `accent` the root color mixes in the hover tint. `hasUnderline` underlines at rest.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Current source and tests                                                                          |
 | FR8  | Press feedback follows `design:user-states` DR1 and DR2 for Link's text surface: an enabled link or button form paints the pressed overlay, and a disabled Link does not.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `design:user-states` DR1, DR2; current tests                                                      |
 | FR9  | `label`, when non-empty, becomes `aria-label` and replaces the content as the accessible name; a caller `aria-label` overrides it; otherwise the content is the name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Current tests                                                                                     |
@@ -191,7 +192,7 @@ carries no anatomy-theming map.
 | FR2, FR3, AR3    | `Link.test.tsx` external, target, rel, and new-tab cases; `Link.a11y.chromium.spec.ts` external state             | External; explicit `_blank`; custom label                | A missing safety token, icon, or new-tab text fails. Evidence gap: no test checks the accessible name of an external link with `label`. Evidence gap: no test sets `referrerPolicy` or asserts the external icon's size or color.                                                                                                       | `audit:Link/accessibility` |
 | FR4              | `Link.navigation.a11y.chromium.spec.ts`                                                                           | Rejected and ordinary schemes; native, router, downloads | A rejected destination that navigates or reaches a router fails.                                                                                                                                                                                                                                                                        | `audit:Link/behavior`      |
 | FR5, AR2         | `Link.test.tsx` disabled cases                                                                                    | Disabled anchor; disabled button form; with `onClick`    | Navigation, a consumer `onClick`, a lost Tab stop, or a custom component on a disabled link fails. Evidence gap: no test disables a focused link or passes a caller `aria-disabled`, `role`, or `tabIndex`. Evidence gap: no test asserts that other keys reach the caller's `onKeyDown`, or the half-opacity, no-pointer-events paint. | `audit:Link/accessibility` |
-| FR6 (type)       | `Link.test.tsx` text-type cases                                                                                   | Default `body`; `type="inherit"`                         | A dropped Text `type` fails. Evidence gap: no test asserts that `size`, `weight`, `color`, `display`, or `maxLines` reach Text, or the `isStandalone` root size.                                                                                                                                                                        | `audit:Link/visual`        |
+| FR6 (type)       | `Link.test.tsx` text-type cases                                                                                   | Default `body`; `type="inherit"`                         | A dropped Text `type` fails. `Link.truncation.a11y.chromium.spec.ts`: an anchor and a button Link with `maxLines={1}` in a fixed-width line stop at the line and draw an ellipsis. Evidence gap: no test asserts that `size`, `weight`, `color`, or `display` reach Text, or the `isStandalone` root size.                                   | `audit:Link/visual`        |
 | FR6, FR7 (paint) | Evidence gap: the color, underline, and standalone cases assert only that a link renders; hover paint is untested | Each color; `hasUnderline`; `isStandalone`               | —                                                                                                                                                                                                                                                                                                                                       | `audit:Link/visual`        |
 | FR8              | `Link.test.tsx` pressed-state suite                                                                               | Link, button form, disabled                              | No press paint, or press paint on a disabled Link, fails.                                                                                                                                                                                                                                                                               | `audit:Link/behavior`      |
 | FR9, FR11, AR4   | `Link.test.tsx` label, ref, and theme-class cases                                                                 | With and without `label`; `data-color`                   | A missing or extra `aria-label`, target, `data-color`, or ref fails. The accessibility suites assert a passed `data-*` attribute and `aria-current` on the root, and the navigation suite asserts `download`. Evidence gap: no test passes both `label` and `aria-label`, or passes `className`, `style`, or `xstyle`.                  | `audit:Link/theming`       |

package/src/Link/Link.tsx

@@ -76,6 +76,14 @@ const styles = stylex.create({
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
   },
+  // A truncating label needs a box that stops at its container: an
+  // inline-flex root otherwise grows to its whole text, so its Text never
+  // overflows and draws no ellipsis (`component:Link` FR6, `component:Text`
+  // FR4).
+  truncating: {
+    maxWidth: '100%',
+    minWidth: 0,
+  },
   /**
    * Reset styles for rendering as a <button> when href is undefined.
    * Strips all native button chrome so it looks identical to a link.
@@ -370,6 +378,7 @@ export function Link({
             hasUnderline && styles.hasUnderline,
             isStandalone && styles.standalone,
             isDisabled && styles.disabled,
+            maxLines > 0 && styles.truncating,
             xstyle,
           ),
           className,
@@ -403,6 +412,7 @@ export function Link({
             hasUnderline && styles.hasUnderline,
             isStandalone && styles.standalone,
             styles.disabled,
+            maxLines > 0 && styles.truncating,
             xstyle,
           ),
           className,
@@ -434,6 +444,7 @@ export function Link({
             hasUnderline && styles.hasUnderline,
             isStandalone && styles.standalone,
             isDisabled && styles.disabled,
+            maxLines > 0 && styles.truncating,
             xstyle,
           ),
           className,