@excom/gesture-handler 0.1.0

package/support/package-meta.json

@@ -0,0 +1,489 @@
+{
+  "shortName": "gesture-handler",
+  "package": {
+    "name": "@excom/gesture-handler",
+    "version": "0.1.0",
+    "description": "<gesture-handler> custom element",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "kit-element"
+    }
+  },
+  "demos": {
+    "carousel": "<gesture-handler gesture-types=\"pan-x swipe\" pointer-types=\"touch pen mouse\" progress-axis=\"left\"\n  range-ref=\":scope > content-carousel\" progress-min=\"-1\" progress-max=\"1\" snap-points=\"-1 0 1\"\n  overshoot-resistance=\"0.2\">\n  <quark-sheet>\n    :scope {\n      /* no wrap-around while dragging: clamp the ends */\n      &:has(content-carousel-slide[is-active]:first-of-type) { progress-min: 0; }\n      &:not(:has(content-carousel-slide[is-active]:first-of-type)) { progress-min: -1; }\n      &:has(content-carousel-slide[is-active]:last-of-type) { progress-max: 0; }\n      &:not(:has(content-carousel-slide[is-active]:last-of-type)) { progress-max: 1; }\n      @on gesture-handler-start {\n        content-carousel { is-scrubbing: \"\"; }\n      }\n      /* commit once the glide lands: the slide swap and the un-scrub paint together */\n      @on gesture-handler-snap {\n        /* snap-points \"-1 0 1\" → index 0 = previous, 1 = stay, 2 = next */\n        $snap: event.detail.index;\n        content-carousel {\n          is-scrubbing: none;\n          content-carousel-slide[is-active] + content-carousel-slide {\n            is-active: $snap == 2 or preserve;\n          }\n          content-carousel-slide:has(+ content-carousel-slide[is-active]) {\n            is-active: $snap == 0 or preserve;\n          }\n          content-carousel-slide[is-active] {\n            is-active: $snap == 1 or none;\n          }\n        }\n      }\n    }\n  </quark-sheet>\n  <content-carousel slide-animation=\"track\">\n    <content-carousel-slide is-active>\n      <h2>One</h2>\n    </content-carousel-slide>\n    <content-carousel-slide>\n      <h2>Two</h2>\n    </content-carousel-slide>\n    <content-carousel-slide>\n      <h2>Three</h2>\n    </content-carousel-slide>\n  </content-carousel>\n</gesture-handler>",
+    "pinch": "<gesture-handler gesture-types=\"pan pinch rotate\" pointer-types=\"touch pen mouse\">\n  <figure>Drag, pinch, twist</figure>\n  <style>\n    #demo-gesture-handler-pinch > :first-child figure {\n      translate: var(--gesture-dx, 0px) var(--gesture-dy, 0px);\n      scale: var(--gesture-scale, 1);\n      rotate: var(--gesture-rotate, 0deg);\n    }\n  </style>\n</gesture-handler>\n",
+    "sheet": "<gesture-handler gesture-types=\"pan-y swipe\" pointer-types=\"touch pen mouse\" from-ref=\":scope > content-drawer > header\"\n  handoff-ref=\":scope > content-drawer\" progress-axis=\"up\" range-ref=\":scope > content-drawer\" snap-points=\"0 1\">\n  <quark-sheet>\n    :scope {\n      /* dragging an open sheet starts from fully open */\n      &:has(> content-drawer[is-open]) {\n        progress-offset: 1;\n      }\n      &:not(:has(> content-drawer[is-open])) {\n        progress-offset: 0;\n      }\n      @on gesture-handler-start {\n        content-drawer { is-scrubbing: \"\"; }\n      }\n      @on gesture-handler-end {\n        content-drawer { is-open: event.detail.snap == 1; is-scrubbing: none; }\n      }\n    }\n  </quark-sheet>\n  <button type=\"button\" command=\"--open\" commandfor=\"demo-gesture-sheet\">Open sheet</button>\n  <content-drawer id=\"demo-gesture-sheet\" class=\"absolute\">\n    <header><h2>Drag me</h2></header>\n    <p>Two ways to dismiss it. Drag the header down and let go, or flick it —\n      that is the <code>from-ref</code> grab handle.</p>\n    <p>Or pull the text itself down: <code>handoff-ref</code> lets the sheet's\n      own content scroll first, and only once it is back at the top does the\n      next pull down become the same drag. Pulling up, or pulling down while\n      the text is scrolled, keeps scrolling as usual.</p>\n    <p>Scroll on. The sheet only takes the drag over at the very top, which is\n      how a native sheet behaves.</p>\n    <p>Keep going.</p>\n    <p>Nearly there.</p>\n    <p>Now scroll back up and pull once more — the sheet follows your finger\n      and snaps to <code>0</code> or <code>1</code> on release.</p>\n  </content-drawer>\n  <style>\n    #demo-gesture-handler-sheet > :first-child {\n      /* short enough that the text scrolls: the handoff needs a scroller */\n      content-drawer { max-block-size: 11rem; }\n      /* the drag handle owns its touches; the content keeps scrolling */\n      content-drawer > header {\n        position: sticky;\n        top: 0;\n        touch-action: none;\n        cursor: grab;\n        background-color: inherit;\n      }\n    }\n  </style>\n</gesture-handler>\n",
+    "swipe": "<gesture-handler gesture-types=\"pan-x swipe tap\" pointer-types=\"touch pen mouse\" range-px=\"240\" progress-min=\"-1\" progress-max=\"1\"\n  snap-points=\"-1 0 1\" overshoot-resistance=\"0.4\">\n  <quark-sheet>\n    :scope {\n      @on gesture-handler-snap {\n        article { data-is-dismissed: event.detail.value != 0; }\n      }\n      @on gesture-handler-tap {\n        article { data-is-dismissed: none; }\n      }\n    }\n  </quark-sheet>\n  <article>\n    <h2>Swipe me away</h2>\n    <p>Flick left or right. Tap to bring it back.</p>\n  </article>\n  <style>\n    #demo-gesture-handler-swipe > :first-child article {\n      translate: calc(var(--gesture-progress, 0) * 240px);\n      rotate: calc(var(--gesture-progress, 0) * 8deg);\n      &[data-is-dismissed] { opacity: 0.25; }\n    }\n  </style>\n</gesture-handler>\n"
+  },
+  "readme": "<h1 id=\"md-gesture-handler\">gesture-handler</h1>\n<p>Let users drag, swipe, pinch and flick your UI — sheets, carousels, cards and images follow the finger, in CSS, with no per-frame script.</p>\n<p><include-content data-demo=\"sheet\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Swipe / pan / pinch / rotate / tap / long-press</strong> Each recognized gesture is a tag-prefixed event</li>\n<li><strong>Follow the finger in CSS</strong> Every frame lands in <code>--gesture-*</code> custom properties: scrubbable bottom sheets, swipe-to-dismiss, pinch-to-zoom, pull-to-refresh, parallax</li>\n<li><strong>Snap &amp; fling</strong> <code>snap-points</code> with velocity projection, a CSS transition on release (<code>--gesture-snap-duration</code> / <code>--gesture-snap-ease</code>), <code>gesture-handler-snap</code> when it lands</li>\n<li><strong>Drivable</strong> Bounds, <code>progress-offset</code> and <code>is-disabled</code> are attributes a Quark rule sets from the driven element&#39;s state</li>\n<li><strong>Scoped starts</strong> <code>from-ref</code> for drag handles, <code>from-edge</code> for edge swipes</li>\n<li><strong>Scroll handoff</strong> <code>handoff-ref</code> lets a sheet&#39;s own scrolling content take the drag over when it runs out of scroll — a native-feeling pull-to-close</li>\n<li><strong>Native scrolling kept</strong> <code>touch-action</code> follows <code>gesture-types</code>, so the page still scrolls where you don&#39;t pan</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Wrap the surface the user touches. Pick the gestures with <code>gesture-types</code>; read the finger from <code>--gesture-*</code> in CSS (custom properties inherit, so any descendant can <code>var()</code> them); commit State on <code>gesture-handler-end</code> or <code>-snap</code> from a Quark <code>@on</code> block.</p>\n<include-content data-language=\"html\"><template>&lt;gesture-handler gesture-types=\"pan-y swipe\" progress-axis=\"up\" range-ref=\":scope &gt; content-drawer\" snap-points=\"0 1\"&gt;\n  &lt;quark-sheet&gt;\n    :scope {\n      @on gesture-handler-start { content-drawer { is-scrubbing: \"\"; } }\n      @on gesture-handler-end { content-drawer { is-open: event.detail.snap == 1; is-scrubbing: none; } }\n    }\n  &lt;/quark-sheet&gt;\n  &lt;content-drawer&gt;…&lt;/content-drawer&gt;\n&lt;/gesture-handler&gt;</template></include-content>\n<p><code>--gesture-progress</code> is the travel along <code>progress-axis</code> as a fraction of the range (<code>range-ref</code> measures the driven element; <code>range-px</code> is a literal), clamped to <code>progress-min</code>..<code>progress-max</code> with optional <code>overshoot-resistance</code>. Written alongside it every frame: <code>--gesture-dx</code> / <code>-dy</code>, <code>--gesture-x</code> / <code>-y</code>, <code>--gesture-scale</code>, <code>--gesture-rotate</code>, <code>--gesture-vx</code> / <code>-vy</code>, <code>--gesture-pointers</code>; once per gesture: <code>--gesture-range-px</code>, <code>--gesture-width</code> / <code>-height</code>. Everything else is derived from those in the element&#39;s own CSS — <code>--gesture-distance</code>, <code>--gesture-angle</code>, <code>--gesture-progress-px</code>, <code>--gesture-x-ratio</code> / <code>-y-ratio</code> — so <code>var()</code> them the same way.</p>\n<p>Values persist after release until the next gesture starts. On release the default action writes <code>--gesture-progress</code> straight to <code>detail.snap</code> and the element&#39;s own <code>transition</code> settles it there over <code>--gesture-snap-duration</code> (<code>200ms</code>) with <code>--gesture-snap-ease</code> (<code>ease-out</code>), firing <code>gesture-handler-snap</code> when it lands; the transition is off while <code>is-active</code>, so the finger itself is never eased, and a new gesture that interrupts the settle simply cancels it (no <code>-snap</code>).</p>\n<h3 id=\"md-driving-nucleus-kit-elements\">Driving Nucleus Kit elements</h3>\n<p>Elements that can be scrubbed expose a <code>--&lt;tag&gt;-…-progress</code> input and an <code>is-scrubbing</code> attribute; both default to the wrapping gesture-handler&#39;s <code>--gesture-progress</code>, so no mapping is needed:</p>\n<table>\n<thead>\n<tr>\n<th>Element</th>\n<th>Set up</th>\n<th>While <code>is-scrubbing</code></th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>content-drawer</code></td>\n<td><code>progress-axis</code> towards its open side, <code>range-ref</code> the drawer, <code>handoff-ref</code> the drawer too (it scrolls its own content)</td>\n<td>Position follows <code>--content-drawer-open-progress</code> (<code>0</code> closed, <code>1</code> open), no transition</td>\n</tr>\n<tr>\n<td><code>content-carousel</code></td>\n<td><code>slide-animation=&quot;track&quot;</code>, <code>progress-min=&quot;-1&quot; progress-max=&quot;1&quot; snap-points=&quot;-1 0 1&quot;</code></td>\n<td>The track follows <code>--content-carousel-progress</code> in slide widths</td>\n</tr>\n</tbody></table>\n<p>The handoff is one Quark commit: the block that writes the final state (<code>is-open</code>, the active slide) also removes <code>is-scrubbing</code>, so the element switches from finger to State in the same paint. Commit on <code>-end</code> when a CSS transition should finish the motion (the drawer), on <code>-snap</code> when the element must be exactly at the snap point first (the carousel).</p>\n<p>Anything else follows the same recipe: read <code>--gesture-*</code> in your own CSS, gate the mapping on a fact your sheet writes on start and clears on end.</p>\n<p>Give a drag handle <code>touch-action: none</code> when using <code>from-ref</code>, so the browser does not scroll it away; without <code>from-ref</code> the element sets <code>touch-action</code> itself from <code>gesture-types</code>. Add <code>mouse</code> to <code>pointer-types</code> for desktop dragging.</p>\n<h3 id=\"md-scroll-handoff\">Scroll handoff</h3>\n<p><code>handoff-ref</code> names the scroll container(s) inside the surface whose <em>overscroll</em> starts a gesture (a <code>:scope</code>-relative selector; a comma list matches several). A pointer that goes down in one of them scrolls natively as usual. Only when its <strong>first</strong> move runs along <code>progress-axis</code>, the container is at its scroll limit that way, and <code>progress-offset</code> still has room to travel in that direction does the element cancel the native scroll for the rest of the touch and take the drag over — the same gesture, the same <code>--gesture-*</code> values and the same <code>-start</code> / <code>-end</code> / <code>-snap</code> events as a drag from a handle:</p>\n<include-content data-language=\"html\"><template>&lt;gesture-handler gesture-types=\"pan-y swipe\" progress-axis=\"up\" snap-points=\"0 1\"\n  from-ref=\":scope &gt; content-drawer &gt; header\" handoff-ref=\":scope &gt; content-drawer\"\n  range-ref=\":scope &gt; content-drawer\"&gt;</template></include-content>\n<p>An open sheet (<code>progress-offset: 1</code>) closes either from its header or by pulling its text down once the text is back at the top; pulling up, or pulling down mid-scroll, keeps scrolling. <code>handoff-ref</code> is additive — <code>from-ref</code> and <code>from-edge</code> starts are unchanged, and a <code>from-ref</code> handle inside a handoff container still starts on pointerdown. The element keeps <code>touch-action</code> out of the way while <code>handoff-ref</code> is set (the containers must be able to scroll), so give handles their own <code>touch-action: none</code>.</p>\n<p>Mouse drags (<code>pointer-types=&quot;… mouse&quot;</code>) take the same route with no native scroll to cancel: the first <code>pointermove</code> inside the container starts the gesture when the container is at its limit.</p>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-swipeable-carousel\">Swipeable carousel</h4>\n<p><code>slide-animation=&quot;track&quot;</code> turns <code>content-carousel</code> into a draggable track. <code>progress-axis=&quot;left&quot;</code> makes a leftward drag pull the next slide in; the <code>:has()</code> rules narrow the bounds at the first and last slide so nothing wraps mid-drag; the <code>gesture-handler-snap</code> block swaps <code>is-active</code> and un-scrubs in one commit.</p>\n<p><include-content data-demo=\"carousel\"></include-content></p>\n<h4 id=\"md-pinch-rotate-drag\">Pinch, rotate, drag</h4>\n<p>Two fingers (a trackpad or touch screen) for <code>--gesture-scale</code> and <code>--gesture-rotate</code>; one for <code>--gesture-dx</code> / <code>--gesture-dy</code>. Pure CSS mapping, no sheet. Each gesture starts from the resting values.</p>\n<p><include-content data-demo=\"pinch\"></include-content></p>\n<h4 id=\"md-swipe-to-dismiss\">Swipe to dismiss</h4>\n<p><code>snap-points=&quot;-1 0 1&quot;</code> with a literal <code>range-px</code>: a flick past <code>swipe-min-velocity</code> snaps the card off to the side, and the <code>gesture-handler-snap</code> block records the fact. A tap starts a new gesture (values reset) and clears it.</p>\n<p><include-content data-demo=\"swipe\"></include-content></p>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-gesture-handler\">gesture-handler</h1>\n<p>Let users drag, swipe, pinch and flick your UI — sheets, carousels, cards and images follow the finger, in CSS, with no per-frame script.</p>\n<p><include-content data-demo=\"sheet\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Swipe / pan / pinch / rotate / tap / long-press</strong> Each recognized gesture is a tag-prefixed event</li>\n<li><strong>Follow the finger in CSS</strong> Every frame lands in <code>--gesture-*</code> custom properties: scrubbable bottom sheets, swipe-to-dismiss, pinch-to-zoom, pull-to-refresh, parallax</li>\n<li><strong>Snap &amp; fling</strong> <code>snap-points</code> with velocity projection, a CSS transition on release (<code>--gesture-snap-duration</code> / <code>--gesture-snap-ease</code>), <code>gesture-handler-snap</code> when it lands</li>\n<li><strong>Drivable</strong> Bounds, <code>progress-offset</code> and <code>is-disabled</code> are attributes a Quark rule sets from the driven element&#39;s state</li>\n<li><strong>Scoped starts</strong> <code>from-ref</code> for drag handles, <code>from-edge</code> for edge swipes</li>\n<li><strong>Scroll handoff</strong> <code>handoff-ref</code> lets a sheet&#39;s own scrolling content take the drag over when it runs out of scroll — a native-feeling pull-to-close</li>\n<li><strong>Native scrolling kept</strong> <code>touch-action</code> follows <code>gesture-types</code>, so the page still scrolls where you don&#39;t pan</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Wrap the surface the user touches. Pick the gestures with <code>gesture-types</code>; read the finger from <code>--gesture-*</code> in CSS (custom properties inherit, so any descendant can <code>var()</code> them); commit State on <code>gesture-handler-end</code> or <code>-snap</code> from a Quark <code>@on</code> block.</p>\n<include-content data-language=\"html\"><template>&lt;gesture-handler gesture-types=\"pan-y swipe\" progress-axis=\"up\" range-ref=\":scope &gt; content-drawer\" snap-points=\"0 1\"&gt;\n  &lt;quark-sheet&gt;\n    :scope {\n      @on gesture-handler-start { content-drawer { is-scrubbing: \"\"; } }\n      @on gesture-handler-end { content-drawer { is-open: event.detail.snap == 1; is-scrubbing: none; } }\n    }\n  &lt;/quark-sheet&gt;\n  &lt;content-drawer&gt;…&lt;/content-drawer&gt;\n&lt;/gesture-handler&gt;</template></include-content>\n<p><code>--gesture-progress</code> is the travel along <code>progress-axis</code> as a fraction of the range (<code>range-ref</code> measures the driven element; <code>range-px</code> is a literal), clamped to <code>progress-min</code>..<code>progress-max</code> with optional <code>overshoot-resistance</code>. Written alongside it every frame: <code>--gesture-dx</code> / <code>-dy</code>, <code>--gesture-x</code> / <code>-y</code>, <code>--gesture-scale</code>, <code>--gesture-rotate</code>, <code>--gesture-vx</code> / <code>-vy</code>, <code>--gesture-pointers</code>; once per gesture: <code>--gesture-range-px</code>, <code>--gesture-width</code> / <code>-height</code>. Everything else is derived from those in the element&#39;s own CSS — <code>--gesture-distance</code>, <code>--gesture-angle</code>, <code>--gesture-progress-px</code>, <code>--gesture-x-ratio</code> / <code>-y-ratio</code> — so <code>var()</code> them the same way.</p>\n<p>Values persist after release until the next gesture starts. On release the default action writes <code>--gesture-progress</code> straight to <code>detail.snap</code> and the element&#39;s own <code>transition</code> settles it there over <code>--gesture-snap-duration</code> (<code>200ms</code>) with <code>--gesture-snap-ease</code> (<code>ease-out</code>), firing <code>gesture-handler-snap</code> when it lands; the transition is off while <code>is-active</code>, so the finger itself is never eased, and a new gesture that interrupts the settle simply cancels it (no <code>-snap</code>).</p>\n<h3 id=\"md-driving-nucleus-kit-elements\">Driving Nucleus Kit elements</h3>\n<p>Elements that can be scrubbed expose a <code>--&lt;tag&gt;-…-progress</code> input and an <code>is-scrubbing</code> attribute; both default to the wrapping gesture-handler&#39;s <code>--gesture-progress</code>, so no mapping is needed:</p>\n<table>\n<thead>\n<tr>\n<th>Element</th>\n<th>Set up</th>\n<th>While <code>is-scrubbing</code></th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>content-drawer</code></td>\n<td><code>progress-axis</code> towards its open side, <code>range-ref</code> the drawer, <code>handoff-ref</code> the drawer too (it scrolls its own content)</td>\n<td>Position follows <code>--content-drawer-open-progress</code> (<code>0</code> closed, <code>1</code> open), no transition</td>\n</tr>\n<tr>\n<td><code>content-carousel</code></td>\n<td><code>slide-animation=&quot;track&quot;</code>, <code>progress-min=&quot;-1&quot; progress-max=&quot;1&quot; snap-points=&quot;-1 0 1&quot;</code></td>\n<td>The track follows <code>--content-carousel-progress</code> in slide widths</td>\n</tr>\n</tbody></table>\n<p>The handoff is one Quark commit: the block that writes the final state (<code>is-open</code>, the active slide) also removes <code>is-scrubbing</code>, so the element switches from finger to State in the same paint. Commit on <code>-end</code> when a CSS transition should finish the motion (the drawer), on <code>-snap</code> when the element must be exactly at the snap point first (the carousel).</p>\n<p>Anything else follows the same recipe: read <code>--gesture-*</code> in your own CSS, gate the mapping on a fact your sheet writes on start and clears on end.</p>\n<p>Give a drag handle <code>touch-action: none</code> when using <code>from-ref</code>, so the browser does not scroll it away; without <code>from-ref</code> the element sets <code>touch-action</code> itself from <code>gesture-types</code>. Add <code>mouse</code> to <code>pointer-types</code> for desktop dragging.</p>\n<h3 id=\"md-scroll-handoff\">Scroll handoff</h3>\n<p><code>handoff-ref</code> names the scroll container(s) inside the surface whose <em>overscroll</em> starts a gesture (a <code>:scope</code>-relative selector; a comma list matches several). A pointer that goes down in one of them scrolls natively as usual. Only when its <strong>first</strong> move runs along <code>progress-axis</code>, the container is at its scroll limit that way, and <code>progress-offset</code> still has room to travel in that direction does the element cancel the native scroll for the rest of the touch and take the drag over — the same gesture, the same <code>--gesture-*</code> values and the same <code>-start</code> / <code>-end</code> / <code>-snap</code> events as a drag from a handle:</p>\n<include-content data-language=\"html\"><template>&lt;gesture-handler gesture-types=\"pan-y swipe\" progress-axis=\"up\" snap-points=\"0 1\"\n  from-ref=\":scope &gt; content-drawer &gt; header\" handoff-ref=\":scope &gt; content-drawer\"\n  range-ref=\":scope &gt; content-drawer\"&gt;</template></include-content>\n<p>An open sheet (<code>progress-offset: 1</code>) closes either from its header or by pulling its text down once the text is back at the top; pulling up, or pulling down mid-scroll, keeps scrolling. <code>handoff-ref</code> is additive — <code>from-ref</code> and <code>from-edge</code> starts are unchanged, and a <code>from-ref</code> handle inside a handoff container still starts on pointerdown. The element keeps <code>touch-action</code> out of the way while <code>handoff-ref</code> is set (the containers must be able to scroll), so give handles their own <code>touch-action: none</code>.</p>\n<p>Mouse drags (<code>pointer-types=&quot;… mouse&quot;</code>) take the same route with no native scroll to cancel: the first <code>pointermove</code> inside the container starts the gesture when the container is at its limit.</p>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-swipeable-carousel\">Swipeable carousel</h4>\n<p><code>slide-animation=&quot;track&quot;</code> turns <code>content-carousel</code> into a draggable track. <code>progress-axis=&quot;left&quot;</code> makes a leftward drag pull the next slide in; the <code>:has()</code> rules narrow the bounds at the first and last slide so nothing wraps mid-drag; the <code>gesture-handler-snap</code> block swaps <code>is-active</code> and un-scrubs in one commit.</p>\n<p><include-content data-demo=\"carousel\"></include-content></p>\n<h4 id=\"md-pinch-rotate-drag\">Pinch, rotate, drag</h4>\n<p>Two fingers (a trackpad or touch screen) for <code>--gesture-scale</code> and <code>--gesture-rotate</code>; one for <code>--gesture-dx</code> / <code>--gesture-dy</code>. Pure CSS mapping, no sheet. Each gesture starts from the resting values.</p>\n<p><include-content data-demo=\"pinch\"></include-content></p>\n<h4 id=\"md-swipe-to-dismiss\">Swipe to dismiss</h4>\n<p><code>snap-points=&quot;-1 0 1&quot;</code> with a literal <code>range-px</code>: a flick past <code>swipe-min-velocity</code> snaps the card off to the side, and the <code>gesture-handler-snap</code> block records the fact. A tap starts a new gesture (values reset) and clears it.</p>\n<p><include-content data-demo=\"swipe\"></include-content></p>\n"
+  },
+  "installation": {
+    "name": "@excom/gesture-handler",
+    "shortName": "gesture-handler",
+    "version": "0.1.0",
+    "description": "<gesture-handler> custom element",
+    "packageType": "kit-element",
+    "cdn": "<script src=\"https://unpkg.com/@excom/kit-utils/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/neutron/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/gesture-handler@0.1.0/dist/index.umd.min.js\"></script>\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@excom/gesture-handler@0.1.0/dist/index.css\">",
+    "install": {
+      "npm": "npm install @excom/gesture-handler"
+    },
+    "imports": {
+      "js": "import \"@excom/gesture-handler\";",
+      "css": "@import \"@excom/gesture-handler\";",
+      "html": "<!-- import path to `node_modules` will depend on your build setup -->\n<script type=\"module\" src=\"/node_modules/@excom/gesture-handler\"></script>\n<link rel=\"stylesheet\" href=\"/node_modules/@excom/gesture-handler\">"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "tag": "gesture-handler",
+      "summary": "Swipe / pan / pinch / tap recognition as events + CSS variables.",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "arm-after",
+          "type": "string",
+          "description": "Pans only arm after this gesture — <code>long-press</code> for hold-then-drag.",
+          "fieldName": "armAfter",
+          "surface": "option",
+          "values": "\"long-press\""
+        },
+        {
+          "name": "double-tap-ms",
+          "type": "number",
+          "description": "Max gap (ms) between taps for <code>double-tap</code>.",
+          "fieldName": "doubleTapMs",
+          "surface": "option",
+          "default": "300"
+        },
+        {
+          "name": "edge-px",
+          "type": "number",
+          "description": "Width of <code>from-edge</code> start zone (px).",
+          "fieldName": "edgePx",
+          "surface": "option",
+          "default": "40"
+        },
+        {
+          "name": "from-edge",
+          "type": "tokenlist",
+          "description": "Only start within <code>edge-px</code> of these edges — edge swipes (back nav, pulling a closed sheet up).",
+          "fieldName": "fromEdge",
+          "surface": "option",
+          "values": "\"left\" | \"right\" | \"top\" | \"bottom\""
+        },
+        {
+          "name": "from-ref",
+          "type": "string",
+          "description": "Only start when pointerdown is inside this descendant (<code>:scope</code>-relative selector) — a drag handle, the sheet itself. Combined with <code>from-edge</code>, either qualifies.",
+          "fieldName": "fromRef",
+          "surface": "option",
+          "values": "<CSS Selector>"
+        },
+        {
+          "name": "gesture-types",
+          "type": "tokenlist",
+          "description": "Gestures to recognize. <code>pan-x</code> / <code>pan-y</code> one axis (other stays native scroll); <code>pan</code> both; <code>pinch</code> / <code>rotate</code> need two fingers; <code>swipe</code> velocity on release; <code>tap</code> / <code>double-tap</code> / <code>long-press</code> fire events.",
+          "fieldName": "gestureTypes",
+          "surface": "option",
+          "default": "\"pan\"",
+          "values": "\"pan\" | \"pan-x\" | \"pan-y\" | \"pinch\" | \"rotate\" | \"swipe\" | \"tap\" | \"double-tap\" | \"long-press\""
+        },
+        {
+          "name": "handoff-ref",
+          "type": "string",
+          "description": "Scroll containers that hand overscroll to the gesture (<code>:scope</code>-relative selector, comma list matches several) — e.g. a sheet closed by pulling its own content down. Pointerdown inside one scrolls natively; gesture takes over only when first move runs along <code>progress-axis</code>, container is at that scroll limit, and <code>progress-offset</code> still has room that way. Additive to <code>from-ref</code> / <code>from-edge</code>.",
+          "fieldName": "handoffRef",
+          "surface": "option",
+          "values": "<CSS Selector>"
+        },
+        {
+          "name": "lock-axis",
+          "type": "boolean",
+          "description": "A free <code>pan</code> locks to its dominant axis once recognized (<code>gesture-type</code> becomes <code>pan-x</code> / <code>pan-y</code>).",
+          "fieldName": "lockAxis",
+          "surface": "option"
+        },
+        {
+          "name": "long-press-ms",
+          "type": "number",
+          "description": "Hold time (ms) for <code>long-press</code>; also tap time limit.",
+          "fieldName": "longPressMs",
+          "surface": "option",
+          "default": "500"
+        },
+        {
+          "name": "max-pointers",
+          "type": "number",
+          "description": "Extra pointers beyond this many are ignored. Unset = <code>2</code> when <code>pinch</code> / <code>rotate</code> listed, else <code>1</code>.",
+          "fieldName": "maxPointers",
+          "surface": "option"
+        },
+        {
+          "name": "overshoot-resistance",
+          "type": "number",
+          "description": "Rubber-band past <code>progress-min</code> / <code>progress-max</code>: <code>0</code> clamps, <code>0.3</code> overshoots at a third of travel.",
+          "fieldName": "overshootResistance",
+          "surface": "option",
+          "default": "0"
+        },
+        {
+          "name": "pointer-types",
+          "type": "tokenlist",
+          "description": "Pointer types that can start a gesture. Add <code>mouse</code> for desktop drag.",
+          "fieldName": "pointerTypes",
+          "surface": "option",
+          "default": "\"touch pen\"",
+          "values": "\"touch\" | \"pen\" | \"mouse\""
+        },
+        {
+          "name": "progress-axis",
+          "type": "string",
+          "description": "Direction <code>--gesture-progress</code> grows. Unset = <code>down</code> for a <code>pan-y</code>-only element, else <code>right</code>.",
+          "fieldName": "progressAxis",
+          "surface": "option",
+          "values": "\"up\" | \"down\" | \"left\" | \"right\""
+        },
+        {
+          "name": "progress-max",
+          "type": "number",
+          "description": "Upper bound of <code>progress</code>.",
+          "fieldName": "progressMax",
+          "surface": "option",
+          "default": "1"
+        },
+        {
+          "name": "progress-min",
+          "type": "number",
+          "description": "Lower bound of <code>progress</code>.",
+          "fieldName": "progressMin",
+          "surface": "option",
+          "default": "0"
+        },
+        {
+          "name": "progress-offset",
+          "type": "number",
+          "description": "Progress the gesture starts from. Set from a rule that reads the driven element&#39;s state (<code>1</code> while a sheet is open) so dragging it closed starts full.",
+          "fieldName": "progressOffset",
+          "surface": "option",
+          "default": "0"
+        },
+        {
+          "name": "range-px",
+          "type": "number",
+          "description": "Literal range (px) instead of <code>range-ref</code>.",
+          "fieldName": "rangePx",
+          "surface": "option"
+        },
+        {
+          "name": "range-ref",
+          "type": "string",
+          "description": "Element whose size along <code>progress-axis</code> is the range of <code>progress</code> <code>0</code>..<code>1</code> (<code>:scope</code>-relative, read once per gesture) — sheet being dragged, slide being swiped.",
+          "fieldName": "rangeRef",
+          "surface": "option",
+          "values": "<CSS Selector>"
+        },
+        {
+          "name": "should-emit-move",
+          "type": "boolean",
+          "description": "Fire <code>gesture-handler-move</code> every frame. Off by default; <code>--gesture-*</code> is enough for CSS.",
+          "fieldName": "shouldEmitMove",
+          "surface": "option"
+        },
+        {
+          "name": "snap-points",
+          "type": "tokenlist",
+          "description": "Progress values to settle on after release (<code>0 0.5 1</code>). Target picked from position, fling velocity and swipe direction, reported as <code>detail.snap</code> on <code>-end</code>, settled on by the default action (a CSS transition, <code>--gesture-snap-duration</code> / <code>--gesture-snap-ease</code>).",
+          "fieldName": "snapPoints",
+          "surface": "option",
+          "values": "<number>…"
+        },
+        {
+          "name": "swipe-directions",
+          "type": "tokenlist",
+          "description": "Swipe directions to report. Unset = all four.",
+          "fieldName": "swipeDirections",
+          "surface": "option",
+          "values": "\"left\" | \"right\" | \"up\" | \"down\""
+        },
+        {
+          "name": "swipe-min-velocity",
+          "type": "number",
+          "description": "Release velocity (px/ms) that counts as a swipe.",
+          "fieldName": "swipeMinVelocity",
+          "surface": "option",
+          "default": "0.5"
+        },
+        {
+          "name": "threshold-px",
+          "type": "number",
+          "description": "Movement (px) before a pan is recognized. Taps / native scroll stay untouched below it.",
+          "fieldName": "thresholdPx",
+          "surface": "option",
+          "default": "8"
+        },
+        {
+          "name": "is-disabled",
+          "type": "boolean",
+          "description": "Ignore new pointers; a gesture in progress is cancelled. State-driven veto.",
+          "fieldName": "isDisabled",
+          "surface": "hybrid"
+        },
+        {
+          "name": "gesture-direction",
+          "type": "string",
+          "description": "Dominant travel direction of gesture in progress.",
+          "fieldName": "gestureDirection",
+          "surface": "state",
+          "values": "\"left\" | \"right\" | \"up\" | \"down\""
+        },
+        {
+          "name": "gesture-type",
+          "type": "string",
+          "description": "Recognized gesture in progress, unset before recognition and after release.",
+          "fieldName": "gestureType",
+          "surface": "state",
+          "values": "\"pan\" | \"pan-x\" | \"pan-y\" | \"pinch\" | \"rotate\""
+        },
+        {
+          "name": "is-active",
+          "type": "boolean",
+          "description": "A pointer is down on the surface. Set from first pointer until release, so it also covers taps and pre-threshold phase.",
+          "fieldName": "isActive",
+          "surface": "state"
+        },
+        {
+          "name": "last-gesture",
+          "type": "string",
+          "description": "What last gesture turned out to be — style a &quot;just swiped&quot; state from it.",
+          "fieldName": "lastGesture",
+          "surface": "state",
+          "values": "\"pan\" | \"pan-x\" | \"pan-y\" | \"pinch\" | \"rotate\" | \"swipe-left\" | \"swipe-right\" | \"swipe-up\" | \"swipe-down\" | \"tap\" | \"double-tap\" | \"long-press\""
+        },
+        {
+          "name": "pointer-count",
+          "type": "number",
+          "description": "Pointers currently down.",
+          "fieldName": "pointerCount",
+          "surface": "state"
+        }
+      ],
+      "events": [
+        {
+          "name": "gesture-handler-cancel",
+          "description": "Recognized gesture cut short: browser took pointer (<code>pointercancel</code>, usually native scroll), <code>is-disabled</code> set, or element left the document. <code>detail</code> = provision. No <code>-end</code>, no glide.",
+          "type": "GestureHandlerCancelEvent",
+          "typeExpanded": "CustomEvent & { type: \"gesture-handler-cancel\"; detail: { x: number; y: number; dx: number; dy: number; vx: number; vy: number; progress: number; scale: number; rotate: number; pointers: number; } & { type: | \"pan\" | \"pan-x\" | \"pan-y\" | \"pinch\" | \"rotate\" | \"swipe\" | \"tap\" | \"double-tap\" | \"long-press\" | null; pointerType: string; distance: number; rangePx: number; durationMs: number; snap: number | null; swipe: \"left\" | \"right\" | \"up\" | \"down\" | null; }; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "gesture-handler-double-tap",
+          "description": "Second tap within <code>double-tap-ms</code> of the previous (after its <code>gesture-handler-tap</code>). <code>detail</code> = <code>{ x, y }</code>. Pair consumed; a third tap starts over.",
+          "type": "GestureHandlerPointEvent",
+          "typeExpanded": "CustomEvent & { type: | \"gesture-handler-tap\" | \"gesture-handler-double-tap\" | \"gesture-handler-long-press\"; detail: { x: number; y: number }; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "gesture-handler-end",
+          "description": "Last pointer up after a recognized gesture. After <code>is-active</code> unset, <code>last-gesture</code> + <code>provision</code> set, and after <code>gesture-handler-swipe</code> if one was recognized. <code>detail.snap</code> = <code>snap-points</code> target from position / velocity / swipe (<code>null</code> without <code>snap-points</code>); <code>detail.swipe</code> = swipe direction. Default action: write <code>--gesture-progress</code> = <code>detail.snap</code>, which settles with a CSS transition (<code>--gesture-snap-duration</code> / <code>--gesture-snap-ease</code>), then <code>gesture-handler-snap</code>. <code>preventDefault()</code> leaves values where the finger left them. Persist until next gesture.",
+          "type": "GestureHandlerEndEvent",
+          "typeExpanded": "CustomEvent & { type: \"gesture-handler-end\"; detail: { x: number; y: number; dx: number; dy: number; vx: number; vy: number; progress: number; scale: number; rotate: number; pointers: number; } & { type: | \"pan\" | \"pan-x\" | \"pan-y\" | \"pinch\" | \"rotate\" | \"swipe\" | \"tap\" | \"double-tap\" | \"long-press\" | null; pointerType: string; distance: number; rangePx: number; durationMs: number; snap: number | null; swipe: \"left\" | \"right\" | \"up\" | \"down\" | null; }; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "gesture-handler-long-press",
+          "description": "Pointer stayed down without moving for <code>long-press-ms</code>. <code>detail</code> = <code>{ x, y }</code>.",
+          "type": "GestureHandlerPointEvent",
+          "typeExpanded": "CustomEvent & { type: | \"gesture-handler-tap\" | \"gesture-handler-double-tap\" | \"gesture-handler-long-press\"; detail: { x: number; y: number }; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "gesture-handler-move",
+          "description": "Once per frame while a recognized gesture moves, only with <code>should-emit-move</code>. <code>detail</code> = provision. <code>--gesture-*</code> always updates, event or not.",
+          "type": "GestureHandlerMoveEvent",
+          "typeExpanded": "CustomEvent & { type: \"gesture-handler-move\"; detail: { x: number; y: number; dx: number; dy: number; vx: number; vy: number; progress: number; scale: number; rotate: number; pointers: number; } & { type: | \"pan\" | \"pan-x\" | \"pan-y\" | \"pinch\" | \"rotate\" | \"swipe\" | \"tap\" | \"double-tap\" | \"long-press\" | null; pointerType: string; distance: number; rangePx: number; durationMs: number; snap: number | null; swipe: \"left\" | \"right\" | \"up\" | \"down\" | null; }; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "gesture-handler-snap",
+          "description": "The settle transition reached the snap point (at once when there is nothing to animate; never when a new gesture interrupts it). <code>detail</code> = <code>{ value, index }</code> into <code>snap-points</code>. Commit here when consumer CSS follows <code>--gesture-progress</code> until the end.",
+          "type": "GestureHandlerSnapEvent",
+          "typeExpanded": "CustomEvent & { type: \"gesture-handler-snap\"; detail: { value: number; index: number }; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "gesture-handler-start",
+          "description": "Gesture recognized: pan passed <code>threshold-px</code> (after <code>arm-after</code> if set), or a second finger for <code>pinch</code> / <code>rotate</code>. After <code>gesture-type</code> + <code>provision</code> set. <code>detail</code> = provision. Not cancelable — gate with <code>is-disabled</code>.",
+          "type": "GestureHandlerStartEvent",
+          "typeExpanded": "CustomEvent & { type: \"gesture-handler-start\"; detail: { x: number; y: number; dx: number; dy: number; vx: number; vy: number; progress: number; scale: number; rotate: number; pointers: number; } & { type: | \"pan\" | \"pan-x\" | \"pan-y\" | \"pinch\" | \"rotate\" | \"swipe\" | \"tap\" | \"double-tap\" | \"long-press\" | null; pointerType: string; distance: number; rangePx: number; durationMs: number; snap: number | null; swipe: \"left\" | \"right\" | \"up\" | \"down\" | null; }; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "gesture-handler-swipe",
+          "description": "On release, velocity along dominant axis ≥ <code>swipe-min-velocity</code> and direction allowed by <code>swipe-directions</code>. <code>detail</code> = <code>{ direction, velocity }</code> (px/ms). Direction twin fires next (<code>gesture-handler-swipe-left</code> / <code>-right</code> / <code>-up</code> / <code>-down</code>).",
+          "type": "GestureHandlerSwipeEvent",
+          "typeExpanded": "CustomEvent & { type: \"gesture-handler-swipe\" | `gesture-handler-swipe-${\"left\" | \"right\" | \"up\" | \"down\"}`; detail: { direction: \"left\" | \"right\" | \"up\" | \"down\"; velocity: number }; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "gesture-handler-tap",
+          "description": "Down and up without moving past <code>threshold-px</code>, within <code>long-press-ms</code>. <code>detail</code> = <code>{ x, y }</code> relative to the element.",
+          "type": "GestureHandlerPointEvent",
+          "typeExpanded": "CustomEvent & { type: | \"gesture-handler-tap\" | \"gesture-handler-double-tap\" | \"gesture-handler-long-press\"; detail: { x: number; y: number }; bubbles: true; cancelable: true; composed: true }"
+        }
+      ],
+      "slots": [],
+      "cssProperties": [
+        {
+          "name": "--gesture-angle",
+          "description": "Direction of the travel: <code>0deg</code> right, <code>90deg</code> down. Computed from <code>--gesture-dx</code> / <code>--gesture-dy</code>.",
+          "syntax": "<angle>",
+          "default": "atan2(var(--gesture-dy), var(--gesture-dx))"
+        },
+        {
+          "name": "--gesture-distance",
+          "description": "Length of the travel (px). Computed from <code>--gesture-dx</code> / <code>--gesture-dy</code>.",
+          "syntax": "<length>",
+          "default": "hypot(var(--gesture-dx), var(--gesture-dy))"
+        },
+        {
+          "name": "--gesture-dx",
+          "description": "Horizontal travel since the gesture started (px) — drag-to-move, swipe-to-dismiss.",
+          "syntax": "<length>",
+          "default": "0px"
+        },
+        {
+          "name": "--gesture-dy",
+          "description": "Vertical travel since the gesture started (px).",
+          "syntax": "<length>",
+          "default": "0px"
+        },
+        {
+          "name": "--gesture-height",
+          "description": "The element&#39;s own height, measured when the gesture starts.",
+          "syntax": "<length>",
+          "default": "0px"
+        },
+        {
+          "name": "--gesture-pointers",
+          "description": "Pointers currently down.",
+          "syntax": "<integer>",
+          "default": "0"
+        },
+        {
+          "name": "--gesture-progress",
+          "description": "Travel along <code>progress-axis</code> as a fraction of the range, clamped to <code>progress-min</code>..<code>progress-max</code> — the value a scrubbable sheet, carousel or slider follows. Persists after release until the next gesture.",
+          "syntax": "<number>",
+          "default": "0"
+        },
+        {
+          "name": "--gesture-progress-px",
+          "description": "<code>--gesture-progress</code> in px. Computed from <code>--gesture-progress</code> and <code>--gesture-range-px</code>.",
+          "syntax": "<length>",
+          "default": "calc(var(--gesture-progress) * var(--gesture-range-px))"
+        },
+        {
+          "name": "--gesture-range-px",
+          "description": "The measured range (<code>range-ref</code> size along the axis, or <code>range-px</code>). Written once, when the gesture starts.",
+          "syntax": "<length>",
+          "default": "0px"
+        },
+        {
+          "name": "--gesture-rotate",
+          "description": "Two-finger rotation — rotate-to-adjust.",
+          "syntax": "<angle>",
+          "default": "0deg"
+        },
+        {
+          "name": "--gesture-scale",
+          "description": "Two-finger pinch ratio (<code>1</code> = unchanged) — pinch-to-zoom.",
+          "syntax": "<number>",
+          "default": "1"
+        },
+        {
+          "name": "--gesture-snap-duration",
+          "description": "How long <code>--gesture-progress</code> takes to settle on its snap point after release.",
+          "syntax": "<time>",
+          "default": "200ms"
+        },
+        {
+          "name": "--gesture-snap-ease",
+          "description": "Easing of that settle.",
+          "syntax": "<easing-function>",
+          "default": "ease-out"
+        },
+        {
+          "name": "--gesture-vx",
+          "description": "Horizontal velocity over the last ~100 ms (px/ms).",
+          "syntax": "<number>",
+          "default": "0"
+        },
+        {
+          "name": "--gesture-vy",
+          "description": "Vertical velocity over the last ~100 ms (px/ms).",
+          "syntax": "<number>",
+          "default": "0"
+        },
+        {
+          "name": "--gesture-width",
+          "description": "The element&#39;s own width, measured when the gesture starts.",
+          "syntax": "<length>",
+          "default": "0px"
+        },
+        {
+          "name": "--gesture-x",
+          "description": "Pointer centroid inside the element (px), horizontal — spotlight / parallax effects. Written every frame of a gesture; this is the resting value.",
+          "syntax": "<length>",
+          "default": "0px"
+        },
+        {
+          "name": "--gesture-x-ratio",
+          "description": "<code>--gesture-x</code> as a 0..1 fraction of the element&#39;s width. Computed from <code>--gesture-x</code> and <code>--gesture-width</code>.",
+          "syntax": "<number>",
+          "default": "tan(atan2(var(--gesture-x), var(--gesture-width)))"
+        },
+        {
+          "name": "--gesture-y",
+          "description": "Pointer centroid inside the element (px), vertical.",
+          "syntax": "<length>",
+          "default": "0px"
+        },
+        {
+          "name": "--gesture-y-ratio",
+          "description": "<code>--gesture-y</code> as a 0..1 fraction of the element&#39;s height. Computed from <code>--gesture-y</code> and <code>--gesture-height</code>.",
+          "syntax": "<number>",
+          "default": "tan(atan2(var(--gesture-y), var(--gesture-height)))"
+        }
+      ],
+      "cssClasses": [],
+      "cssAliases": [
+        {
+          "name": ":--gesture-handler",
+          "selectors": [
+            "gesture-handler",
+            ".tag-gesture-handler"
+          ],
+          "kind": "element",
+          "description": ""
+        },
+        {
+          "name": ":--gesture-handler--is-active",
+          "selectors": [
+            "[is-active]",
+            "[data-active]"
+          ],
+          "kind": "state",
+          "description": ""
+        }
+      ],
+      "listens": [],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [],
+      "provisions": [
+        {
+          "name": "provision",
+          "type": "GestureHandlerProvision",
+          "typeExpanded": "{ x: number; y: number; dx: number; dy: number; vx: number; vy: number; progress: number; scale: number; rotate: number; pointers: number; } & { type: | \"pan\" | \"pan-x\" | \"pan-y\" | \"pinch\" | \"rotate\" | \"swipe\" | \"tap\" | \"double-tap\" | \"long-press\" | null; pointerType: string; distance: number; rangePx: number; durationMs: number; snap: number | null; swipe: \"left\" | \"right\" | \"up\" | \"down\" | null; }",
+          "description": "Last <code>-start</code> / <code>-end</code> / <code>-cancel</code> snapshot (<code>type</code>, travel, velocity, progress, <code>snap</code>, <code>swipe</code>, …). Not an attribute; per-frame values live in <code>--gesture-*</code>.",
+          "fieldName": "provision"
+        }
+      ]
+    }
+  ],
+  "exportedFiles": {}
+}

package/support/tests/carousel.view.test.ts

@@ -0,0 +1,67 @@
+import "@excom/quark-sheet";
+import "@excom/content-carousel";
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+  wait,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import {
+  flush,
+  mountView,
+  readDemo,
+} from "@excom/quark/support/tests/view-helpers";
+import { drag } from "./pointer-utils";
+
+describe("carousel view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("drags the track, snaps to the next slide and clamps at the ends", async () => {
+    const { root } = await mountView(readDemo(import.meta.url, "carousel"));
+    const handler = root as HTMLGestureHandlerElement;
+    const carousel = root.querySelector("content-carousel")!;
+    const slides = [...carousel.querySelectorAll("content-carousel-slide")];
+    Object.defineProperty(carousel, "offsetWidth", { value: 300 });
+    const active = () => slides.findIndex((s) => s.hasAttribute("is-active"));
+    expect(active()).toBe(0);
+    // first slide: no dragging backwards
+    expect(handler.getAttribute("progress-min")).toBe("0");
+    expect(handler.getAttribute("progress-max")).toBe("1");
+
+    // drag left two thirds of a slide, let go: snaps to 1 → slide two
+    const release = await drag(carousel, { x: 250, y: 50 }, { x: 50, y: 50 });
+    await flush();
+    expect(carousel.hasAttribute("is-scrubbing")).toBe(true);
+    expect(handler.style.getPropertyValue("--gesture-progress")).toBe("0.6667");
+    await wait(150);
+    release();
+    expect(handler.provision?.snap).toBe(1);
+    await wait(0); // the settle has nothing to animate here → -snap at once
+    await flush();
+    expect(handler.style.getPropertyValue("--gesture-progress")).toBe("1");
+    expect(active()).toBe(1);
+    expect(carousel.hasAttribute("is-scrubbing")).toBe(false);
+    expect(handler.getAttribute("progress-min")).toBe("-1");
+
+    // a short drag right snaps back to 0: the slide stays
+    const stay = await drag(carousel, { x: 100, y: 50 }, { x: 130, y: 50 });
+    await wait(150);
+    stay();
+    await wait(0);
+    await flush();
+    expect(active()).toBe(1);
+
+    // drag right past half: previous slide
+    const back = await drag(carousel, { x: 50, y: 50 }, { x: 250, y: 50 });
+    await wait(150);
+    back();
+    await wait(0);
+    await flush();
+    expect(active()).toBe(0);
+    expect(handler.getAttribute("progress-min")).toBe("0");
+  });
+});