feat(core): code outside a component relates to its gesture recognizers by name

.changeset/build-stylex-cross-file-consts.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/build': patch
+---
+
+[fix] `astryxStylex` resolves `defineConsts` values read from another file. With the `{stylexOptions}` form (the one Storybook uses), a file that read only constants from a `.stylex.ts` module lost that import once StyleX compiled it, so the constants never reached the CSS: a constant used as a media-query key failed the build ("Invalid empty selector") and one used as a value shipped as a custom property nothing declares. A constant defined on the library side of the layer split and read on the product side stayed unresolved in either form. A production build now also warns, naming the variable and the rule that reads it, when its stylesheet reads a StyleX-generated custom property that nothing declares; set `undefinedVariables: 'error'` to fail the build instead.
+
+@vjeux

.changeset/gesture-browser-negotiation.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: touch-action derivation, the native scroll probe and haptics for the gesture system. Not exported from the package entry point; no component uses them yet.
+
+@vjeux

.changeset/gesture-delegates.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: code outside a component relates to the component's own gesture recognizers by name, the way a UIKit app uses a recognizer's name and its own delegate (`gestureNamed`, `addGestureDelegate`, `useGestureDelegate`). Not exported from the package entry point; no component uses it yet.
+
+@vjeux

.changeset/gesture-host.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the gesture system's DOM host (claims, click suppression, the browser's takeover, the pointer behind a contact). Not exported from the package entry point; no component uses it yet.
+
+@vjeux

.changeset/gesture-pan.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the pan gesture recognizer, with UIKit's measured hysteresis and velocity filter. Not exported from the package entry point; no component uses it yet.
+
+@vjeux

.changeset/gesture-press-tracking.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: UIControl press tracking with control and cell profiles, the shared press paint, delegated press tracking and the gesture hooks. Not exported from the package entry point; no component uses them yet.
+
+@vjeux

.changeset/gesture-readme.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the gesture system's README for component authors, with its browser proof in Chromium and WebKit.
+
+@vjeux

.changeset/gesture-recognizer-core.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the gesture recognizer core for touch presentations: UIKit's recognizer state machine and the arena that settles which recognizer owns a touch. Not exported from the package entry point; no component uses it yet.
+
+@vjeux

.changeset/gesture-swipe-pinch-rotation-edge-hover.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: swipe, pinch, rotation, screen-edge pan and hover gesture recognizers. Not exported from the package entry point; no component uses them yet.
+
+@vjeux

.changeset/gesture-tap-long-press.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: tap and long-press gesture recognizers with UIKit's measured thresholds. Not exported from the package entry point; no component uses them yet.
+
+@vjeux

.changeset/reduced-motion-record.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] The experimental touch animator follows design:reduced-motion. Under Reduce Motion every `animate` and `play` (travel or opacity, on a spring or any curve) becomes an opacity-only cross-fade of 200 ms on a coarse primary pointer, or for a call marked `touchRelease`, and completes at once on any other pointer; nothing moves, scales or springs, and travel lands with a plain style write while the element is transparent, never as an animated transform. `timing.reducedMotionCrossFadeMs` is now 200 ms and is no longer a theme role. The `reducedMotion` and `crossfade` call options are removed; `crossfadeAs` stays. `animator.reducedMotion()` reports the mode for feedback with no fade of its own, `reducedMotionFade()` gives the same fade to code beside the animator, and `reducedMotion.stylex.ts` holds its constants for StyleX transitions.
+
+@vjeux

.changeset/touch-motion-theme-roles.md

@@ -0,0 +1,8 @@
+---
+'@astryxdesign/core': patch
+'@astryxdesign/cli': patch
+---
+
+[feat] Themes can retune touch motion roles. `defineTheme({motion})` takes `springs`, `durations` and `curves` keyed by motion role, the table path of a measured touch motion value (`springs.sheetPresent`, `navigation.transitionMs`), at the root or in an adaptation rule, and writes one `--motion-*` variable per role it sets. A role the theme leaves out keeps its measured default, an unknown role id is refused, and the duration scale (`fast`, `medium`, `ratio`) is optional when a theme sets only roles. No shipped component reads the roles yet. `astryx docs motion` lists every motion role with its CSS variable and default, and the theme authoring guide and template describe the new fields.
+
+@vjeux

.changeset/touch-presentation.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] `presentation="adaptive"` on DropdownMenu, ContextMenu, MoreMenu, Selector and MultiSelector, and a DropdownMenu's or ContextMenu's default sub-menu drill-in, now use the theme's compact definition with a coarse primary pointer: a viewport narrower than the theme's `md` point (768px by default) or shorter than 500px. This is a behavior change. The old default was a bottom sheet at 768px wide and below on a coarse pointer. Now a coarse-pointer screen exactly 768px wide keeps the anchored popover, and a phone in landscape (wider than 768px but shorter than 500px) gets the bottom sheet and the drilled-in sub-menu. A theme that moves `md` moves the edge with it. To pin a component's presentation regardless of the rule, pass `presentation="popover"` or `presentation="bottom-sheet"`; to keep a sub-menu's flyout, pass `presentation="flyout"` on `DropdownMenuSubMenu`. Mouse and keyboard users on desktop see no change, because every case requires a coarse pointer.
+
+@vjeux

.changeset/uikit-constants-table.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the UIKit constants table for touch presentations (springs, scroll physics, timing curves and navigation values), each value with its source and a checked list of the simulator measurements still owed. Not exported from the package entry point; no component reads it yet.
+
+@vjeux

.changeset/uikit-motion-animator-curves.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the touch presentations' animator plays any closed-form curve (such as a spring chasing a moving target), drives a pseudo-element such as a dialog's ::backdrop, follows design:reduced-motion (under Reduce Motion, an opacity-only cross-fade of 200 ms on a coarse pointer or after a touch release and an immediate change on any other pointer, with no option or theme value that keeps travel or lengthens the fade; an entrance or exit role orients a slide that changes no opacity), and starts a call from rest when the browser commits it, as Core Animation does. Not exported from the package entry point.
+
+@vjeux

.changeset/uikit-motion-animator.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: a compositor animator for touch presentations. It plays UIKit's springs, scroll coasts and any closed-form curve as Web Animations on translate, rotate, scale and opacity, so they keep running while JavaScript is busy, and reads values and velocities back from the curves for interruption, retargeting and Reduce Motion cross-fades. Not exported from the package entry point; no component uses it yet.
+
+@vjeux

.changeset/uikit-motion-math.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the spring, decay, rubber-band and projection math of UIKit for touch presentations, as pure functions checked against an independent integration and against values read from UIKit. Not exported from the package entry point; no component uses it yet.
+
+@vjeux

.changeset/uikit-motion-use-animator.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: useAnimator, a React wrapper around the touch presentations' animator that never re-renders per frame, and browser proofs on the interaction harness that the animator's motion keeps running through a blocked main thread in Chromium and WebKit. Not exported from the package entry point.
+
+@vjeux

.github/scripts/ci-test-routing.test.mjs

@@ -612,3 +612,52 @@ describe('deploy.yml push gating', () => {
     }
   });
 });
+
+describe('ci.yml interaction proofs', () => {
+  const workflow = load('ci.yml');
+  const job = workflow.jobs['pr-interaction'];
+  const step = name => job.steps.find(candidate => candidate.name === name);
+
+  it('runs the interaction config in Chromium against the exact PR head', () => {
+    expect(KNOWN_RUNNERS.has(job['runs-on'])).toBe(true);
+    expect(job.needs).toEqual(
+      expect.arrayContaining(['check-scope', 'build-storybook']),
+    );
+    const checkout = job.steps.find(candidate =>
+      candidate.uses?.startsWith('actions/checkout@'),
+    );
+    expect(checkout?.with?.ref).toBe(
+      '${{ github.event.pull_request.head.sha }}',
+    );
+    const run = step('Run interaction proofs').run;
+    expect(run).toContain('--config playwright.interaction.config.ts');
+    expect(run).toContain('--project chromium');
+    const packageJson = JSON.parse(read('package.json'));
+    expect(packageJson.scripts['test:interaction']).toBe(
+      'playwright test --config playwright.interaction.config.ts',
+    );
+  });
+
+  it('runs whenever the harness, its config, a component or a story changes', () => {
+    const scope = step('Check interaction scope').run;
+    expect(scope).toContain('.github/scripts/pr-scope-touches.sh');
+    for (const path of [
+      'internal/interaction-harness/',
+      'playwright\\.interaction\\.config\\.ts',
+      'packages/[^/]+/src/',
+      'apps/storybook/',
+    ]) {
+      expect(scope).toContain(path);
+    }
+    // Unknown scope (exit 2) runs the proofs; only "out of scope" skips them.
+    expect(scope).toContain('if [ "$scope" = 1 ]; then');
+  });
+
+  it('typechecks the harness in both workflows', () => {
+    for (const file of ['ci.yml', 'deploy.yml']) {
+      expect(runLines(load(file).jobs.typecheck), file).toContain(
+        '@astryxdesign/interaction-harness typecheck',
+      );
+    }
+  });
+});

.github/workflows/ci.yml

@@ -1270,6 +1270,12 @@ jobs:
         if: needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true' && needs.check-scope.outputs.tooling_only != 'true'
         run: pnpm -F @astryxdesign/native typecheck:types
 
+      # The interaction harness is consumed as TypeScript source by Vitest and
+      # Playwright, which do not typecheck; this is the only gate over it.
+      - name: Typecheck interaction harness
+        if: needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true' && needs.check-scope.outputs.tooling_only != 'true'
+        run: pnpm -F @astryxdesign/interaction-harness typecheck
+
   # Sandbox preview build — the single slowest piece of PR CI (~4min), run as
   # its own job so it overlaps build-storybook instead of serializing after it.
   # PR-only: merge_group runs never deploy previews, and docsite-only PRs skip
@@ -3803,6 +3809,88 @@ jobs:
           retention-days: 30
           delete-merged: true
 
+  # Touch interaction and animation proofs: the harness in
+  # internal/interaction-harness and every *.interaction.browser.spec.ts.
+  # Real touch input, composited frames, rendering traces and presented
+  # animation values only exist in a real engine, and the specs read stories
+  # from this PR's own Storybook build. The harness's self-test runs with
+  # them, so a change to an instrument is proven by its negative controls
+  # before a component spec relies on it. Chromium only on these runners;
+  # see the harness README for running WebKit.
+  pr-interaction:
+    needs: [check-scope, build-storybook]
+    if: github.event_name == 'pull_request' && needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true' && needs.check-scope.outputs.tooling_only != 'true'
+    # Frame evidence measures timing: four cores, one Playwright worker.
+    runs-on: 4-core-ubuntu
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Verify evidence checkout
+        env:
+          EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: test "$(git rev-parse HEAD)" = "$EXPECTED_HEAD_SHA"
+
+      # The helper comes from the base, since an older PR head lacks it.
+      # Exit 1 means out of scope; 0 in scope; 2 unknown, so run.
+      - name: Check interaction scope
+        id: scope
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          scope=2
+          helper="$(mktemp)"
+          if git fetch --quiet --no-tags --depth=1 origin "$BASE_SHA" \
+            && git show "$BASE_SHA:.github/scripts/pr-scope-touches.sh" > "$helper"; then
+            scope=0
+            bash "$helper" "$BASE_SHA" '^(internal/interaction-harness/|playwright\.interaction\.config\.ts$|packages/[^/]+/src/|apps/storybook/)' || scope=$?
+          fi
+          if [ "$scope" = 1 ]; then
+            echo "Neither the interaction harness nor a component changed; skipping the interaction proofs."
+            echo 'run=false' >> "$GITHUB_OUTPUT"
+          else
+            echo 'run=true' >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Setup Node and pnpm
+        if: steps.scope.outputs.run == 'true'
+        uses: ./.github/actions/setup
+        with:
+          install: 'false'
+
+      - name: Download Storybook artifact
+        if: steps.scope.outputs.run == 'true'
+        uses: actions/download-artifact@v8
+        with:
+          name: storybook-${{ needs.build-storybook.outputs.short_hash }}
+          path: apps/storybook/dist
+
+      - name: Install Playwright
+        if: steps.scope.outputs.run == 'true'
+        run: pnpm install --frozen-lockfile && npx playwright install chromium
+
+      - name: Run interaction proofs
+        if: steps.scope.outputs.run == 'true'
+        run: |
+          pnpm exec playwright test \
+            --config playwright.interaction.config.ts \
+            --project chromium \
+            --output interaction-proof-output
+
+      # Storyboards (PNG contact sheets) and curve traces, for review.
+      - name: Upload interaction evidence
+        if: always() && steps.scope.outputs.run == 'true'
+        uses: actions/upload-artifact@v7
+        with:
+          name: interaction-evidence
+          path: test-results/interaction-evidence
+          if-no-files-found: ignore
+          retention-days: 7
+
   # Build package test owner. The plugin's production CSS partition is a Build
   # integration contract: source inspection cannot prove which declaration
   # paints after Vite emits the final bundle. The `test-build` name makes that

.github/workflows/deploy.yml

@@ -146,6 +146,9 @@ jobs:
       - name: Typecheck accessibility spec-test contracts
         run: pnpm -F @astryxdesign/a11y-spec typecheck
 
+      - name: Typecheck interaction harness
+        run: pnpm -F @astryxdesign/interaction-harness typecheck
+
   # Stable join for the three post-merge validation lanes.
   test:
     needs: [test-ui, test-node, typecheck]

apps/sandbox/vite.config.mts

@@ -192,6 +192,7 @@ export default defineConfig({
         unstable_moduleResolution: stylexResolution.stylexModuleResolution,
       },
       stylexPrefix: 'x',
+      undefinedVariables: 'error',
     }),
     react({
       babel: {

apps/storybook/.storybook/main.test.ts

@@ -57,6 +57,7 @@ const runtimeImports = [
 describe('storybook main.ts workspace source aliases', () => {
   let viteAliases: Record<string, string>;
   let stylexAliases: Record<string, string[]>;
+  let undefinedVariables: unknown;
   const stylexSpy = vi.spyOn(build, 'astryxStylex');
 
   beforeAll(async () => {
@@ -69,6 +70,11 @@ describe('storybook main.ts workspace source aliases', () => {
       throw new Error('Expected the Storybook StyleX options');
     }
     stylexAliases = options.stylexOptions!.aliases as Record<string, string[]>;
+    undefinedVariables = options.undefinedVariables;
+  });
+
+  it('fails the build on a generated variable nothing declares', () => {
+    expect(undefinedVariables).toBe('error');
   });
 
   afterAll(() => stylexSpy.mockRestore());

apps/storybook/.storybook/main.ts

@@ -198,6 +198,9 @@ const config: StorybookConfig = {
             },
           },
           libraryPattern: 'packages/',
+          // CI catches a style that reads a generated variable nothing
+          // declares (a dropped declaration) instead of shipping it.
+          undefinedVariables: 'error',
         }),
       ],
       resolve: {

apps/storybook/stories/ContextMenu.stories.tsx

@@ -494,7 +494,7 @@ export const AdaptivePresentation: Story = {
     docs: {
       description: {
         story:
-          'Uses the built-in adaptive policy: BottomSheet at 768px and below with a coarse primary pointer, cursor-positioned popover otherwise. Important actions still need a visible MoreMenu or equivalent entry point.',
+          'Uses the built-in adaptive policy: BottomSheet on a compact touch screen (a coarse primary pointer, and a viewport narrower than the theme `md` breakpoint (768px by default) or shorter than 500px), cursor-positioned popover otherwise. Important actions still need a visible MoreMenu or equivalent entry point.',
       },
     },
   },

apps/storybook/stories/MoreMenu.stories.tsx

@@ -316,7 +316,7 @@ export const AdaptivePresentation: Story = {
     docs: {
       description: {
         story:
-          'Uses the built-in adaptive policy: BottomSheet at 768px and below with a coarse primary pointer, anchored popover otherwise. Use device emulation to exercise the touch branch.',
+          'Uses the built-in adaptive policy: BottomSheet on a compact touch screen (a coarse primary pointer, and a viewport narrower than the theme `md` breakpoint (768px by default) or shorter than 500px), anchored popover otherwise. Use device emulation to exercise the touch branch.',
       },
     },
   },

internal/README.md

@@ -4,9 +4,10 @@ Internal tooling packages not published to npm.
 
 <!-- SYNC: When files in this directory change, update this document. -->
 
-| Directory     | Role    | Purpose                                                                 |
-| ------------- | ------- | ----------------------------------------------------------------------- |
-| `a11y-spec/`  | Testing | Reusable accessibility spec-test contracts and their evidence harnesses |
-| `scripts/`    | Tooling | One-off automation scripts (Crowdin screenshot upload, etc.)            |
-| `test-utils/` | Testing | Shared testing utilities and setup for Vitest                           |
-| `vibe-tests/` | Testing | LLM vibeability test harness for component system                       |
+| Directory              | Role    | Purpose                                                                           |
+| ---------------------- | ------- | --------------------------------------------------------------------------------- |
+| `a11y-spec/`           | Testing | Reusable accessibility spec-test contracts and their evidence harnesses           |
+| `interaction-harness/` | Testing | Playwright instruments for touch interaction and animation proofs and storyboards |
+| `scripts/`             | Tooling | One-off automation scripts (Crowdin screenshot upload, etc.)                      |
+| `test-utils/`          | Testing | Shared testing utilities and setup for Vitest                                     |
+| `vibe-tests/`          | Testing | LLM vibeability test harness for component system                                 |