@astryxdesign/core 0.7.4 → 0.7.5-canary.0418c47

package/src/Skeleton/Skeleton.spec.md

@@ -1,40 +1,59 @@
 ---
 schema_version: 3
-template_version: 3
+template_version: 7
 kind: component
 id: component:Skeleton
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-25
 owners: [cixzhang]
-review_triggers: [theming]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
 verified_by:
-  [packages/core/src/Skeleton/Skeleton.test.tsx, scripts/check-knowledge.mjs]
+  [
+    packages/core/src/Skeleton/Skeleton.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    apps/storybook/stories/Skeleton.stories.tsx,
+    scripts/check-knowledge.mjs,
+  ]
 modules: []
 families: []
 design_specs: []
 architecture:
   [architecture:component-theming-surface, architecture:public-component-api]
 contributing: []
-system_specs: []
+system_specs: [spec:AST-009]
 ---
 
 # Skeleton component contract
 
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                               |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | A placeholder block with `width`, `height`, `radius`, and a stagger `index`.                                                                           |
+| Behavior                | The block is hidden from assistive technology, waits one second, then pulses its opacity in ten steps; reduced motion keeps it static.                 |
+| End-user impact         | Sighted users see the shape of content that is loading; screen-reader users are not given empty placeholders; high-contrast users still see the block. |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                           |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. No implementation gap is recorded.                                          |
+| Review checks           | Reject an exposed-by-default placeholder, a `steps()` timing function, a pulse under reduced motion, or a block that disappears under forced colors.   |
+| Governing rules         | `architecture:component-theming-surface/INV2`; `architecture:public-component-api/INV5,INV6,INV8`.                                                     |
+
+This table is a review projection; the body below is authoritative.
+
 ## Intent
 
-Skeleton renders a placeholder shape while surrounding content loads. This draft
-records the component's current consumer anatomy and theming ownership without
-changing its runtime contract.
+Skeleton stands in for content while it loads, so a page keeps its layout and
+shows where content will appear. It owns the placeholder's shape, paint, pulse,
+and its exclusion from the accessibility tree.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
-  targets, and public API remain unchanged
-- Controlled/uncontrolled behavior: not applicable
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  styling, or target output changes
+- Controlled/uncontrolled behavior: not applicable; Skeleton holds no state
 - Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
@@ -43,51 +62,85 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 **Owns**
 
-- The rendered placeholder shape and its existing `skeleton` theming target.
+- The placeholder block, its `skeleton` theming target, size, and radius.
+- Its paint in normal, increased-contrast, and forced-color modes.
+- The delayed, staggered opacity pulse and its reduced-motion suppression.
+- Its default exclusion from the accessibility tree.
 
 **Does not own / non-goals**
 
-- The surrounding content's loading state, layout, or replacement timing — owned
-  by the product callsite.
+- The surrounding region's loading state, busy semantics, layout, and when real
+  content replaces the placeholder — owned by the product callsite.
+- Indeterminate progress without a known shape — owned by
+  `component:Spinner`.
 
 ## Public concepts
 
-No new public concept is introduced. Consumer props and usage remain documented
-in `Skeleton.doc.mjs`.
+| Concept | Closed values or states                                 | Meaning                                             | Availability by variant/orientation/state | Default | Owner                | Stability | Invalid-value behavior                      |
+| ------- | ------------------------------------------------------- | --------------------------------------------------- | ----------------------------------------- | ------- | -------------------- | --------- | ------------------------------------------- |
+| Size    | `width` and `height`: a number of pixels or a CSS value | The block's dimensions.                             | Always                                    | `100%`  | `component:Skeleton` | Stable    | A string passes through as CSS.             |
+| Radius  | `none`, `0`, `1`, `2`, `3`, `4`, `rounded`              | Corner radius from the radius scale.                | Always                                    | `3`     | `component:Skeleton` | Stable    | TypeScript rejects other values.            |
+| Stagger | non-negative integer `index`                            | Delays the pulse so sequential placeholders ripple. | Always                                    | `0`     | `component:Skeleton` | Stable    | Any number is applied in the delay formula. |
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                 | Basis                           | Draft review state                                 |
-| --- | ----------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
-| FR1 | The current render contains one painted placeholder carrying the `skeleton` target. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                    |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | Skeleton renders one childless `div` carrying the `skeleton` target, sized by `width` and `height` (numbers in pixels, strings as CSS), default `100%` each.                                                                                                                                                                                                                                                | Current source and tests |
+| FR2 | `radius` maps `none` to no radius, `0` to `--radius-none`, `1` to `--radius-inner`, `2` to `--radius-element`, `3` and `4` to `--radius-container`, and `rounded` to `--radius-full`; the default is `3`.                                                                                                                                                                                                   | Current source           |
+| FR3 | The block paints `--color-skeleton` at opacity 0.25. Under `prefers-contrast: more` it paints that color mixed 30% toward primary text. Under `forced-colors: active` it paints `GrayText`, which wins over the contrast rule, at full opacity while no pulse runs; with motion allowed the FR4 pulse still varies its opacity.                                                                             | Current source and tests |
+| FR4 | The block pulses its opacity from 0.25 to 0.925 in ten equal held steps and back, alternating indefinitely, each climb and each fall taking `--duration-medium-max` as the theme sets it before `tempo` scales it (`spec:AST-108` FR4), with a linear timing function and no `steps()`. The pulse starts after 1000 ms plus 100 ms times `index`. Under `prefers-reduced-motion: reduce` there is no pulse. | Current source and tests |
+| FR5 | `ref` reaches the block. Supported DOM, ARIA, data, and event props, including `data-testid`, reach the block after the default `aria-hidden`; `xstyle`, `className`, and `style` merge in that order after component styles.                                                                                                                                                                               | Current source and tests |
 
 ### Allowed variation
 
-- This documentation does not constrain behavior beyond the factual anatomy and
-  target relationship recorded here.
+- **AV1 — Theme paint.** A theme may change the block's visual properties through
+  `skeleton` without changing its anatomy or accessibility exclusion.
+- **AV2 — Shape.** Width, height, and radius vary per callsite to match the
+  content they stand in for.
 
 ### Representative states
 
-- The anatomy and target relationship is the same for the documented size,
-  radius, and animation inputs.
+| State             | Required invariant                                                                                                | Allowed variation |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------- |
+| Default           | `aria-hidden` block at 0.25 opacity, pulsing after one second.                                                    | Size and radius.  |
+| Staggered         | Each block's pulse starts 100 ms after the previous index.                                                        | Number of blocks. |
+| Reduced motion    | Static block at 0.25 opacity.                                                                                     | —                 |
+| Forced colors     | `GrayText` block at full opacity while no pulse runs; with motion allowed the FR4 pulse varies its opacity (AR2). | —                 |
+| Exposed by caller | `aria-hidden={false}` reaches the block.                                                                          | —                 |
 
 ### Transformation and precedence order
 
-- No new ordering rule is introduced.
+- **ORD1 — Paint.** Default skeleton color → increased-contrast mix → forced
+  colors `GrayText`.
+- **ORD2 — Attributes.** `aria-hidden="true"` and `data-testid` → component
+  class → component styles → `xstyle` → `className` → `style` → caller props.
 
 ### Performance and resources
 
-- No new performance or resource rule is introduced.
+- **PR1 — Off-main-thread pulse.** The pulse changes only opacity and uses no
+  stepped timing function, so supported engines can run it without main-thread
+  repaint. Skeleton adds no listener, observer, or timer.
 
 ## Accessibility contract
 
-This draft does not change or extend Skeleton's existing accessibility behavior.
+- **AR1 — Hidden by default.** The block is `aria-hidden="true"`, so
+  assistive technology does not announce empty placeholders; a caller may pass
+  `aria-hidden={false}`. The surrounding region conveys busy state.
+- **AR2 — Forced-color and increased-contrast paint.** The placeholder is
+  decorative. In forced-color mode it paints `GrayText` so it stays visible
+  where the browser would strip its fill, at full opacity while no pulse runs;
+  with motion allowed the FR4 pulse still varies its opacity from 0.25 to
+  0.925. Under increased contrast its color moves 30% toward the primary text
+  color.
+- **AR3 — Reduced motion.** The pulse is removed when the reader asks for
+  reduced motion.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                         | Representation authority       | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------ | ------------------------------ | -------------- | ------------------ |
-| Placeholder      | Represents the current painted loading UI. | Current source and public docs | Supporting     | FR1                |
+| Anatomy or state | Design requirement                                       | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Placeholder      | Previews the shape of loading content with a soft pulse. | Current source and public docs | Supporting     | FR1–FR4, AR1–AR3   |
 
 ### Theming anatomy
 
@@ -101,21 +154,25 @@ This draft does not change or extend Skeleton's existing accessibility behavior.
 
 ## Family and system relationships
 
-This draft references the current shared owners without restating their rules:
-`architecture:component-theming-surface` and
-`architecture:public-component-api`.
+- `architecture:component-theming-surface` owns target qualification for the
+  `skeleton` target.
+- `architecture:public-component-api` owns ref, passthrough, and styling-input
+  rules; FR5 applies them to the block.
 
 ## Verification map
 
-| Contract            | Verification                     | Representative states                | Mutation or failure expectation                                         | Audit section            |
-| ------------------- | -------------------------------- | ------------------------------------ | ----------------------------------------------------------------------- | ------------------------ |
-| FR1                 | `Skeleton.test.tsx` render suite | A rendered placeholder               | Removing the placeholder fails the existing render assertion.           | `audit:Skeleton/anatomy` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`    | Canonical anatomy and current target | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:Skeleton/theming` |
+| Contract            | Verification                                                          | Representative states                             | Mutation or failure expectation                                                                                                                                                                                                                                               | Audit section            |
+| ------------------- | --------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1, FR5, AR1       | `Skeleton.test.tsx` render and a11y tests                             | Default; caller `aria-hidden={false}`             | Removing the block, the default `aria-hidden`, or the caller override fails. Gap: no test covers the ref, the default `100%` size, or the styling-input order.                                                                                                                | `audit:Skeleton/a11y`    |
+| FR4, PR1, AR3       | `Skeleton.test.tsx` pulse suite                                       | Compiled keyframes and timing                     | A `steps()` timing function or changed opacity steps fails. Gap: the duration, opacity-only keyframes, the start delay, the per-index stagger, and the reduced-motion removal have no automated check.                                                                        | `audit:Skeleton/motion`  |
+| FR3, AR2            | `Skeleton.test.tsx` forced-colors suite                               | Forced colors                                     | Dropping the `GrayText` or full-opacity override from the compiled CSS fails. Gap: the increased-contrast mix, and which rule wins when both media features apply, have no automated check, forced-colors rendering, including the pulse there, is not verified in a browser. | `audit:Skeleton/a11y`    |
+| FR1–FR3             | `Skeleton.stories.tsx` Shapes and StaggeredList fixtures in a browser | Radii `rounded`, `3`, `2`, `none`; staggered list | Gap: no unit test asserts size, radius, or the increased-contrast paint, and no fixed story renders radius `0`, `1`, or `4` or increased-contrast mode; other values are visible only in the rendered fixtures.                                                               | `audit:Skeleton/layout`  |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                         | Canonical anatomy and current target              | Missing, extra, prefixed, or stale mappings fail repository validation.                                                                                                                                                                                                       | `audit:Skeleton/theming` |
+| AR1                 | Accessibility-tree evidence (`spec:AST-009` FR3)                      | Default and exposed placeholder                   | Gap: no accessibility-tree check proves the placeholder is absent from the tree; the unit test asserts the attribute.                                                                                                                                                         | `audit:Skeleton/a11y`    |
 
 ## Decision log
 
-None. This draft records current facts and introduces no component-local design
-decision.
+None recorded. The record describes shipped behavior.
 
 ## Open questions
 
@@ -123,5 +180,5 @@ None.
 
 ## Content boundary
 
-This file does not duplicate consumer prop tables, examples, implementation
-steps, or system rules. It links to their owners.
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.

package/src/Skeleton/Skeleton.test.tsx

@@ -3,7 +3,63 @@
 import {describe, it, expect} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {Skeleton} from './Skeleton';
-import {getForcedColorsRules} from '../__tests__/forcedColors';
+import {
+  getAllInjectedCss,
+  getForcedColorsRules,
+} from '../__tests__/forcedColors';
+
+/** The declarations the element's atomic classes carry, as `prop: value`. */
+function declarationsOf(el: Element, css: string): string[] {
+  const out: string[] = [];
+  for (const cls of Array.from(el.classList)) {
+    const re = new RegExp(`\\.${cls}\\b[^{]*\\{([^}]*)\\}`, 'g');
+    for (const match of css.matchAll(re)) {
+      out.push(
+        ...match[1]
+          .split(';')
+          .map(d => d.trim())
+          .filter(Boolean),
+      );
+    }
+  }
+  return out;
+}
+
+/** The whole `@keyframes <name> { … }` rule, braces matched. */
+function keyframesRule(css: string, name: string): string {
+  const start = css.search(new RegExp(`@keyframes ${name}\\b`, 'i'));
+  expect(start).toBeGreaterThanOrEqual(0);
+  let depth = 0;
+  for (let i = css.indexOf('{', start); i < css.length; i += 1) {
+    if (css[i] === '{') {
+      depth += 1;
+    }
+    if (css[i] === '}' && --depth === 0) {
+      return css.slice(start, i + 1);
+    }
+  }
+  throw new Error(`unterminated @keyframes ${name}`);
+}
+
+/** The named animation's opacity keyframes as [offset 0..1, opacity], in order. */
+function opacityKeyframes(css: string, name: string): [number, number][] {
+  return Array.from(
+    keyframesRule(css, name).matchAll(/([\d.]+)%\s*\{\s*opacity:\s*([\d.]+)/g),
+    m => [Number(m[1]) / 100, Number(m[2])] as [number, number],
+  );
+}
+
+/** Opacity at iteration progress x, linear between keyframes. */
+function opacityAt(frames: [number, number][], x: number): number {
+  for (let i = 1; i < frames.length; i += 1) {
+    const [x0, y0] = frames[i - 1];
+    const [x1, y1] = frames[i];
+    if (x <= x1) {
+      return x1 === x0 ? y1 : y0 + ((y1 - y0) * (x - x0)) / (x1 - x0);
+    }
+  }
+  return frames[frames.length - 1][1];
+}
 
 describe('Skeleton', () => {
   it('renders a placeholder element', () => {
@@ -25,6 +81,57 @@ describe('Skeleton', () => {
   });
 });
 
+describe('pulse', () => {
+  function pulse() {
+    render(<Skeleton width={200} height={20} data-testid="sk" />);
+    const css = getAllInjectedCss();
+    const declarations = declarationsOf(screen.getByTestId('sk'), css);
+    const value = (prop: string) =>
+      declarations
+        .filter(d => d.startsWith(`${prop}:`))
+        .map(d => d.slice(prop.length + 1).trim());
+    return {css, value};
+  }
+
+  // WebKit runs no animation with a steps() timing function on the
+  // compositor, so a stepped pulse would freeze in Safari while a script runs.
+  it('keeps steps() out of the timing function so every engine can composite it', () => {
+    const {css, value} = pulse();
+    expect(value('animation-timing-function')).toEqual(['linear']);
+    expect(value('animation-direction')).toEqual(['alternate']);
+    expect(value('animation-iteration-count')).toEqual(['infinite']);
+    const name = value('animation-name').find(v => v !== 'none');
+    expect(name).toBeTruthy();
+    const rule = keyframesRule(css, name ?? '');
+    expect(rule).toMatch(/opacity/);
+    expect(rule).not.toMatch(/steps\(|animation-timing-function/);
+  });
+
+  it('climbs and falls through the same ten opacity steps at the same times', () => {
+    const {css, value} = pulse();
+    const name = value('animation-name').find(v => v !== 'none') ?? '';
+    const frames = opacityKeyframes(css, name);
+    expect(frames[0]).toEqual([0, 0.25]);
+    // The previous pulse: 0.25 → 1 through steps(10, end), played back down
+    // by `alternate`. Sample each tenth away from its edges.
+    for (let step = 0; step < 10; step += 1) {
+      for (const within of [0.02, 0.5, 0.98]) {
+        const x = (step + within) / 10;
+        const expected = 0.25 + 0.75 * (step / 10);
+        expect(opacityAt(frames, x)).toBeCloseTo(expected, 6);
+      }
+    }
+    // Each change between steps takes 0.01% of an iteration.
+    for (let i = 1; i < frames.length; i += 1) {
+      const [x0, y0] = frames[i - 1];
+      const [x1, y1] = frames[i];
+      if (y1 !== y0) {
+        expect(x1 - x0).toBeCloseTo(0.0001, 6);
+      }
+    }
+  });
+});
+
 // jsdom cannot emulate forced-colors rendering, so these assert that the
 // compiled output includes the forced-colors rules; visual behavior needs
 // manual verification under Windows High Contrast.

package/src/Skeleton/Skeleton.tsx

@@ -39,9 +39,36 @@ const STAGGER_TIME = 100;
 // Animation Keyframes
 // =============================================================================
 
+/**
+ * The pulse climbs from 0.25 to 0.925 opacity in ten equal steps, then plays
+ * back down (`alternate`). The steps are written out as holds joined by
+ * 0.01% ramps, with a linear timing function, rather than produced by a
+ * `steps()` timing function: WebKit never runs a `steps()` animation on the
+ * compositor, so Safari would repaint the pulse on the main thread and freeze
+ * it whenever a script runs. These keyframes give the same values at the same
+ * times, which every engine can animate off the main thread.
+ */
 const skeletonFade = stylex.keyframes({
   '0%': {opacity: 0.25},
-  '100%': {opacity: 1},
+  '9.99%': {opacity: 0.25},
+  '10%': {opacity: 0.325},
+  '19.99%': {opacity: 0.325},
+  '20%': {opacity: 0.4},
+  '29.99%': {opacity: 0.4},
+  '30%': {opacity: 0.475},
+  '39.99%': {opacity: 0.475},
+  '40%': {opacity: 0.55},
+  '49.99%': {opacity: 0.55},
+  '50%': {opacity: 0.625},
+  '59.99%': {opacity: 0.625},
+  '60%': {opacity: 0.7},
+  '69.99%': {opacity: 0.7},
+  '70%': {opacity: 0.775},
+  '79.99%': {opacity: 0.775},
+  '80%': {opacity: 0.85},
+  '89.99%': {opacity: 0.85},
+  '90%': {opacity: 0.925},
+  '100%': {opacity: 0.925},
 });
 
 // =============================================================================
@@ -78,7 +105,8 @@ const styles = stylex.create({
       default: skeletonFade,
       '@media (prefers-reduced-motion: reduce)': 'none',
     },
-    animationTimingFunction: 'steps(10, end)',
+    // Linear between the keyframes' holds; see skeletonFade.
+    animationTimingFunction: 'linear',
   },
 });
 

package/src/Slider/Slider.test.tsx

@@ -19,6 +19,7 @@ import {
 } from '../__tests__/pressState';
 import * as stylex from '@stylexjs/stylex';
 import {Slider} from './Slider';
+import {FormLayout} from '../FormLayout';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {
   __resetInteractionModalityForTest,
@@ -1330,6 +1331,177 @@ describe('Slider', () => {
   });
 });
 
+describe('one pointer per drag', () => {
+  // valueDisplay="none" keeps the thumb a direct child of the track, so the
+  // mocked rect lands on it: 200 px wide, thumbs travel 10 px (0) to 190 px
+  // (100), value = (x - 10) / 1.8.
+  function ControlledSlider({
+    id,
+    onChangeEnd,
+  }: {
+    id: string;
+    onChangeEnd?: (value: number) => void;
+  }) {
+    const [value, setValue] = useState(50);
+    return (
+      <Slider
+        label={id}
+        value={value}
+        min={0}
+        max={100}
+        valueDisplay="none"
+        onChange={setValue}
+        onChangeEnd={onChangeEnd}
+      />
+    );
+  }
+
+  function trackOf(thumb: HTMLElement): HTMLElement {
+    const track = thumb.parentElement!;
+    track.getBoundingClientRect = () => ({
+      left: 0,
+      top: 0,
+      right: 200,
+      bottom: 20,
+      width: 200,
+      height: 20,
+      x: 0,
+      y: 0,
+      toJSON: () => {},
+    });
+    return track;
+  }
+
+  it('ignores a second finger that lands, moves or lifts during a drag', () => {
+    const onChangeEnd = vi.fn();
+    render(<ControlledSlider id="Volume" onChangeEnd={onChangeEnd} />);
+    const thumb = screen.getByRole('slider');
+    const track = trackOf(thumb);
+
+    fireEvent.pointerDown(track, {clientX: 100, clientY: 10, pointerId: 1});
+    fireEvent.pointerDown(track, {clientX: 28, clientY: 10, pointerId: 2});
+    expect(thumb).toHaveAttribute('aria-valuenow', '50');
+
+    fireEvent.pointerMove(track, {clientX: 136, clientY: 10, pointerId: 1});
+    fireEvent.pointerMove(track, {clientX: 46, clientY: 10, pointerId: 2});
+    expect(thumb).toHaveAttribute('aria-valuenow', '70');
+
+    // The second finger lifting does not end the first finger's drag.
+    fireEvent.pointerUp(track, {clientX: 46, clientY: 10, pointerId: 2});
+    expect(onChangeEnd).not.toHaveBeenCalled();
+    expect(declaresPressedOverlay(thumb)).toBe(true);
+
+    fireEvent.pointerMove(track, {clientX: 154, clientY: 10, pointerId: 1});
+    fireEvent.pointerUp(track, {clientX: 154, clientY: 10, pointerId: 1});
+    expect(thumb).toHaveAttribute('aria-valuenow', '80');
+    expect(onChangeEnd).toHaveBeenCalledOnce();
+    expect(onChangeEnd).toHaveBeenCalledWith(80);
+    expect(declaresPressedOverlay(thumb)).toBe(false);
+  });
+
+  it('ends the drag when its pointer capture is lost without an up', () => {
+    const onChangeEnd = vi.fn();
+    render(<ControlledSlider id="Volume" onChangeEnd={onChangeEnd} />);
+    const thumb = screen.getByRole('slider');
+    const track = trackOf(thumb);
+
+    fireEvent.pointerDown(track, {clientX: 136, clientY: 10, pointerId: 1});
+    fireEvent.lostPointerCapture(track, {pointerId: 1});
+    expect(onChangeEnd).toHaveBeenCalledOnce();
+    expect(onChangeEnd).toHaveBeenCalledWith(70);
+    expect(declaresPressedOverlay(thumb)).toBe(false);
+
+    // The slider answers the next press.
+    fireEvent.pointerDown(track, {clientX: 28, clientY: 10, pointerId: 3});
+    expect(thumb).toHaveAttribute('aria-valuenow', '10');
+  });
+
+  it('ends the drag when its control node is replaced mid-drag and the capture is lost', () => {
+    // A FormLayout direction change re-renders the field in another layout,
+    // replacing the control node while the drag holds it. The browser then
+    // fires lostpointercapture at the document, not at the removed node.
+    const onChangeEnd = vi.fn();
+    function InLayout({
+      direction,
+    }: {
+      direction: 'vertical' | 'horizontal-labels';
+    }) {
+      return (
+        <FormLayout direction={direction}>
+          <ControlledSlider id="Volume" onChangeEnd={onChangeEnd} />
+        </FormLayout>
+      );
+    }
+    const {rerender} = render(<InLayout direction="vertical" />);
+    const before = trackOf(screen.getByRole('slider'));
+    fireEvent.pointerDown(before, {clientX: 136, clientY: 10, pointerId: 1});
+
+    rerender(<InLayout direction="horizontal-labels" />);
+    fireEvent.lostPointerCapture(document, {pointerId: 1});
+    expect(onChangeEnd).toHaveBeenCalledOnce();
+
+    // The slider answers the next press on whichever node it renders now.
+    const thumb = screen.getByRole('slider');
+    const after = trackOf(thumb);
+    fireEvent.pointerDown(after, {clientX: 28, clientY: 10, pointerId: 3});
+    expect(thumb).toHaveAttribute('aria-valuenow', '10');
+  });
+
+  it('holds a document listener only while a drag is in progress', () => {
+    const add = vi.spyOn(document, 'addEventListener');
+    const remove = vi.spyOn(document, 'removeEventListener');
+    const lostCapture = (spy: typeof add) =>
+      spy.mock.calls.filter(([type]) => type === 'lostpointercapture');
+    const {unmount} = render(<ControlledSlider id="Volume" />);
+    const track = trackOf(screen.getByRole('slider'));
+    // Idle: no document listener.
+    expect(lostCapture(add)).toHaveLength(0);
+
+    fireEvent.pointerDown(track, {clientX: 136, clientY: 10, pointerId: 1});
+    expect(lostCapture(add)).toHaveLength(1);
+    const listener = lostCapture(add)[0][1];
+    fireEvent.pointerUp(track, {clientX: 136, clientY: 10, pointerId: 1});
+    expect(lostCapture(remove).map(([, fn]) => fn)).toEqual([listener]);
+
+    // A slider unmounted mid-drag removes its listener too.
+    fireEvent.pointerDown(track, {clientX: 28, clientY: 10, pointerId: 2});
+    const second = lostCapture(add)[1][1];
+    unmount();
+    expect(lostCapture(remove).map(([, fn]) => fn)).toEqual([listener, second]);
+    add.mockRestore();
+    remove.mockRestore();
+  });
+
+  it('lets two fingers drag two sliders at once', () => {
+    render(
+      <>
+        <ControlledSlider id="Treble" />
+        <ControlledSlider id="Bass" />
+      </>,
+    );
+    const treble = screen.getByRole('slider', {name: 'Treble'});
+    const bass = screen.getByRole('slider', {name: 'Bass'});
+    const trebleTrack = trackOf(treble);
+    const bassTrack = trackOf(bass);
+
+    fireEvent.pointerDown(trebleTrack, {
+      clientX: 100,
+      clientY: 10,
+      pointerId: 1,
+    });
+    fireEvent.pointerDown(bassTrack, {clientX: 100, clientY: 10, pointerId: 2});
+    fireEvent.pointerMove(trebleTrack, {
+      clientX: 154,
+      clientY: 10,
+      pointerId: 1,
+    });
+    fireEvent.pointerMove(bassTrack, {clientX: 28, clientY: 10, pointerId: 2});
+
+    expect(treble).toHaveAttribute('aria-valuenow', '80');
+    expect(bass).toHaveAttribute('aria-valuenow', '10');
+  });
+});
+
 describe('pressed state', () => {
   it('paints the pressed overlay on the thumb for as long as it is dragged, from wherever the press lands', () => {
     render(