@astryxdesign/core 0.7.5 → 0.7.6-canary.0135af4

package/src/Lightbox/Lightbox.spec.md

@@ -3,31 +3,34 @@ schema_version: 3
 template_version: 3
 kind: component
 id: component:Lightbox
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang]
-review_triggers: [behavior, theming, accessibility]
+review_triggers: [public-api, behavior, interaction, theming, accessibility]
 verified_by:
   [
     packages/core/src/Lightbox/Lightbox.test.tsx,
+    packages/core/src/Lightbox/LightboxKeyboard.a11y.browser.spec.ts,
+    packages/core/src/Lightbox/LightboxViewport.a11y.browser.spec.ts,
     packages/core/src/theme/themingTargets.test.ts,
     scripts/check-knowledge.mjs,
   ]
 modules: []
 families: [family:overlay-dismissal]
-design_specs: []
+design_specs: [design:reduced-motion]
 architecture:
   [
     architecture:component-theming-surface,
     architecture:interaction-modality,
     architecture:layer-runtime,
     architecture:public-component-api,
+    architecture:react-component-runtime,
   ]
 contributing: []
-system_specs: []
+system_specs: [spec:AST-017, spec:AST-020, spec:AST-086, spec:AST-094]
 ---
 
 # Lightbox component contract
@@ -35,81 +38,205 @@ system_specs: []
 ## Intent
 
 Lightbox presents one active image or video in a full-viewport viewer and may
-add gallery navigation, a caption, and a position counter. This draft records
-current consumer anatomy and theming ownership without changing runtime
-behavior, styling, targets, or public API.
+add gallery navigation, a caption, and a position counter. On a touch screen it
+behaves like a native photo viewer: a person pinches and double-taps to zoom,
+swipes between items, drags a photo down or pinches it in to close, and taps to
+hide the controls. Every gesture has a button, key, or single-pointer
+alternative, so keyboard, screen-reader, and single-pointer users reach the
+same actions.
 
 ## Compatibility and migration
 
-- Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
-  targets, aliases, and public API remain unchanged
-- Controlled/uncontrolled behavior: unchanged
-- Migration decision: none
+- Released default preserved: `no`. Under a coarse primary pointer the touch
+  presentation (FR5–FR10) and the touch exit (FR16) are the default
+  (`spec:AST-094` FR13). Under a fine pointer a mouse or pen drag pages and
+  closes the viewer, a ctrl-wheel or trackpad pinch over the photo zooms the
+  photo instead of the page, a wheel pans a zoomed photo, and a double-click
+  zooms 2× about the clicked point instead of the centre (FR11). Preserved: a
+  click on the photo keeps the controls, the viewer opens at once under every
+  pointer and closes at once under a fine pointer, keyboard zoom stays 2× about
+  the centre, and video playback and controls are unchanged; a drag on a video
+  item's frame pages (FR7)
+- Compatibility class: additive behavior, released in three kinds under
+  `spec:AST-017`. `[fix]` under FR53, as accessibility conformance: Tab
+  containment (FR4), the double-click about the clicked point (AR2), the `0`
+  key (AR3), and position and zoom announcements delivered inside the open
+  viewer with the zoom level (AR4). `[feat]`: the touch presentation and touch
+  exit (FR5–FR10, FR16) and the fine-pointer gestures (FR11), which are named
+  cross-device consistency under FR59 and need fine-pointer evidence before and
+  after. `[experimental]`: the thumbnail transition and `experimental.sourceFor`
+  (FR12, FR21)
+- Controlled/uncontrolled behavior: unchanged; a swipe reports through
+  `onIndexChange`, and a controlled `index` the caller refuses springs back
+- Migration decision: none required. `hasZoom={false}` turns off FR6, FR9, and
+  FR10 (FR13)
 
 Consumer migration instructions belong in consumer docs and release notes.
 
+## Current-state impact
+
+The shipped Lightbox does not yet meet every requirement below. Each gap names
+the requirement it misses and the person it affects.
+
+- **Touch presentation (FR5–FR10, FR12).** On a touch screen a pinch zooms the
+  page instead of the photo, a double tap zooms 2× about the centre, and there
+  is no swipe paging, drag or pinch to close, tap to hide the controls, or
+  thumbnail transition.
+- **Tab containment (FR4).** Tab from the viewer's last control can move focus
+  to the browser's own interface.
+- **Single-pointer pan (AR2, FR11).** A double-click zooms 2× about the centre,
+  not about the clicked point, so a single-pointer user can reach a zoomed
+  photo's edge only by dragging.
+- **Zoom reset key (AR3).** `0` does not return a zoomed photo to its fitted
+  size.
+- **Zoom announcement (AR4).** A zoom change announces "zoomed in" or "zoomed
+  out" without the zoom level.
+- **Announcements outside the open viewer (AR4).** Position and zoom messages
+  are sent from above the modal Lightbox renders, so they reach the page body
+  and a screen-reader user does not hear them while the viewer is open
+  (`spec:AST-086` FR14).
+- **Lightbox-owned pan listeners (FR14).** The pan drag registers Lightbox's
+  own `window` pointer listeners instead of using the shared touch modules.
+- **Fine-pointer gestures (FR11).** A mouse drag on a fitted photo does
+  nothing, a ctrl-wheel zooms the page, and a wheel does not pan a zoomed photo.
+- **Touch exit (FR16).** On a touch screen the viewer disappears at once when
+  it closes.
+
 ## Ownership boundary
 
 **Owns**
 
 - The Viewer overlay and its current `lightbox` target.
-- Media presentation, optional Caption and Counter placement, gallery navigation,
-  and current image zoom and pan behavior.
+- Media presentation, optional Caption and Counter placement, gallery
+  navigation, image zoom and pan, the touch presentation (FR5–FR12), and the
+  touch exit (FR16).
+- The accessible alternative for every gesture it presents (AR1–AR8).
 
 **Does not own / non-goals**
 
 - The Close, Previous, and Next button surfaces — delegated to
   `component:Button` through IconButton.
 - Caller-provided Caption content.
-- New targets for Media, Caption, or Counter; none exist on current `main`.
-- Shared layer hosting or dismissal policy.
+- New targets for Media, Caption, or Counter; none exist.
+- Shared layer hosting or dismissal policy — owned by
+  `architecture:layer-runtime` and `family:overlay-dismissal`.
+- Touch physics, measured values, and motion roles' values — owned by
+  `spec:AST-094` and its measured motion table.
 
 ## Public concepts
 
-No new public concept is introduced. Consumer props and usage remain documented
-in `Lightbox.doc.mjs`.
+No new stable public concept is introduced. `experimental.sourceFor` is an
+experimental option inside the `experimental` prop object (`spec:AST-017`
+FR21). Consumer props and usage remain documented in `Lightbox.doc.mjs`.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                                                                                                                | Basis                           | Draft review state                                 |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
-| FR1 | The current viewer contains one active Media item and a Close button; galleries additionally contain Previous and Next buttons plus a Counter, and Caption renders only when supplied.                                                                                             | Current source, docs, and tests | Verified current behavior; no new behavior decided |
-| FR2 | Viewer overlay carries the current `lightbox` target. Media, Caption, and Counter carry no Lightbox public target.                                                                                                                                                                 | Current source and public docs  | Verified current reachability; no target change    |
-| FR3 | Close, Previous, and Next button surfaces use Button's `button` target through IconButton rather than Lightbox-owned button targets.                                                                                                                                               | Current source and target docs  | Verified current delegation; no ownership change   |
-| FR4 | The open viewer is a focus region through Core's shared focus-region module (`component:Dialog/DEC-2`): Tab from its last control moves focus to its first and Shift+Tab from its first moves focus to its last, so focus never leaves the viewer for the browser's own interface. | `component:Dialog/DEC-2`        | Owner decision; tests land with the implementation |
+| ID   | Candidate invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Basis                                        | Draft review state          |
+| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | --------------------------- |
+| FR1  | The viewer contains one active Media item and a Close button; galleries additionally contain Previous and Next buttons plus a Counter, and Caption renders only when supplied.                                                                                                                                                                                                                                                                                                                                                                                                      | Current source, docs, and tests              | settled                     |
+| FR2  | Viewer overlay carries the current `lightbox` target. Media, Caption, and Counter carry no Lightbox public target.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Current source and public docs               | settled                     |
+| FR3  | Close, Previous, and Next button surfaces use Button's `button` target through IconButton rather than Lightbox-owned button targets.                                                                                                                                                                                                                                                                                                                                                                                                                                                | Current source and target docs               | settled                     |
+| FR4  | The open viewer is a focus region through Core's shared focus-region module (`component:Dialog/DEC-2`): Tab from its last control moves focus to its first and Shift+Tab from its first moves focus to its last, so focus never leaves the viewer for the browser's own interface.                                                                                                                                                                                                                                                                                                  | `component:Dialog/DEC-2`                     | settled; implementation gap |
+| FR5  | Under a coarse primary pointer, after hydration, Lightbox presents FR6–FR10 with no opt-in. Every spring, duration, and curve they play is a named motion role (zoom settle, page settle, dismiss, pinch close, controls fade, zoom transition) read through the motion role table, never a literal. Under reduced motion they follow AR6.                                                                                                                                                                                                                                          | `spec:AST-094` FR4, FR13                     | settled; implementation gap |
+| FR6  | With `hasZoom`, on an image, a pinch zooms about the fingers and pans while it zooms; past the minimum or maximum the photo resists and eases back without overshoot. A double tap zooms to the larger of filling the viewer and 2×, about the tapped point; a second double tap returns to the fitted size. A zoomed photo pans with momentum and rubber-band edges. A pinch on the controls or the caption still zooms the page.                                                                                                                                                  | `spec:AST-094` FR3, FR10                     | settled; implementation gap |
+| FR7  | In a gallery, a horizontal drag moves the row of items, which sit apart by the measured gap. The release lands on at most one neighbouring item by the projection rule. Paging applies over a video item's frame as over a photo; a drag that starts on the video's own controls, such as its scrubber or volume, stays the video's. A zoomed photo pans to its edge before a new drag pages. A pinch never pages. Previous, Next, and the arrow keys keep paging. A controlled `index` the caller refuses springs back. `onIndexChange` reports a swipe.                           | `spec:AST-094` FR14, FR36–FR39               | settled; implementation gap |
+| FR8  | On a fitted image, a downward drag moves the photo with the finger, shrinks it, and fades the backdrop. The release decides once: a projected travel past the commit point closes the viewer and reports `onOpenChange(false)` at the lift; a release moving back springs back. Video is unchanged.                                                                                                                                                                                                                                                                                 | `spec:AST-094` FR36–FR40                     | settled; implementation gap |
+| FR9  | With `hasZoom`, a pinch in from the fitted size is a release decision: below the measured fraction of the fitted size the release closes the viewer; opening the fingers again by the measured amount before the lift is moving back and cancels. A pinch that starts zoomed in never closes the viewer.                                                                                                                                                                                                                                                                            | `spec:AST-094` FR36, FR37                    | settled; implementation gap |
+| FR10 | With `hasZoom`, under a coarse pointer only, a tap on the photo fades the controls and caption and darkens the backdrop. While they are hidden, the next tap on the photo, a tap beside the photo, or a cancelled drag brings them back, and that tap beside the photo does not close the viewer (ORD3). AR5 governs keyboard and assistive-technology access while they are hidden.                                                                                                                                                                                                | `architecture:public-component-api` INV16    | settled; implementation gap |
+| FR11 | A mouse, a pen, and a trackpad also use FR7's drag paging, FR8's drag to close, a ctrl-wheel or trackpad pinch over the photo for FR6's zoom and FR9's close, and a wheel to pan a zoomed photo; over the photo these replace the browser's page zoom and scroll. A double-click zooms 2× about the clicked point. A click on the photo keeps the controls, and the viewer opens and closes at once.                                                                                                                                                                                | `spec:AST-094` FR43; `spec:AST-017` FR59     | settled; implementation gap |
+| FR12 | Inside `experimental` only, under a coarse pointer, the photo grows out of its source when the viewer opens and returns into it when it closes: the element `experimental.sourceFor(index)` returns, else the opener when it shows a picture. A close reports `onOpenChange(false)` at the request; the viewer stays only until the photo lands. Pointer input during the entrance is held; keys and assistive technology stay live. Without `experimental`, opening is unchanged and closing plays FR16.                                                                           | `spec:AST-017` FR21; `spec:AST-094` FR35     | settled; implementation gap |
+| FR13 | `hasZoom={false}` turns off FR6, FR9, and FR10. FR7 and FR8 add to the buttons, keys, and Escape and remove none of them, so Lightbox takes no `presentation` prop.                                                                                                                                                                                                                                                                                                                                                                                                                 | `architecture:public-component-api` INV16    | settled                     |
+| FR14 | Gestures, paging, motion, and reduced motion run through Core's one shared set of internal touch modules; Lightbox bundles no copy of a module's primitive and adds no gesture listener outside them.                                                                                                                                                                                                                                                                                                                                                                               | `architecture:react-component-runtime` INV13 | settled; implementation gap |
+| FR15 | Lightbox supports a Picture-in-Picture window as its only second document; there it ranks Escape and platform close among that window's members.                                                                                                                                                                                                                                                                                                                                                                                                                                    | `family:overlay-dismissal` FR8               | settled                     |
+| FR16 | Under a coarse primary pointer, a close that is not a drag down (FR8), a pinch in (FR9), or a return into a source (FR12) plays the touch exit: Close, Escape, a platform close, and a tap beside the photo while the controls are shown (ORD3). The photo shrinks a little and fades out in place with the backdrop and controls, as the native viewer's zoom transition does without a source, on its named motion role. `onOpenChange(false)` reports at the request, and the viewer takes no input while the exit plays. Under a fine pointer the viewer closes at once (FR11). | `spec:AST-094` FR7                           | settled; implementation gap |
 
 ### Allowed variation
 
-- **AV1 — Media mode.** Media may be an image or video; zoom and pan are available
-  only on the current image path.
+- **AV1 — Media mode.** Media may be an image or video; zoom, pan, drag down to
+  close, pinch to close, and the tap that hides the controls are available only
+  on images. Paging applies to both (FR7).
 - **AV2 — Gallery mode.** Previous, Next, and Counter are absent for a single
   item. Navigation button disabled state follows the current gallery boundary.
 - **AV3 — Caption content.** Caller-provided Caption content may vary without
   becoming a Lightbox-owned target.
+- **AV4 — Measured values.** Thresholds, gaps, commit points, and timings may
+  change with the measured motion table without changing this record.
 
 ### Representative states
 
-| State            | Required invariant                                                  | Allowed variation                             |
-| ---------------- | ------------------------------------------------------------------- | --------------------------------------------- |
-| Single image     | Viewer overlay, Media, and Close button render.                     | Caption and zoom may be absent or present.    |
-| Gallery boundary | Both navigation buttons and Counter remain rendered.                | Previous or Next is disabled at its boundary. |
-| Video            | Media renders native video controls without image zoom interaction. | Autoplay follows the existing consumer prop.  |
-| Captioned media  | Caption follows the active Media inside the centered media group.   | Caption content remains caller-provided.      |
+| State            | Required invariant                                                                      | Allowed variation                             |
+| ---------------- | --------------------------------------------------------------------------------------- | --------------------------------------------- |
+| Single image     | Viewer overlay, Media, and Close button render.                                         | Caption and zoom may be absent or present.    |
+| Gallery boundary | Both navigation buttons and Counter remain rendered.                                    | Previous or Next is disabled at its boundary. |
+| Video            | Media renders native video controls without image zoom interaction.                     | Autoplay follows the existing consumer prop.  |
+| Captioned media  | Caption follows the active Media inside the centered media group.                       | Caption content remains caller-provided.      |
+| Zoomed image     | A double tap or double-click, `-`, or `0` returns to the fitted size.                   | The zoom level and pan position.              |
+| Controls hidden  | Controls stay focusable and in the accessibility tree; focus or a key brings them back. | Backdrop shade while hidden.                  |
 
 ### Transformation and precedence order
 
-- No new index, zoom, pan, media, or styling precedence rule is introduced.
+- **ORD1 — Zoom before paging.** A drag on a zoomed photo pans it until the
+  photo's edge; only a new drag from that edge pages (FR7).
+- **ORD2 — Fitted size before closing.** A drag down or a pinch in closes the
+  viewer only from the fitted size (FR8, FR9).
+- **ORD3 — Hidden controls before closing.** While the controls are hidden, the
+  first tap beside the photo only brings them back; only while they are shown
+  does a tap beside the photo close the viewer (FR10, FR16).
 
 ### Performance and resources
 
-- No new performance or resource rule is introduced.
+- **PR1 — Settles survive a busy page.** Zoom, page, dismiss, and transition
+  settles keep moving while the main thread is busy (`spec:AST-094`).
 
 ## Accessibility contract
 
-Apart from Tab containment (FR4), this draft does not change or extend
-Lightbox's existing dialog naming, focus, media alternatives, announcements,
-button labels, keyboard behavior, or dismissal behavior.
+Every expectation below cites its WCAG 2.2 Level A or AA success criterion
+under `spec:AST-020` FR1; reduced motion cites `design:reduced-motion`.
+
+- **AR1 — Every multipoint or path gesture has a single-pointer alternative
+  (WCAG 2.2 2.5.1).** Pinch zoom has the double tap or double-click (FR6,
+  FR11); swipe paging has the Previous and Next buttons (FR7); drag down and
+  pinch in to close have the Close button (FR8, FR9).
+- **AR2 — Every drag has a non-drag alternative (WCAG 2.2 2.5.7).** Drag to
+  close has the Close button; drag paging has the Previous and Next buttons; a
+  zoomed photo's pan has the double tap or double-click, which returns to the
+  fitted size, and a double tap or double-click on a point, which zooms in about
+  that point (FR6, FR11).
+- **AR3 — Keyboard operation (WCAG 2.2 2.1.1, 2.1.2, 2.4.3).** Escape closes
+  the viewer. ArrowLeft and ArrowRight page in the logical direction, so in a
+  right-to-left page ArrowLeft moves to the next item. With `hasZoom`, `+` zooms
+  in, `-` zooms out, and `0` returns to the fitted size; while zoomed, the arrow
+  keys pan the photo. Focus stays inside the viewer (FR4), and on close returns
+  to the element that opened the viewer when that element is still connected and
+  can receive focus (`family:overlay-dismissal` AV1).
+- **AR4 — Screen-reader semantics and announcements (WCAG 2.2 1.1.1, 4.1.2,
+  4.1.3).** The viewer is a modal dialog named by the active item's `alt`, or a
+  localized "Media viewer" when it has none. Every item requires `alt`, which
+  reaches the image's alternative text or the video's accessible name. Moving to
+  another item in an open viewer, by button, key, or swipe, announces the item
+  and its position ("<alt>, 3 of 12") once, through the `spec:AST-086` FR14
+  route. Every zoom change, by any input, announces the new zoom level once when
+  it settles, or that the photo is back at its fitted size.
+- **AR5 — Hidden controls stay reachable (WCAG 2.2 2.1.1, 2.4.11, 4.1.2).**
+  FR10 hides the controls visually only: they stay focusable and in the
+  accessibility tree. Focus reaching a control, from the keyboard or from
+  assistive technology, and any key press inside the viewer bring them back. A
+  zoom from the keyboard never hides them.
+- **AR6 — Reduced motion (`design:reduced-motion` DR1–DR3).** Under reduced
+  motion, the thumbnail transition, the touch exit, the page settle, the dismiss
+  and pinch-close settles, and the controls fade change opacity only and finish
+  within 200 ms when the primary pointer is coarse or when the release of a
+  touch drag starts them (DR2), including a mouse, pen, or trackpad release
+  where the primary pointer is coarse (`spec:AST-094` FR43). Otherwise they
+  complete at once (DR3). The momentum coast of a thrown zoomed photo is direct
+  movement and continues (DR2). These motions read the named motion roles (FR5), which carry the
+  reduced-motion path.
+- **AR7 — Focus visible and not obscured (WCAG 2.2 2.4.7, 2.4.11).** Every
+  focusable control and the zoom target show the shared focus indicator. A
+  focused control is never hidden by FR10 (AR5), and the caption or counter
+  never covers it.
+- **AR8 — The page keeps its own zoom (WCAG 2.2 1.4.4).** A pinch on the
+  controls or the caption zooms the page, so their text stays resizable (FR6).
 
 ## Design relationships
 
@@ -117,11 +244,12 @@ button labels, keyboard behavior, or dismissal behavior.
 | ---------------- | -------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
 | Viewer overlay   | Presents the full-viewport dialog and surrounding overlay treatment. | Current source and public docs | Supporting        | FR1, FR2           |
 | Media            | Presents the active image or video.                                  | Current source and public docs | Prominent         | FR1, FR2           |
-| Close button     | Provides the persistent viewer dismissal action.                     | `component:Button`             | Supporting        | FR1, FR3           |
-| Previous button  | Moves gallery presentation to the preceding item.                    | `component:Button`             | Supporting        | FR1, FR3           |
-| Next button      | Moves gallery presentation to the following item.                    | `component:Button`             | Supporting        | FR1, FR3           |
+| Close button     | Provides the persistent viewer dismissal action.                     | `component:Button`             | Supporting        | FR1, FR3, AR1      |
+| Previous button  | Moves gallery presentation to the preceding item.                    | `component:Button`             | Supporting        | FR1, FR3, AR1      |
+| Next button      | Moves gallery presentation to the following item.                    | `component:Button`             | Supporting        | FR1, FR3, AR1      |
 | Caption          | Presents caller-provided context below the active Media.             | Current source and public docs | Context-dependent | FR1, FR2           |
 | Counter          | Presents current gallery position and total.                         | Current source and tests       | Supporting        | FR1, FR2           |
+| Reduced motion   | `design:reduced-motion/DR1`–`DR3`                                    | prescribed                     | Supporting        | AR6                |
 
 Media, Caption, and Counter are stable visible parts, but no current public
 target reaches them. Their `none` dispositions record factual reachability, not
@@ -163,37 +291,97 @@ a decision that they must remain unthemeable.
 
 ## Family and system relationships
 
+- `spec:AST-094` owns touch physics, release decisions, measured values, and
+  motion roles; this record names which gestures Lightbox presents and when.
+- `spec:AST-017` owns experimental isolation (FR21) and fine-pointer
+  preservation (FR59); FR11 and FR12 apply them.
+- `spec:AST-020` owns the WCAG 2.2 A and AA baseline AR1–AR5, AR7, and AR8 cite.
+- `spec:AST-086` owns how position and zoom announcements are delivered inside
+  an open modal (FR14).
+- `design:reduced-motion` owns the reduced-motion representation AR6 applies.
 - `architecture:component-theming-surface` owns anatomy qualification, target
   mapping, delegation, and factual `none` dispositions.
 - `architecture:layer-runtime` owns the current native-dialog host and shared
-  layer plumbing; Lightbox retains its current media and local backdrop behavior.
-- `family:overlay-dismissal` owns shared Escape and platform-close ordering and
-  records Lightbox as a current adopter.
-- `architecture:interaction-modality` and `architecture:public-component-api`
-  own their shared modality and API boundaries; this draft changes neither.
+  layer plumbing; Lightbox retains its media and local backdrop behavior.
+- `architecture:react-component-runtime` owns the shared internal touch modules
+  FR14 uses (INV13).
+- `architecture:public-component-api` owns the caller's way back from touch
+  defaults (INV16); FR13 applies it.
+- `family:overlay-dismissal` owns shared Escape and platform-close ordering,
+  including per-document ranking (FR8), and records Lightbox as an adopter.
+- `architecture:interaction-modality` owns shared modality boundaries; this
+  record changes none.
 
 ## Verification map
 
-| Contract            | Verification                                                         | Representative states                       | Mutation or failure expectation                                                                | Audit section            |
-| ------------------- | -------------------------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1                 | `Lightbox.test.tsx` render, gallery, caption, media, and zoom suites | Single image, gallery edges, caption, video | Removing a documented part fails existing role, content, media, or navigation assertions.      | `audit:Lightbox/anatomy` |
-| FR2                 | Source inspection and `themingTargets.test.ts`                       | Viewer overlay, Media, Caption, and Counter | Removing the root target or documenting an unshipped child target fails evidence or inventory. | `audit:Lightbox/theming` |
-| FR3                 | Source inspection plus Button and IconButton public composition      | Close and gallery navigation controls       | Re-owning a control surface requires the delegated owner and this map to change.               | `audit:Lightbox/theming` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                        | Canonical anatomy and current target        | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation.     | `audit:Lightbox/theming` |
+| Contract            | Verification                                                                                                            | Representative states                                                                                                                                   | Mutation or failure expectation                                                                                                                                                                                                                       | Audit section                  |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| FR1                 | `Lightbox.test.tsx` render, gallery, caption, media, and zoom suites                                                    | Single image, gallery edges, caption, video                                                                                                             | Removing a documented part fails existing role, content, media, or navigation assertions.                                                                                                                                                             | `audit:Lightbox/anatomy`       |
+| FR2                 | Source inspection and `themingTargets.test.ts`                                                                          | Viewer overlay, Media, Caption, and Counter                                                                                                             | Removing the root target or documenting an unshipped child target fails evidence or inventory.                                                                                                                                                        | `audit:Lightbox/theming`       |
+| FR3                 | Source inspection plus Button and IconButton public composition                                                         | Close and gallery navigation controls                                                                                                                   | Re-owning a control surface requires the delegated owner and this map to change.                                                                                                                                                                      | `audit:Lightbox/theming`       |
+| FR4, AR3            | Browser keyboard test: Tab and Shift+Tab at both ends, Escape, arrows in LTR and RTL, `+`, `-`, `0`, close focus        | Single image, gallery, zoomed image, removed opener                                                                                                     | Focus leaving the viewer, a key without its action, or focus not returning to a connected opener fails.                                                                                                                                               | `audit:Lightbox/accessibility` |
+| FR5–FR10            | Interaction tests on synthetic touch streams with explicit timestamps; Reduce Motion; a busy main thread                | Below and past each commit point; a release moving back; a drag on a video's frame and on its scrubber; a tap beside the photo with the controls hidden | A literal timing, a second decision during a settle, a gesture that pages while pinching, a drag on a video's frame that does not page, a drag on its controls that pages, or a tap beside the photo that closes while the controls are hidden fails. | `audit:Lightbox/touch`         |
+| FR11                | Fine-pointer browser tests                                                                                              | Double-click, click on the photo, drag, ctrl-wheel, wheel                                                                                               | A double-click that does not zoom 2× about the point, a click that hides the controls, or a fine-pointer close that animates fails.                                                                                                                   | `audit:Lightbox/touch`         |
+| FR6, AR1            | Touch test double-tapping a photo shaped like the screen and a landscape photo                                          | 9:16 photo on a phone viewport, 3:2 photo                                                                                                               | A double tap that zooms less than 2×, or not about the tapped point, fails.                                                                                                                                                                           | `audit:Lightbox/touch`         |
+| FR16                | Touch tests closing by Close, Escape, platform close, and a tap beside the photo with the controls shown; Reduce Motion | With and without `experimental`; controls shown and hidden                                                                                              | A touch close without the exit, a literal timing, input reaching the viewer during the exit, or a tap beside the photo that closes while the controls are hidden fails.                                                                               | `audit:Lightbox/touch`         |
+| FR12                | Opener and `sourceFor` tests, with and without `experimental`                                                           | Image opener, text-button opener, mid-entrance close                                                                                                    | Any change to opening or closing without `experimental` fails.                                                                                                                                                                                        | `audit:Lightbox/touch`         |
+| FR13                | `hasZoom={false}` tests under a coarse pointer                                                                          | Gallery, single image                                                                                                                                   | A zoom, a pinch close, or a tap that hides the controls with `hasZoom={false}` fails.                                                                                                                                                                 | `audit:Lightbox/touch`         |
+| FR14                | Source boundary check and bundle analysis                                                                               | A page with Lightbox and another touch component                                                                                                        | A second copy of a touch module or a Lightbox-owned gesture listener fails.                                                                                                                                                                           | `audit:Lightbox/touch`         |
+| AR1, AR2            | Browser tests that complete every gesture's action with one pointer and no drag                                         | Zoom, page, close, reach a zoomed photo's edge                                                                                                          | An action reachable only by a multipoint, path, or drag gesture fails.                                                                                                                                                                                | `audit:Lightbox/accessibility` |
+| AR4                 | Accessibility-tree and announcement tests                                                                               | Open, page by button, key, and swipe, zoom by every input                                                                                               | A missing dialog name or `alt`, a repeated or missing position announcement, a message not exposed inside the open viewer, or a zoom without its level fails.                                                                                         | `audit:Lightbox/accessibility` |
+| AR5, AR7            | Browser tests with the controls hidden                                                                                  | Tab, assistive-technology focus, a key press, keyboard zoom                                                                                             | A hidden control that is unfocusable, absent from the tree, or still hidden when focused fails.                                                                                                                                                       | `audit:Lightbox/accessibility` |
+| AR6                 | Reduced-motion tests under a coarse and a fine pointer                                                                  | Transition, page settle, dismiss, pinch close, controls fade                                                                                            | Travel, scaling, or a cross-fade over 200 ms under reduced motion fails.                                                                                                                                                                              | `audit:Lightbox/accessibility` |
+| AR8                 | Touch test pinching on the controls and on the caption                                                                  | Single image, gallery                                                                                                                                   | A pinch on the controls or caption that does not zoom the page fails.                                                                                                                                                                                 | `audit:Lightbox/accessibility` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                           | Canonical anatomy and current target                                                                                                                    | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation.                                                                                                                                                            | `audit:Lightbox/theming`       |
 
 ## Decision log
 
-None. This draft records current facts and introduces no component-local design,
-API, theming, or layer-system decision.
+### DEC-1 — The touch presentation is the native photo viewer
+
+**Reference:** `component:Lightbox/DEC-1`
+**Decider:** cixzhang, 2026-10-31
+
+On a touch screen people compare Lightbox with the photo viewer on their own
+phone, so Lightbox presents its gestures by default (FR5–FR10), each close or
+page decided once at the release.
+
+### DEC-2 — Fine pointers get the gestures and keep the desktop look
+
+**Reference:** `component:Lightbox/DEC-2`
+**Decider:** cixzhang, 2026-10-31
+
+Mouse, pen, and trackpad get the gestures `spec:AST-094` FR43 gives every
+pointer, while a double-click zooms 2× about the clicked point, a click keeps
+the controls, and the viewer opens and closes at once (FR11), so the viewer
+keeps its desktop look.
+
+Rejected: filling the viewer on a double-click, which barely zooms a landscape
+photo in a wide window.
+
+### DEC-3 — The thumbnail transition is experimental
+
+**Reference:** `component:Lightbox/DEC-3`
+**Decider:** cixzhang, 2026-10-31
+
+The thumbnail transition, `experimental.sourceFor`, and the close that waits for
+the landing stay inside `experimental` (FR12), so their API can still change.
+
+### DEC-4 — `hasZoom` is the way back
+
+**Reference:** `component:Lightbox/DEC-4`
+**Decider:** cixzhang, 2026-10-31
+
+`hasZoom={false}` turns off the zoom-related touch behaviors, and the other
+gestures only add to existing controls, so Lightbox needs no `presentation`
+prop (FR13).
 
 ## Open questions
 
-- **OQ1 — Should Media, Caption, or Counter gain a stable public theming target?**
-  (`human-api`) Their current lack of reachability is an audit gap, not settled
-  intent.
+None. Media, Caption, and Counter keep no public target; adding one is a change
+to this record.
 
 ## Content boundary
 
-This file does not duplicate consumer prop tables/examples, media algorithms,
-shared layer rules, current audit results, or implementation steps. It links to
-their owners.
+This file does not duplicate consumer prop tables/examples, measured values,
+media algorithms, shared layer rules, current audit results, or implementation
+steps. It links to their owners.

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/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

@@ -43,7 +43,7 @@ import type {LinkComponentType} from './types';
 import {mergeProps} from '../utils';
 import {computeTargetAndRel} from './computeTargetAndRel';
 import {useInteractiveRole} from '../hooks/useInteractiveRole';
-import {themeProps} from '../utils/themeProps';
+import {themeDataAttributes, themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
@@ -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.
@@ -327,6 +335,10 @@ export function Link({
   const renderAsButton =
     role === 'button' || (role === 'inert' && href == null);
 
+  // The reflected theme attributes win over a caller's same-named `data-*`, so
+  // theme targeting always sees the real value (public-component-api INV5).
+  const reflectedAttributes = themeDataAttributes({color});
+
   const sharedContent = (
     <>
       <Text
@@ -370,12 +382,14 @@ export function Link({
             hasUnderline && styles.hasUnderline,
             isStandalone && styles.standalone,
             isDisabled && styles.disabled,
+            maxLines > 0 && styles.truncating,
             xstyle,
           ),
           className,
           style,
         )}
         {...props}
+        {...reflectedAttributes}
         // Focusable while disabled (spec:AST-085 FR1), but inert (FR2).
         {...(isDisabled ? disabledInteractionProps(props.onKeyDown) : null)}>
         {sharedContent}
@@ -403,12 +417,14 @@ export function Link({
             hasUnderline && styles.hasUnderline,
             isStandalone && styles.standalone,
             styles.disabled,
+            maxLines > 0 && styles.truncating,
             xstyle,
           ),
           className,
           style,
         )}
         {...props}
+        {...reflectedAttributes}
         {...disabledInteractionProps(props.onKeyDown)}>
         {sharedContent}
       </a>
@@ -434,12 +450,14 @@ export function Link({
             hasUnderline && styles.hasUnderline,
             isStandalone && styles.standalone,
             isDisabled && styles.disabled,
+            maxLines > 0 && styles.truncating,
             xstyle,
           ),
           className,
           style,
         )}
-        {...props}>
+        {...props}
+        {...reflectedAttributes}>
         {sharedContent}
       </LinkComponent>
     );

package/src/List/List.tsx

@@ -29,7 +29,7 @@ import {
   type ListEdge,
   type ListMarkerStyle,
 } from './ListContext';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 import {useDevWarning} from '../hooks/useDevWarning';