chore(deps): update dependency eslint-plugin-unicorn to v73

FetchOptions['body'] listed `Record<string, unknown>`, which a named interface
is not assignable to (interfaces carry no implicit index signature), so every
caller passing a typed body had to cast it. Widen the object member to `object`:
named interfaces and arrays now assign directly, `any` is not introduced, and
bare primitives (number/boolean) are still rejected. Runtime is unchanged — the
serializer already narrows the body with its own casts.

Guard it with a type test (src/types.test-d.ts, run under vitest --typecheck):
a named interface must assign to the body type and flow through the method
shortcuts with no cast, while bare primitives stay rejected. Enable typecheck
for the package's vitest project so the assertions are enforced by tsc.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.gitea/workflows/ci.yaml

@@ -53,7 +53,7 @@ jobs:
         with:
           run_install: false
 
-      - uses: actions/setup-node@v6
+      - uses: actions/setup-node@v7
         with:
           node-version: ${{ env.NODE_VERSION }}
           cache: pnpm

.gitea/workflows/publish.yaml

@@ -5,6 +5,12 @@ on:
     branches:
       - master
 
+# The registry is append-only — a half-finished release cannot be rolled back.
+# One publish at a time, and never cancel one that is already writing.
+concurrency:
+  group: publish-npm
+  cancel-in-progress: false
+
 env:
   NODE_VERSION: 24.x
 
@@ -22,11 +28,41 @@ jobs:
         with:
           run_install: false
 
-      - uses: actions/setup-node@v6
+      - uses: actions/setup-node@v7
         with:
           node-version: ${{ env.NODE_VERSION }}
           cache: pnpm
-          registry-url: 'https://registry.npmjs.org'
+          # No `registry-url:` on purpose. It writes an npmrc holding the literal
+          # string `${NODE_AUTH_TOKEN}` and points NPM_CONFIG_USERCONFIG at it,
+          # which would shadow the file the next step writes. We supply the token
+          # verbatim instead, so no variable-expansion rules can apply.
+
+      # npm masks an unauthorized write as `404 Not Found` rather than 401, so a
+      # dead token surfaces as "package does not exist" three steps later, after
+      # a full build+test. Verify the credential up front and say so plainly.
+      - name: Authenticate to npm
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "${NPM_TOKEN:-}" ]; then
+            echo "::error::secrets.NPM_TOKEN is empty or not set for this repo."
+            echo "::error::Add it under Gitea > Settings > Actions > Secrets."
+            exit 1
+          fi
+
+          printf '//registry.npmjs.org/:_authToken=%s\n' "$NPM_TOKEN" > "$HOME/.npmrc"
+          chmod 600 "$HOME/.npmrc"
+
+          if ! WHO=$(npm whoami --registry=https://registry.npmjs.org 2>&1); then
+            echo "::error::npm rejected the token — expired, revoked, or wrong account."
+            echo "::error::npm said: ${WHO}"
+            echo "::error::Mint a granular token with read+write on the @robonen scope"
+            echo "::error::at npmjs.com and update the Gitea secret."
+            exit 1
+          fi
+          echo "Authenticated to npm as: ${WHO}"
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
@@ -38,8 +74,6 @@ jobs:
         run: pnpm build && pnpm test
 
       - name: Check for version changes and publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
           # Find all package.json files (excluding node_modules)
           PACKAGE_FILES=$(find . -path "*/package.json" -not -path "*/node_modules/*")
@@ -79,3 +113,7 @@ jobs:
               echo "No version change detected for $PACKAGE_NAME"
             fi
           done
+
+      - name: Scrub credentials
+        if: always()
+        run: rm -f "$HOME/.npmrc"

configs/eslint/package.json

@@ -17,7 +17,7 @@
     "url": "git+https://github.com/robonen/tools.git",
     "directory": "configs/eslint"
   },
-  "packageManager": "pnpm@11.7.0",
+  "packageManager": "pnpm@11.18.0",
   "engines": {
     "node": ">=24.16.0"
   },
@@ -48,15 +48,15 @@
   "dependencies": {
     "@eslint/js": "^10.0.1",
     "@stylistic/eslint-plugin": "catalog:",
-    "@vitest/eslint-plugin": "^1.6.20",
-    "eslint-plugin-import-x": "^4.16.2",
-    "eslint-plugin-n": "^18.1.0",
-    "eslint-plugin-regexp": "^3.1.0",
-    "eslint-plugin-unicorn": "^71.1.0",
-    "eslint-plugin-vue": "^10.9.2",
-    "globals": "^17.6.0",
+    "@vitest/eslint-plugin": "^1.6.24",
+    "eslint-plugin-import-x": "^4.17.1",
+    "eslint-plugin-n": "^18.2.2",
+    "eslint-plugin-regexp": "^3.1.1",
+    "eslint-plugin-unicorn": "^73.0.0",
+    "eslint-plugin-vue": "^10.10.0",
+    "globals": "^17.8.0",
     "jiti": "^2.7.0",
-    "typescript-eslint": "^8.61.1",
+    "typescript-eslint": "^8.65.0",
     "vue-eslint-parser": "^10.4.1"
   },
   "devDependencies": {

configs/tsconfig/package.json

@@ -15,7 +15,7 @@
     "url": "git+https://github.com/robonen/tools.git",
     "directory": "packages/tsconfig"
   },
-  "packageManager": "pnpm@11.7.0",
+  "packageManager": "pnpm@11.18.0",
   "engines": {
     "node": ">=24.16.0"
   },

configs/tsdown/package.json

@@ -15,7 +15,7 @@
     "url": "git+https://github.com/robonen/tools.git",
     "directory": "configs/tsdown"
   },
-  "packageManager": "pnpm@11.7.0",
+  "packageManager": "pnpm@11.18.0",
   "engines": {
     "node": ">=24.16.0"
   },

core/crdt/package.json

@@ -17,7 +17,7 @@
     "url": "git+https://github.com/robonen/tools.git",
     "directory": "core/crdt"
   },
-  "packageManager": "pnpm@11.7.0",
+  "packageManager": "pnpm@11.18.0",
   "engines": {
     "node": ">=24.16.0"
   },

core/encoding/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/robonen/tools.git",
     "directory": "core/encoding"
   },
-  "packageManager": "pnpm@11.7.0",
+  "packageManager": "pnpm@11.18.0",
   "engines": {
     "node": ">=24.16.0"
   },

core/fetch/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robonen/fetch",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "license": "Apache-2.0",
   "description": "A lightweight, type-safe fetch wrapper with interceptors, retry, and V8-optimized internals",
   "keywords": [
@@ -15,7 +15,7 @@
     "url": "git+https://github.com/robonen/tools.git",
     "directory": "core/fetch"
   },
-  "packageManager": "pnpm@11.7.0",
+  "packageManager": "pnpm@11.18.0",
   "engines": {
     "node": ">=24.16.0"
   },

core/fetch/src/types.test-d.ts

@@ -0,0 +1,40 @@
+import { assertType, describe, expectTypeOf, it } from 'vitest';
+
+import type { FetchOptions } from './types';
+import { createFetch } from './fetch';
+
+type Body = FetchOptions['body'];
+
+describe('FetchOptions body', () => {
+  it('accepts a named interface without a cast', () => {
+    // The regression under test: a named `interface` has no implicit index
+    // signature, so a `Record<string, unknown>` body type would reject it and
+    // force a cast at every call site. It must assign directly.
+    interface CreateUser { name: string; age: number }
+    expectTypeOf<CreateUser>().toExtend<Body>();
+    assertType<Body>({ name: 'Alice', age: 30 } satisfies CreateUser);
+  });
+
+  it('accepts plain objects, arrays, BodyInit strings and null', () => {
+    assertType<Body>({ a: 1 });
+    assertType<Body>([1, 2, 3]);
+    assertType<Body>('raw string');
+    assertType<Body>(new FormData());
+    assertType<Body>(null);
+  });
+
+  it('rejects bare primitives', () => {
+    // @ts-expect-error a bare number is not a valid request body
+    assertType<Body>(42);
+    // @ts-expect-error a bare boolean is not a valid request body
+    assertType<Body>(true);
+  });
+
+  it('lets a typed interface flow through the method shortcuts', () => {
+    interface CreateDeal { title: string; amount: number }
+    const $fetch = createFetch();
+    const deal: CreateDeal = { title: 'x', amount: 1 };
+    // Must type-check with no cast on the body.
+    expectTypeOf($fetch.post).toBeCallableWith('/deals', { body: deal });
+  });
+});

core/fetch/src/types.ts

@@ -79,8 +79,14 @@ export interface FetchOptions<R extends ResponseType = 'json', T = unknown>
   FetchHooks<T, R> {
   /** Base URL prepended to all relative request URLs */
   baseURL?: string;
-  /** Request body — plain objects are automatically JSON-serialized */
-  body?: RequestInit['body'] | Record<string, unknown> | unknown[] | null;
+  /**
+   * Request body. `BodyInit` values (string, Blob, FormData, streams, …) are
+   * sent as-is; any other object or array is JSON-serialized. Typed as `object`
+   * rather than `Record<string, unknown>` so a named `interface` assigns
+   * directly — interfaces carry no implicit index signature and would otherwise
+   * force every caller to cast the body.
+   */
+  body?: RequestInit['body'] | object | null;
   /** Suppress throwing on 4xx/5xx responses */
   ignoreResponseError?: boolean;
   /** URL query parameters serialized and appended to the request URL */

core/fetch/vitest.config.ts

@@ -3,5 +3,11 @@ import { defineConfig } from 'vitest/config';
 export default defineConfig({
   test: {
     environment: 'node',
+    // Type tests (*.test-d.ts) are statically analyzed with `tsc --noEmit`
+    // alongside the runtime suite.
+    typecheck: {
+      enabled: true,
+      tsconfig: './tsconfig.src.json',
+    },
   },
 });

core/platform/package.json

@@ -18,7 +18,7 @@
     "url": "git+https://github.com/robonen/tools.git",
     "directory": "packages/platform"
   },
-  "packageManager": "pnpm@11.7.0",
+  "packageManager": "pnpm@11.18.0",
   "engines": {
     "node": ">=24.16.0"
   },

core/stdlib/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robonen/stdlib",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "license": "Apache-2.0",
   "description": "A collection of tools, utilities, and helpers for TypeScript",
   "keywords": [
@@ -18,7 +18,7 @@
     "url": "git+https://github.com/robonen/tools.git",
     "directory": "packages/stdlib"
   },
-  "packageManager": "pnpm@11.7.0",
+  "packageManager": "pnpm@11.18.0",
   "engines": {
     "node": ">=24.16.0"
   },
@@ -52,6 +52,6 @@
     "@robonen/tsdown": "workspace:*",
     "eslint": "catalog:",
     "tsdown": "catalog:",
-    "typescript": "^6.0.3"
+    "typescript": "catalog:"
   }
 }

core/stdlib/src/patterns/behavioral/StateMachine/index.test-d.ts

@@ -21,4 +21,28 @@ describe('createMachine', () => {
   it('send returns the (typed) resulting state', () => {
     expectTypeOf(machine.send('START')).toEqualTypeOf<'idle' | 'running'>();
   });
+
+  it('empty terminal nodes do not widen the event union to string', () => {
+    const terminal = createMachine({
+      initial: 'idle',
+      states: {
+        idle: { on: { START: 'done' } },
+        done: {},
+      },
+    });
+
+    expectTypeOf(terminal.send).parameter(0).toEqualTypeOf<'START'>();
+  });
+
+  it('entry/exit-only nodes do not widen the event union either', () => {
+    const hooked = createMachine({
+      initial: 'idle',
+      states: {
+        idle: { on: { START: 'done' } },
+        done: { entry: () => {} },
+      },
+    });
+
+    expectTypeOf(hooked.send).parameter(0).toEqualTypeOf<'START'>();
+  });
 });

core/stdlib/src/patterns/behavioral/StateMachine/index.test.ts

@@ -418,6 +418,7 @@ describe('asyncStateMachine', () => {
         },
       });
 
+      // @ts-expect-error -- deliberately undeclared event: runtime must ignore it
       const result = await machine.send('STOP');
 
       expect(result).toBe('idle');
@@ -597,6 +598,7 @@ describe('asyncStateMachine', () => {
         },
       });
 
+      // @ts-expect-error -- deliberately undeclared event: can() must report false
       expect(await machine.can('STOP')).toBe(false);
     });
 

core/stdlib/src/patterns/behavioral/StateMachine/types.ts

@@ -57,8 +57,12 @@ export type AsyncStateNodeConfig<Context> = StateNodeConfig<Context, MaybePromis
 
 export type ExtractStates<T> = keyof T & string;
 
+// `on` is matched as REQUIRED here on purpose: an empty terminal node (`{}`)
+// satisfies an optional-`on` pattern with no inference candidate, so `infer E`
+// would fall back to its constraint and collapse the whole union to `string`,
+// silently accepting any event name in `send`/`can`.
 export type ExtractEvents<T> = {
-  [K in keyof T]: T[K] extends { readonly on?: Readonly<Record<infer E extends string, unknown>> }
+  [K in keyof T]: T[K] extends { readonly on: Readonly<Record<infer E extends string, unknown>> }
     ? E
     : never;
 }[keyof T];

core/stdlib/src/structs/FenwickTree/index.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+
+import { FenwickTree } from '.';
+
+/** Deterministic LCG so failures reproduce. */
+function lcg(seed: number): () => number {
+  let state = seed;
+  return () => {
+    state = (state * 48271) % 2147483647;
+    return state / 2147483647;
+  };
+}
+
+describe('FenwickTree', () => {
+  it('should match naive sums after build', () => {
+    const rand = lcg(1);
+    const values = Array.from({ length: 137 }, () => Math.floor(rand() * 100));
+    const tree = new FenwickTree(values.length);
+    tree.build(values);
+
+    let sum = 0;
+    for (let i = 0; i <= values.length; i++) {
+      expect(tree.prefix(i)).toBe(sum);
+      if (i < values.length)
+        sum += values[i]!;
+    }
+  });
+
+  it('should keep prefix sums consistent with a naive array under updates', () => {
+    const rand = lcg(2);
+    const length = 64;
+    const naive = Array.from({ length }, () => Math.floor(rand() * 50));
+    const tree = new FenwickTree(length);
+    tree.build(naive);
+
+    for (let op = 0; op < 500; op++) {
+      const index = Math.floor(rand() * length);
+      const delta = Math.floor(rand() * 40) - 20;
+      naive[index]! += delta;
+      tree.update(index, delta);
+
+      const probe = Math.floor(rand() * (length + 1));
+      const expected = naive.slice(0, probe).reduce((a, b) => a + b, 0);
+      expect(tree.prefix(probe)).toBe(expected);
+    }
+  });
+
+  it('should match a linear scan in lowerBound, including stride and zero values', () => {
+    const rand = lcg(3);
+    for (let round = 0; round < 20; round++) {
+      const length = 1 + Math.floor(rand() * 40);
+      const values = Array.from({ length }, () => rand() < 0.2 ? 0 : Math.floor(rand() * 60));
+      const stride = round % 3 === 0 ? 0 : Math.floor(rand() * 10);
+      const tree = new FenwickTree(length);
+      tree.build(values);
+
+      const total = values.reduce((a, b) => a + b, 0) + length * stride;
+      for (const target of [-5, 0, 1, total / 3, total / 2, total - 1, total, total + 100]) {
+        let expected = 0;
+        for (let c = 0; c <= length; c++) {
+          const g = values.slice(0, c).reduce((a, b) => a + b, 0) + c * stride;
+          if (g <= target)
+            expected = c;
+          else
+            break;
+        }
+        if (target < 0)
+          expected = 0;
+        expect(tree.lowerBound(target, stride), `length=${length} stride=${stride} target=${target}`).toBe(expected);
+      }
+    }
+  });
+
+  it('should handle an empty tree', () => {
+    const tree = new FenwickTree(0);
+
+    expect(tree.prefix(0)).toBe(0);
+    expect(tree.lowerBound(0)).toBe(0);
+    expect(tree.lowerBound(100)).toBe(0);
+  });
+
+  it('should rebuild in place via build', () => {
+    const tree = new FenwickTree(4);
+    tree.build([1, 2, 3, 4]);
+    expect(tree.prefix(4)).toBe(10);
+
+    tree.build([10, 10, 10, 10]);
+    expect(tree.prefix(2)).toBe(20);
+    expect(tree.prefix(4)).toBe(40);
+  });
+});

core/stdlib/src/structs/FenwickTree/index.ts

@@ -0,0 +1,95 @@
+/**
+ * @name FenwickTree
+ * @category Data Structures
+ * @description Fenwick (Binary Indexed) tree over an array of non-negative
+ * numbers: O(log n) prefix sums, point updates, and monotonic lower-bound
+ * search, plus O(n) bulk rebuild. `lowerBound` assumes all values are
+ * non-negative (the prefix function must be non-decreasing)
+ *
+ * @example
+ * const tree = new FenwickTree(5);
+ * tree.build([10, 20, 30, 40, 50]);
+ * tree.prefix(3); // 60
+ * tree.update(1, 5); // value at index 1 becomes 25
+ * tree.lowerBound(65); // 3 — largest c with prefix(c) <= 65
+ *
+ * @since 0.0.11
+ */
+export class FenwickTree {
+  readonly size: number;
+  private readonly tree: Float64Array;
+  private readonly highBit: number;
+
+  constructor(size: number) {
+    this.size = size;
+    this.tree = new Float64Array(size + 1);
+    this.highBit = size > 0 ? 1 << (31 - Math.clz32(size)) : 0;
+  }
+
+  /**
+   * Bulk (re)initialization from raw values, O(n)
+   *
+   * @param {ArrayLike<number>} values The values to load, `values.length` must equal `size`
+   */
+  build(values: ArrayLike<number>): void {
+    const { tree, size } = this;
+    tree.fill(0);
+    for (let i = 1; i <= size; i++) {
+      tree[i]! += values[i - 1]!;
+      const parent = i + (i & -i);
+      if (parent <= size)
+        tree[parent]! += tree[i]!;
+    }
+  }
+
+  /**
+   * Add `delta` to the value at `index`, O(log n)
+   *
+   * @param {number} index Zero-based index of the value to change
+   * @param {number} delta Amount to add (may be negative)
+   */
+  update(index: number, delta: number): void {
+    for (let i = index + 1; i <= this.size; i += i & -i)
+      this.tree[i]! += delta;
+  }
+
+  /**
+   * Sum of the first `count` values, O(log n)
+   *
+   * @param {number} count How many leading values to sum
+   * @returns {number} The prefix sum
+   */
+  prefix(count: number): number {
+    let sum = 0;
+    for (let i = count; i > 0; i -= i & -i)
+      sum += this.tree[i]!;
+    return sum;
+  }
+
+  /**
+   * Largest `c` in `[0, size]` with `prefix(c) + c * stride <= target`, O(log n).
+   * `stride` models a constant per-item addition (e.g. a layout gap) without
+   * storing it in the tree
+   *
+   * @param {number} target The offset to search for
+   * @param {number} stride Constant added per item, defaults to `0`
+   * @returns {number} The largest count whose strided prefix does not exceed `target`
+   */
+  lowerBound(target: number, stride = 0): number {
+    if (target < 0)
+      return 0;
+    let pos = 0;
+    let sum = 0;
+    for (let step = this.highBit; step > 0; step >>= 1) {
+      const next = pos + step;
+      if (next <= this.size) {
+        const candidate = sum + this.tree[next]!;
+        if (candidate + next * stride <= target) {
+          pos = next;
+          sum = candidate;
+        }
+      }
+    }
+    return pos;
+  }
+}

core/stdlib/src/structs/index.ts

@@ -1,6 +1,7 @@
 export * from './BinaryHeap';
 export * from './CircularBuffer';
 export * from './Deque';
+export * from './FenwickTree';
 export * from './LinkedList';
 export * from './PriorityQueue';
 export * from './Queue';

docs/package.json

@@ -17,22 +17,22 @@
     "extract": "jiti ./modules/extractor/extract.ts"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "marked": "^18.0.5",
-    "shiki": "^4.2.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "marked": "^18.0.7",
+    "shiki": "^4.3.1",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@nuxt/fonts": "^0.14.0",
-    "@nuxt/kit": "^4.4.8",
+    "@nuxt/kit": "^4.5.1",
     "@robonen/eslint": "workspace:*",
-    "@tailwindcss/vite": "^4.3.1",
+    "@tailwindcss/vite": "^4.3.3",
     "eslint": "catalog:",
     "jiti": "^2.7.0",
     "nuxt": "catalog:",
-    "tailwindcss": "^4.3.1",
+    "tailwindcss": "^4.3.3",
     "ts-morph": "^28.0.0",
     "vue": "catalog:",
-    "vue-router": "^5.1.0"
+    "vue-router": "^5.2.0"
   }
 }

infra/renovate/package.json

@@ -16,7 +16,7 @@
     "url": "git+https://github.com/robonen/tools.git",
     "directory": "packages/renovate"
   },
-  "packageManager": "pnpm@11.7.0",
+  "packageManager": "pnpm@11.18.0",
   "engines": {
     "node": ">=24.16.0"
   },
@@ -27,6 +27,6 @@
     "test": "renovate-config-validator ./default.json"
   },
   "devDependencies": {
-    "renovate": "^43.228.0"
+    "renovate": "^44.2.1"
   }
 }

package.json

@@ -15,20 +15,20 @@
     "type": "git",
     "url": "git+https://github.com/robonen/tools.git"
   },
-  "packageManager": "pnpm@11.7.0",
+  "packageManager": "pnpm@11.18.0",
   "engines": {
     "node": ">=24.16.0"
   },
   "type": "module",
   "devDependencies": {
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.1.2",
     "@vitest/coverage-v8": "catalog:",
     "@vitest/ui": "catalog:",
     "citty": "^0.2.2",
     "jiti": "^2.7.0",
     "jsdom": "catalog:",
     "scule": "^1.3.0",
-    "typescript": "^6.0.3",
+    "typescript": "catalog:",
     "vitest": "catalog:"
   },
   "scripts": {

pnpm-workspace.yaml

@@ -16,17 +16,30 @@ allowBuilds:
 
 catalog:
   '@stylistic/eslint-plugin': ^5.10.0
-  '@vitest/browser': ^4.1.9
-  '@vitest/coverage-v8': ^4.1.9
-  '@vitest/ui': ^4.1.9
-  '@vue/shared': ^3.5.38
+  '@vitest/browser': ^4.1.10
+  '@vitest/coverage-v8': ^4.1.10
+  '@vitest/ui': ^4.1.10
+  '@vue/shared': ^3.5.40
   '@vue/test-utils': ^2.4.11
-  eslint: ^10.5.0
-  jsdom: ^29.1.1
-  nuxt: ^4.4.8
-  tsdown: ^0.22.3
-  vitest: ^4.1.9
-  vue: ^3.5.38
+  eslint: ^10.8.0
+  jsdom: ^30.0.1
+  nuxt: ^4.5.1
+  tsdown: ^0.22.14
+  typescript: npm:typescript-native-bridge@6.0.3-bridge.7.tsgo.7.0.2
+  vitest: ^4.1.10
+  vue: ^3.5.40
+
+# TypeScript 7.0 dropped the classic JS compiler API (`require('typescript')`
+# exports only `version`/`versionMajorMinor`), which breaks every Volar/tsc-API
+# consumer we depend on: `@vue/compiler-sfc` type resolution (needs `ts.sys`),
+# `rolldown-plugin-dts`'s Vue language (needs `ts.ScriptKind`) and `vue-tsc`.
+# `typescript-native-bridge` keeps that API surface while type-checking on the
+# native tsgo 7.0.2 engine, so we get the new compiler without the breakage.
+# Overridden (not just cataloged) because the consumers above resolve
+# `typescript` as a transitive peer, not as one of our direct dependencies.
+# The version must be pinned exactly — caret ranges never match prereleases.
+overrides:
+  typescript: npm:typescript-native-bridge@6.0.3-bridge.7.tsgo.7.0.2
 
 ignoredBuiltDependencies:
   - '@parcel/watcher'

vue/primitives/jsr.json

@@ -2,6 +2,6 @@
   "$schema": "https://jsr.io/schema/config-file.v1.json",
   "name": "@robonen/primitives",
   "license": "Apache-2.0",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "exports": "./src/index.ts"
 }

vue/primitives/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robonen/primitives",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "license": "Apache-2.0",
   "description": "Collection of UI primitives",
   "keywords": [
@@ -15,7 +15,7 @@
     "url": "git+https://github.com/robonen/tools.git",
     "directory": "vue/primitives"
   },
-  "packageManager": "pnpm@11.7.0",
+  "packageManager": "pnpm@11.18.0",
   "engines": {
     "node": ">=24.16.0"
   },
@@ -59,19 +59,19 @@
     "@robonen/tsconfig": "workspace:*",
     "@robonen/tsdown": "workspace:*",
     "@vitest/browser": "catalog:",
-    "@vitest/browser-playwright": "^4.1.9",
+    "@vitest/browser-playwright": "^4.1.10",
     "@vue/test-utils": "catalog:",
     "axe-core": "^4.12.1",
     "eslint": "catalog:",
-    "playwright": "^1.61.0",
+    "playwright": "^1.62.0",
     "tsdown": "catalog:",
     "unplugin-vue": "^7.2.0",
     "vitest-browser-vue": "^2.1.0",
     "vue": "catalog:",
-    "vue-tsc": "^3.3.5"
+    "vue-tsc": "^3.3.8"
   },
   "dependencies": {
-    "@floating-ui/vue": "^2.0.0",
+    "@floating-ui/vue": "^2.0.1",
     "@robonen/encoding": "workspace:*",
     "@robonen/platform": "workspace:*",
     "@robonen/stdlib": "workspace:*",

vue/primitives/playground/package.json

@@ -13,14 +13,14 @@
   "dependencies": {
     "@robonen/primitives": "workspace:*",
     "vue": "catalog:",
-    "vue-router": "^5.1.0"
+    "vue-router": "^5.2.0"
   },
   "devDependencies": {
     "@robonen/tsconfig": "workspace:*",
-    "@tailwindcss/vite": "^4.3.1",
-    "@vitejs/plugin-vue": "^6.0.7",
-    "tailwindcss": "^4.3.1",
-    "vite": "^8.0.16",
-    "vue-tsc": "^3.3.5"
+    "@tailwindcss/vite": "^4.3.3",
+    "@vitejs/plugin-vue": "^6.0.8",
+    "tailwindcss": "^4.3.3",
+    "vite": "^8.1.5",
+    "vue-tsc": "^3.3.8"
   }
 }

vue/primitives/src/overlays/drawer/DrawerClose.vue

@@ -0,0 +1,25 @@
+<script lang="ts">
+import type { DialogCloseProps } from '../dialog';
+
+/**
+ * A button that closes the drawer when activated. A thin wrapper over Dialog's
+ * Close that tags the resulting `update:open` with the `close-press` reason.
+ */
+export interface DrawerCloseProps extends DialogCloseProps {}
+</script>
+
+<script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
+import { DialogClose } from '../dialog';
+import { injectDrawerRootContext } from './context';
+
+const props = defineProps<DrawerCloseProps>();
+const { armReason } = injectDrawerRootContext();
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <DialogClose v-bind="props" :ref="forwardRef" @click="armReason('close-press')">
+    <slot />
+  </DialogClose>
+</template>

vue/primitives/src/overlays/drawer/DrawerContent.vue

@@ -14,6 +14,7 @@ export type DrawerContentEmits = DialogContentEmits;
 
 <script setup lang="ts">
 import { computed, ref, watch, watchEffect } from 'vue';
+import { isClient } from '@robonen/platform/multi';
 import { useForwardExpose } from '@robonen/vue';
 import { DialogContent } from '../dialog';
 import { injectDrawerRootContext } from './context';
@@ -30,6 +31,9 @@ const {
   onPress,
   onDrag,
   onRelease,
+  onCancel,
+  armReason,
+  isAllowedToDrag,
   modal,
   dismissible,
   keyboardIsOpen,
@@ -49,10 +53,12 @@ useScaleBackground();
 const delayedSnapPoints = ref(false);
 
 const snapPointHeight = computed(() => {
-  if (snapPointsOffset.value && snapPointsOffset.value.length > 0)
-    return `${snapPointsOffset.value[0]}px`;
+  const offset = snapPointsOffset.value?.[0];
 
-  return '0';
+  if (typeof offset === 'number' && Number.isFinite(offset))
+    return `${offset}px`;
+
+  return '0px';
 });
 
 function handlePointerDownOutside(event: Event) {
@@ -66,13 +72,21 @@ function handlePointerDownOutside(event: Event) {
 
   // Let the underlying DismissableLayer close a dismissible modal drawer;
   // otherwise hold it open.
-  if (!dismissible.value)
+  if (!dismissible.value) {
     event.preventDefault();
+    return;
+  }
+
+  armReason('outside-press');
 }
 
 function handleEscapeKeyDown(event: KeyboardEvent) {
-  if (!dismissible.value)
+  if (!dismissible.value) {
     event.preventDefault();
+    return;
+  }
+
+  armReason('escape-key');
 }
 
 function handlePointerDown(event: PointerEvent) {
@@ -88,8 +102,9 @@ function handlePointerMove(event: PointerEvent) {
 }
 
 watchEffect(() => {
-  if (hasSnapPoints.value) {
-    globalThis.requestAnimationFrame(() => {
+  // `flush: 'pre'` effects run during SSR, where rAF doesn't exist.
+  if (hasSnapPoints.value && isClient) {
+    requestAnimationFrame(() => {
       delayedSnapPoints.value = true;
     });
   }
@@ -103,10 +118,13 @@ watchEffect(() => {
     :data-drawer-direction="direction"
     :data-drawer-delayed-snap-points="delayedSnapPoints ? 'true' : 'false'"
     :data-drawer-snap-points="isOpen && hasSnapPoints ? 'true' : 'false'"
+    :data-swiping="isAllowedToDrag ? 'true' : undefined"
     :style="{ '--snap-point-height': snapPointHeight }"
     @pointerdown="handlePointerDown"
     @pointermove="handlePointerMove"
     @pointerup="onRelease"
+    @pointercancel="onCancel"
+    @lostpointercapture="onCancel"
     @open-auto-focus.prevent
     @pointer-down-outside="handlePointerDownOutside"
     @escape-key-down="handleEscapeKeyDown"

vue/primitives/src/overlays/drawer/DrawerHandle.vue

@@ -11,7 +11,8 @@ export type { DrawerHandleProps } from './controls';
 </script>
 
 <script setup lang="ts">
-import { ref, useTemplateRef, watchPostEffect } from 'vue';
+import { onScopeDispose, useTemplateRef, watch, watchPostEffect } from 'vue';
+import { onLongPress, useStateMachine } from '@robonen/vue';
 import { injectDrawerRootContext } from './context';
 
 const { preventCycle = false } = defineProps<DrawerHandleProps>();
@@ -19,7 +20,7 @@ const { preventCycle = false } = defineProps<DrawerHandleProps>();
 const LONG_HANDLE_PRESS_TIMEOUT = 250;
 const DOUBLE_TAP_TIMEOUT = 120;
 
-const { onPress, onDrag, handleRef, handleOnly, isOpen, snapPoints, activeSnapPoint, isDragging, dismissible, closeDrawer }
+const { onPress, onDrag, onCancel, handleRef, handleOnly, isOpen, snapPoints, activeSnapPoint, isDragging, isAllowedToDrag, dismissible, closeDrawer }
   = injectDrawerRootContext();
 
 // Mirror the element into the shared context ref. A local template ref + watch
@@ -31,33 +32,67 @@ watchPostEffect(() => {
   handleRef.value = handleElement.value;
 });
 
-const closeTimeoutId = ref<number | null>(null);
-const shouldCancelInteraction = ref(false);
+let cycleTimer: ReturnType<typeof setTimeout> | undefined;
 
-function handleStartCycle() {
-  // Ignore the second tap of a double-tap.
-  if (shouldCancelInteraction.value) {
-    handleCancelInteraction();
-    return;
-  }
+// Tap-to-cycle as an explicit machine: a tap schedules the cycle after the
+// double-tap window, a long hold suppresses it, and a second press inside the
+// window cancels the pending cycle — so a double-tap cycles once, never twice.
+const tap = useStateMachine({
+  initial: 'idle',
+  states: {
+    idle: { on: { PRESS: 'pressed', TAP: 'tapPending' } },
+    pressed: { on: { LONG_PRESS: 'suppressed', DRAG: 'suppressed', TAP: 'tapPending', CANCEL: 'idle' } },
+    suppressed: { on: { TAP: 'idle', PRESS: 'pressed', CANCEL: 'idle' } },
+    tapPending: {
+      entry: () => {
+        cycleTimer = setTimeout(fireCycleElapsed, DOUBLE_TAP_TIMEOUT);
+      },
+      exit: () => clearTimeout(cycleTimer),
+      on: {
+        ELAPSED: { target: 'idle', action: cycleSnapPoints },
+        PRESS: 'pressed',
+        // A long-press timer armed before the release can still outrace the
+        // pending cycle — treat it as suppression, like the release-time flag
+        // check of the pre-machine code did.
+        LONG_PRESS: 'suppressed',
+        DRAG: 'suppressed',
+        CANCEL: 'idle',
+      },
+    },
+  },
+});
 
-  globalThis.setTimeout(() => {
-    handleCycleSnapPoints();
-  }, DOUBLE_TAP_TIMEOUT);
+// The exit hook covers every transition; this covers unmount mid-window.
+onScopeDispose(() => clearTimeout(cycleTimer));
+
+// A gesture that actually engaged the drawer must never read as a tap: pointer
+// capture keeps the release's click on the handle, and 120ms later the drag is
+// long over (isDragging is false again), so only a latch armed DURING the
+// press can tell a short drag apart from a tap.
+watch(isAllowedToDrag, (dragging) => {
+  if (dragging)
+    tap.send('DRAG');
+});
+
+// Annotated `: void` so the machine config can reference it without a type cycle.
+function fireCycleElapsed(): void {
+  tap.send('ELAPSED');
 }
 
-function handleCycleSnapPoints() {
-  // Don't treat an accidental tap during a resize as a cycle.
-  if (isDragging.value || preventCycle || shouldCancelInteraction.value) {
-    handleCancelInteraction();
-    return;
-  }
+// A long hold suppresses the tap-to-cycle. `distanceThreshold: false` keeps the
+// original semantics: the hold counts even while the pointer drags the drawer.
+onLongPress(handleElement, () => {
+  tap.send('LONG_PRESS');
+}, { delay: LONG_HANDLE_PRESS_TIMEOUT, distanceThreshold: false });
 
-  handleCancelInteraction();
+function cycleSnapPoints() {
+  // Don't treat an accidental tap during a resize as a cycle.
+  if (isDragging.value || preventCycle)
+    return;
 
   if (!snapPoints.value || snapPoints.value.length === 0) {
-    if (!dismissible.value)
-      closeDrawer();
+    if (dismissible.value)
+      closeDrawer('handle-press');
 
     return;
   }
@@ -65,7 +100,7 @@ function handleCycleSnapPoints() {
   const isLastSnapPoint = activeSnapPoint.value === snapPoints.value[snapPoints.value.length - 1];
 
   if (isLastSnapPoint && dismissible.value) {
-    closeDrawer();
+    closeDrawer('handle-press');
     return;
   }
 
@@ -78,30 +113,38 @@ function handleCycleSnapPoints() {
   activeSnapPoint.value = snapPoints.value[nextSnapPointIndex];
 }
 
-function handleStartInteraction() {
-  closeTimeoutId.value = globalThis.setTimeout(() => {
-    // A long press cancels the tap-to-cycle.
-    shouldCancelInteraction.value = true;
-  }, LONG_HANDLE_PRESS_TIMEOUT);
-}
-
-function handleCancelInteraction() {
-  if (closeTimeoutId.value)
-    globalThis.clearTimeout(closeTimeoutId.value);
-
-  shouldCancelInteraction.value = false;
+function handleClick() {
+  tap.send('TAP');
 }
 
 function handlePointerDown(event: PointerEvent) {
+  tap.send('PRESS');
+
+  // In handleOnly mode the handle is the capture target so moves keep
+  // arriving here even when the pointer leaves it.
   if (handleOnly.value)
-    onPress(event);
-  handleStartInteraction();
+    onPress(event, handleElement.value ?? undefined);
 }
 
 function handlePointerMove(event: PointerEvent) {
   if (handleOnly.value)
     onDrag(event);
 }
+
+function handlePointerCancel(event: PointerEvent) {
+  tap.send('CANCEL');
+
+  if (handleOnly.value)
+    onCancel(event);
+}
+
+// Fires after every normal release too (pointer capture sits on the pressed
+// element), so it must NOT cancel the tap intent — that would defeat the
+// long-press suppression. Only the drag engine cares, and it ignores stale calls.
+function handleLostPointerCapture(event: PointerEvent) {
+  if (handleOnly.value)
+    onCancel(event);
+}
 </script>
 
 <template>
@@ -110,8 +153,9 @@ function handlePointerMove(event: PointerEvent) {
     :data-drawer-visible="isOpen ? 'true' : 'false'"
     data-drawer-handle
     aria-hidden="true"
-    @click="handleStartCycle"
-    @pointercancel="handleCancelInteraction"
+    @click="handleClick"
+    @pointercancel="handlePointerCancel"
+    @lostpointercapture="handleLostPointerCapture"
     @pointerdown="handlePointerDown"
     @pointermove="handlePointerMove"
   >

vue/primitives/src/overlays/drawer/DrawerOverlay.vue

@@ -17,7 +17,7 @@ import { injectDrawerRootContext } from './context';
 
 defineProps<DrawerOverlayProps>();
 
-const { overlayRef, hasSnapPoints, isOpen, shouldFade } = injectDrawerRootContext();
+const { overlayRef, hasSnapPoints, isOpen, shouldFade, isAllowedToDrag } = injectDrawerRootContext();
 const { forwardRef, currentElement } = useForwardExpose();
 
 watch(currentElement, (el) => {
@@ -31,6 +31,7 @@ watch(currentElement, (el) => {
     data-drawer-overlay
     :data-drawer-snap-points="isOpen && hasSnapPoints ? 'true' : 'false'"
     :data-drawer-snap-points-overlay="isOpen && shouldFade ? 'true' : 'false'"
+    :data-swiping="isAllowedToDrag ? 'true' : undefined"
   >
     <slot />
   </DialogOverlay>

vue/primitives/src/overlays/drawer/DrawerRoot.vue

@@ -18,12 +18,13 @@ export type { DrawerRootEmits, DrawerRootProps } from './controls';
 
 <script setup lang="ts">
 import { computed, ref, toRefs, watch } from 'vue';
-import { useStyleTag } from '@robonen/vue';
+import { useEventListener, useStyleTag } from '@robonen/vue';
+import { isClient } from '@robonen/platform/multi';
 import { DialogRoot } from '../dialog';
 import { provideDrawerRootContext } from './context';
 import { useDrawer } from './controls';
 import { CLOSE_THRESHOLD, SCROLL_LOCK_TIMEOUT, TRANSITIONS } from './constants';
-import { DRAWER_STYLES, DRAWER_STYLE_ID } from './style';
+import { DRAWER_STYLES, DRAWER_STYLE_ID, registerDrawerCssProperties } from './style';
 
 defineOptions({ inheritAttrs: false });
 
@@ -45,6 +46,7 @@ const props = withDefaults(defineProps<DrawerRootProps>(), {
   noBodyStyles: false,
   handleOnly: false,
   preventScrollRestoration: false,
+  snapToSequentialPoints: false,
 });
 
 const emit = defineEmits<DrawerRootEmits>();
@@ -52,6 +54,9 @@ const emit = defineEmits<DrawerRootEmits>();
 // Inject the critical drawer CSS once (reference-counted across every drawer).
 useStyleTag(DRAWER_STYLES, { id: DRAWER_STYLE_ID });
 
+if (isClient)
+  registerDrawerCssProperties();
+
 const fadeFromIndex = computed(() => props.fadeFromIndex ?? (props.snapPoints && props.snapPoints.length - 1));
 
 // `isOpen` is the single source of truth for the open state. It's seeded from the
@@ -64,14 +69,6 @@ watch(() => props.open, (value) => {
     isOpen.value = value;
 });
 
-// Every change to `isOpen` (from any source) notifies the consumer's `v-model`
-// once and schedules `animationEnd`. Close-specific effects (`close`, snap reset)
-// live in the engine's own watch on the same ref.
-watch(isOpen, (o) => {
-  emit('update:open', o);
-  setTimeout(() => emit('animationEnd', o), TRANSITIONS.DURATION * 1000);
-});
-
 const localActiveSnapPoint = ref<number | string | null | undefined>(
   props.activeSnapPoint ?? props.snapPoints?.[0] ?? null,
 );
@@ -91,7 +88,7 @@ const emitHandlers = {
   emitClose: () => emit('close'),
 };
 
-const { modal } = provideDrawerRootContext(
+const { modal, drawerRef, pendingReason, notifySettled, hasSnapPoints } = provideDrawerRootContext(
   useDrawer({
     ...emitHandlers,
     ...toRefs(props),
@@ -101,6 +98,68 @@ const { modal } = provideDrawerRootContext(
   }),
 );
 
+// `animationEnd` fires on the drawer element's own transitionend/animationend
+// (so dynamic settle durations and consumer-tuned animations report honestly),
+// with a fixed-duration timeout kept as an upper-bound fallback for
+// reduced-motion and animation-less environments. The listener rides the
+// reactive `drawerRef`, so it (re)attaches whenever the content (re)mounts;
+// `pendingAnimationEnd` gates it to the transition armed by the open flip.
+let pendingAnimationEnd: boolean | null = null;
+let animationEndTimer: ReturnType<typeof setTimeout> | undefined;
+
+function fireAnimationEnd() {
+  if (pendingAnimationEnd === null)
+    return;
+
+  const open = pendingAnimationEnd;
+
+  pendingAnimationEnd = null;
+  clearTimeout(animationEndTimer);
+  // Advance the engine's lifecycle phase first, so `animationEnd` observers see
+  // the settled state (e.g. the snap point already reset after a close).
+  notifySettled();
+  emit('animationEnd', open);
+}
+
+useEventListener(drawerRef, ['transitionend', 'animationend'], (event) => {
+  // Only the drawer's own settle counts — ignore bubbled child transitions.
+  if (event.target !== event.currentTarget)
+    return;
+
+  if (event.type === 'transitionend') {
+    // Transform transitions signal a settle only for snap-point drawers; the
+    // keyframe-driven enter/exit of plain drawers also sees transform
+    // transitions from other sources (a nested child writing to this element,
+    // a drag settle) that must not consume an armed flip.
+    if (!hasSnapPoints.value || (event as TransitionEvent).propertyName !== 'transform')
+      return;
+  }
+  // Only the stylesheet's slide keyframes mark a settle; consumer keyframes on
+  // the content fall through to the fallback timeout instead.
+  else if (!(event as AnimationEvent).animationName.startsWith('slide')) {
+    return;
+  }
+
+  fireAnimationEnd();
+});
+
+// Every change to `isOpen` (from any source) notifies the consumer's `v-model`
+// once — tagged with the reason armed by whichever part caused the flip — and
+// arms `animationEnd`. Close-specific effects (`close`, snap reset) live in the
+// engine's own watch on the same ref.
+watch(isOpen, (o, _prev, onCleanup) => {
+  const reason = pendingReason.current;
+
+  pendingReason.current = undefined;
+  emit('update:open', o, reason ? { reason } : undefined);
+
+  pendingAnimationEnd = o;
+  animationEndTimer = setTimeout(fireAnimationEnd, TRANSITIONS.DURATION * 1000);
+  // Runs before the next flip re-arms, and on unmount — the fallback never
+  // outlives the transition it was armed for.
+  onCleanup(() => clearTimeout(animationEndTimer));
+});
+
 // The Dialog reports its own dismissals (trigger, close button, escape, outside
 // click) here; mirror them into `isOpen` and let the watchers do the rest.
 function handleOpenChange(o: boolean) {

vue/primitives/src/overlays/drawer/DrawerRootNested.vue

@@ -9,6 +9,7 @@
 <script setup lang="ts">
 import DrawerRoot from './DrawerRoot.vue';
 import type { DrawerRootEmits, DrawerRootProps } from './controls';
+import type { DrawerOpenChangeDetails } from './types';
 import { injectDrawerRootContext } from './context';
 
 const props = defineProps<DrawerRootProps>();
@@ -31,10 +32,10 @@ function onRelease(open: boolean) {
   emit('release', open);
 }
 
-function onOpenChange(open: boolean) {
+function onOpenChange(open: boolean, details?: DrawerOpenChangeDetails) {
   if (open)
     onNestedOpenChange(open);
-  emit('update:open', open);
+  emit('update:open', open, details);
 }
 </script>
 

vue/primitives/src/overlays/drawer/DrawerTrigger.vue

@@ -0,0 +1,25 @@
+<script lang="ts">
+import type { DialogTriggerProps } from '../dialog';
+
+/**
+ * The button that toggles the drawer open. A thin wrapper over Dialog's Trigger
+ * that tags the resulting `update:open` with the `trigger-press` reason.
+ */
+export interface DrawerTriggerProps extends DialogTriggerProps {}
+</script>
+
+<script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
+import { DialogTrigger } from '../dialog';
+import { injectDrawerRootContext } from './context';
+
+const props = defineProps<DrawerTriggerProps>();
+const { armReason } = injectDrawerRootContext();
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <DialogTrigger v-bind="props" :ref="forwardRef" @click="armReason('trigger-press')">
+    <slot />
+  </DialogTrigger>
+</template>

vue/primitives/src/overlays/drawer/__test__/Drawer.test.ts

@@ -2,6 +2,7 @@ import type { VueWrapper } from '@vue/test-utils';
 import { mount } from '@vue/test-utils';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { defineComponent, h, nextTick, ref } from 'vue';
+import type { VNode } from 'vue';
 import {
   DrawerClose,
   DrawerContent,
@@ -13,6 +14,7 @@ import {
   DrawerTitle,
   DrawerTrigger,
 } from '../index';
+import { DRAWER_STYLE_ID } from '../style';
 
 const wrappers: Array<VueWrapper<any>> = [];
 
@@ -20,7 +22,7 @@ afterEach(() => {
   while (wrappers.length) wrappers.pop()!.unmount();
   document.body.innerHTML = '';
   document.body.removeAttribute('style');
-  document.getElementById('robonen-drawer')?.remove();
+  document.getElementById(DRAWER_STYLE_ID)?.remove();
 });
 
 function track<T extends VueWrapper<any>>(w: T): T {
@@ -35,6 +37,16 @@ async function flush(): Promise<void> {
   await nextTick();
 }
 
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/** Waits out the 500ms "no dragging during the open animation" guard. */
+async function openSettled(): Promise<void> {
+  await flush();
+  await sleep(600);
+}
+
 function $<T extends Element = HTMLElement>(selector: string): T | null {
   return document.querySelector<T>(selector);
 }
@@ -51,14 +63,52 @@ function $close(): HTMLButtonElement | undefined {
   return [...document.querySelectorAll('button')].find(b => b.textContent === 'Close');
 }
 
+function pointer(el: Element, type: string, x: number, y: number) {
+  el.dispatchEvent(new PointerEvent(type, {
+    button: type === 'pointermove' ? -1 : 0,
+    pointerId: 1,
+    isPrimary: true,
+    clientX: x,
+    clientY: y,
+    bubbles: true,
+    cancelable: true,
+  }));
+}
+
+/**
+ * Quick drag: ~10ms between moves keeps the velocity tracker's samples fresh,
+ * so releasing right after reads as a fling.
+ */
+async function fastDrag(el: Element, points: Array<[number, number]>) {
+  pointer(el, 'pointerdown', points[0]![0], points[0]![1]);
+
+  for (const [x, y] of points.slice(1)) {
+    await sleep(10);
+    pointer(el, 'pointermove', x, y);
+  }
+}
+
+/** Drag, then pause past MAX_VELOCITY_AGE so the release velocity reads 0. */
+async function slowDrag(el: Element, points: Array<[number, number]>) {
+  await fastDrag(el, points);
+  await sleep(120);
+}
+
 interface MountOptions {
   open?: boolean;
   defaultOpen?: boolean;
   modal?: boolean;
   dismissible?: boolean;
   direction?: 'top' | 'bottom' | 'left' | 'right';
+  snapPoints?: Array<number | string>;
+  handleOnly?: boolean;
   withHandle?: boolean;
-  onUpdateOpen?: (v: boolean) => void;
+  contentStyle?: Record<string, string>;
+  extraContent?: () => VNode;
+  onUpdateOpen?: (v: boolean, details?: { reason?: string }) => void;
+  onUpdateActiveSnapPoint?: (v: number | string) => void;
+  onRelease?: (open: boolean) => void;
+  onAnimationEnd?: (open: boolean) => void;
   onClose?: () => void;
 }
 
@@ -75,7 +125,12 @@ function mountDrawer(options: MountOptions = {}) {
           modal: options.modal ?? true,
           dismissible: options.dismissible ?? true,
           direction: options.direction ?? 'bottom',
+          snapPoints: options.snapPoints,
+          handleOnly: options.handleOnly,
           'onUpdate:open': options.onUpdateOpen,
+          'onUpdate:activeSnapPoint': options.onUpdateActiveSnapPoint,
+          onRelease: options.onRelease,
+          onAnimationEnd: options.onAnimationEnd,
           onClose: options.onClose,
         },
         {
@@ -84,12 +139,13 @@ function mountDrawer(options: MountOptions = {}) {
             h(DrawerPortal, null, {
               default: () => [
                 h(DrawerOverlay, { 'data-testid': 'overlay' }),
-                h(DrawerContent, null, {
+                h(DrawerContent, { style: { height: '200px', width: '200px', ...options.contentStyle } }, {
                   default: () => [
                     withHandle ? h(DrawerHandle) : null,
                     h(DrawerTitle, null, { default: () => 'Title' }),
                     h(DrawerDescription, null, { default: () => 'Desc' }),
                     h(DrawerClose, null, { default: () => 'Close' }),
+                    options.extraContent ? options.extraContent() : null,
                   ],
                 }),
               ],
@@ -113,7 +169,7 @@ describe('Drawer / markup', () => {
   it('injects the critical drawer stylesheet once', async () => {
     mountDrawer({ defaultOpen: true });
     await flush();
-    const tags = document.querySelectorAll('#robonen-drawer');
+    const tags = document.querySelectorAll(`#${DRAWER_STYLE_ID}`);
     expect(tags.length).toBe(1);
     expect(tags[0]!.textContent).toContain('@keyframes slideFromBottom');
   });
@@ -152,13 +208,13 @@ describe('Drawer / open state', () => {
     expect($content()?.getAttribute('data-state') ?? 'closed').toBe('closed');
   });
 
-  it('emits update:open when the trigger is clicked (controlled)', async () => {
+  it('emits update:open with a trigger-press reason (controlled)', async () => {
     const onUpdateOpen = vi.fn();
     mountDrawer({ open: false, onUpdateOpen });
 
     $trigger().click();
     await flush();
-    expect(onUpdateOpen).toHaveBeenCalledWith(true);
+    expect(onUpdateOpen).toHaveBeenCalledWith(true, { reason: 'trigger-press' });
   });
 
   it('emits close exactly once when dismissed via DrawerClose', async () => {
@@ -175,6 +231,7 @@ describe('Drawer / open state', () => {
     // Regression: closing purely by setting the bound `open` prop to false (not
     // via a dialog dismissal) must still run the close side effects.
     const onClose = vi.fn();
+    const onUpdateOpen = vi.fn();
     const state = ref(true);
     const Wrapper = defineComponent({
       setup() {
@@ -182,7 +239,10 @@ describe('Drawer / open state', () => {
           DrawerRoot,
           {
             open: state.value,
-            'onUpdate:open': (v: boolean) => { state.value = v; },
+            'onUpdate:open': (v: boolean, details?: unknown) => {
+              state.value = v;
+              onUpdateOpen(v, details);
+            },
             onClose,
           },
           {
@@ -203,6 +263,8 @@ describe('Drawer / open state', () => {
     state.value = false;
     await flush();
     expect(onClose).toHaveBeenCalledTimes(1);
+    // A programmatic flip carries no reason.
+    expect(onUpdateOpen).toHaveBeenCalledWith(false, undefined);
   });
 });
 
@@ -219,3 +281,497 @@ describe('Drawer / overlay', () => {
     expect($('[data-drawer-overlay]')).toBeNull();
   });
 });
+
+describe('Drawer / dismiss reasons', () => {
+  it('tags an Escape dismissal with escape-key', async () => {
+    const onUpdateOpen = vi.fn();
+    mountDrawer({ defaultOpen: true, onUpdateOpen });
+    await flush();
+
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', cancelable: true }));
+    await flush();
+    expect(onUpdateOpen).toHaveBeenCalledWith(false, { reason: 'escape-key' });
+  });
+
+  it('tags a DrawerClose click with close-press', async () => {
+    const onUpdateOpen = vi.fn();
+    mountDrawer({ defaultOpen: true, onUpdateOpen });
+    await flush();
+
+    $close()!.click();
+    await flush();
+    expect(onUpdateOpen).toHaveBeenCalledWith(false, { reason: 'close-press' });
+  });
+});
+
+describe('Drawer / handle', () => {
+  it('closes a dismissible drawer without snap points on a handle tap', async () => {
+    const onUpdateOpen = vi.fn();
+    mountDrawer({ defaultOpen: true, onUpdateOpen });
+    await flush();
+
+    $('[data-drawer-handle]')!.click();
+    await sleep(250); // past the double-tap window
+    await flush();
+    expect(onUpdateOpen).toHaveBeenCalledWith(false, { reason: 'handle-press' });
+  });
+
+  it('keeps a non-dismissible drawer open on a handle tap', async () => {
+    // Regression: the condition used to be inverted — a handle tap closed
+    // exactly the drawers that declared themselves non-dismissible.
+    const onUpdateOpen = vi.fn();
+    mountDrawer({ defaultOpen: true, dismissible: false, onUpdateOpen });
+    await flush();
+
+    $('[data-drawer-handle]')!.click();
+    await sleep(250);
+    await flush();
+    expect(onUpdateOpen).not.toHaveBeenCalled();
+    expect($content()!.getAttribute('data-state')).toBe('open');
+  });
+
+  it('cycles snap points on tap and reports the new active point', async () => {
+    const onUpdateActiveSnapPoint = vi.fn();
+    mountDrawer({ defaultOpen: true, snapPoints: [0.5, 1], onUpdateActiveSnapPoint });
+    await flush();
+
+    $('[data-drawer-handle]')!.click();
+    await sleep(250);
+    await flush();
+    expect(onUpdateActiveSnapPoint).toHaveBeenCalledWith(1);
+  });
+
+  it('cycles once on a double tap, not twice', async () => {
+    const onUpdateActiveSnapPoint = vi.fn();
+    mountDrawer({ defaultOpen: true, snapPoints: [0.3, 0.6, 1], onUpdateActiveSnapPoint });
+    await flush();
+    onUpdateActiveSnapPoint.mockClear();
+
+    const handle = $('[data-drawer-handle]')!;
+
+    // A full tap is pointerdown → pointerup → click. Both taps are dispatched
+    // in the same synchronous block: no timer can fire in between, so the
+    // second press deterministically lands inside the double-tap window and
+    // must cancel the first pending cycle.
+    pointer(handle, 'pointerdown', 100, 100);
+    pointer(handle, 'pointerup', 100, 100);
+    handle.click();
+    pointer(handle, 'pointerdown', 100, 100);
+    pointer(handle, 'pointerup', 100, 100);
+    handle.click();
+
+    await sleep(300);
+    await flush();
+
+    expect(onUpdateActiveSnapPoint).toHaveBeenCalledWith(0.6);
+    expect(onUpdateActiveSnapPoint).not.toHaveBeenCalledWith(1);
+  });
+
+  it('does not cycle when a short drag on the handle ends in a click', async () => {
+    const onUpdateActiveSnapPoint = vi.fn();
+    const onUpdateOpen = vi.fn();
+    // Full-height content: fraction snap points assume the drawer can cover
+    // the window, otherwise every release projects as "closer to closed".
+    mountDrawer({ defaultOpen: true, snapPoints: [0.5, 1], contentStyle: { height: '100vh' }, onUpdateActiveSnapPoint, onUpdateOpen });
+    await openSettled();
+    onUpdateActiveSnapPoint.mockClear();
+
+    const handle = $('[data-drawer-handle]')!;
+
+    // A small real drag from the handle (upward, so a dismissible drawer at
+    // its first snap point doesn't legitimately close), then the click the
+    // browser dispatches after release — pointer capture keeps it on the
+    // handle. The engaged drag must suppress the tap-to-cycle.
+    await slowDrag(handle, [[100, 300], [100, 290], [100, 280]]);
+    pointer(handle, 'pointerup', 100, 280);
+    handle.click();
+
+    await sleep(300);
+    await flush();
+
+    expect(onUpdateActiveSnapPoint).not.toHaveBeenCalledWith(1);
+    expect(onUpdateOpen).not.toHaveBeenCalled();
+  });
+
+  it('does not fire a pending tap cycle after the handle unmounts', async () => {
+    const showHandle = ref(true);
+    const onUpdateActiveSnapPoint = vi.fn();
+
+    // The root must stay mounted (its emitter alive) while only the handle
+    // unmounts — otherwise a leaked timer could never be observed.
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(
+          DrawerRoot,
+          { defaultOpen: true, snapPoints: [0.5, 1], 'onUpdate:activeSnapPoint': onUpdateActiveSnapPoint },
+          {
+            default: () => h(DrawerPortal, null, {
+              default: () => h(DrawerContent, { style: { height: '200px' } }, {
+                default: () => [
+                  showHandle.value ? h(DrawerHandle) : null,
+                  h(DrawerTitle, null, { default: () => 'Title' }),
+                  h(DrawerDescription, null, { default: () => 'Desc' }),
+                ],
+              }),
+            }),
+          },
+        );
+      },
+    });
+
+    track(mount(Wrapper, { attachTo: document.body }));
+    await flush();
+    onUpdateActiveSnapPoint.mockClear();
+
+    $('[data-drawer-handle]')!.click();
+    showHandle.value = false; // unmount inside the 120ms window
+    await flush();
+    await sleep(250);
+
+    expect(onUpdateActiveSnapPoint).not.toHaveBeenCalled();
+  });
+});
+
+describe('Drawer / drag gesture', () => {
+  it('closes on a swipe past the close threshold with a swipe reason', async () => {
+    const onUpdateOpen = vi.fn();
+    const onRelease = vi.fn();
+    mountDrawer({ defaultOpen: true, onUpdateOpen, onRelease });
+    await openSettled();
+
+    const content = $content()!;
+    await slowDrag(content, [[100, 300], [100, 330], [100, 360], [100, 390]]);
+    pointer(content, 'pointerup', 100, 390);
+    await flush();
+
+    expect(onUpdateOpen).toHaveBeenCalledWith(false, { reason: 'swipe' });
+    expect(onRelease).toHaveBeenCalledWith(false);
+  });
+
+  it('marks the content and overlay with data-swiping while dragging', async () => {
+    mountDrawer({ defaultOpen: true });
+    await openSettled();
+
+    const content = $content()!;
+    // Small drag + pause: stays under both the distance and velocity
+    // thresholds, so the drawer remains open after release.
+    await slowDrag(content, [[100, 300], [100, 315], [100, 330]]);
+
+    expect(content.hasAttribute('data-swiping')).toBe(true);
+    expect(content.classList.contains('drawer-dragging')).toBe(true);
+    expect($('[data-drawer-overlay]')!.hasAttribute('data-swiping')).toBe(true);
+
+    pointer(content, 'pointerup', 100, 330);
+    await flush();
+    expect(content.getAttribute('data-state')).toBe('open');
+    expect(content.hasAttribute('data-swiping')).toBe(false);
+  });
+
+  it('settles back below the threshold when released without momentum', async () => {
+    const onUpdateOpen = vi.fn();
+    const onRelease = vi.fn();
+    mountDrawer({ defaultOpen: true, onUpdateOpen, onRelease });
+    await openSettled();
+
+    const content = $content()!;
+    // 30px of a 200px drawer — under the 25% threshold; pause kills momentum.
+    await slowDrag(content, [[100, 300], [100, 315], [100, 330]]);
+    pointer(content, 'pointerup', 100, 330);
+    await flush();
+
+    expect(onUpdateOpen).not.toHaveBeenCalled();
+    expect(onRelease).toHaveBeenCalledWith(true);
+    expect(content.style.transform).toBe('translate3d(0px, 0px, 0px)');
+  });
+
+  it('does not close after the user reverses past the cancel threshold', async () => {
+    // "Changed my mind": drag well past the close threshold, pull back, hold,
+    // release — the drawer must stay open even though the release point alone
+    // clears the distance threshold.
+    const onUpdateOpen = vi.fn();
+    mountDrawer({ defaultOpen: true, onUpdateOpen });
+    await openSettled();
+
+    const content = $content()!;
+    await slowDrag(content, [[100, 300], [100, 360], [100, 420], [100, 360]]);
+    pointer(content, 'pointerup', 100, 360);
+    await flush();
+
+    expect(onUpdateOpen).not.toHaveBeenCalled();
+    expect(content.getAttribute('data-state')).toBe('open');
+  });
+
+  it('recovers cleanly from pointercancel mid-drag', async () => {
+    const onUpdateOpen = vi.fn();
+    mountDrawer({ defaultOpen: true, onUpdateOpen });
+    await openSettled();
+
+    const content = $content()!;
+    await fastDrag(content, [[100, 300], [100, 330], [100, 360]]);
+    expect(content.classList.contains('drawer-dragging')).toBe(true);
+
+    pointer(content, 'pointercancel', 100, 360);
+    await flush();
+
+    expect(content.classList.contains('drawer-dragging')).toBe(false);
+    expect(content.hasAttribute('data-swiping')).toBe(false);
+    expect(onUpdateOpen).not.toHaveBeenCalled();
+    expect(content.style.transform).toBe('translate3d(0px, 0px, 0px)');
+
+    // The next gesture still works.
+    await slowDrag(content, [[100, 300], [100, 340], [100, 380], [100, 420]]);
+    pointer(content, 'pointerup', 100, 420);
+    await flush();
+    expect(onUpdateOpen).toHaveBeenCalledWith(false, { reason: 'swipe' });
+  });
+
+  it('ignores a cross-axis gesture (axis lock)', async () => {
+    const onUpdateOpen = vi.fn();
+    mountDrawer({ defaultOpen: true, onUpdateOpen });
+    await openSettled();
+
+    const content = $content()!;
+    // Mostly-horizontal movement on a bottom drawer must never latch a drag.
+    await fastDrag(content, [[100, 300], [140, 305], [180, 310], [220, 315]]);
+    pointer(content, 'pointerup', 220, 315);
+    await flush();
+
+    expect(content.classList.contains('drawer-dragging')).toBe(false);
+    expect(onUpdateOpen).not.toHaveBeenCalled();
+  });
+
+  it('scales the close-out animation with the fling velocity', async () => {
+    const onUpdateOpen = vi.fn();
+    const onAnimationEnd = vi.fn();
+    mountDrawer({ defaultOpen: true, onUpdateOpen, onAnimationEnd });
+    await openSettled();
+
+    const content = $content()!;
+    // Rapid successive moves keep the instantaneous velocity high.
+    await fastDrag(content, [[100, 300], [100, 330], [100, 360], [100, 390]]);
+    pointer(content, 'pointerup', 100, 390);
+    await flush();
+
+    expect(onUpdateOpen).toHaveBeenCalledWith(false, { reason: 'swipe' });
+    // The inline duration overrides the stylesheet's 0.5s for this close only.
+    expect(content.style.animationDuration).not.toBe('');
+    expect(Number.parseFloat(content.style.animationDuration)).toBeLessThan(0.5);
+
+    // animationEnd follows the (scaled) animation, via the real animationend.
+    await vi.waitFor(() => expect(onAnimationEnd).toHaveBeenCalledWith(false), { timeout: 1000 });
+  });
+
+  it('keeps the default close duration for a slow release past the threshold', async () => {
+    const onUpdateOpen = vi.fn();
+    mountDrawer({ defaultOpen: true, onUpdateOpen });
+    await openSettled();
+
+    const content = $content()!;
+    await slowDrag(content, [[100, 300], [100, 330], [100, 360], [100, 390]]);
+    pointer(content, 'pointerup', 100, 390);
+    await flush();
+
+    expect(onUpdateOpen).toHaveBeenCalledWith(false, { reason: 'swipe' });
+    expect(content.style.animationDuration).toBe('');
+  });
+});
+
+describe('Drawer / pointer capture', () => {
+  it('captures the pointer on the pressed element, not the drawer content', async () => {
+    mountDrawer({
+      defaultOpen: true,
+      extraContent: () => h('button', { 'data-testid': 'inner' }, 'Inner'),
+    });
+    await flush();
+
+    const content = $content()!;
+    const button = $<HTMLButtonElement>('[data-testid="inner"]')!;
+    const captured: Element[] = [];
+
+    for (const el of [content, button])
+      (el as any).setPointerCapture = () => captured.push(el);
+
+    pointer(button, 'pointerdown', 100, 300);
+
+    // Capturing on the drawer would retarget the compat mouse events, so the
+    // button would never receive `click` — the capture must land on the button.
+    expect(captured).toEqual([button]);
+
+    pointer(button, 'pointerup', 100, 300);
+    await flush();
+    expect(content.getAttribute('data-state')).toBe('open');
+  });
+
+  it('captures on the handle for handleOnly gestures', async () => {
+    mountDrawer({ defaultOpen: true, handleOnly: true });
+    await flush();
+
+    const content = $content()!;
+    const handle = $('[data-drawer-handle]')!;
+    const hitarea = $('[data-drawer-handle-hitarea]')!;
+    const captured: Element[] = [];
+
+    for (const el of [content, handle, hitarea])
+      (el as any).setPointerCapture = () => captured.push(el);
+
+    pointer(hitarea, 'pointerdown', 100, 300);
+
+    expect(captured).toEqual([handle]);
+
+    pointer(hitarea, 'pointerup', 100, 300);
+    await flush();
+  });
+});
+
+describe('Drawer / lifecycle machine', () => {
+  it('resets the active snap point only when a close actually settles', async () => {
+    const open = ref(true);
+    const active = ref<number | string | null | undefined>(0.9);
+
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(
+          DrawerRoot,
+          {
+            open: open.value,
+            snapPoints: [0.4, 0.9],
+            activeSnapPoint: active.value,
+            'onUpdate:open': (v: boolean) => { open.value = v; },
+            'onUpdate:activeSnapPoint': (v: number | string) => { active.value = v; },
+          },
+          {
+            default: () => h(DrawerPortal, null, {
+              default: () => h(DrawerContent, { style: { height: '200px' } }, {
+                default: () => [
+                  h(DrawerTitle, null, { default: () => 'Title' }),
+                  h(DrawerDescription, null, { default: () => 'Desc' }),
+                ],
+              }),
+            }),
+          },
+        );
+      },
+    });
+
+    track(mount(Wrapper, { attachTo: document.body }));
+    await flush();
+
+    // Close, then reopen before the exit settles: the pending close cleanup
+    // must NOT fire on the now-live drawer (the old fixed 500ms timeout did).
+    open.value = false;
+    await flush();
+    await sleep(60);
+    open.value = true;
+    await flush();
+    await sleep(700);
+
+    expect(active.value).toBe(0.9);
+
+    // A close that actually settles still resets to the first snap point.
+    open.value = false;
+    await flush();
+    await sleep(700);
+
+    expect(active.value).toBe(0.4);
+  });
+});
+
+describe('Drawer / scroll containers', () => {
+  function scrollerContent(direction: 'vertical' | 'horizontal') {
+    return () => h(
+      'div',
+      {
+        'data-testid': 'scroller',
+        style: direction === 'vertical'
+          ? 'height: 100px; overflow-y: auto;'
+          : 'width: 100px; overflow-x: auto;',
+      },
+      [h('div', {
+        style: direction === 'vertical' ? 'height: 400px;' : 'width: 400px; height: 20px;',
+      }, [h('span', { 'data-testid': 'leaf' }, 'content')])],
+    );
+  }
+
+  it('lets a mid-scroll container own the gesture (vertical)', async () => {
+    const onUpdateOpen = vi.fn();
+    mountDrawer({ defaultOpen: true, onUpdateOpen, extraContent: scrollerContent('vertical') });
+    await openSettled();
+
+    const content = $content()!;
+    const scroller = $('[data-testid="scroller"]')!;
+    const leaf = $('[data-testid="leaf"]')!;
+
+    scroller.scrollTop = 50;
+    await slowDrag(leaf, [[100, 300], [100, 340], [100, 380], [100, 420]]);
+    pointer(leaf, 'pointerup', 100, 420);
+    await flush();
+    expect(content.classList.contains('drawer-dragging')).toBe(false);
+    expect(onUpdateOpen).not.toHaveBeenCalled();
+
+    // At the top edge the same gesture is a dismiss.
+    scroller.scrollTop = 0;
+    await sleep(150); // clear the scroll-lock timeout
+    await slowDrag(leaf, [[100, 300], [100, 340], [100, 380], [100, 420]]);
+    pointer(leaf, 'pointerup', 100, 420);
+    await flush();
+    expect(onUpdateOpen).toHaveBeenCalledWith(false, { reason: 'swipe' });
+  });
+
+  it('respects horizontal scroll containers in side drawers', async () => {
+    // Regression: left/right drawers used to skip every shouldDrag check.
+    const onUpdateOpen = vi.fn();
+    mountDrawer({
+      defaultOpen: true,
+      direction: 'right',
+      onUpdateOpen,
+      extraContent: scrollerContent('horizontal'),
+    });
+    await openSettled();
+
+    const content = $content()!;
+    const scroller = $('[data-testid="scroller"]')!;
+    const leaf = $('[data-testid="leaf"]')!;
+
+    scroller.scrollLeft = 50;
+    await slowDrag(leaf, [[100, 300], [140, 300], [180, 300], [220, 300]]);
+    pointer(leaf, 'pointerup', 220, 300);
+    await flush();
+    expect(content.classList.contains('drawer-dragging')).toBe(false);
+    expect(onUpdateOpen).not.toHaveBeenCalled();
+
+    scroller.scrollLeft = 0;
+    await sleep(150);
+    await slowDrag(leaf, [[100, 300], [140, 300], [180, 300], [220, 300]]);
+    pointer(leaf, 'pointerup', 220, 300);
+    await flush();
+    expect(onUpdateOpen).toHaveBeenCalledWith(false, { reason: 'swipe' });
+  });
+});
+
+describe('Drawer / snap points', () => {
+  it('positions the drawer at the first snap point and exposes the offsets', async () => {
+    mountDrawer({ defaultOpen: true, snapPoints: [0.5, 1] });
+    await flush();
+
+    const content = $content()!;
+    expect(content.getAttribute('data-drawer-snap-points')).toBe('true');
+
+    const expected = Math.round(window.innerHeight - window.innerHeight * 0.5);
+    await vi.waitFor(() => {
+      expect(content.style.transform).toBe(`translate3d(0px, ${expected}px, 0px)`);
+    });
+    expect(content.style.getPropertyValue('--snap-point-height')).toBe(`${expected}px`);
+  });
+
+  it('resolves px and rem snap points', async () => {
+    mountDrawer({ defaultOpen: true, snapPoints: ['10rem', '500px'] });
+    await flush();
+
+    const content = $content()!;
+    const rem = Number.parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
+    const expected = Math.round(window.innerHeight - 10 * rem);
+    await vi.waitFor(() => {
+      expect(content.style.transform).toBe(`translate3d(0px, ${expected}px, 0px)`);
+    });
+  });
+});

vue/primitives/src/overlays/drawer/__test__/a11y.test.ts

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { mount } from '@vue/test-utils';
+import axe from 'axe-core';
+import { defineComponent, h, nextTick } from 'vue';
+import {
+  DrawerClose,
+  DrawerContent,
+  DrawerDescription,
+  DrawerHandle,
+  DrawerOverlay,
+  DrawerPortal,
+  DrawerRoot,
+  DrawerTitle,
+  DrawerTrigger,
+} from '../index';
+
+async function violations(element: Element) {
+  const results = await axe.run(element);
+  return results.violations;
+}
+
+async function flush() {
+  await nextTick();
+  await nextTick();
+  await nextTick();
+}
+
+function drawerFixture(defaultOpen: boolean) {
+  return defineComponent({
+    setup() {
+      return () => h(DrawerRoot, { defaultOpen }, {
+        default: () => [
+          h(DrawerTrigger, null, { default: () => 'Open drawer' }),
+          h(DrawerPortal, null, {
+            default: () => [
+              h(DrawerOverlay),
+              h(DrawerContent, null, {
+                default: () => [
+                  h(DrawerHandle),
+                  h(DrawerTitle, null, { default: () => 'Drawer title' }),
+                  h(DrawerDescription, null, { default: () => 'Drawer description' }),
+                  h(DrawerClose, null, { default: () => 'Close' }),
+                ],
+              }),
+            ],
+          }),
+        ],
+      });
+    },
+  });
+}
+
+describe('Drawer a11y', () => {
+  let wrapper: ReturnType<typeof mount> | undefined;
+
+  afterEach(() => {
+    wrapper?.unmount();
+    wrapper = undefined;
+    document.body.innerHTML = '';
+    document.body.removeAttribute('style');
+  });
+
+  it('has no axe violations when closed', async () => {
+    wrapper = mount(drawerFixture(false), { attachTo: document.body });
+    await flush();
+    expect(await violations(document.body)).toHaveLength(0);
+  });
+
+  it('has no axe violations when open', async () => {
+    wrapper = mount(drawerFixture(true), { attachTo: document.body });
+    await flush();
+    expect(await violations(document.body)).toHaveLength(0);
+  });
+});

vue/primitives/src/overlays/drawer/__test__/gesture.test.ts

@@ -0,0 +1,224 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  computeSettleDuration,
+  createReverseCancelTracker,
+  createVelocityTracker,
+  findScrollableAncestor,
+  isAtScrollEdge,
+} from '../gesture';
+import { MAX_VELOCITY_AGE, MIN_SETTLE_DURATION, MIN_VELOCITY_DT, TRANSITIONS } from '../constants';
+
+afterEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('createVelocityTracker', () => {
+  it('computes instantaneous velocity from the trailing pair of samples', () => {
+    const tracker = createVelocityTracker();
+
+    tracker.add(0, 0);
+    tracker.add(10, 20); // 0.5 px/ms — but superseded below
+    tracker.add(50, 40); // (50-10)/20 = 2 px/ms
+
+    expect(tracker.read(45)).toBe(2);
+  });
+
+  it('reads 0 when the pointer paused before release', () => {
+    const tracker = createVelocityTracker();
+
+    tracker.add(0, 0);
+    tracker.add(100, 20);
+
+    expect(tracker.read(20 + MAX_VELOCITY_AGE + 1)).toBe(0);
+  });
+
+  it('clamps tiny sample intervals so same-frame bursts do not spike', () => {
+    const tracker = createVelocityTracker();
+
+    tracker.add(0, 0);
+    tracker.add(32, 1); // dt clamped 1 → MIN_VELOCITY_DT
+
+    expect(tracker.read(2)).toBe(32 / MIN_VELOCITY_DT);
+  });
+
+  it('reads 0 before two samples exist', () => {
+    const tracker = createVelocityTracker();
+
+    expect(tracker.read(0)).toBe(0);
+    tracker.add(10, 0);
+    expect(tracker.read(1)).toBe(0);
+  });
+
+  it('ignores out-of-order samples', () => {
+    const tracker = createVelocityTracker();
+
+    tracker.add(0, 100);
+    tracker.add(50, 120);
+    tracker.add(999, 90); // stale timestamp — must not produce a velocity
+
+    expect(tracker.read(121)).toBe(50 / 20);
+  });
+});
+
+describe('createReverseCancelTracker', () => {
+  it('cancels once an armed gesture pulls back past the threshold', () => {
+    const tracker = createReverseCancelTracker();
+
+    tracker.update(60); // armed (> 20)
+    expect(tracker.cancelled).toBe(false);
+
+    tracker.update(45); // pulled back 15 > 10
+    expect(tracker.cancelled).toBe(true);
+  });
+
+  it('does not cancel before the arm distance', () => {
+    const tracker = createReverseCancelTracker();
+
+    tracker.update(15);
+    tracker.update(0); // pulled back 15, but max never armed
+
+    expect(tracker.cancelled).toBe(false);
+  });
+
+  it('tolerates jitter below the reverse threshold', () => {
+    const tracker = createReverseCancelTracker();
+
+    tracker.update(80);
+    tracker.update(72); // only 8 back
+
+    expect(tracker.cancelled).toBe(false);
+  });
+
+  it('re-arms when the drag surpasses its previous furthest point', () => {
+    const tracker = createReverseCancelTracker();
+
+    tracker.update(60);
+    tracker.update(40);
+    expect(tracker.cancelled).toBe(true);
+
+    tracker.update(70); // renewed intent
+    expect(tracker.cancelled).toBe(false);
+  });
+});
+
+describe('computeSettleDuration', () => {
+  it('keeps the default duration for slow releases', () => {
+    expect(computeSettleDuration(300, 0.1)).toBe(TRANSITIONS.DURATION);
+    expect(computeSettleDuration(300, 0)).toBe(TRANSITIONS.DURATION);
+  });
+
+  it('scales the duration down with a hard flick', () => {
+    // 100px left at 2px/ms → 50ms, clamped up to the minimum.
+    expect(computeSettleDuration(100, 2)).toBe(MIN_SETTLE_DURATION / 1000);
+    // 400px left at 1px/ms → 400ms.
+    expect(computeSettleDuration(400, 1)).toBe(0.4);
+  });
+
+  it('never exceeds the default duration', () => {
+    expect(computeSettleDuration(10_000, 0.5)).toBe(TRANSITIONS.DURATION);
+  });
+
+  it('falls back on degenerate distances', () => {
+    expect(computeSettleDuration(0, 3)).toBe(TRANSITIONS.DURATION);
+    expect(computeSettleDuration(Number.NaN, 3)).toBe(TRANSITIONS.DURATION);
+  });
+});
+
+function scrollableFixture() {
+  document.body.innerHTML = `
+    <div id="drawer" style="height: 200px;">
+      <div id="scroller" style="height: 100px; width: 100px; overflow: auto;">
+        <div id="inner" style="height: 400px; width: 400px;">
+          <span id="leaf">content</span>
+        </div>
+      </div>
+    </div>
+  `;
+
+  return {
+    drawer: document.getElementById('drawer')! as HTMLElement,
+    scroller: document.getElementById('scroller')! as HTMLElement,
+    leaf: document.getElementById('leaf')! as HTMLElement,
+  };
+}
+
+describe('findScrollableAncestor', () => {
+  it('finds the nearest scrollable ancestor along the axis', () => {
+    const { drawer, scroller, leaf } = scrollableFixture();
+
+    expect(findScrollableAncestor(leaf, drawer, 'y')).toBe(scroller);
+    expect(findScrollableAncestor(leaf, drawer, 'x')).toBe(scroller);
+  });
+
+  it('returns null when nothing scrolls', () => {
+    const { drawer } = scrollableFixture();
+
+    expect(findScrollableAncestor(drawer, drawer, 'y')).toBeNull();
+  });
+
+  it('stops at the boundary', () => {
+    const { scroller, leaf } = scrollableFixture();
+    const inner = document.getElementById('inner')! as HTMLElement;
+
+    // Boundary below the scroller — the walk must not escape it.
+    expect(findScrollableAncestor(leaf, inner, 'y')).toBeNull();
+    void scroller;
+  });
+
+  it('ignores overflow visible/hidden containers', () => {
+    document.body.innerHTML = `
+      <div id="drawer">
+        <div id="clipped" style="height: 50px; overflow: hidden;">
+          <div style="height: 300px;"><span id="leaf">x</span></div>
+        </div>
+      </div>
+    `;
+
+    const drawer = document.getElementById('drawer')! as HTMLElement;
+    const leaf = document.getElementById('leaf')! as HTMLElement;
+
+    expect(findScrollableAncestor(leaf, drawer, 'y')).toBeNull();
+  });
+});
+
+describe('isAtScrollEdge', () => {
+  it('bottom drawer requires the scroller at its top', () => {
+    const { scroller } = scrollableFixture();
+
+    scroller.scrollTop = 0;
+    expect(isAtScrollEdge(scroller, 'bottom')).toBe(true);
+
+    scroller.scrollTop = 50;
+    expect(isAtScrollEdge(scroller, 'bottom')).toBe(false);
+  });
+
+  it('top drawer requires the scroller at its bottom', () => {
+    const { scroller } = scrollableFixture();
+
+    scroller.scrollTop = scroller.scrollHeight - scroller.clientHeight;
+    expect(isAtScrollEdge(scroller, 'top')).toBe(true);
+
+    scroller.scrollTop = 0;
+    expect(isAtScrollEdge(scroller, 'top')).toBe(false);
+  });
+
+  it('right drawer requires the scroller at its left edge', () => {
+    const { scroller } = scrollableFixture();
+
+    scroller.scrollLeft = 0;
+    expect(isAtScrollEdge(scroller, 'right')).toBe(true);
+
+    scroller.scrollLeft = 40;
+    expect(isAtScrollEdge(scroller, 'right')).toBe(false);
+  });
+
+  it('left drawer requires the scroller at its right edge', () => {
+    const { scroller } = scrollableFixture();
+
+    scroller.scrollLeft = scroller.scrollWidth - scroller.clientWidth;
+    expect(isAtScrollEdge(scroller, 'left')).toBe(true);
+
+    scroller.scrollLeft = 0;
+    expect(isAtScrollEdge(scroller, 'left')).toBe(false);
+  });
+});

vue/primitives/src/overlays/drawer/__test__/snapping.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, it } from 'vitest';
+import {
+  findSnapPointIndex,
+  projectSnapRelease,
+  resolveSnapPointOffset,
+  resolveSnapPointSize,
+} from '../snapping';
+
+const WINDOW = 800;
+const REM = 16;
+
+describe('resolveSnapPointSize', () => {
+  it('treats numbers in (0, 1] as window fractions', () => {
+    expect(resolveSnapPointSize(0.5, WINDOW, REM)).toBe(400);
+    expect(resolveSnapPointSize(1, WINDOW, REM)).toBe(WINDOW);
+  });
+
+  it('treats numbers above 1 as pixels', () => {
+    expect(resolveSnapPointSize(620, WINDOW, REM)).toBe(620);
+  });
+
+  it('parses px strings', () => {
+    expect(resolveSnapPointSize('148px', WINDOW, REM)).toBe(148);
+    expect(resolveSnapPointSize('148.6px', WINDOW, REM)).toBe(149);
+  });
+
+  it('parses rem strings against the root font size', () => {
+    expect(resolveSnapPointSize('30rem', WINDOW, REM)).toBe(480);
+    expect(resolveSnapPointSize('30rem', WINDOW, 20)).toBe(600);
+  });
+
+  it('rejects unknown units and degenerate values', () => {
+    expect(resolveSnapPointSize('50%', WINDOW, REM)).toBeNull();
+    expect(resolveSnapPointSize('10vh', WINDOW, REM)).toBeNull();
+    expect(resolveSnapPointSize('abc', WINDOW, REM)).toBeNull();
+    expect(resolveSnapPointSize('-10px', WINDOW, REM)).toBeNull();
+    expect(resolveSnapPointSize(0, WINDOW, REM)).toBeNull();
+    expect(resolveSnapPointSize(-0.5, WINDOW, REM)).toBeNull();
+    expect(resolveSnapPointSize(Number.NaN, WINDOW, REM)).toBeNull();
+  });
+});
+
+describe('resolveSnapPointOffset', () => {
+  it('signs the translate toward the anchored edge', () => {
+    expect(resolveSnapPointOffset(0.25, 'bottom', WINDOW, REM)).toBe(600);
+    expect(resolveSnapPointOffset(0.25, 'right', WINDOW, REM)).toBe(600);
+    expect(resolveSnapPointOffset(0.25, 'top', WINDOW, REM)).toBe(-600);
+    expect(resolveSnapPointOffset(0.25, 'left', WINDOW, REM)).toBe(-600);
+  });
+
+  it('clamps oversized snap points at fully open', () => {
+    expect(resolveSnapPointOffset(1200, 'bottom', WINDOW, REM)).toBe(0);
+  });
+
+  it('maps invalid points to NaN', () => {
+    expect(resolveSnapPointOffset('50%', 'bottom', WINDOW, REM)).toBeNaN();
+  });
+});
+
+describe('findSnapPointIndex', () => {
+  const points = [0.25, '400px', '30rem'];
+
+  it('matches by identity first', () => {
+    expect(findSnapPointIndex(points, '400px', WINDOW, REM)).toBe(1);
+  });
+
+  it('matches equivalent representations by resolved size', () => {
+    expect(findSnapPointIndex(points, 0.5, WINDOW, REM)).toBe(1); // 0.5 * 800 = 400px
+    expect(findSnapPointIndex(points, 480, WINDOW, REM)).toBe(2); // 30rem = 480px
+  });
+
+  it('returns null when nothing matches', () => {
+    expect(findSnapPointIndex(points, 0.9, WINDOW, REM)).toBeNull();
+    expect(findSnapPointIndex(points, null, WINDOW, REM)).toBeNull();
+    expect(findSnapPointIndex(points, undefined, WINDOW, REM)).toBeNull();
+  });
+});
+
+describe('projectSnapRelease', () => {
+  // Dismiss-positive space on an 800px-tall drawer: fully open = 0, closed = 800.
+  const base = {
+    offsets: [600, 400, 0], // least → most visible
+    drawerSize: 800,
+    dismissible: true,
+    sequential: false,
+  };
+
+  it('snaps to the point nearest the drag target when slow', () => {
+    // From 600, dragged 180 toward open → 420 → nearest is 400.
+    expect(projectSnapRelease({
+      ...base,
+      activeIndex: 0,
+      draggedDistance: 180,
+      velocity: 0,
+    })).toEqual({ type: 'snap', index: 1 });
+  });
+
+  it('stays on the active point after a tiny slow drag', () => {
+    expect(projectSnapRelease({
+      ...base,
+      activeIndex: 0,
+      draggedDistance: 40,
+      velocity: 0,
+    })).toEqual({ type: 'snap', index: 0 });
+  });
+
+  it('projects a fling across points the drag alone would not reach', () => {
+    // From 600, dragged only 40 toward open, but flung at -1.5 px/ms
+    // (toward open) → 560 - 450 = 110 → nearest is 0 (fully open).
+    expect(projectSnapRelease({
+      ...base,
+      activeIndex: 0,
+      draggedDistance: 40,
+      velocity: -1.5,
+    })).toEqual({ type: 'snap', index: 2 });
+  });
+
+  it('closes when the projection lands nearer to fully-closed', () => {
+    // From 600, dragged 100 toward dismiss → 700; 100 from closed vs 100 from
+    // 600 — ties stay open; add a dismiss fling to push past.
+    expect(projectSnapRelease({
+      ...base,
+      activeIndex: 0,
+      draggedDistance: -100,
+      velocity: 0.6,
+    })).toEqual({ type: 'close' });
+  });
+
+  it('never closes a non-dismissible drawer', () => {
+    expect(projectSnapRelease({
+      ...base,
+      dismissible: false,
+      activeIndex: 0,
+      draggedDistance: -150,
+      velocity: 2,
+    })).toEqual({ type: 'snap', index: 0 });
+  });
+
+  it('clamps the fling velocity', () => {
+    // Absurd velocity toward open must land on the last point, not overshoot
+    // into an invalid index.
+    expect(projectSnapRelease({
+      ...base,
+      activeIndex: 0,
+      draggedDistance: 0,
+      velocity: -50,
+    })).toEqual({ type: 'snap', index: 2 });
+  });
+
+  it('skips NaN offsets', () => {
+    expect(projectSnapRelease({
+      ...base,
+      offsets: [600, Number.NaN, 0],
+      activeIndex: 0,
+      draggedDistance: 250, // → 350, nearest usable is 600? |350-600|=250 vs |350-0|=350
+      velocity: 0,
+    })).toEqual({ type: 'snap', index: 0 });
+  });
+
+  describe('sequential mode', () => {
+    const sequential = { ...base, sequential: true };
+
+    it('advances a single step on a physical crossing', () => {
+      // From 600 dragged far toward open (target 100, crossed 400) — but only
+      // one step is allowed.
+      expect(projectSnapRelease({
+        ...sequential,
+        activeIndex: 0,
+        draggedDistance: 500,
+        velocity: 0,
+      })).toEqual({ type: 'snap', index: 1 });
+    });
+
+    it('advances on a fast fling without a crossing', () => {
+      expect(projectSnapRelease({
+        ...sequential,
+        activeIndex: 1,
+        draggedDistance: 60,
+        velocity: -0.8,
+      })).toEqual({ type: 'snap', index: 2 });
+    });
+
+    it('stays put on a slow drag without a crossing', () => {
+      expect(projectSnapRelease({
+        ...sequential,
+        activeIndex: 1,
+        draggedDistance: 60,
+        velocity: 0,
+      })).toEqual({ type: 'snap', index: 1 });
+    });
+  });
+});

vue/primitives/src/overlays/drawer/constants.ts

@@ -24,3 +24,33 @@ export const WINDOW_TOP_OFFSET = 26;
 
 /** Class applied to the drawer element while a drag is in progress. */
 export const DRAG_CLASS = 'drawer-dragging';
+
+/** Smallest dt (ms) a velocity sample may span — clamps out same-frame event spikes. */
+export const MIN_VELOCITY_DT = 16;
+
+/** A velocity sample older than this (ms) at release means the pointer stopped — velocity is 0. */
+export const MAX_VELOCITY_AGE = 80;
+
+/** Dismiss displacement (px) a gesture must reach before the reverse-cancel detector arms. */
+export const REVERSE_CANCEL_ARM_DISTANCE = 20;
+
+/** Pulling back this many px from the gesture's furthest point cancels the dismiss. */
+export const REVERSE_CANCEL_THRESHOLD = 10;
+
+/** Pointer movement (px) needed before the gesture locks onto an axis. */
+export const AXIS_LOCK_DISTANCE = 2;
+
+/** Snap release: velocity (px/ms) below which the fling projection is skipped. */
+export const SNAP_VELOCITY_THRESHOLD = 0.5;
+
+/** Snap release: ms worth of travel a fling projects the release target ahead. */
+export const SNAP_VELOCITY_MULTIPLIER = 300;
+
+/** Snap release: velocity clamp (px/ms) for the fling projection. */
+export const MAX_SNAP_VELOCITY = 4;
+
+/** Release velocity (px/ms) below which the settle keeps the default duration. */
+export const SETTLE_VELOCITY_THRESHOLD = 0.2;
+
+/** Fastest settle transition (ms) a hard flick can produce. */
+export const MIN_SETTLE_DURATION = 80;

vue/primitives/src/overlays/drawer/context.ts

@@ -1,13 +1,24 @@
-import type { Ref } from 'vue';
+import type { Ref, ShallowRef } from 'vue';
 import { useContextFactory } from '@robonen/vue';
 import type { MaybeElementRef } from '@robonen/vue';
-import type { DrawerDirection } from './types';
+import type { DrawerDirection, DrawerOpenChangeReason, DrawerPhase } from './types';
 
 export interface DrawerRootContext {
   /** Source-of-truth open state (also bound to the underlying Dialog). */
   open: Ref<boolean>;
   /** Alias of {@link open}; kept for parity with consumers reading `isOpen`. */
   isOpen: Ref<boolean>;
+  /**
+   * Lifecycle phase of the drawer — unlike {@link open}, the enter/exit
+   * transitions are explicit states (`opening`/`closing`).
+   */
+  phase: Readonly<ShallowRef<DrawerPhase>>;
+  /**
+   * Signal that the open/close animation settled. Called by DrawerRoot when the
+   * drawer element's transition/animation ends (or its fallback timeout fires);
+   * advances {@link phase} out of `opening`/`closing`.
+   */
+  notifySettled: () => void;
   /** Whether the drawer blocks the rest of the page (focus trap, scroll lock). */
   modal: Ref<boolean>;
   /** Becomes `true` the first time the drawer opens; gates Safari position fixes. */
@@ -20,11 +31,11 @@ export interface DrawerRootContext {
   handleRef: MaybeElementRef<HTMLElement | undefined>;
   /** Whether a pointer drag is currently in progress. */
   isDragging: Ref<boolean>;
-  /** Timestamp the active drag started, for velocity calculations. */
-  dragStartTime: Ref<Date | null>;
+  /** `event.timeStamp` of the active drag's start (ms, `performance.now()` clock). */
+  dragStartTime: Ref<number | null>;
   /** Latched once a drag is permitted, so it can't be cancelled mid-gesture. */
   isAllowedToDrag: Ref<boolean>;
-  /** Configured snap points (fractions of the screen or px strings). */
+  /** Configured snap points (fractions of the screen, px numbers, or px/rem strings). */
   snapPoints: Ref<Array<number | string> | undefined>;
   /** Whether any snap points are configured. */
   hasSnapPoints: Ref<boolean>;
@@ -38,18 +49,35 @@ export interface DrawerRootContext {
   dismissible: Ref<boolean>;
   /** Measured height of the drawer content in px. */
   drawerHeightRef: Ref<number>;
-  /** Pixel offset of each snap point along the drag axis. */
+  /** Pixel offset of each snap point along the drag axis (`NaN` for invalid points). */
   snapPointsOffset: Ref<number[]>;
   /** The edge the drawer is anchored to. */
   direction: Ref<DrawerDirection>;
-  /** Begin a drag gesture. */
-  onPress: (event: PointerEvent) => void;
+  /**
+   * Begin a drag gesture. `captureTarget` is the element that receives pointer
+   * capture (defaults to the pressed element — capturing any higher, e.g. on
+   * the drawer itself, would retarget `click` away from controls inside; the
+   * handle passes itself so `handleOnly` gestures keep receiving moves).
+   */
+  onPress: (event: PointerEvent, captureTarget?: HTMLElement) => void;
   /** Update the drawer position during a drag. */
   onDrag: (event: PointerEvent) => void;
   /** Settle the drawer (snap, close, or reset) when the pointer is released. */
   onRelease: (event: PointerEvent) => void;
-  /** Programmatically close the drawer. */
-  closeDrawer: () => void;
+  /**
+   * Abort the active drag without a user release (`pointercancel`, lost
+   * capture): resets the drag state and settles the drawer back in place.
+   */
+  onCancel: (event: PointerEvent) => void;
+  /** Programmatically close the drawer, optionally tagging what caused it. */
+  closeDrawer: (reason?: DrawerOpenChangeReason) => void;
+  /**
+   * Tag the next open-state flip with a reason. Consumed (and cleared) by
+   * DrawerRoot's `update:open` emitter; auto-expires when no flip follows.
+   */
+  armReason: (reason: DrawerOpenChangeReason) => void;
+  /** Reason armed for the next open-state flip, if any. */
+  pendingReason: { current: DrawerOpenChangeReason | undefined };
   /** Whether the overlay should fade with the drag at the current snap point. */
   shouldFade: Ref<boolean>;
   /** Snap point index from which the overlay starts fading. */

vue/primitives/src/overlays/drawer/controls.ts

@@ -2,21 +2,31 @@ import type { Ref } from 'vue';
 import { computed, ref, shallowRef, watch, watchEffect } from 'vue';
 import { isClient } from '@robonen/platform/multi';
 import { getTranslate, resetStyle, setStyle } from '@robonen/platform/browsers';
-import { dampenValue, getDrawerWrapper, isVertical } from './helpers';
-import { BORDER_RADIUS, DRAG_CLASS, NESTED_DISPLACEMENT, TRANSITIONS, VELOCITY_THRESHOLD, WINDOW_TOP_OFFSET } from './constants';
+import { useStateMachine, useTextSelection, useWindowSize } from '@robonen/vue';
+import { dampenValue, getDrawerWrapper, getScaleFactor, isVertical, translate3d, translateAxis, writeTransform } from './helpers';
+import {
+  AXIS_LOCK_DISTANCE,
+  BORDER_RADIUS,
+  DRAG_CLASS,
+  NESTED_DISPLACEMENT,
+  TRANSITIONS,
+  VELOCITY_THRESHOLD,
+} from './constants';
+import type { GestureAxis, ReverseCancelTracker, VelocityTracker } from './gesture';
+import { computeSettleDuration, createReverseCancelTracker, createVelocityTracker, findScrollableAncestor, isAtScrollEdge } from './gesture';
 import { useSnapPoints } from './useSnapPoints';
 import { usePositionFixed } from './usePositionFixed';
 import type { DrawerRootContext } from './context';
-import type { DrawerDirection } from './types';
+import type { DrawerDirection, DrawerOpenChangeDetails, DrawerOpenChangeReason } from './types';
 
 /** Shared, never-mutated — avoids allocating `{ transition: 'none' }` per drag frame. */
 const STYLE_NO_TRANSITION = { transition: 'none' };
 
 export interface WithoutFadeFromProps {
   /**
-   * Fractions (0–1) of the screen each snap point occupies, ordered from least
-   * to most visible — e.g. `[0.2, 0.5, 0.8]`. Px strings (e.g. `'200px'`) are
-   * also accepted and ignore screen height.
+   * Snap points ordered from least to most visible: fractions (0–1) of the
+   * screen, raw pixel numbers (> 1), or `'Npx'`/`'Nrem'` strings — e.g.
+   * `[0.2, '148px', 0.8]`.
    */
   snapPoints?: Array<number | string>;
   /** Index of the snap point from which the overlay fade begins. Defaults to the last. */
@@ -82,6 +92,12 @@ export type DrawerRootProps = {
   handleOnly?: boolean;
   /** Don't restore scroll position when the drawer closes after a navigation. */
   preventScrollRestoration?: boolean;
+  /**
+   * Settle on the snap point adjacent to the active one (one step per gesture)
+   * instead of the nearest to where the drag ended.
+   * @default false
+   */
+  snapToSequentialPoints?: boolean;
 } & WithoutFadeFromProps;
 
 export interface UseDrawerProps {
@@ -101,6 +117,7 @@ export interface UseDrawerProps {
   noBodyStyles: Ref<boolean>;
   preventScrollRestoration: Ref<boolean>;
   handleOnly: Ref<boolean>;
+  snapToSequentialPoints: Ref<boolean>;
 }
 
 export interface DrawerRootEmits {
@@ -110,8 +127,8 @@ export interface DrawerRootEmits {
   (e: 'release', open: boolean): void;
   /** Fired when the drawer begins closing. */
   (e: 'close'): void;
-  /** Two-way binding for the open state. */
-  (e: 'update:open', open: boolean): void;
+  /** Two-way binding for the open state. `details.reason` says what flipped it. */
+  (e: 'update:open', open: boolean, details?: DrawerOpenChangeDetails): void;
   /** Two-way binding for the active snap point. */
   (e: 'update:activeSnapPoint', val: string | number): void;
   /** Fired after the open/close animation ends, with the open state at that time. */
@@ -129,6 +146,47 @@ export interface DrawerHandleProps {
   preventCycle?: boolean;
 }
 
+/**
+ * Everything the drag hot path needs, snapshotted once at `onPress` so no
+ * pointer-move ever reads layout (`getBoundingClientRect`/`getComputedStyle`),
+ * queries the document, or allocates. Discarded on release/cancel.
+ */
+interface GestureState {
+  pointerId: number;
+  captureTarget: Element;
+  vertical: boolean;
+  /** +1 when the dismiss direction increases the client coordinate (bottom/right). */
+  multiplier: 1 | -1;
+  startX: number;
+  startY: number;
+  /** Drawer size (px) along the drag axis, measured once at press. */
+  size: number;
+  /** Window dimension (px) along the drag axis. */
+  windowSize: number;
+  /** Background-scale factor, cached so drag frames don't read `window.innerWidth`. */
+  scale: number;
+  /**
+   * Inline translate currently applied to the drawer (px, signed). Seeded from
+   * the computed style once at press (so a mid-animation grab starts from the
+   * on-screen position) and mirrored on every write afterwards — the drag path
+   * never reads computed styles.
+   */
+  translate: number;
+  wrapper: HTMLElement | null;
+  /** Nearest scrollable ancestor under the pointer along the drag axis. */
+  scroller: HTMLElement | null;
+  /** Whether the first significant movement has locked the gesture's axis. */
+  axisLocked: boolean;
+  /** The gesture locked onto the cross axis — never a drawer drag. */
+  blocked: boolean;
+  velocity: VelocityTracker;
+  reverse: ReverseCancelTracker;
+  /** Last written overlay opacity (`''` = none yet) — skips redundant writes. */
+  lastOverlayOpacity: string;
+  /** Last wrapper-scale progress written (`-1` = none yet) — skips redundant writes. */
+  lastWrapperProgress: number;
+}
+
 function usePropOrDefaultRef<T>(prop: Ref<T | undefined> | undefined, defaultRef: Ref<T>): Ref<T> {
   return prop && !!prop.value ? (prop as Ref<T>) : defaultRef;
 }
@@ -157,19 +215,19 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
     noBodyStyles,
     handleOnly,
     preventScrollRestoration,
+    snapToSequentialPoints,
   } = props;
 
   const hasBeenOpened = ref(open.value);
   const isDragging = ref(false);
-  const justReleased = ref(false);
+  const isAllowedToDrag = ref(false);
+  const dragStartTime = ref<number | null>(null);
 
   const overlayRef = shallowRef<HTMLElement | undefined>(undefined);
 
-  const openTime = ref<Date | null>(null);
-  const dragStartTime = ref<Date | null>(null);
-  const dragEndTime = ref<Date | null>(null);
-  const lastTimeDragPrevented = ref<Date | null>(null);
-  const isAllowedToDrag = ref(false);
+  // Timestamps on the `performance.now()` clock (same origin as event.timeStamp).
+  let openTime: number | null = null;
+  let lastTimeDragPrevented: number | null = null;
 
   const nestedOpenChangeTimer = ref<number | null>(null);
 
@@ -185,11 +243,31 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
 
   const handleRef = shallowRef<HTMLElement | undefined>(undefined);
 
+  // Shared reactive window dimensions (0 during SSR) and text selection — one
+  // listener each, reused by the gesture, the scale math, and the snap engine.
+  const { width: windowWidth, height: windowHeight } = useWindowSize({ initialWidth: 0, initialHeight: 0 });
+  const { text: selectedText } = useTextSelection();
+
+  /** Reason armed for the next open-state flip; consumed by DrawerRoot's emitter. */
+  const pendingReason: { current: DrawerOpenChangeReason | undefined } = { current: undefined };
+
+  function armReason(reason: DrawerOpenChangeReason) {
+    pendingReason.current = reason;
+
+    // Auto-expire so a dismiss that ends up prevented can't mislabel a later
+    // programmatic flip. The open watcher (microtask) always wins this timeout.
+    setTimeout(() => {
+      if (pendingReason.current === reason)
+        pendingReason.current = undefined;
+    }, 0);
+  }
+
   const {
     activeSnapPointIndex,
     onRelease: onReleaseSnapPoints,
     snapPointsOffset,
     onDrag: onDragSnapPoints,
+    restoreActiveSnapPoint,
     shouldFade,
     getPercentageDragged: getSnapPointsPercentageDragged,
   } = useSnapPoints({
@@ -200,13 +278,16 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
     overlayRef,
     onSnapPointChange,
     direction,
+    snapToSequentialPoints,
+    windowWidth,
+    windowHeight,
   });
 
   function onSnapPointChange(activeSnapPointIndex: number, snapPointsOffset: number[]) {
     // Refresh openTime when we reach the last snap point so scrollable content
     // there isn't immediately draggable.
     if (snapPoints.value && activeSnapPointIndex === snapPointsOffset.length - 1)
-      openTime.value = new Date();
+      openTime = performance.now();
   }
 
   usePositionFixed({
@@ -218,203 +299,300 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
     preventScrollRestoration,
   });
 
-  function getScale() {
-    return (window.innerWidth - WINDOW_TOP_OFFSET) / window.innerWidth;
-  }
+  // The drawer's lifecycle as explicit phases. `OPEN`/`CLOSE` are driven by the
+  // shared `open` ref below; `SETTLE` arrives from DrawerRoot when the enter/exit
+  // animation actually ends (element event or its fallback timeout). Close-side
+  // cleanup lives on the `closed` entry hook instead of duration-guessing
+  // timeouts: re-opening mid-close moves `closing → opening`, so it can never
+  // fire on a live drawer.
+  const lifecycle = useStateMachine({
+    initial: open.value ? 'open' : 'closed',
+    states: {
+      closed: {
+        entry: () => {
+          if (snapPoints.value)
+            activeSnapPoint.value = snapPoints.value[0];
+        },
+        on: { OPEN: 'opening' },
+      },
+      opening: {
+        entry: () => {
+          openTime = performance.now();
+          hasBeenOpened.value = true;
+          // A fast-flick close writes an inline animation-duration override;
+          // reopening before that exit settles reuses the SAME element
+          // (Presence keeps it alive), so clear the override here or the enter
+          // — and any later gentle exit — replays at flick speed.
+          drawerRef.value?.style.removeProperty('animation-duration');
+          overlayRef.value?.style.removeProperty('animation-duration');
+        },
+        on: { SETTLE: 'open', CLOSE: 'closing' },
+      },
+      open: { on: { CLOSE: 'closing' } },
+      closing: { on: { SETTLE: 'closed', OPEN: 'opening' } },
+    },
+  });
+
+  let gesture: GestureState | null = null;
+
+  function shouldDrag(el: EventTarget | null, isDraggingInDirection: boolean, now: number): boolean {
+    const g = gesture!;
 
-  function shouldDrag(el: EventTarget | null, isDraggingInDirection: boolean) {
     if (!el)
       return false;
-    let element = el as HTMLElement;
-    const highlightedText = globalThis.getSelection()?.toString();
-    const swipeAmount = drawerRef.value ? getTranslate(drawerRef.value, isVertical(direction.value) ? 'y' : 'x') : null;
-    const date = new Date();
 
-    if (element.hasAttribute('data-drawer-no-drag') || element.closest('[data-drawer-no-drag]'))
+    const element = el as HTMLElement;
+
+    if (element.closest?.('[data-drawer-no-drag]'))
       return false;
 
-    if (direction.value === 'right' || direction.value === 'left')
-      return true;
-
     // Allow scrolling during the open animation.
-    if (openTime.value && date.getTime() - openTime.value.getTime() < 500)
+    if (openTime !== null && now - openTime < 500)
       return false;
 
-    if (swipeAmount !== null) {
-      if (direction.value === 'bottom' ? swipeAmount > 0 : swipeAmount < 0)
-        return true;
-    }
+    // Partially hidden (a snap point below fully open, or a mid-animation
+    // grab) — the drawer is always draggable.
+    const swipeAmount = g.translate;
 
-    // Don't drag when text is selected.
-    if (highlightedText && highlightedText.length > 0)
+    if (g.multiplier === 1 ? swipeAmount > 0 : swipeAmount < 0)
+      return true;
+
+    // Don't drag when text is selected (reactive — no per-move getSelection).
+    if (selectedText.value.length > 0)
       return false;
 
     // Don't drag right after scrolling inside the drawer.
     if (
-      lastTimeDragPrevented.value
-      && date.getTime() - lastTimeDragPrevented.value.getTime() < scrollLockTimeout.value
+      lastTimeDragPrevented !== null
+      && now - lastTimeDragPrevented < scrollLockTimeout.value
       && swipeAmount === 0
     ) {
-      lastTimeDragPrevented.value = date;
+      lastTimeDragPrevented = now;
       return false;
     }
 
     if (isDraggingInDirection) {
-      lastTimeDragPrevented.value = date;
+      lastTimeDragPrevented = now;
       // Dragging in the open direction → allow scrolling instead.
       return false;
     }
 
-    // Walk up the tree; if a scrollable ancestor isn't at the top, scroll it instead of dragging.
-    while (element) {
-      if (element.scrollHeight > element.clientHeight) {
-        if (element.scrollTop !== 0) {
-          lastTimeDragPrevented.value = new Date();
-          return false;
-        }
-
-        if (element.getAttribute('role') === 'dialog')
-          return true;
-      }
-
-      element = element.parentNode as HTMLElement;
+    // A scroll container under the pointer owns the gesture unless it already
+    // sits at the edge the dismiss direction pulls away from.
+    if (g.scroller && !isAtScrollEdge(g.scroller, direction.value)) {
+      lastTimeDragPrevented = now;
+      return false;
     }
 
     return true;
   }
 
-  // Measured once per gesture in onPress and reused every move — avoids a
-  // per-frame getBoundingClientRect (forced reflow) and document.querySelector.
-  let dragStartHeight = 0;
-  let dragWrapper: HTMLElement | null = null;
+  function onPress(event: PointerEvent, captureTarget?: HTMLElement) {
+    // One gesture at a time; a second touch never steals an active drag. But a
+    // gesture whose capture element left the DOM can never finish (its
+    // lostpointercapture fires at the document, past our listeners) — reclaim
+    // it instead of wedging every future drag.
+    if (gesture) {
+      if (gesture.captureTarget.isConnected)
+        return;
 
-  function onPress(event: PointerEvent) {
+      gesture = null;
+      isAllowedToDrag.value = false;
+      isDragging.value = false;
+      drawerRef.value?.classList.remove(DRAG_CLASS);
+    }
     if (!dismissible.value && !snapPoints.value)
       return;
-    if (drawerRef.value && !drawerRef.value.contains(event.target as Node))
+    if (event.button > 0)
       return;
-    isDragging.value = true;
-    dragStartTime.value = new Date();
-    dragStartHeight = drawerRef.value?.getBoundingClientRect().height || 0;
-    dragWrapper = getDrawerWrapper();
 
-    (event.target as HTMLElement).setPointerCapture(event.pointerId);
-    pointerStart.value = isVertical(direction.value) ? event.clientY : event.clientX;
+    const el = drawerRef.value;
+
+    if (!el || !el.contains(event.target as Node))
+      return;
+
+    const vertical = isVertical(direction.value);
+    const axis: GestureAxis = vertical ? 'y' : 'x';
+    const rect = el.getBoundingClientRect();
+    // Capture on the pressed element, never the drawer: while a capture is
+    // active the compat mouse events retarget to the capturing element, so
+    // capturing on the drawer would swallow `click` for every control inside it.
+    const capture = captureTarget ?? (event.target as Element);
+
+    // Synthetic pointers (tests) and already-released pointers have no active
+    // pointer id to capture — the drag still works, only retargeting is lost.
+    try {
+      capture.setPointerCapture(event.pointerId);
+    }
+    catch {
+      // No active pointer to capture — the drag still works, only retargeting is lost.
+    }
+
+    isDragging.value = true;
+    dragStartTime.value = event.timeStamp;
+    pointerStart.value = vertical ? event.clientY : event.clientX;
+
+    gesture = {
+      pointerId: event.pointerId,
+      captureTarget: capture,
+      vertical,
+      multiplier: direction.value === 'bottom' || direction.value === 'right' ? 1 : -1,
+      startX: event.clientX,
+      startY: event.clientY,
+      size: (vertical ? rect.height : rect.width) || 0,
+      windowSize: vertical ? windowHeight.value : windowWidth.value,
+      scale: getScaleFactor(windowWidth.value),
+      // The one intentional computed-style read of the gesture: catches the
+      // drawer mid-animation so the drag continues from the on-screen position.
+      translate: getTranslate(el, axis) ?? 0,
+      wrapper: getDrawerWrapper(),
+      scroller: findScrollableAncestor(event.target as Element, el, axis),
+      axisLocked: false,
+      blocked: false,
+      velocity: createVelocityTracker(),
+      reverse: createReverseCancelTracker(),
+      lastOverlayOpacity: '',
+      lastWrapperProgress: -1,
+    };
   }
 
   function onDrag(event: PointerEvent) {
-    if (!drawerRef.value)
+    const g = gesture;
+
+    if (!g || event.pointerId !== g.pointerId || !isDragging.value || g.blocked || !drawerRef.value)
       return;
 
-    if (isDragging.value) {
-      const directionMultiplier = direction.value === 'bottom' || direction.value === 'right' ? 1 : -1;
-      const draggedDistance
-        = (pointerStart.value - (isVertical(direction.value) ? event.clientY : event.clientX)) * directionMultiplier;
-      const isDraggingInDirection = draggedDistance > 0;
+    const dx = event.clientX - g.startX;
+    const dy = event.clientY - g.startY;
 
-      // Don't allow dragging toward close past the first snap point when not dismissible.
-      const noCloseSnapPointsPreCondition = snapPoints.value && !dismissible.value && !isDraggingInDirection;
+    // Lock onto an axis on the first significant movement. A gesture that
+    // locks onto the cross axis is a scroll/pan — never a drawer drag.
+    if (!g.axisLocked) {
+      const absX = Math.abs(dx);
+      const absY = Math.abs(dy);
 
-      if (noCloseSnapPointsPreCondition && activeSnapPointIndex.value === 0)
+      if (absX < AXIS_LOCK_DISTANCE && absY < AXIS_LOCK_DISTANCE)
         return;
 
-      const absDraggedDistance = Math.abs(draggedDistance);
-      const wrapper = dragWrapper;
+      g.axisLocked = true;
 
-      // 1 means the closed position. Height cached at drag start (no reflow).
-      let percentageDragged = absDraggedDistance / (dragStartHeight || 1);
-      const snapPointPercentageDragged = getSnapPointsPercentageDragged(absDraggedDistance, isDraggingInDirection);
-
-      if (snapPointPercentageDragged !== null)
-        percentageDragged = snapPointPercentageDragged;
-
-      if (noCloseSnapPointsPreCondition && percentageDragged >= 1)
-        return;
-
-      // Decide-to-drag gate + one-time gesture setup. Once allowed, stay allowed
-      // for the whole gesture, so the class add + transition writes fire ONCE,
-      // not on every move.
-      if (!isAllowedToDrag.value) {
-        if (!shouldDrag(event.target, isDraggingInDirection))
-          return;
-        isAllowedToDrag.value = true;
-        drawerRef.value.classList.add(DRAG_CLASS);
-        setStyle(drawerRef.value, STYLE_NO_TRANSITION);
-        setStyle(overlayRef.value, STYLE_NO_TRANSITION);
-      }
-
-      if (snapPoints.value)
-        onDragSnapPoints({ draggedDistance });
-
-      // Rubber-band past the open position when there are no snap points.
-      if (isDraggingInDirection && !snapPoints.value) {
-        const dampenedDraggedDistance = dampenValue(draggedDistance);
-
-        const translateValue = Math.min(dampenedDraggedDistance * -1, 0) * directionMultiplier;
-        setStyle(drawerRef.value, {
-          transform: isVertical(direction.value)
-            ? `translate3d(0, ${translateValue}px, 0)`
-            : `translate3d(${translateValue}px, 0, 0)`,
-        });
+      if ((absX > absY) === g.vertical) {
+        g.blocked = true;
         return;
       }
+    }
 
-      const opacityValue = 1 - percentageDragged;
+    g.velocity.add(g.vertical ? event.clientY : event.clientX, event.timeStamp);
 
-      if (shouldFade.value || (fadeFromIndex.value && activeSnapPointIndex.value === fadeFromIndex.value - 1)) {
-        emitDrag(percentageDragged);
+    const draggedDistance = (g.vertical ? g.startY - event.clientY : g.startX - event.clientX) * g.multiplier;
+    const isDraggingInDirection = draggedDistance > 0;
 
-        setStyle(overlayRef.value, { opacity: `${opacityValue}`, transition: 'none' }, true);
+    // Dismiss-positive displacement feeds the "changed my mind" detector.
+    g.reverse.update(-draggedDistance);
+
+    // Don't allow dragging toward close past the first snap point when not dismissible.
+    const noCloseSnapPointsPreCondition = snapPoints.value && !dismissible.value && !isDraggingInDirection;
+
+    if (noCloseSnapPointsPreCondition && activeSnapPointIndex.value === 0)
+      return;
+
+    const absDraggedDistance = Math.abs(draggedDistance);
+
+    // 1 means the closed position. Size cached at drag start (no reflow).
+    let percentageDragged = absDraggedDistance / (g.size || 1);
+    const snapPointPercentageDragged = getSnapPointsPercentageDragged(absDraggedDistance, isDraggingInDirection);
+
+    if (snapPointPercentageDragged !== null)
+      percentageDragged = snapPointPercentageDragged;
+
+    if (noCloseSnapPointsPreCondition && percentageDragged >= 1)
+      return;
+
+    // Decide-to-drag gate + one-time gesture setup. Once allowed, stay allowed
+    // for the whole gesture, so the class add + transition writes fire ONCE,
+    // not on every move.
+    if (!isAllowedToDrag.value) {
+      if (!shouldDrag(event.target, isDraggingInDirection, event.timeStamp))
+        return;
+      isAllowedToDrag.value = true;
+      drawerRef.value.classList.add(DRAG_CLASS);
+      setStyle(drawerRef.value, STYLE_NO_TRANSITION);
+      setStyle(overlayRef.value, STYLE_NO_TRANSITION);
+    }
+
+    if (snapPoints.value) {
+      const applied = onDragSnapPoints({ draggedDistance });
+
+      if (applied !== null)
+        g.translate = applied;
+    }
+
+    // Rubber-band past the open position when there are no snap points.
+    if (isDraggingInDirection && !snapPoints.value) {
+      const dampenedDraggedDistance = dampenValue(draggedDistance);
+      const translateValue = Math.min(dampenedDraggedDistance * -1, 0) * g.multiplier;
+
+      writeTransform(drawerRef.value, translateAxis(g.vertical, translateValue));
+      g.translate = translateValue;
+      return;
+    }
+
+    if (shouldFade.value || (fadeFromIndex.value && activeSnapPointIndex.value === fadeFromIndex.value - 1)) {
+      emitDrag(percentageDragged);
+
+      const overlay = overlayRef.value;
+      const opacity = `${1 - percentageDragged}`;
+
+      if (overlay && opacity !== g.lastOverlayOpacity) {
+        g.lastOverlayOpacity = opacity;
+        overlay.style.opacity = opacity;
+        overlay.style.transition = 'none';
       }
+    }
 
-      if (wrapper && overlayRef.value && shouldScaleBackground.value) {
-        const scaleValue = Math.min(getScale() + percentageDragged * (1 - getScale()), 1);
-        const borderRadiusValue = 8 - percentageDragged * 8;
-        const translateValue = Math.max(0, 14 - percentageDragged * 14);
+    if (g.wrapper && overlayRef.value && shouldScaleBackground.value && percentageDragged !== g.lastWrapperProgress) {
+      g.lastWrapperProgress = percentageDragged;
 
-        setStyle(
-          wrapper,
-          {
-            borderRadius: `${borderRadiusValue}px`,
-            transform: isVertical(direction.value)
-              ? `scale(${scaleValue}) translate3d(0, ${translateValue}px, 0)`
-              : `scale(${scaleValue}) translate3d(${translateValue}px, 0, 0)`,
-            transition: 'none',
-          },
-          true,
-        );
-      }
+      const scaleValue = Math.min(g.scale + percentageDragged * (1 - g.scale), 1);
+      const borderRadiusValue = 8 - percentageDragged * 8;
+      const translateValue = Math.max(0, 14 - percentageDragged * 14);
+      const style = g.wrapper.style;
 
-      if (!snapPoints.value) {
-        const translateValue = absDraggedDistance * directionMultiplier;
+      style.borderRadius = `${borderRadiusValue}px`;
+      style.transform = g.vertical
+        ? `scale(${scaleValue}) translate3d(0, ${translateValue}px, 0)`
+        : `scale(${scaleValue}) translate3d(${translateValue}px, 0, 0)`;
+      style.transition = 'none';
+    }
 
-        setStyle(drawerRef.value, {
-          transform: isVertical(direction.value)
-            ? `translate3d(0, ${translateValue}px, 0)`
-            : `translate3d(${translateValue}px, 0, 0)`,
-        });
-      }
+    if (!snapPoints.value) {
+      const translateValue = absDraggedDistance * g.multiplier;
+
+      writeTransform(drawerRef.value, translateAxis(g.vertical, translateValue));
+      g.translate = translateValue;
     }
   }
 
-  function resetDrawer() {
+  function resetDrawer(duration: number = TRANSITIONS.DURATION, currentSwipeAmount?: number | null) {
     if (!drawerRef.value)
       return;
     const wrapper = getDrawerWrapper();
-    const currentSwipeAmount = getTranslate(drawerRef.value, isVertical(direction.value) ? 'y' : 'x');
+    const swipeAmount = currentSwipeAmount
+      ?? getTranslate(drawerRef.value, isVertical(direction.value) ? 'y' : 'x');
+    const ease = `cubic-bezier(${TRANSITIONS.EASE.join(',')})`;
 
     setStyle(drawerRef.value, {
       transform: 'translate3d(0, 0, 0)',
-      transition: `transform ${TRANSITIONS.DURATION}s cubic-bezier(${TRANSITIONS.EASE.join(',')})`,
+      transition: `transform ${duration}s ${ease}`,
     });
 
     setStyle(overlayRef.value, {
-      transition: `opacity ${TRANSITIONS.DURATION}s cubic-bezier(${TRANSITIONS.EASE.join(',')})`,
+      transition: `opacity ${duration}s ${ease}`,
       opacity: '1',
     });
 
     // Keep the background scaled if we didn't swipe back down.
-    if (shouldScaleBackground.value && currentSwipeAmount && currentSwipeAmount > 0 && open.value) {
+    if (shouldScaleBackground.value && swipeAmount && swipeAmount > 0 && open.value) {
       setStyle(
         wrapper,
         {
@@ -422,11 +600,11 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
           overflow: 'hidden',
           ...(isVertical(direction.value)
             ? {
-                transform: `scale(${getScale()}) translate3d(0, calc(env(safe-area-inset-top) + 14px), 0)`,
+                transform: `scale(${getScaleFactor(windowWidth.value)}) translate3d(0, calc(env(safe-area-inset-top) + 14px), 0)`,
                 transformOrigin: 'top',
               }
             : {
-                transform: `scale(${getScale()}) translate3d(calc(env(safe-area-inset-top) + 14px), 0, 0)`,
+                transform: `scale(${getScaleFactor(windowWidth.value)}) translate3d(calc(env(safe-area-inset-top) + 14px), 0, 0)`,
                 transformOrigin: 'left',
               }),
           transitionProperty: 'transform, border-radius',
@@ -442,13 +620,136 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
   // snap-point reset, update:open) is driven off the `open` transition below, so
   // this stays the single place that closes — whatever the trigger (drag, handle,
   // dialog dismissal, or a controlled `v-model:open` flip).
-  function closeDrawer() {
+  function closeDrawer(reason?: DrawerOpenChangeReason) {
     if (!drawerRef.value)
       return;
 
+    if (reason)
+      armReason(reason);
+
     open.value = false;
   }
 
+  /**
+   * Close via the exit keyframes, scaled to the fling: the inline
+   * `animation-duration` overrides the stylesheet's 0.5s so a hard flick
+   * finishes in as little as 80ms. A reopen before the exit settles reuses the
+   * same element (Presence holds it), so the `opening` entry hook clears the
+   * override before the enter plays.
+   */
+  function closeWithSettle(remainingDistance: number, velocity: number) {
+    const duration = computeSettleDuration(remainingDistance, velocity);
+
+    if (duration !== TRANSITIONS.DURATION) {
+      const durationValue = `${duration}s`;
+
+      if (drawerRef.value)
+        drawerRef.value.style.animationDuration = durationValue;
+      if (overlayRef.value)
+        overlayRef.value.style.animationDuration = durationValue;
+    }
+
+    closeDrawer('swipe');
+  }
+
+  function endGesture(event: PointerEvent): GestureState | null {
+    const g = gesture;
+
+    if (!g || event.pointerId !== g.pointerId)
+      return null;
+
+    gesture = null;
+    drawerRef.value?.classList.remove(DRAG_CLASS);
+
+    try {
+      g.captureTarget.releasePointerCapture(event.pointerId);
+    }
+    catch {
+      // Capture was never acquired (synthetic pointer) or already released.
+    }
+
+    const wasAllowed = isAllowedToDrag.value;
+
+    isAllowedToDrag.value = false;
+    isDragging.value = false;
+
+    return wasAllowed ? g : null;
+  }
+
+  function onRelease(event: PointerEvent) {
+    if (!isDragging.value || !drawerRef.value) {
+      endGesture(event);
+      return;
+    }
+
+    const g = endGesture(event);
+
+    if (!g)
+      return;
+
+    const swipeAmount = g.translate;
+    const cancelled = g.reverse.cancelled;
+    const rawVelocity = g.velocity.read(event.timeStamp);
+    const velocityToDismiss = cancelled ? 0 : rawVelocity * g.multiplier;
+    const distMoved = g.vertical ? g.startY - event.clientY : g.startX - event.clientX;
+    const draggedDistance = distMoved * g.multiplier;
+
+    if (snapPoints.value) {
+      onReleaseSnapPoints({
+        draggedDistance,
+        closeDrawer: () => closeDrawer('swipe'),
+        velocity: velocityToDismiss,
+        dismissible: dismissible.value,
+        drawerSize: g.size,
+      });
+      emitRelease(true);
+      return;
+    }
+
+    // Moved toward open, or pulled back to cancel → settle into place.
+    if (draggedDistance > 0 || cancelled) {
+      resetDrawer(computeSettleDuration(Math.abs(swipeAmount), rawVelocity), swipeAmount);
+      emitRelease(true);
+      return;
+    }
+
+    const dismissTravel = swipeAmount * g.multiplier;
+    const remaining = Math.max(g.size - dismissTravel, 0);
+
+    if (velocityToDismiss > VELOCITY_THRESHOLD) {
+      closeWithSettle(remaining, velocityToDismiss);
+      emitRelease(false);
+      return;
+    }
+
+    const visibleSize = Math.min(g.size || 0, g.windowSize);
+
+    if (dismissTravel >= visibleSize * closeThreshold.value) {
+      closeWithSettle(remaining, velocityToDismiss);
+      emitRelease(false);
+      return;
+    }
+
+    emitRelease(true);
+    resetDrawer(computeSettleDuration(dismissTravel, rawVelocity), swipeAmount);
+  }
+
+  function onCancel(event: PointerEvent) {
+    const g = endGesture(event);
+
+    if (!g)
+      return;
+
+    // A cancelled pointer is not a user decision — settle back where the
+    // drawer was, never close.
+    if (snapPoints.value)
+      restoreActiveSnapPoint();
+    else
+      resetDrawer(TRANSITIONS.DURATION, g.translate);
+
+    emitRelease(true);
+  }
+
   watchEffect(() => {
     if (!open.value && shouldScaleBackground.value && isClient) {
       // The component is invisible by the time onAnimationEnd would fire, so use a timeout.
@@ -462,99 +763,28 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
     return undefined;
   });
 
-  function onRelease(event: PointerEvent) {
-    if (!isDragging.value || !drawerRef.value)
-      return;
-
-    drawerRef.value.classList.remove(DRAG_CLASS);
-    isAllowedToDrag.value = false;
-    isDragging.value = false;
-    dragWrapper = null;
-    dragEndTime.value = new Date();
-    const swipeAmount = getTranslate(drawerRef.value, isVertical(direction.value) ? 'y' : 'x');
-
-    if (!shouldDrag(event.target, false) || !swipeAmount || Number.isNaN(swipeAmount))
-      return;
-
-    if (dragStartTime.value === null)
-      return;
-
-    const timeTaken = dragEndTime.value.getTime() - dragStartTime.value.getTime();
-    const distMoved = pointerStart.value - (isVertical(direction.value) ? event.clientY : event.clientX);
-    const velocity = Math.abs(distMoved) / timeTaken;
-
-    if (velocity > 0.05) {
-      // Prevents the drawer from focusing an input as the drag ends.
-      justReleased.value = true;
-
-      globalThis.setTimeout(() => {
-        justReleased.value = false;
-      }, 200);
-    }
-
-    if (snapPoints.value) {
-      const directionMultiplier = direction.value === 'bottom' || direction.value === 'right' ? 1 : -1;
-
-      onReleaseSnapPoints({
-        draggedDistance: distMoved * directionMultiplier,
-        closeDrawer,
-        velocity,
-        dismissible: dismissible.value,
-      });
-      emitRelease(true);
-      return;
-    }
-
-    // Moved in the open direction → settle back.
-    if (direction.value === 'bottom' || direction.value === 'right' ? distMoved > 0 : distMoved < 0) {
-      resetDrawer();
-      emitRelease(true);
-      return;
-    }
-
-    if (velocity > VELOCITY_THRESHOLD) {
-      closeDrawer();
-      emitRelease(false);
-      return;
-    }
-
-    const visibleDrawerHeight = Math.min(drawerRef.value.getBoundingClientRect().height ?? 0, window.innerHeight);
-
-    if (swipeAmount >= visibleDrawerHeight * closeThreshold.value) {
-      closeDrawer();
-      emitRelease(false);
-      return;
-    }
-
-    emitRelease(true);
-    resetDrawer();
-  }
-
   // Single owner of open/close side effects. Reacts to every source that writes
   // the shared `open` ref: the drag/handle paths (closeDrawer), the dialog's
   // dismissals (DrawerRoot.handleOpenChange), and a controlled `v-model:open`
   // flip (DrawerRoot's prop watch). `update:open`/`animationEnd` are emitted by
-  // DrawerRoot's own watch on the same ref.
+  // DrawerRoot's own watch on the same ref; everything else rides the lifecycle
+  // machine's entry hooks.
   watch(open, (o) => {
     if (o) {
-      openTime.value = new Date();
-      hasBeenOpened.value = true;
+      lifecycle.send('OPEN');
     }
     else {
       emitClose();
-      globalThis.setTimeout(() => {
-        if (snapPoints.value)
-          activeSnapPoint.value = snapPoints.value[0];
-      }, TRANSITIONS.DURATION * 1000);
+      lifecycle.send('CLOSE');
     }
   });
 
   function onNestedOpenChange(o: boolean) {
-    const scale = o ? (window.innerWidth - NESTED_DISPLACEMENT) / window.innerWidth : 1;
+    const scale = o ? (windowWidth.value - NESTED_DISPLACEMENT) / windowWidth.value : 1;
     const y = o ? -NESTED_DISPLACEMENT : 0;
 
     if (nestedOpenChangeTimer.value)
-      globalThis.clearTimeout(nestedOpenChangeTimer.value);
+      clearTimeout(nestedOpenChangeTimer.value);
 
     setStyle(drawerRef.value, {
       transition: `transform ${TRANSITIONS.DURATION}s cubic-bezier(${TRANSITIONS.EASE.join(',')})`,
@@ -562,13 +792,11 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
     });
 
     if (!o && drawerRef.value) {
-      nestedOpenChangeTimer.value = globalThis.setTimeout(() => {
+      nestedOpenChangeTimer.value = setTimeout(() => {
         const translateValue = getTranslate(drawerRef.value!, isVertical(direction.value) ? 'y' : 'x');
         setStyle(drawerRef.value, {
           transition: 'none',
-          transform: isVertical(direction.value)
-            ? `translate3d(0, ${translateValue}px, 0)`
-            : `translate3d(${translateValue}px, 0, 0)`,
+          transform: translate3d(direction.value, translateValue ?? 0),
         });
       }, 500);
     }
@@ -578,21 +806,25 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
     if (percentageDragged < 0)
       return;
 
-    const initialDim = isVertical(direction.value) ? window.innerHeight : window.innerWidth;
+    const el = drawerRef.value;
+
+    if (!el)
+      return;
+
+    const initialDim = isVertical(direction.value) ? windowHeight.value : windowWidth.value;
     const initialScale = (initialDim - NESTED_DISPLACEMENT) / initialDim;
     const newScale = initialScale + percentageDragged * (1 - initialScale);
     const newTranslate = -NESTED_DISPLACEMENT + percentageDragged * NESTED_DISPLACEMENT;
 
-    setStyle(drawerRef.value, {
-      transform: isVertical(direction.value)
-        ? `scale(${newScale}) translate3d(0, ${newTranslate}px, 0)`
-        : `scale(${newScale}) translate3d(${newTranslate}px, 0, 0)`,
-      transition: 'none',
-    });
+    // Per-frame path (driven by the child's drag) — direct writes, no setStyle.
+    el.style.transform = isVertical(direction.value)
+      ? `scale(${newScale}) translate3d(0, ${newTranslate}px, 0)`
+      : `scale(${newScale}) translate3d(${newTranslate}px, 0, 0)`;
+    el.style.transition = 'none';
   }
 
   function onNestedRelease(o: boolean) {
-    const dim = isVertical(direction.value) ? window.innerHeight : window.innerWidth;
+    const dim = isVertical(direction.value) ? windowHeight.value : windowWidth.value;
     const scale = o ? (dim - NESTED_DISPLACEMENT) / dim : 1;
     const translate = o ? -NESTED_DISPLACEMENT : 0;
 
@@ -609,6 +841,10 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
   return {
     open,
     isOpen: open,
+    phase: lifecycle.state,
+    notifySettled: () => {
+      lifecycle.send('SETTLE');
+    },
     modal,
     keyboardIsOpen,
     hasBeenOpened,
@@ -633,7 +869,10 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
     onPress,
     onDrag,
     onRelease,
+    onCancel,
     closeDrawer,
+    armReason,
+    pendingReason,
     onNestedDrag,
     onNestedRelease,
     onNestedOpenChange,

vue/primitives/src/overlays/drawer/gesture.ts

@@ -0,0 +1,178 @@
+import { clamp } from '@robonen/stdlib';
+import type { DrawerDirection } from './types';
+import {
+  MAX_VELOCITY_AGE,
+  MIN_SETTLE_DURATION,
+  MIN_VELOCITY_DT,
+  REVERSE_CANCEL_ARM_DISTANCE,
+  REVERSE_CANCEL_THRESHOLD,
+  SETTLE_VELOCITY_THRESHOLD,
+  TRANSITIONS,
+} from './constants';
+
+/** The client-coordinate axis a drawer drags along. */
+export type GestureAxis = 'x' | 'y';
+
+export interface VelocityTracker {
+  /** Record a pointer sample (client coordinate along the axis + event timeStamp). */
+  add: (position: number, time: number) => void;
+  /**
+   * Instantaneous velocity (px/ms) over the two newest samples. Returns 0 when
+   * the last sample is older than {@link MAX_VELOCITY_AGE} — the pointer paused
+   * before release, so no fling momentum should apply.
+   */
+  read: (now: number) => number;
+  reset: () => void;
+}
+
+/**
+ * Instantaneous release velocity from the trailing pair of pointer samples,
+ * instead of averaging the whole gesture: "slow pull, then flick" reads as a
+ * flick, and "fast start, stop, release" reads as a stop.
+ */
+export function createVelocityTracker(): VelocityTracker {
+  let lastPosition = 0;
+  let lastTime = Number.NaN;
+  let velocity = 0;
+
+  return {
+    add(position, time) {
+      if (!Number.isNaN(lastTime) && time > lastTime) {
+        // Clamp dt so same-frame event bursts don't produce huge spikes.
+        const dt = Math.max(time - lastTime, MIN_VELOCITY_DT);
+        velocity = (position - lastPosition) / dt;
+      }
+
+      lastPosition = position;
+      lastTime = time;
+    },
+    read(now) {
+      if (Number.isNaN(lastTime) || now - lastTime > MAX_VELOCITY_AGE)
+        return 0;
+
+      return velocity;
+    },
+    reset() {
+      lastPosition = 0;
+      lastTime = Number.NaN;
+      velocity = 0;
+    },
+  };
+}
+
+export interface ReverseCancelTracker {
+  /** Feed the current dismiss-positive displacement (px). */
+  update: (displacement: number) => void;
+  /** Whether the gesture pulled back far enough to cancel the dismiss. */
+  readonly cancelled: boolean;
+  reset: () => void;
+}
+
+/**
+ * Detects the "changed my mind" gesture: once the drawer has been dragged at
+ * least {@link REVERSE_CANCEL_ARM_DISTANCE} toward dismiss, pulling back by
+ * {@link REVERSE_CANCEL_THRESHOLD} from the furthest point cancels the dismiss
+ * even if the release still sits past the close threshold. Dragging past the
+ * previous furthest point re-arms the dismiss (renewed intent).
+ */
+export function createReverseCancelTracker(): ReverseCancelTracker {
+  let max = 0;
+  let cancelled = false;
+
+  return {
+    update(displacement) {
+      if (displacement >= max) {
+        max = displacement;
+        cancelled = false;
+        return;
+      }
+
+      if (max > REVERSE_CANCEL_ARM_DISTANCE && max - displacement > REVERSE_CANCEL_THRESHOLD)
+        cancelled = true;
+    },
+    get cancelled() {
+      return cancelled;
+    },
+    reset() {
+      max = 0;
+      cancelled = false;
+    },
+  };
+}
+
+/**
+ * Settle duration (in seconds) scaled by the release velocity: a hard flick
+ * over a short remaining distance settles in as little as
+ * {@link MIN_SETTLE_DURATION}ms, while a gentle release keeps the default
+ * {@link TRANSITIONS} duration. Never returns a duration longer than the default.
+ */
+export function computeSettleDuration(remainingDistance: number, velocity: number): number {
+  const fallback = TRANSITIONS.DURATION;
+
+  if (!Number.isFinite(remainingDistance) || remainingDistance <= 0)
+    return fallback;
+
+  const speed = Math.abs(velocity);
+
+  if (!Number.isFinite(speed) || speed < SETTLE_VELOCITY_THRESHOLD)
+    return fallback;
+
+  return clamp(remainingDistance / speed, MIN_SETTLE_DURATION, fallback * 1000) / 1000;
+}
+
+/**
+ * The nearest ancestor (from `start` up to and including `boundary`) that can
+ * scroll along `axis`. The `getComputedStyle` read runs at most once per
+ * candidate and only at gesture start — never per pointer move.
+ */
+export function findScrollableAncestor(
+  start: Element | null,
+  boundary: HTMLElement,
+  axis: GestureAxis,
+): HTMLElement | null {
+  let element: Element | null = start;
+
+  while (element) {
+    if (element instanceof HTMLElement) {
+      const canScroll = axis === 'y'
+        ? element.scrollHeight > element.clientHeight
+        : element.scrollWidth > element.clientWidth;
+
+      if (canScroll) {
+        const overflow = getComputedStyle(element)[axis === 'y' ? 'overflowY' : 'overflowX'];
+
+        if (overflow === 'auto' || overflow === 'scroll')
+          return element;
+      }
+    }
+
+    if (element === boundary)
+      break;
+
+    element = element.parentElement;
+  }
+
+  return null;
+}
+
+/**
+ * Whether a scroll container sits at the edge the dismiss gesture pulls away
+ * from — only then may a drag that starts inside it become a drawer gesture;
+ * otherwise the user is scrolling, not dismissing:
+ * - `bottom` drawer dismisses downward → the scroller must be at its top;
+ * - `top` drawer dismisses upward → at its bottom;
+ * - `right` drawer dismisses rightward → at its left edge;
+ * - `left` drawer dismisses leftward → at its right edge.
+ */
+export function isAtScrollEdge(scroller: HTMLElement, direction: DrawerDirection): boolean {
+  switch (direction) {
+    case 'bottom':
+      return scroller.scrollTop <= 0;
+    case 'top':
+      return scroller.scrollTop >= scroller.scrollHeight - scroller.clientHeight;
+    case 'right':
+      return scroller.scrollLeft <= 0;
+    case 'left':
+      return scroller.scrollLeft >= scroller.scrollWidth - scroller.clientWidth;
+  }
+}

vue/primitives/src/overlays/drawer/helpers.ts

@@ -1,4 +1,5 @@
 import type { DrawerDirection } from './types';
+import { WINDOW_TOP_OFFSET } from './constants';
 
 /**
  * Whether a direction runs along the vertical axis (`top`/`bottom`) as opposed
@@ -25,3 +26,39 @@ export function dampenValue(v: number): number {
 export function getDrawerWrapper(): HTMLElement | null {
   return document.querySelector<HTMLElement>('[data-drawer-wrapper]');
 }
+
+/**
+ * The background-scale factor for a given window width (the stacked-card look
+ * leaves {@link WINDOW_TOP_OFFSET}px of the page peeking out).
+ */
+export function getScaleFactor(windowWidth: number): number {
+  return (windowWidth - WINDOW_TOP_OFFSET) / windowWidth;
+}
+
+/**
+ * A GPU-friendly translate along an axis, from a pre-resolved axis flag — the
+ * drag hot path variant: no direction-string comparisons per frame.
+ */
+export function translateAxis(vertical: boolean, value: number): string {
+  return vertical
+    ? `translate3d(0, ${value}px, 0)`
+    : `translate3d(${value}px, 0, 0)`;
+}
+
+/**
+ * {@link translateAxis} keyed by direction, for cold paths that hold the
+ * direction string rather than a gesture snapshot.
+ */
+export function translate3d(direction: DrawerDirection, value: number): string {
+  return translateAxis(isVertical(direction), value);
+}
+
+/**
+ * Per-frame single-property transform write for the drag hot path. Unlike
+ * `setStyle` this allocates nothing (no patch object, no `Object.entries`, no
+ * restore snapshot) — restoration is handled wholesale on release.
+ */
+export function writeTransform(element: HTMLElement | undefined | null, value: string): void {
+  if (element)
+    element.style.transform = value;
+}

vue/primitives/src/overlays/drawer/index.ts

@@ -3,11 +3,15 @@ export { default as DrawerRootNested } from './DrawerRootNested.vue';
 export { default as DrawerContent } from './DrawerContent.vue';
 export { default as DrawerOverlay } from './DrawerOverlay.vue';
 export { default as DrawerHandle } from './DrawerHandle.vue';
+export { default as DrawerTrigger } from './DrawerTrigger.vue';
+export { default as DrawerClose } from './DrawerClose.vue';
 
 export type { DrawerRootEmits, DrawerRootProps, DrawerHandleProps } from './controls';
 export type { DrawerContentEmits, DrawerContentProps } from './DrawerContent.vue';
 export type { DrawerOverlayProps } from './DrawerOverlay.vue';
-export type { DrawerDirection, SnapPoint } from './types';
+export type { DrawerTriggerProps } from './DrawerTrigger.vue';
+export type { DrawerCloseProps } from './DrawerClose.vue';
+export type { DrawerDirection, DrawerOpenChangeDetails, DrawerOpenChangeReason } from './types';
 
 export { injectDrawerRootContext, provideDrawerRootContext } from './context';
 export type { DrawerRootContext } from './context';
@@ -15,17 +19,13 @@ export type { DrawerRootContext } from './context';
 // Parts with no drawer-specific behaviour reuse Dialog directly, re-exported
 // under Drawer names so consumers stay within one namespace.
 export {
-  DialogClose as DrawerClose,
   DialogDescription as DrawerDescription,
   DialogPortal as DrawerPortal,
   DialogTitle as DrawerTitle,
-  DialogTrigger as DrawerTrigger,
 } from '../dialog';
 
 export type {
-  DialogCloseProps as DrawerCloseProps,
   DialogDescriptionProps as DrawerDescriptionProps,
   DialogPortalProps as DrawerPortalProps,
   DialogTitleProps as DrawerTitleProps,
-  DialogTriggerProps as DrawerTriggerProps,
 } from '../dialog';

vue/primitives/src/overlays/drawer/snapping.ts

@@ -0,0 +1,184 @@
+import { clamp } from '@robonen/stdlib';
+import type { DrawerDirection } from './types';
+import { MAX_SNAP_VELOCITY, SNAP_VELOCITY_MULTIPLIER, SNAP_VELOCITY_THRESHOLD } from './constants';
+
+const PX_RE = /^-?(?:\d+(?:\.\d+)?|\.\d+)px$/;
+const REM_RE = /^-?(?:\d+(?:\.\d+)?|\.\d+)rem$/;
+
+/**
+ * Resolve a snap point to the visible size (px) it gives the drawer along the
+ * drag axis:
+ * - a number in (0, 1] is a fraction of the window dimension;
+ * - a number above 1 is pixels;
+ * - `'Npx'` / `'Nrem'` strings are pixels (rem scaled by the root font size).
+ *
+ * Unknown units (`'50%'`, `'10vh'`) and non-finite/non-positive results are
+ * unsupported and resolve to `null` so they never reach the geometry as `NaN`.
+ */
+export function resolveSnapPointSize(
+  point: number | string,
+  windowSize: number,
+  rootFontSize: number,
+): number | null {
+  let size: number | null = null;
+
+  if (typeof point === 'number')
+    size = point > 1 ? point : point * windowSize;
+  else if (PX_RE.test(point))
+    size = Number.parseFloat(point);
+  else if (REM_RE.test(point))
+    size = Number.parseFloat(point) * rootFontSize;
+
+  if (size === null || !Number.isFinite(size) || size <= 0)
+    return null;
+
+  return Math.round(size);
+}
+
+/**
+ * The inline translate (px, signed the way the drawer's transform is written)
+ * that shows exactly `point` worth of the drawer: positive toward the
+ * bottom/right edge, negative toward the top/left edge, clamped so a snap point
+ * larger than the window rests at fully open. Unresolvable points map to `NaN`
+ * — callers must `Number.isFinite`-guard before using an offset.
+ */
+export function resolveSnapPointOffset(
+  point: number | string,
+  direction: DrawerDirection,
+  windowSize: number,
+  rootFontSize: number,
+): number {
+  const size = resolveSnapPointSize(point, windowSize, rootFontSize);
+
+  if (size === null)
+    return Number.NaN;
+
+  const distance = Math.max(Math.round(windowSize - size), 0);
+
+  return direction === 'bottom' || direction === 'right' ? distance : -distance;
+}
+
+/**
+ * Index of the active snap point: matched by identity first, then by resolved
+ * size within a 1px tolerance, so a controlled drawer may use interchangeable
+ * representations (`0.5` vs `'360px'` on a 720px window). Returns `null` when
+ * nothing matches.
+ */
+export function findSnapPointIndex(
+  snapPoints: Array<number | string>,
+  active: number | string | null | undefined,
+  windowSize: number,
+  rootFontSize: number,
+): number | null {
+  if (active === null || active === undefined)
+    return null;
+
+  const byIdentity = snapPoints.indexOf(active);
+
+  if (byIdentity !== -1)
+    return byIdentity;
+
+  const activeSize = resolveSnapPointSize(active, windowSize, rootFontSize);
+
+  if (activeSize === null)
+    return null;
+
+  const bySize = snapPoints.findIndex((point) => {
+    const size = resolveSnapPointSize(point, windowSize, rootFontSize);
+    return size !== null && Math.abs(size - activeSize) <= 1;
+  });
+
+  return bySize === -1 ? null : bySize;
+}
+
+export interface SnapReleaseInput {
+  /**
+   * Snap offsets in dismiss-positive space: 0 is fully open, larger is more
+   * hidden. `NaN` entries (unresolvable points) are skipped.
+   */
+  offsets: number[];
+  activeIndex: number | null;
+  /** Drag distance since press, positive toward open/expand. */
+  draggedDistance: number;
+  /** Instantaneous release velocity, positive toward dismiss (px/ms). */
+  velocity: number;
+  /** Drawer size (px) along the drag axis — the fully-closed offset. */
+  drawerSize: number;
+  dismissible: boolean;
+  /** Step at most one snap point per gesture instead of jumping to the nearest. */
+  sequential: boolean;
+}
+
+export type SnapReleaseResult = { type: 'close' } | { type: 'snap'; index: number };
+
+/**
+ * Where a snap-point drawer settles on release: the drag target is projected
+ * ahead along the release velocity (a fling crosses points a slow drag would
+ * not), then the nearest snap point wins — or the drawer closes when the
+ * projection lands strictly closer to fully-closed and the drawer is
+ * dismissible. In `sequential` mode the result is clamped to the snap point
+ * adjacent to the active one.
+ */
+export function projectSnapRelease(input: SnapReleaseInput): SnapReleaseResult {
+  const { offsets, activeIndex, draggedDistance, velocity, drawerSize, dismissible, sequential } = input;
+
+  const active = activeIndex !== null && Number.isFinite(offsets[activeIndex])
+    ? offsets[activeIndex]
+    : 0;
+
+  // Where the drag alone left the drawer, clamped to its travel range.
+  const dragTarget = clamp(active - draggedDistance, 0, drawerSize);
+
+  let target = dragTarget;
+
+  if (Math.abs(velocity) >= SNAP_VELOCITY_THRESHOLD)
+    target = dragTarget + clamp(velocity, -MAX_SNAP_VELOCITY, MAX_SNAP_VELOCITY) * SNAP_VELOCITY_MULTIPLIER;
+
+  let closestIndex = -1;
+  let closestDistance = Number.POSITIVE_INFINITY;
+
+  for (const [index, offset] of offsets.entries()) {
+    if (!Number.isFinite(offset))
+      continue;
+
+    const distance = Math.abs(target - offset);
+
+    if (distance < closestDistance) {
+      closestIndex = index;
+      closestDistance = distance;
+    }
+  }
+
+  if (closestIndex === -1)
+    return { type: 'snap', index: activeIndex ?? 0 };
+
+  if (dismissible && Math.abs(target - drawerSize) < closestDistance)
+    return { type: 'close' };
+
+  if (!sequential || activeIndex === null)
+    return { type: 'snap', index: closestIndex };
+
+  // Sequential mode: rank the usable points by offset and move at most one
+  // step toward the drag; a fast fling or a physical crossing of the adjacent
+  // point advances, anything else stays.
+  const stepDirection = Math.sign(dragTarget - active);
+
+  if (stepDirection === 0)
+    return { type: 'snap', index: activeIndex };
+
+  const order = offsets
+    .map((offset, index) => ({ offset, index }))
+    .filter(entry => Number.isFinite(entry.offset))
+    .sort((a, b) => a.offset - b.offset);
+
+  const rank = order.findIndex(entry => entry.index === activeIndex);
+
+  if (rank === -1)
+    return { type: 'snap', index: closestIndex };
+
+  const adjacent = order[clamp(rank + stepDirection, 0, order.length - 1)];
+  const flungPast = Math.sign(velocity) === stepDirection && Math.abs(velocity) >= SNAP_VELOCITY_THRESHOLD;
+  const crossed = stepDirection > 0 ? target > adjacent.offset : target < adjacent.offset;
+
+  return { type: 'snap', index: flungPast || crossed ? adjacent.index : activeIndex };
+}

vue/primitives/src/overlays/drawer/style.ts

@@ -8,7 +8,35 @@
  * The selectors here mirror the `data-drawer-*` attributes set in the component
  * templates and {@link ./controls} — keep them in sync.
  */
-export const DRAWER_STYLE_ID = 'robonen-drawer';
+export const DRAWER_STYLE_ID = 'drawer';
+
+let cssPropertiesRegistered = false;
+
+/**
+ * Registers the drawer's animated custom properties with `inherits: false`, so
+ * a per-frame write of `--snap-point-height` on the content invalidates only
+ * that element instead of cascading a var recompute over its whole subtree.
+ * `--initial-transform` is deliberately NOT registered: consumers may set it on
+ * an ancestor and rely on inheritance. No-op where the API is missing.
+ */
+export function registerDrawerCssProperties(): void {
+  if (cssPropertiesRegistered || typeof CSS === 'undefined' || !CSS.registerProperty)
+    return;
+
+  cssPropertiesRegistered = true;
+
+  try {
+    CSS.registerProperty({
+      name: '--snap-point-height',
+      syntax: '<length>',
+      inherits: false,
+      initialValue: '0px',
+    });
+  }
+  catch {
+    // Older engines without @property support simply keep var inheritance.
+  }
+}
 
 export const DRAWER_STYLES = `
 [data-drawer] {

vue/primitives/src/overlays/drawer/types.ts

@@ -4,10 +4,25 @@
 export type DrawerDirection = 'top' | 'bottom' | 'left' | 'right';
 
 /**
- * A resolved snap point: the original `fraction` (0–1 of the screen, or a raw
- * px value) paired with its computed pixel `height`.
+ * Lifecycle phase of the drawer. `opening`/`closing` last for the duration of
+ * the enter/exit animation; the settle signal (animation end or its fallback
+ * timeout) advances them to `open`/`closed`.
  */
-export interface SnapPoint {
-  fraction: number;
-  height: number;
+export type DrawerPhase = 'closed' | 'opening' | 'open' | 'closing';
+
+/**
+ * What flipped the drawer's open state. Absent details mean a programmatic
+ * change (a controlled `v-model:open` write).
+ */
+export type DrawerOpenChangeReason
+  = | 'swipe'
+    | 'escape-key'
+    | 'outside-press'
+    | 'trigger-press'
+    | 'close-press'
+    | 'handle-press';
+
+/** Extra context attached to `update:open`. */
+export interface DrawerOpenChangeDetails {
+  reason?: DrawerOpenChangeReason;
 }

vue/primitives/src/overlays/drawer/usePositionFixed.ts

@@ -79,7 +79,7 @@ export function usePositionFixed(options: PositionFixedOptions) {
 
       Object.assign(document.body.style, previousBodyPosition);
 
-      globalThis.requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
         if (preventScrollRestoration.value && activeUrl.value !== globalThis.location.href) {
           activeUrl.value = globalThis.location.href;
           return;

vue/primitives/src/overlays/drawer/useScaleBackground.ts

@@ -2,8 +2,8 @@ import { onWatcherCleanup, ref, watchEffect } from 'vue';
 import { isClient } from '@robonen/platform/multi';
 import { assignStyle } from '@robonen/platform/browsers';
 import { injectDrawerRootContext } from './context';
-import { getDrawerWrapper, isVertical } from './helpers';
-import { BORDER_RADIUS, TRANSITIONS, WINDOW_TOP_OFFSET } from './constants';
+import { getDrawerWrapper, getScaleFactor, isVertical } from './helpers';
+import { BORDER_RADIUS, TRANSITIONS } from './constants';
 
 /**
  * Scales the page background down behind the drawer (the stacked-card effect),
@@ -16,10 +16,6 @@ export function useScaleBackground() {
   const timeoutIdRef = ref<number | null>(null);
   const initialBackgroundColor = ref(typeof document !== 'undefined' ? document.body.style.backgroundColor : '');
 
-  function getScale() {
-    return (window.innerWidth - WINDOW_TOP_OFFSET) / window.innerWidth;
-  }
-
   watchEffect(() => {
     // `flush: 'pre'` watchers run during SSR; this effect touches document/window,
     // so it must stay client-only.
@@ -42,17 +38,18 @@ export function useScaleBackground() {
         transitionTimingFunction: `cubic-bezier(${TRANSITIONS.EASE.join(',')})`,
       });
 
+      const scale = getScaleFactor(window.innerWidth);
       const wrapperStylesCleanup = assignStyle(wrapper, {
         borderRadius: `${BORDER_RADIUS}px`,
         overflow: 'hidden',
         ...(isVertical(direction.value)
-          ? { transform: `scale(${getScale()}) translate3d(0, calc(env(safe-area-inset-top) + 14px), 0)` }
-          : { transform: `scale(${getScale()}) translate3d(calc(env(safe-area-inset-top) + 14px), 0, 0)` }),
+          ? { transform: `scale(${scale}) translate3d(0, calc(env(safe-area-inset-top) + 14px), 0)` }
+          : { transform: `scale(${scale}) translate3d(calc(env(safe-area-inset-top) + 14px), 0, 0)` }),
       });
 
       onWatcherCleanup(() => {
         wrapperStylesCleanup();
-        timeoutIdRef.value = globalThis.setTimeout(() => {
+        timeoutIdRef.value = setTimeout(() => {
           if (initialBackgroundColor.value)
             document.body.style.background = initialBackgroundColor.value;
           else

vue/primitives/src/overlays/drawer/useSnapPoints.ts

@@ -1,9 +1,10 @@
 import type { Ref } from 'vue';
-import { computed, nextTick, ref, watch } from 'vue';
+import { computed, nextTick, watch } from 'vue';
 import { setStyle } from '@robonen/platform/browsers';
-import { useEventListener } from '@robonen/vue';
-import { isVertical } from './helpers';
-import { TRANSITIONS, VELOCITY_THRESHOLD } from './constants';
+import { isVertical, translateAxis, writeTransform } from './helpers';
+import { TRANSITIONS } from './constants';
+import { computeSettleDuration } from './gesture';
+import { findSnapPointIndex, projectSnapRelease, resolveSnapPointOffset } from './snapping';
 import type { DrawerDirection } from './types';
 
 interface UseSnapPointsProps {
@@ -14,16 +15,23 @@ interface UseSnapPointsProps {
   overlayRef: Ref<HTMLElement | undefined>;
   onSnapPointChange: (activeSnapPointIndex: number, snapPointsOffset: number[]) => void;
   direction: Ref<DrawerDirection>;
+  snapToSequentialPoints: Ref<boolean>;
+  /** Shared reactive window dimensions (from the engine's `useWindowSize`). */
+  windowWidth: Ref<number>;
+  windowHeight: Ref<number>;
 }
 
-const transition = (property: 'transform' | 'opacity') =>
-  `${property} ${TRANSITIONS.DURATION}s cubic-bezier(${TRANSITIONS.EASE.join(',')})`;
+const transition = (property: 'transform' | 'opacity', duration: number = TRANSITIONS.DURATION) =>
+  `${property} ${duration}s cubic-bezier(${TRANSITIONS.EASE.join(',')})`;
+
+function readRootFontSize(): number {
+  return Number.parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
+}
 
 /**
  * Drag/release maths for drawers configured with snap points: resolves each
- * snap point to a pixel offset, animates the drawer between them, and decides
- * which point to settle on (or whether to close) based on drag distance and
- * velocity.
+ * snap point to a pixel offset, animates the drawer between them, and settles
+ * on release by projecting the drag target along the fling velocity.
  */
 export function useSnapPoints({
   activeSnapPoint,
@@ -33,26 +41,64 @@ export function useSnapPoints({
   fadeFromIndex,
   onSnapPointChange,
   direction,
+  snapToSequentialPoints,
+  windowWidth,
+  windowHeight,
 }: UseSnapPointsProps) {
-  const windowDimensions = ref(globalThis.window !== undefined
-    ? { innerWidth: window.innerWidth, innerHeight: window.innerHeight }
-    : undefined);
+  // Direction resolved once per change instead of string-comparing per move.
+  const verticalAxis = computed(() => isVertical(direction.value));
+  const dismissMultiplier = computed<1 | -1>(() =>
+    direction.value === 'bottom' || direction.value === 'right' ? 1 : -1,
+  );
 
-  function onResize() {
-    const innerWidth = window.innerWidth;
-    const innerHeight = window.innerHeight;
-    const cur = windowDimensions.value;
-    // Skip the ref write (and the snapPointsOffset recompute it would trigger)
-    // when dimensions are unchanged — some resize events report identical sizes.
-    if (!cur || cur.innerWidth !== innerWidth || cur.innerHeight !== innerHeight)
-      windowDimensions.value = { innerWidth, innerHeight };
+  function windowSizeFor(dir: DrawerDirection): number {
+    return isVertical(dir) ? windowHeight.value : windowWidth.value;
   }
 
-  // Defaults to `defaultWindow` (SSR-safe) and auto-removes on scope dispose.
-  useEventListener('resize', onResize);
+  let warnedInvalid = false;
+
+  /**
+   * Inline-translate offsets, index-aligned with `snapPoints` (identity such as
+   * `fadeFromIndex` is preserved). Unresolvable points map to `NaN` and are
+   * excluded from every settle decision.
+   */
+  const snapPointsOffset = computed<number[]>(() => {
+    const points = snapPoints.value;
+
+    if (!points)
+      return [];
+
+    const windowSize = windowSizeFor(direction.value);
+    const rootFontSize = globalThis.document !== undefined ? readRootFontSize() : 16;
+    const offsets = points.map(point => resolveSnapPointOffset(point, direction.value, windowSize, rootFontSize));
+
+    if (!warnedInvalid && offsets.some(offset => !Number.isFinite(offset))) {
+      warnedInvalid = true;
+      console.warn(
+        '[Drawer] Unsupported snap point value. Use a fraction (0-1), a px number, or a px/rem string:',
+        points.filter((_, index) => !Number.isFinite(offsets[index])),
+      );
+    }
+
+    return offsets;
+  });
+
+  const activeSnapPointIndex = computed<number | null>(() => {
+    const points = snapPoints.value;
+
+    if (!points)
+      return null;
+
+    const windowSize = windowSizeFor(direction.value);
+    const rootFontSize = globalThis.document !== undefined ? readRootFontSize() : 16;
+
+    // Identity first, then resolved-size equivalence (`0.5` vs `'360px'`) so a
+    // controlled active point in a different representation still matches.
+    return findSnapPointIndex(points, activeSnapPoint.value, windowSize, rootFontSize);
+  });
 
   const isLastSnapPoint = computed(
-    () => (snapPoints.value && activeSnapPoint.value === snapPoints.value[snapPoints.value.length - 1]) ?? null,
+    () => (snapPoints.value && activeSnapPointIndex.value === snapPoints.value.length - 1) ?? null,
   );
 
   const shouldFade = computed(
@@ -65,58 +111,25 @@ export function useSnapPoints({
       || !snapPoints.value,
   );
 
-  const activeSnapPointIndex = computed(
-    () => snapPoints.value?.indexOf(activeSnapPoint.value) ?? null,
-  );
-
-  const snapPointsOffset = computed(
-    () =>
-      snapPoints.value?.map((snapPoint) => {
-        const isPx = typeof snapPoint === 'string';
-        let snapPointAsNumber = 0;
-
-        if (isPx)
-          snapPointAsNumber = Number.parseInt(snapPoint, 10);
-
-        if (isVertical(direction.value)) {
-          const height = isPx
-            ? snapPointAsNumber
-            : windowDimensions.value
-              ? (snapPoint as number) * windowDimensions.value.innerHeight
-              : 0;
-
-          if (windowDimensions.value)
-            return direction.value === 'bottom' ? windowDimensions.value.innerHeight - height : -windowDimensions.value.innerHeight + height;
-
-          return height;
-        }
-
-        const width = isPx
-          ? snapPointAsNumber
-          : windowDimensions.value
-            ? (snapPoint as number) * windowDimensions.value.innerWidth
-            : 0;
-
-        if (windowDimensions.value)
-          return direction.value === 'right' ? windowDimensions.value.innerWidth - width : -windowDimensions.value.innerWidth + width;
-
-        return width;
-      }) ?? [],
-  );
-
   const activeSnapPointOffset = computed(() =>
     activeSnapPointIndex.value !== null ? snapPointsOffset.value?.[activeSnapPointIndex.value] : null,
   );
 
-  function snapToPoint(dimension: number) {
+  function snapToPoint(dimension: number, options?: { velocity?: number; from?: number | null }) {
+    if (!Number.isFinite(dimension))
+      return;
+
     const newSnapPointIndex = snapPointsOffset.value?.indexOf(dimension) ?? null;
+    const from = options?.from;
+    const remaining = typeof from === 'number' ? Math.abs(dimension - from) : Number.NaN;
+    const duration = computeSettleDuration(remaining, options?.velocity ?? 0);
 
     // Wait for the element to be mounted before transforming it.
     nextTick(() => {
       onSnapPointChange(newSnapPointIndex, snapPointsOffset.value);
       setStyle(drawerRef.value, {
-        transition: transition('transform'),
-        transform: isVertical(direction.value) ? `translate3d(0, ${dimension}px, 0)` : `translate3d(${dimension}px, 0, 0)`,
+        transition: transition('transform', duration),
+        transform: translateAxis(verticalAxis.value, dimension),
       });
     });
 
@@ -125,22 +138,30 @@ export function useSnapPoints({
       && newSnapPointIndex !== snapPointsOffset.value.length - 1
       && newSnapPointIndex !== fadeFromIndex?.value
     ) {
-      setStyle(overlayRef.value, { transition: transition('opacity'), opacity: '0' });
+      setStyle(overlayRef.value, { transition: transition('opacity', duration), opacity: '0' });
     }
     else {
-      setStyle(overlayRef.value, { transition: transition('opacity'), opacity: '1' });
+      setStyle(overlayRef.value, { transition: transition('opacity', duration), opacity: '1' });
     }
 
     activeSnapPoint.value = newSnapPointIndex !== null ? snapPoints.value?.[newSnapPointIndex] ?? null : null;
   }
 
+  /** Settle back onto the active snap point (used when a gesture is aborted). */
+  function restoreActiveSnapPoint() {
+    const offset = activeSnapPointOffset.value;
+
+    if (typeof offset === 'number' && Number.isFinite(offset))
+      snapToPoint(offset);
+  }
+
   watch(
     [activeSnapPoint, snapPointsOffset, snapPoints],
     () => {
       if (activeSnapPoint.value) {
-        const newIndex = snapPoints.value?.indexOf(activeSnapPoint.value) ?? -1;
+        const newIndex = activeSnapPointIndex.value ?? -1;
 
-        if (snapPointsOffset.value && newIndex !== -1 && typeof snapPointsOffset.value[newIndex] === 'number')
+        if (snapPointsOffset.value && newIndex !== -1 && Number.isFinite(snapPointsOffset.value[newIndex]))
           snapToPoint(snapPointsOffset.value[newIndex]);
       }
     },
@@ -152,89 +173,66 @@ export function useSnapPoints({
     closeDrawer,
     velocity,
     dismissible,
+    drawerSize,
   }: {
+    /** Drag distance since press, positive toward open/expand. */
     draggedDistance: number;
     closeDrawer: () => void;
+    /** Instantaneous release velocity, positive toward dismiss (px/ms). */
     velocity: number;
     dismissible: boolean;
+    /** Drawer size (px) along the drag axis. */
+    drawerSize: number;
   }) {
     if (fadeFromIndex.value === undefined)
       return;
 
-    const currentPosition
-      = direction.value === 'bottom' || direction.value === 'right'
-        ? (activeSnapPointOffset.value ?? 0) - draggedDistance
-        : (activeSnapPointOffset.value ?? 0) + draggedDistance;
+    const multiplier = dismissMultiplier.value;
+    const offsets = snapPointsOffset.value.map(offset => offset * multiplier);
     const isOverlaySnapPoint = activeSnapPointIndex.value === fadeFromIndex.value - 1;
-    const isFirst = activeSnapPointIndex.value === 0;
-    const hasDraggedUp = draggedDistance > 0;
 
     if (isOverlaySnapPoint)
       setStyle(overlayRef.value, { transition: transition('opacity') });
 
-    if (velocity > 2 && !hasDraggedUp) {
-      if (dismissible)
-        closeDrawer();
-      else
-        snapToPoint(snapPointsOffset.value[0]); // snap to initial point
-      return;
-    }
-
-    if (velocity > 2 && hasDraggedUp && snapPointsOffset.value && snapPoints.value) {
-      snapToPoint(snapPointsOffset.value[snapPoints.value.length - 1]);
-      return;
-    }
-
-    // Settle on the snap point closest to where the drag ended.
-    const closestSnapPoint = snapPointsOffset.value?.reduce((prev, curr) => {
-      if (typeof prev !== 'number' || typeof curr !== 'number')
-        return prev;
-
-      return Math.abs(curr - currentPosition) < Math.abs(prev - currentPosition) ? curr : prev;
+    const result = projectSnapRelease({
+      offsets,
+      activeIndex: activeSnapPointIndex.value,
+      draggedDistance,
+      velocity,
+      drawerSize,
+      dismissible,
+      sequential: snapToSequentialPoints.value,
     });
 
-    const dim = isVertical(direction.value) ? window.innerHeight : window.innerWidth;
-    if (velocity > VELOCITY_THRESHOLD && Math.abs(draggedDistance) < dim * 0.4) {
-      const dragDirection = hasDraggedUp ? 1 : -1; // 1 = up, -1 = down
-
-      // Ignore an upward flick while already on the last snap point.
-      if (dragDirection > 0 && isLastSnapPoint.value) {
-        snapToPoint(snapPointsOffset.value[(snapPoints.value?.length ?? 0) - 1]);
-        return;
-      }
-
-      if (isFirst && dragDirection < 0 && dismissible)
-        closeDrawer();
-
-      if (activeSnapPointIndex.value === null)
-        return;
-
-      snapToPoint(snapPointsOffset.value[activeSnapPointIndex.value + dragDirection]);
+    if (result.type === 'close') {
+      closeDrawer();
       return;
     }
 
-    snapToPoint(closestSnapPoint);
+    const target = snapPointsOffset.value[result.index];
+    const from = (activeSnapPointOffset.value ?? 0) - draggedDistance * multiplier;
+
+    snapToPoint(target, { velocity, from });
   }
 
-  function onDrag({ draggedDistance }: { draggedDistance: number }) {
-    if (activeSnapPointOffset.value === null)
-      return;
+  function onDrag({ draggedDistance }: { draggedDistance: number }): number | null {
+    const activeOffset = activeSnapPointOffset.value;
 
-    const newValue
-      = direction.value === 'bottom' || direction.value === 'right'
-        ? (activeSnapPointOffset.value ?? 0) - draggedDistance
-        : (activeSnapPointOffset.value ?? 0) + draggedDistance;
+    if (activeOffset === null || activeOffset === undefined || !Number.isFinite(activeOffset))
+      return null;
+
+    const positive = dismissMultiplier.value === 1;
+    const newValue = positive ? activeOffset - draggedDistance : activeOffset + draggedDistance;
+    const offsets = snapPointsOffset.value;
+    const lastOffset = offsets[offsets.length - 1];
 
     // Don't drag past the last (largest) snap point.
-    if ((direction.value === 'bottom' || direction.value === 'right') && newValue < snapPointsOffset.value[snapPointsOffset.value.length - 1])
-      return;
+    if (Number.isFinite(lastOffset) && (positive ? newValue < lastOffset : newValue > lastOffset))
+      return null;
 
-    if ((direction.value === 'top' || direction.value === 'left') && newValue > snapPointsOffset.value[snapPointsOffset.value.length - 1])
-      return;
+    writeTransform(drawerRef.value, translateAxis(verticalAxis.value, newValue));
 
-    setStyle(drawerRef.value, {
-      transform: isVertical(direction.value) ? `translate3d(0, ${newValue}px, 0)` : `translate3d(${newValue}px, 0, 0)`,
-    });
+    return newValue;
   }
 
   function getPercentageDragged(absDraggedDistance: number, isDraggingDown: boolean) {
@@ -278,6 +276,7 @@ export function useSnapPoints({
     activeSnapPointIndex,
     onRelease,
     onDrag,
+    restoreActiveSnapPoint,
     snapPointsOffset,
   };
 }

vue/stories/package.json

@@ -19,12 +19,12 @@
   "devDependencies": {
     "@robonen/eslint": "workspace:*",
     "@robonen/tsconfig": "workspace:*",
-    "@storybook/addon-a11y": "^10.4.6",
-    "@storybook/addon-docs": "^10.4.6",
-    "@storybook/vue3-vite": "^10.4.6",
-    "@vitejs/plugin-vue": "^6.0.7",
+    "@storybook/addon-a11y": "^10.5.5",
+    "@storybook/addon-docs": "^10.5.5",
+    "@storybook/vue3-vite": "^10.5.5",
+    "@vitejs/plugin-vue": "^6.0.8",
     "eslint": "catalog:",
-    "storybook": "^10.4.6",
-    "vite": "^8.0.16"
+    "storybook": "^10.5.5",
+    "vite": "^8.1.5"
   }
 }

vue/toolkit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robonen/vue",
-  "version": "0.0.14",
+  "version": "0.2.0",
   "license": "Apache-2.0",
   "description": "Collection of powerful tools for Vue",
   "keywords": [
@@ -16,7 +16,7 @@
     "url": "git+https://github.com/robonen/tools.git",
     "directory": "vue/toolkit"
   },
-  "packageManager": "pnpm@11.7.0",
+  "packageManager": "pnpm@11.18.0",
   "engines": {
     "node": ">=24.16.0"
   },

vue/toolkit/src/composables/component/useVirtualList/demo.vue

@@ -2,45 +2,84 @@
 import { computed, ref, shallowRef } from 'vue';
 import { useVirtualList } from './index';
 
-// 10,000 rows — only the visible window (plus overscan) is ever in the DOM.
-const total = 10000;
-const items = shallowRef(
-  Array.from({ length: total }, (_, i) => ({
-    id: i,
-    label: `Row #${(i + 1).toString().padStart(5, '0')}`,
-    hue: (i * 37) % 360,
-  })),
-);
+interface Message {
+  id: number;
+  author: string;
+  text: string;
+  expanded: boolean;
+}
 
-const itemHeight = 44;
+const WORDS = 'virtual scrolling keeps the DOM small while the list pretends to be infinite and every row is free to size itself'.split(' ');
 
-const { list, containerProps, wrapperProps, scrollTo } = useVirtualList(items, {
-  itemHeight,
+let nextId = 0;
+function makeMessage(): Message {
+  const id = nextId++;
+  const length = 4 + (id * 31) % 60; // deterministic variable length
+  const text = Array.from({ length }, (_, i) => WORDS[(id + i) % WORDS.length]).join(' ');
+  return { id, author: `user-${id % 7}`, text, expanded: false };
+}
+
+function makeMessages(count: number): Message[] {
+  return Array.from({ length: count }, makeMessage);
+}
+
+const messages = shallowRef<Message[]>(makeMessages(10000));
+
+const CHARS_PER_LINE = 58; // calibrated against the docs demo card width
+
+const { list, containerProps, wrapperProps, scrollTo, isScrolling } = useVirtualList(messages, {
+  // Rows are genuinely variable (1–2 clamped lines collapsed, full text
+  // expanded), so the estimate is data-driven. It only has to be close, not
+  // exact — measured sizes replace it per row and are cached by key. What
+  // hurts is *systematic* error: a big overestimate makes every revealed row
+  // shrink on measure, and anchoring then fights the scroll.
+  estimateSize: message => 37 + Math.min(2, Math.ceil(message.text.length / CHARS_PER_LINE)) * 20,
+  getItemKey: message => message.id, // measurements survive prepend/reorder
+  followOutput: true, // pinned to the newest message when the user is at the end
   overscan: 6,
+  gap: 6,
+  paddingStart: 8,
+  paddingEnd: 8,
 });
 
+function prepend() {
+  // Immutable update: getItemKey keeps measurements attached to the right
+  // messages and scroll anchoring keeps the viewport visually still.
+  messages.value = [...makeMessages(20), ...messages.value];
+}
+
+function append() {
+  // With followOutput the view stays glued to the end if the user is there.
+  messages.value = [...messages.value, ...makeMessages(5)];
+}
+
+function toggle(message: Message) {
+  messages.value = messages.value.map(current =>
+    current === message ? { ...current, expanded: !current.expanded } : current,
+  );
+  // No manual remeasure: the row's ResizeObserver sees the new height
+  // before paint and the layout shifts without flicker.
+}
+
 const jumpTo = ref(5000);
 
 function go() {
-  const index = Math.min(Math.max(jumpTo.value || 0, 0), total - 1);
-  scrollTo(index, { behavior: 'smooth', block: 'center' });
+  scrollTo(jumpTo.value || 0, { align: 'center' });
 }
 
 const visibleRange = computed(() => {
   if (list.value.length === 0)
     return '—';
-  const first = list.value[0]!.index;
-  const last = list.value[list.value.length - 1]!.index;
-  return `${first}–${last}`;
+  return `${list.value[0]!.index}–${list.value[list.value.length - 1]!.index}`;
 });
 </script>
 
 <template>
   <div class="demo-stack max-w-sm">
     <div class="flex items-center justify-between">
-      <span class="demo-label">Virtual list</span>
+      <span class="demo-label">Dynamic virtual list</span>
       <span class="demo-badge">
-        {{ total.toLocaleString() }} rows
+        {{ messages.length.toLocaleString() }} rows
       </span>
     </div>
 
@@ -49,25 +88,32 @@ const visibleRange = computed(() => {
       class="demo-card h-64"
     >
       <div v-bind="wrapperProps">
-        <div
-          v-for="{ data, index } in list"
-          :key="index"
-          class="flex items-center gap-3 border-b border-border px-3"
-          :style="{ height: `${itemHeight}px` }"
+        <article
+          v-for="item in list"
+          :key="item.key"
+          v-bind="item.props"
+          class="cursor-pointer border-b border-border px-3 py-2"
+          @click="toggle(item.data)"
         >
-          <span
-            class="size-6 shrink-0 rounded-md border border-border"
-            :style="{ backgroundColor: `hsl(${data.hue} 65% 55%)` }"
-          />
-          <span class="flex-1 truncate font-mono text-sm text-fg tabular-nums">{{ data.label }}</span>
-          <span class="text-xs text-fg-subtle">idx {{ index }}</span>
-        </div>
+          <div class="flex items-baseline justify-between gap-2">
+            <span class="font-mono text-xs text-fg-subtle">{{ item.data.author }}</span>
+            <span class="text-xs text-fg-subtle tabular-nums">#{{ item.index }}</span>
+          </div>
+          <!-- natural height: collapsed rows clamp to two lines (still variable),
+               expanded rows grow to the full text -->
+          <p
+            class="mt-1 text-sm text-fg"
+            :class="item.data.expanded ? '' : 'line-clamp-2'"
+          >
+            {{ item.data.text }}
+          </p>
+        </article>
       </div>
     </div>
 
     <div class="rounded-lg border border-border bg-bg-inset p-3 font-mono text-sm text-fg tabular-nums flex items-center justify-between">
       <span class="text-fg-muted">rendered</span>
-      <span>{{ list.length }} nodes · idx {{ visibleRange }}</span>
+      <span>{{ list.length }} nodes · idx {{ visibleRange }}<span v-if="isScrolling"> · scrolling</span></span>
     </div>
 
     <div class="flex items-end gap-2">
@@ -77,7 +123,7 @@ const visibleRange = computed(() => {
           v-model.number="jumpTo"
           type="number"
           :min="0"
-          :max="total - 1"
+          :max="messages.length - 1"
           class="demo-input"
         >
       </label>
@@ -88,6 +134,20 @@ const visibleRange = computed(() => {
       >
         Jump
       </button>
+      <button
+        type="button"
+        class="inline-flex items-center justify-center gap-1.5 rounded-lg border border-border bg-bg px-3 py-2 text-sm font-medium text-fg transition hover:bg-bg-inset active:scale-[0.98] cursor-pointer"
+        @click="prepend"
+      >
+        Prepend
+      </button>
+      <button
+        type="button"
+        class="inline-flex items-center justify-center gap-1.5 rounded-lg border border-border bg-bg px-3 py-2 text-sm font-medium text-fg transition hover:bg-bg-inset active:scale-[0.98] cursor-pointer"
+        @click="append"
+      >
+        Append
+      </button>
     </div>
   </div>
 </template>

vue/toolkit/src/composables/component/useVirtualList/index.test.ts

@@ -1,35 +1,54 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { effectScope, nextTick, ref } from 'vue';
+import { effectScope, nextTick, shallowRef } from 'vue';
 import { useVirtualList } from '.';
 
+type ObserverRecord = InstanceType<typeof StubResizeObserver>;
+
+const observers: ObserverRecord[] = [];
+
 class StubResizeObserver {
+  callback: ResizeObserverCallback;
   observe = vi.fn();
-  disconnect = vi.fn();
   unobserve = vi.fn();
+  disconnect = vi.fn();
+
+  constructor(callback: ResizeObserverCallback) {
+    this.callback = callback;
+    observers.push(this);
+  }
 }
 
 function makeContainer(overrides: Partial<{
   clientWidth: number;
   clientHeight: number;
-  scrollWidth: number;
-  scrollHeight: number;
 }> = {}) {
   const el = document.createElement('div');
   Object.defineProperties(el, {
     clientWidth: { value: overrides.clientWidth ?? 100, configurable: true },
     clientHeight: { value: overrides.clientHeight ?? 100, configurable: true },
-    scrollWidth: { value: overrides.scrollWidth ?? 10000, configurable: true },
-    scrollHeight: { value: overrides.scrollHeight ?? 10000, configurable: true },
   });
   el.scrollTop = 0;
   el.scrollLeft = 0;
   el.scrollTo = vi.fn((opts: ScrollToOptions) => {
-    if (typeof opts.top === 'number') el.scrollTop = opts.top;
-    if (typeof opts.left === 'number') el.scrollLeft = opts.left;
+    if (typeof opts.top === 'number')
+      el.scrollTop = opts.top;
+    if (typeof opts.left === 'number')
+      el.scrollLeft = opts.left;
   }) as unknown as typeof el.scrollTo;
   return el;
 }
 
+function makeRow(index: number): HTMLElement {
+  const el = document.createElement('div');
+  el.dataset.index = String(index);
+  document.body.appendChild(el);
+  return el;
+}
+
+function resizeEntry(target: Element, blockSize: number, inlineSize = 50): ResizeObserverEntry {
+  return { target, borderBoxSize: [{ blockSize, inlineSize }] } as unknown as ResizeObserverEntry;
+}
+
 function withScope<T>(fn: () => T): { result: T; scope: ReturnType<typeof effectScope> } {
   const scope = effectScope();
   let result!: T;
@@ -41,181 +60,318 @@ function withScope<T>(fn: () => T): { result: T; scope: ReturnType<typeof effect
 
 describe(useVirtualList, () => {
   beforeEach(() => {
+    observers.length = 0;
     vi.stubGlobal('ResizeObserver', StubResizeObserver);
   });
-  afterEach(() => vi.unstubAllGlobals());
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    document.body.innerHTML = '';
+  });
 
-  it('renders an empty window before the container mounts (SSR-safe)', () => {
-    const data = Array.from({ length: 1000 }, (_, i) => i);
-    const { result, scope } = withScope(() => useVirtualList(data, { itemHeight: 20 }));
+  const items = Array.from({ length: 1000 }, (_, i) => ({ id: i }));
 
+  it('renders the initial window from estimates and initialContainerSize', () => {
+    const { result, scope } = withScope(() => useVirtualList(() => items, {
+      estimateSize: 40,
+      initialContainerSize: 200,
+      overscan: 1,
+    }));
+
+    // top=0 → start 0; bottom=200 → lowerBound=5 (5*40 ≤ 200) → end 6 → +overscan
+    expect(result.range.value).toEqual({ start: 0, end: 7 });
+    expect(result.list.value).toHaveLength(7);
+    expect(result.list.value[0]!.start).toBe(0);
+    expect(result.list.value[3]!.start).toBe(120);
+    expect(result.totalSize.value).toBe(1000 * 40);
+    scope.stop();
+  });
+
+  it('applies paddingStart and gap to offsets and totalSize', () => {
+    const { result, scope } = withScope(() => useVirtualList(() => items.slice(0, 10), {
+      estimateSize: 40,
+      gap: 8,
+      paddingStart: 12,
+      paddingEnd: 20,
+      initialContainerSize: 100,
+      overscan: 0,
+    }));
+
+    expect(result.list.value[0]!.start).toBe(12);
+    expect(result.list.value[1]!.start).toBe(12 + 40 + 8);
+    expect(result.totalSize.value).toBe(12 + 10 * 40 + 9 * 8 + 20);
+    scope.stop();
+  });
+
+  it('passes item and index to the estimate function', () => {
+    const estimateSize = vi.fn((item: { id: number }, _index: number) => 10 + item.id);
+    const { result, scope } = withScope(() => useVirtualList(() => items.slice(0, 3), {
+      estimateSize,
+      initialContainerSize: 100,
+    }));
+
+    expect(estimateSize).toHaveBeenCalledWith(items[0], 0);
+    expect(result.totalSize.value).toBe(10 + 11 + 12);
+    scope.stop();
+  });
+
+  it('rebuilds when the source ref is replaced', async () => {
+    const source = shallowRef(items.slice(0, 10));
+    const { result, scope } = withScope(() => useVirtualList(source, {
+      estimateSize: 40,
+      initialContainerSize: 100,
+    }));
+
+    expect(result.totalSize.value).toBe(400);
+
+    source.value = items.slice(0, 3);
+    await nextTick();
+
+    expect(result.totalSize.value).toBe(120);
+    expect(result.range.value.end).toBeLessThanOrEqual(3);
+    scope.stop();
+  });
+
+  it('clamps the range when the source shrinks to empty', async () => {
+    const source = shallowRef(items.slice(0, 10));
+    const { result, scope } = withScope(() => useVirtualList(source, {
+      estimateSize: 40,
+      initialContainerSize: 100,
+    }));
+
+    source.value = [];
+    await nextTick();
+
+    expect(result.range.value).toEqual({ start: 0, end: 0 });
     expect(result.list.value).toEqual([]);
-    expect(result.containerProps.ref.value).toBeNull();
-    expect(result.containerProps.style).toEqual({ overflowY: 'auto' });
+    expect(result.totalSize.value).toBe(0);
     scope.stop();
   });
 
-  it('exposes the documented return shape', () => {
-    const { result, scope } = withScope(() => useVirtualList([1, 2, 3], { itemHeight: 20 }));
+  it('getOffsetForIndex honors align and clamps to content bounds', () => {
+    const { result, scope } = withScope(() => useVirtualList(() => items.slice(0, 100), {
+      estimateSize: 40,
+      initialContainerSize: 200,
+    }));
 
-    expect(result).toHaveProperty('list');
-    expect(result).toHaveProperty('scrollTo');
-    expect(result).toHaveProperty('containerProps');
-    expect(result).toHaveProperty('wrapperProps');
-    expect(typeof result.scrollTo).toBe('function');
-    expect(typeof result.containerProps.onScroll).toBe('function');
+    expect(result.getOffsetForIndex(0, 'start')).toBe(0);
+    expect(result.getOffsetForIndex(50, 'start')).toBe(2000);
+    expect(result.getOffsetForIndex(50, 'center')).toBe(2000 - (200 - 40) / 2);
+    expect(result.getOffsetForIndex(50, 'end')).toBe(2000 - 200 + 40);
+    // clamp: the last item can't be aligned past max scroll
+    expect(result.getOffsetForIndex(99, 'start')).toBe(100 * 40 - 200);
+    // 'auto' on a visible item → keep the current offset
+    expect(result.getOffsetForIndex(1, 'auto')).toBe(0);
     scope.stop();
   });
 
-  it('slices the visible window plus overscan (vertical, fixed height)', async () => {
-    const data = Array.from({ length: 1000 }, (_, i) => i);
+  it('resolves auto-align with nearest-edge semantics for oversized items', () => {
+    // item 50 is taller than the 200px viewport and lies below it
+    const below = withScope(() => useVirtualList(() => items.slice(0, 100), {
+      estimateSize: (_item, index) => index === 50 ? 500 : 40,
+      initialContainerSize: 200,
+    }));
+    // nearest: approaching an oversized item from above aligns its start
+    expect(below.result.getOffsetForIndex(50, 'auto')).toBe(2000);
+    below.scope.stop();
+
+    // item 0 is taller than the viewport and already covers it → no-op
+    const covering = withScope(() => useVirtualList(() => items.slice(0, 100), {
+      estimateSize: (_item, index) => index === 0 ? 500 : 40,
+      initialContainerSize: 200,
+    }));
+    expect(covering.result.getOffsetForIndex(0, 'auto')).toBe(0);
+    covering.scope.stop();
+  });
+
+  it('scrollTo re-syncs a same-tick source replacement synchronously', () => {
+    const source = shallowRef(items.slice(0, 10));
+    const { result, scope } = withScope(() => useVirtualList(source, {
+      estimateSize: 40,
+      initialContainerSize: 200,
+    }));
+
+    expect(result.totalSize.value).toBe(400);
+
+    source.value = items.slice(0, 100);
+    // no nextTick: the canonical "append then scroll to newest" gesture
+    result.scrollTo(99);
+
+    expect(result.totalSize.value).toBe(4000);
+    scope.stop();
+  });
+
+  it('scrollTo and remeasure are safe no-ops without a scroll element', () => {
+    const { result, scope } = withScope(() => useVirtualList(() => items.slice(0, 10), {
+      estimateSize: 40,
+      initialContainerSize: 100,
+    }));
+
+    expect(() => {
+      result.scrollTo(5);
+      result.scrollToOffset(100);
+      result.remeasure();
+      result.remeasure(2);
+      result.updateLayout();
+    }).not.toThrow();
+    scope.stop();
+  });
+
+  it('slices the window with correct data and indices once the container mounts', async () => {
     const el = makeContainer({ clientHeight: 100 });
-    const { result, scope } = withScope(() => useVirtualList(data, { itemHeight: 20, overscan: 2 }));
+    const { result, scope } = withScope(() => useVirtualList(() => items, {
+      estimateSize: 20,
+      overscan: 2,
+    }));
+
+    // pre-mount: a small fallback window instead of an empty flash
+    expect(result.list.value.length).toBeGreaterThan(0);
+    expect(result.list.value.length).toBeLessThanOrEqual(1 + 2);
+    expect(result.containerProps.style).toMatchObject({ overflowY: 'auto', overflowAnchor: 'none' });
 
     result.containerProps.ref.value = el;
     await nextTick();
 
-    // offset(0) = 0, capacity = ceil(100/20) = 5, overscan 2 -> start 0, end 7.
-    expect(result.list.value[0]).toEqual({ data: 0, index: 0 });
-    expect(result.list.value).toHaveLength(7);
-    expect(result.list.value.at(-1)).toEqual({ data: 6, index: 6 });
+    // capacity = 100/20 = 5 → end 6, +overscan 2 → 8 rows
+    expect(result.list.value[0]).toMatchObject({ data: items[0], index: 0, start: 0, size: 20 });
+    expect(result.list.value).toHaveLength(8);
+    expect(result.list.value[0]!.props['data-index']).toBe(0);
+    expect(result.list.value[0]!.props.style.transform).toBe('translateY(0px)');
     scope.stop();
   });
 
   it('recomputes the window on scroll with correct original indices', async () => {
-    const data = Array.from({ length: 1000 }, (_, i) => i);
     const el = makeContainer({ clientHeight: 100 });
-    const { result, scope } = withScope(() => useVirtualList(data, { itemHeight: 20, overscan: 2 }));
+    const { result, scope } = withScope(() => useVirtualList(() => items, {
+      estimateSize: 20,
+      overscan: 2,
+    }));
 
     result.containerProps.ref.value = el;
     await nextTick();
 
-    el.scrollTop = 400; // offset = floor(400/20) = 20
+    el.scrollTop = 400; // first visible = 400/20 = 20
     el.dispatchEvent(new Event('scroll'));
     await nextTick();
 
-    // start = 20 - 2 = 18, end = 20 + 5 + 2 = 27
-    expect(result.list.value[0]).toEqual({ data: 18, index: 18 });
-    expect(result.list.value.at(-1)).toEqual({ data: 26, index: 26 });
+    expect(result.list.value[0]!.index).toBe(18); // 20 - overscan
+    expect(result.isScrolling.value).toBeTruthy();
     scope.stop();
   });
 
-  it('computes total height and offset spacers via wrapperProps', async () => {
-    const data = Array.from({ length: 50 }, (_, i) => i);
+  it('scrollTo writes the scroll offset for the requested alignment', async () => {
     const el = makeContainer({ clientHeight: 100 });
-    const { result, scope } = withScope(() => useVirtualList(data, { itemHeight: 20, overscan: 0 }));
+    const { result, scope } = withScope(() => useVirtualList(() => items, {
+      estimateSize: 20,
+      overscan: 0,
+    }));
 
     result.containerProps.ref.value = el;
     await nextTick();
 
-    // total height = 50 * 20 = 1000; at top, marginTop = 0
-    expect(result.wrapperProps.value.style.height).toBe('1000px');
-    expect(result.wrapperProps.value.style.marginTop).toBe('0px');
-    expect(result.wrapperProps.value.style.width).toBe('100%');
-
-    el.scrollTop = 200; // offset = 10, start = 10
-    el.dispatchEvent(new Event('scroll'));
-    await nextTick();
-
-    // marginTop = distance(10) = 200px; remaining height = 1000 - 200 = 800px
-    expect(result.wrapperProps.value.style.marginTop).toBe('200px');
-    expect(result.wrapperProps.value.style.height).toBe('800px');
-    scope.stop();
-  });
-
-  it('supports horizontal layout with itemWidth', async () => {
-    const data = Array.from({ length: 1000 }, (_, i) => i);
-    const el = makeContainer({ clientWidth: 100 });
-    const { result, scope } = withScope(() => useVirtualList(data, { itemWidth: 25, overscan: 1 }));
-
-    expect(result.containerProps.style).toEqual({ overflowX: 'auto' });
-
-    result.containerProps.ref.value = el;
-    await nextTick();
-
-    // capacity = ceil(100/25) = 4, overscan 1 -> start 0, end 5
-    expect(result.list.value).toHaveLength(5);
-    expect(result.wrapperProps.value.style.display).toBe('flex');
-    expect(result.wrapperProps.value.style.height).toBe('100%');
-    expect(result.wrapperProps.value.style.marginLeft).toBe('0px');
-    scope.stop();
-  });
-
-  it('supports variable item heights via a getter (prefix-sum metrics)', async () => {
-    const data = Array.from({ length: 100 }, (_, i) => i);
-    const el = makeContainer({ clientHeight: 100 });
-    // even indices: 40px, odd: 10px
-    const itemHeight = (i: number) => (i % 2 === 0 ? 40 : 10);
-    const { result, scope } = withScope(() => useVirtualList(data, { itemHeight, overscan: 0 }));
-
-    result.containerProps.ref.value = el;
-    await nextTick();
-
-    expect(result.list.value[0]).toEqual({ data: 0, index: 0 });
-
-    // total = 50 * 40 + 50 * 10 = 2500
-    expect(result.wrapperProps.value.style.height).toBe('2500px');
-
-    // distance to index 4 = sizes[0..3] = 40+10+40+10 = 100
-    el.scrollTop = 100;
-    el.dispatchEvent(new Event('scroll'));
-    await nextTick();
-
-    expect(result.list.value[0]).toEqual({ data: 4, index: 4 });
-    expect(result.wrapperProps.value.style.marginTop).toBe('100px');
-    scope.stop();
-  });
-
-  it('scrollTo moves the container and re-slices', async () => {
-    const data = Array.from({ length: 1000 }, (_, i) => i);
-    const el = makeContainer({ clientHeight: 100 });
-    const { result, scope } = withScope(() => useVirtualList(data, { itemHeight: 20, overscan: 0 }));
-
-    result.containerProps.ref.value = el;
-    await nextTick();
-
-    result.scrollTo(30);
-    // distance(30) = 30 * 20 = 600; block 'start' keeps offset 0
+    result.scrollTo(30, { align: 'start' });
     expect(el.scrollTop).toBe(600);
-    expect(result.list.value[0]).toEqual({ data: 30, index: 30 });
+
+    result.scrollTo(30, { align: 'center' });
+    expect(el.scrollTop).toBe(600 - (100 - 20) / 2);
     scope.stop();
   });
 
-  it('scrollTo is a no-op when the container is not mounted', () => {
-    const { result, scope } = withScope(() => useVirtualList([1, 2, 3], { itemHeight: 20 }));
-    expect(() => result.scrollTo(2)).not.toThrow();
-    scope.stop();
-  });
-
-  it('reacts to a changing source ref', async () => {
-    const data = ref(Array.from({ length: 10 }, (_, i) => i));
+  it('applies measured sizes delivered by the ResizeObserver', async () => {
     const el = makeContainer({ clientHeight: 100 });
-    const { result, scope } = withScope(() => useVirtualList(data, { itemHeight: 20, overscan: 0 }));
+    const { result, scope } = withScope(() => useVirtualList(() => items, {
+      estimateSize: 20,
+      overscan: 0,
+    }));
 
     result.containerProps.ref.value = el;
     await nextTick();
 
-    // total = 10 * 20 = 200
-    expect(result.wrapperProps.value.style.height).toBe('200px');
+    const observer = observers[0]!;
+    const row = makeRow(0);
+    result.measureElement(row);
+    expect(observer.observe).toHaveBeenCalledWith(row, { box: 'border-box' });
 
-    data.value = Array.from({ length: 100 }, (_, i) => i);
+    observer.callback([resizeEntry(row, 90)], observer as unknown as ResizeObserver);
     await nextTick();
 
-    // total = 100 * 20 = 2000
-    expect(result.wrapperProps.value.style.height).toBe('2000px');
+    // row 0: 20 → 90, total grows by 70
+    expect(result.totalSize.value).toBe(1000 * 20 + 70);
+    expect(result.list.value[0]!.size).toBe(90);
+    expect(result.list.value[1]!.start).toBe(90);
     scope.stop();
   });
 
-  it('clamps the window to the source bounds', async () => {
-    const data = Array.from({ length: 3 }, (_, i) => i);
-    const el = makeContainer({ clientHeight: 1000 });
-    const { result, scope } = withScope(() => useVirtualList(data, { itemHeight: 20, overscan: 5 }));
+  it('compensates the scroll offset when an item above the viewport grows', async () => {
+    const el = makeContainer({ clientHeight: 100 });
+    const { result, scope } = withScope(() => useVirtualList(() => items, {
+      estimateSize: 20,
+      overscan: 0,
+    }));
 
     result.containerProps.ref.value = el;
     await nextTick();
 
-    expect(result.list.value).toHaveLength(3);
-    expect(result.list.value.at(-1)).toEqual({ data: 2, index: 2 });
+    el.scrollTop = 400;
+    el.dispatchEvent(new Event('scroll'));
+    await nextTick();
+
+    const observer = observers[0]!;
+    const row = makeRow(0); // starts at 0, above the viewport top (400)
+    result.measureElement(row);
+    observer.callback([resizeEntry(row, 100)], observer as unknown as ResizeObserver);
+    await nextTick(); // deferred compensation write lands post-patch
+
+    // growth of 80 above the viewport → scrollTop compensated to 480
+    expect(el.scrollTop).toBe(480);
+    scope.stop();
+  });
+
+  it('measures component instances through $el', () => {
+    const { result, scope } = withScope(() => useVirtualList(() => items, {
+      estimateSize: 20,
+      initialContainerSize: 100,
+    }));
+
+    const row = makeRow(3);
+    result.measureElement({ $el: row });
+
+    expect(observers[0]!.observe).toHaveBeenCalledWith(row, { box: 'border-box' });
+    scope.stop();
+  });
+
+  it('warns once when the ref target cannot be measured', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const { result, scope } = withScope(() => useVirtualList(() => items, {
+      estimateSize: 20,
+      initialContainerSize: 100,
+    }));
+
+    result.measureElement({ $el: document.createTextNode('fragment anchor') });
+    result.measureElement({ $el: null });
+
+    expect(warn).toHaveBeenCalledTimes(1);
+    warn.mockRestore();
+    scope.stop();
+  });
+
+  it('supports horizontal layout', async () => {
+    const el = makeContainer({ clientWidth: 100 });
+    const { result, scope } = withScope(() => useVirtualList(() => items, {
+      estimateSize: 25,
+      axis: 'x',
+      overscan: 1,
+    }));
+
+    expect(result.containerProps.style).toMatchObject({ overflowX: 'auto' });
+
+    result.containerProps.ref.value = el;
+    await nextTick();
+
+    // capacity = 100/25 = 4 → end 5, +overscan 1 → 6 rows
+    expect(result.list.value).toHaveLength(6);
+    expect(result.list.value[1]!.props.style.transform).toBe('translateX(25px)');
+    expect(result.wrapperProps.value.style.width).toBe(`${1000 * 25}px`);
+    expect(result.wrapperProps.value.style.height).toBe('100%');
     scope.stop();
   });
 });

vue/toolkit/src/composables/sensors/onLongPress/index.ts

@@ -4,6 +4,7 @@ import { computed } from 'vue';
 import type { MaybeComputedElementRef } from '@/composables/component/unrefElement';
 import { unrefElement } from '@/composables/component/unrefElement';
 import { useEventListener } from '@/composables/browser/useEventListener';
+import { tryOnScopeDispose } from '@/composables/lifecycle/tryOnScopeDispose';
 
 const DEFAULT_DELAY = 500;
 const DEFAULT_THRESHOLD = 10;
@@ -220,6 +221,11 @@ export function onLongPress(
     useEventListener(elementRef, ['pointerup', 'pointerleave'], onRelease, listenerOptions),
   ];
 
+  // The listeners above self-dispose with the scope, but a delay timer armed
+  // by a press that never released would outlive the component and fire the
+  // handler against a dead scope.
+  tryOnScopeDispose(clear);
+
   return (): void => {
     clear();
     cleanups.forEach(stop => stop());

vue/toolkit/src/composables/state/activeApp/demo.vue

@@ -0,0 +1,71 @@
+<script setup lang="ts">
+import { createApp, inject, onUnmounted, reactive, ref } from 'vue';
+import type { InjectionKey } from 'vue';
+import { runWithApp } from './index';
+
+interface Settings {
+  volume: number;
+}
+
+const SettingsKey: InjectionKey<Settings> = Symbol('DemoSettings');
+
+// Imagine this is your main.ts: the app provides DI values and is registered
+// once with `app.use(activeAppPlugin)`. The demo keeps a standalone app and
+// passes it explicitly so it does not touch the docs application.
+const app = createApp({ render: () => null });
+const settings = reactive<Settings>({ volume: 50 });
+app.provide(SettingsKey, settings);
+
+onUnmounted(() => app.unmount());
+
+// A plain module-level function — no setup, no injection context. With
+// `runWithApp` it can still resolve `inject()` against the app.
+function readVolumeFromOutside() {
+  return runWithApp(() => inject(SettingsKey)!.volume, app);
+}
+
+const snapshot = ref<number>();
+</script>
+
+<template>
+  <div class="demo-stack max-w-sm">
+    <div class="demo-card p-4 flex flex-col gap-3">
+      <span class="demo-label">App-provided state</span>
+
+      <label class="flex items-center gap-3 text-sm text-fg">
+        <span class="text-xs text-fg-muted w-14">Volume</span>
+        <input
+          v-model.number="settings.volume"
+          type="range"
+          min="0"
+          max="100"
+          class="flex-1 accent-accent cursor-pointer"
+        >
+        <span class="font-mono text-xs tabular-nums text-fg-muted w-8 text-right">{{ settings.volume }}</span>
+      </label>
+    </div>
+
+    <div class="demo-card p-4 flex flex-col gap-3">
+      <span class="demo-label">Plain function, outside any component</span>
+
+      <button
+        type="button"
+        class="inline-flex items-center justify-center gap-1.5 rounded-lg border border-transparent bg-accent px-3 py-1.5 text-sm font-medium text-accent-fg transition hover:bg-accent-hover active:scale-[0.98] cursor-pointer"
+        @click="snapshot = readVolumeFromOutside()"
+      >
+        runWithApp(() =&gt; inject(SettingsKey))
+      </button>
+
+      <p class="font-mono text-xs tabular-nums text-fg-muted">
+        {{ snapshot === undefined ? 'not read yet' : `injected volume: ${snapshot}` }}
+      </p>
+    </div>
+
+    <p class="text-xs text-fg-subtle">
+      The function reading the value has no injection context of its own —
+      <span class="font-mono text-fg-muted">runWithApp</span> wraps it in
+      <span class="font-mono text-fg-muted">app.runWithContext</span> so
+      <span class="font-mono text-fg-muted">inject()</span> resolves app-level provides.
+    </p>
+  </div>
+</template>

vue/toolkit/src/composables/state/activeApp/index.test.ts

@@ -0,0 +1,176 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createApp, defineComponent, h, inject, provide } from 'vue';
+import type { App, InjectionKey } from 'vue';
+import { activeAppPlugin, getActiveApp, injectWithApp, runWithApp, setActiveApp } from '.';
+import { VueToolsError } from '@/utils';
+
+const key: InjectionKey<string> = Symbol('TestKey');
+
+function makeApp(setup?: () => void) {
+  return createApp(defineComponent({
+    setup() {
+      setup?.();
+      return () => h('div');
+    },
+  }));
+}
+
+function mountApp(app: App) {
+  app.mount(document.createElement('div'));
+  return app;
+}
+
+beforeEach(() => {
+  setActiveApp(undefined);
+});
+
+describe(setActiveApp, () => {
+  it('registers the app and returns it for chaining', () => {
+    const app = makeApp();
+
+    expect(getActiveApp()).toBeUndefined();
+    expect(setActiveApp(app)).toBe(app);
+    expect(getActiveApp()).toBe(app);
+  });
+
+  it('clears the registration with undefined', () => {
+    setActiveApp(makeApp());
+    setActiveApp(undefined);
+
+    expect(getActiveApp()).toBeUndefined();
+  });
+});
+
+describe(getActiveApp, () => {
+  it('prefers the current instance app over the registered one', () => {
+    const other = makeApp();
+    setActiveApp(other);
+
+    let captured: App | undefined;
+    const app = mountApp(makeApp(() => {
+      captured = getActiveApp();
+    }));
+
+    expect(captured).toBe(app);
+    expect(captured).not.toBe(other);
+
+    app.unmount();
+  });
+});
+
+describe(runWithApp, () => {
+  it('resolves app-level provides through the active app', () => {
+    const app = makeApp();
+    app.provide(key, 'from app');
+    setActiveApp(app);
+
+    expect(runWithApp(() => inject(key))).toBe('from app');
+  });
+
+  it('uses an explicitly passed app over the active one', () => {
+    const active = makeApp();
+    active.provide(key, 'active');
+    setActiveApp(active);
+
+    const explicit = makeApp();
+    explicit.provide(key, 'explicit');
+
+    expect(runWithApp(() => inject(key), explicit)).toBe('explicit');
+  });
+
+  it('returns the function result', () => {
+    setActiveApp(makeApp());
+
+    expect(runWithApp(() => 42)).toBe(42);
+  });
+
+  it('throws when no app is available', () => {
+    expect(() => runWithApp(() => inject(key))).toThrow(VueToolsError);
+  });
+});
+
+describe(injectWithApp, () => {
+  it('resolves app-level provides outside of setup', () => {
+    const app = makeApp();
+    app.provide(key, 'from app');
+    setActiveApp(app);
+
+    expect(injectWithApp(key)).toBe('from app');
+  });
+
+  it('behaves like inject inside setup, component provides win', () => {
+    const app = makeApp();
+    app.provide(key, 'app level');
+    setActiveApp(app);
+
+    let fromParent: string | undefined;
+    const Child = defineComponent({
+      setup() {
+        fromParent = injectWithApp(key);
+        return () => h('div');
+      },
+    });
+
+    const host = createApp(defineComponent({
+      setup() {
+        provide(key, 'component level');
+        return () => h(Child);
+      },
+    }));
+    host.provide(key, 'host app level');
+    mountApp(host);
+
+    expect(fromParent).toBe('component level');
+
+    host.unmount();
+  });
+
+  it('falls back to the default value when the key is not provided', () => {
+    setActiveApp(makeApp());
+
+    expect(injectWithApp(key, 'fallback')).toBe('fallback');
+    expect(injectWithApp(key, () => 'factory', true)).toBe('factory');
+  });
+
+  it('returns the default value when no app is available at all', () => {
+    expect(injectWithApp(key, 'fallback')).toBe('fallback');
+    expect(injectWithApp(key, () => 'factory', true)).toBe('factory');
+  });
+
+  it('does not call a function default unless treated as factory', () => {
+    const fn = vi.fn(() => 'value');
+    const injected = injectWithApp<() => string>(Symbol('FnKey'), fn);
+
+    expect(injected).toBe(fn);
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('throws when there is no context, no app and no default', () => {
+    expect(() => injectWithApp(key)).toThrow(VueToolsError);
+  });
+});
+
+describe(activeAppPlugin, () => {
+  it('registers the app on install', () => {
+    const app = makeApp().use(activeAppPlugin);
+
+    expect(getActiveApp()).toBe(app);
+  });
+
+  it('clears the registration when the app unmounts', () => {
+    const app = mountApp(makeApp().use(activeAppPlugin));
+
+    app.unmount();
+
+    expect(getActiveApp()).toBeUndefined();
+  });
+
+  it('keeps the registration when a stale app unmounts', () => {
+    const first = mountApp(makeApp().use(activeAppPlugin));
+    const second = makeApp().use(activeAppPlugin);
+
+    first.unmount();
+
+    expect(getActiveApp()).toBe(second);
+  });
+});

vue/toolkit/src/composables/state/activeApp/index.ts

@@ -0,0 +1,150 @@
+import { getCurrentInstance, hasInjectionContext, inject } from 'vue';
+import type { App, InjectionKey, Plugin } from 'vue';
+import { VueToolsError } from '@/utils';
+
+type InjectDefaults<Value> = [defaultValue?: Value | (() => Value), treatDefaultAsFactory?: boolean];
+
+let activeApp: App | undefined;
+
+/**
+ * @name setActiveApp
+ * @category State
+ * @description Registers the Vue app instance used by `getActiveApp`, `runWithApp` and `injectWithApp`
+ * outside of component context. Pass `undefined` to clear the registration.
+ *
+ * The registration is module-global (one slot per JS realm). On the client this is exactly
+ * what you want; on the server create one app per request and prefer passing the app
+ * explicitly to `runWithApp` instead of relying on the global slot, otherwise concurrent
+ * requests may observe each other's app.
+ *
+ * @param {App | undefined} app The app to register, or `undefined` to clear
+ * @returns {App | undefined} The same app, for chaining
+ *
+ * @example
+ * // main.ts
+ * const app = createApp(App);
+ * setActiveApp(app);
+ *
+ * @since 0.1.0
+ */
+export function setActiveApp(app: App | undefined) {
+  activeApp = app;
+  return app;
+}
+
+/**
+ * @name getActiveApp
+ * @category State
+ * @description Returns the closest Vue app instance: the current component's app when called
+ * during setup (or anywhere `getCurrentInstance` works), otherwise the app registered via
+ * `setActiveApp` / `activeAppPlugin`.
+ *
+ * @returns {App | undefined} The resolved app, or `undefined` when none is available
+ *
+ * @example
+ * const app = getActiveApp();
+ * app?.config.globalProperties;
+ *
+ * @since 0.1.0
+ */
+export function getActiveApp(): App | undefined {
+  return getCurrentInstance()?.appContext.app ?? activeApp;
+}
+
+/**
+ * @name runWithApp
+ * @category State
+ * @description Runs a function inside `app.runWithContext`, so `inject` (and everything built
+ * on it) resolves app-level provides even outside of component setup — in router guards,
+ * store actions, event handlers or timers.
+ *
+ * The app defaults to `getActiveApp()`; pass one explicitly to target a specific app
+ * (recommended for SSR, where apps are created per request).
+ *
+ * @param {Function} fn The function to run with the app as injection context
+ * @param {App} [app] The app to use instead of the active one
+ * @returns The return value of `fn`
+ * @throws {VueToolsError} when no app is registered and none is passed
+ *
+ * @example
+ * router.beforeEach(() => {
+ *   const auth = runWithApp(() => inject(AuthKey));
+ * });
+ *
+ * @since 0.1.0
+ */
+export function runWithApp<Result>(fn: () => Result, app: App | undefined = getActiveApp()): Result {
+  if (!app)
+    throw new VueToolsError('runWithApp: no active Vue app, install activeAppPlugin or call setActiveApp first');
+
+  return app.runWithContext(fn);
+}
+
+/**
+ * @name injectWithApp
+ * @category State
+ * @description Drop-in replacement for `inject` that also works outside of component setup.
+ * Inside an injection context it behaves exactly like `inject` (component-level provides
+ * win); outside it resolves app-level provides through the active app. When no app is
+ * available it falls back to the provided default value, or throws if there is none.
+ *
+ * @param {InjectionKey | string} key The injection key
+ * @param {any} [defaultValue] The value (or factory) to fall back to when the key is not provided
+ * @param {boolean} [treatDefaultAsFactory] Call `defaultValue` as a factory, like `inject`
+ * @returns The injected value
+ * @throws {VueToolsError} when called with no injection context, no active app and no default value
+ *
+ * @example
+ * const theme = injectWithApp(ThemeKey, 'light');
+ *
+ * @since 0.1.0
+ */
+export function injectWithApp<Value>(key: InjectionKey<Value> | string): Value | undefined;
+export function injectWithApp<Value>(key: InjectionKey<Value> | string, defaultValue: Value, treatDefaultAsFactory?: false): Value;
+export function injectWithApp<Value>(key: InjectionKey<Value> | string, defaultValue: Value | (() => Value), treatDefaultAsFactory: true): Value;
+export function injectWithApp<Value>(key: InjectionKey<Value> | string, ...defaults: InjectDefaults<Value>): Value | undefined {
+  // spread `defaults` as-is: `inject` distinguishes a missing default from an
+  // explicit `undefined` one via `arguments.length`
+  const doInject = () => (inject as (...args: [typeof key, ...InjectDefaults<Value>]) => Value | undefined)(key, ...defaults);
+
+  if (hasInjectionContext())
+    return doInject();
+
+  const app = getActiveApp();
+
+  if (app)
+    return app.runWithContext(doInject);
+
+  if (defaults.length > 0) {
+    const [defaultValue, treatDefaultAsFactory] = defaults;
+
+    return treatDefaultAsFactory && typeof defaultValue === 'function'
+      ? (defaultValue as () => Value)()
+      : defaultValue as Value;
+  }
+
+  throw new VueToolsError('injectWithApp: no injection context and no active Vue app, install activeAppPlugin or call setActiveApp first');
+}
+
+/**
+ * @name activeAppPlugin
+ * @category State
+ * @description Vue plugin that registers the app as the active one and clears the
+ * registration when the app unmounts (unless another app took over in the meantime).
+ *
+ * @example
+ * // main.ts
+ * createApp(App).use(activeAppPlugin).mount('#app');
+ *
+ * @since 0.1.0
+ */
+export const activeAppPlugin: Plugin = {
+  install(app) {
+    setActiveApp(app);
+
+    app.onUnmount(() => {
+      if (activeApp === app)
+        setActiveApp(undefined);
+    });
+  },
+};

vue/toolkit/src/composables/state/index.ts

@@ -1,3 +1,4 @@
+export * from './activeApp';
 export * from './createSharedComposable';
 export * from './useAppSharedState';
 export * from './useAsyncState';
@@ -11,6 +12,7 @@ export * from './useLastChanged';
 export * from './useManualRefHistory';
 export * from './useOffsetPagination';
 export * from './useRefHistory';
+export * from './useStateMachine';
 export * from './useStepper';
 export * from './useThrottledRefHistory';
 export * from './useToggle';

vue/toolkit/src/composables/state/useStateMachine/demo.vue

@@ -0,0 +1,60 @@
+<script setup lang="ts">
+import { useStateMachine } from './index';
+
+// A media-player transport: the machine makes the button matrix declarative —
+// what each control does (and whether it's enabled) follows from the state.
+const { state, send, can, matches } = useStateMachine({
+  initial: 'stopped',
+  states: {
+    stopped: { on: { PLAY: 'playing' } },
+    playing: { on: { PAUSE: 'paused', STOP: 'stopped' } },
+    paused: { on: { PLAY: 'playing', STOP: 'stopped' } },
+  },
+});
+</script>
+
+<template>
+  <div class="demo-stack max-w-sm">
+    <div class="demo-card p-4">
+      <p class="demo-label">
+        Media transport
+      </p>
+
+      <div class="mt-3 flex items-center gap-3">
+        <span
+          class="demo-badge"
+          :class="matches('playing') ? 'text-emerald-600 dark:text-emerald-400' : ''"
+        >
+          {{ matches('playing') ? '▶' : matches('paused') ? '⏸' : '⏹' }} {{ state }}
+        </span>
+      </div>
+
+      <div class="mt-3 flex gap-2">
+        <button
+          type="button"
+          class="demo-btn-primary flex-1 disabled:cursor-not-allowed disabled:opacity-40 disabled:active:scale-100"
+          :disabled="!can('PLAY')"
+          @click="send('PLAY')"
+        >
+          Play
+        </button>
+        <button
+          type="button"
+          class="demo-btn flex-1 disabled:cursor-not-allowed disabled:opacity-40 disabled:active:scale-100"
+          :disabled="!can('PAUSE')"
+          @click="send('PAUSE')"
+        >
+          Pause
+        </button>
+        <button
+          type="button"
+          class="demo-btn flex-1 disabled:cursor-not-allowed disabled:opacity-40 disabled:active:scale-100"
+          :disabled="!can('STOP')"
+          @click="send('STOP')"
+        >
+          Stop
+        </button>
+      </div>
+    </div>
+  </div>
+</template>

vue/toolkit/src/composables/state/useStateMachine/index.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it, vi } from 'vitest';
+import { computed } from 'vue';
+import { useStateMachine } from './index';
+
+function trafficLight() {
+  return useStateMachine({
+    initial: 'red',
+    states: {
+      red: { on: { NEXT: 'green' } },
+      green: { on: { NEXT: 'yellow' } },
+      yellow: { on: { NEXT: 'red' } },
+    },
+  });
+}
+
+describe(useStateMachine, () => {
+  it('starts in the initial state', () => {
+    const { state, matches } = trafficLight();
+
+    expect(state.value).toBe('red');
+    expect(matches('red')).toBeTruthy();
+    expect(matches('green')).toBeFalsy();
+  });
+
+  it('transitions on send and mirrors the state into the ref', () => {
+    const { state, send } = trafficLight();
+
+    expect(send('NEXT')).toBe('green');
+    expect(state.value).toBe('green');
+
+    send('NEXT');
+    expect(state.value).toBe('yellow');
+  });
+
+  it('ignores events without a matching transition', () => {
+    const { state, send } = useStateMachine({
+      initial: 'idle',
+      states: {
+        idle: { on: { START: 'running' } },
+        running: {},
+      },
+    });
+
+    send('START');
+    expect(send('START')).toBe('running');
+    expect(state.value).toBe('running');
+  });
+
+  it('is reactive: computeds tracking state/matches/can re-evaluate', () => {
+    const { send, matches, can, state } = trafficLight();
+
+    const isRed = computed(() => matches('red'));
+    const label = computed(() => state.value.toUpperCase());
+    const canAdvance = computed(() => can('NEXT'));
+
+    expect(isRed.value).toBeTruthy();
+    expect(label.value).toBe('RED');
+    expect(canAdvance.value).toBeTruthy();
+
+    send('NEXT');
+
+    expect(isRed.value).toBeFalsy();
+    expect(label.value).toBe('GREEN');
+  });
+
+  it('respects guards and exposes them through can()', () => {
+    const { state, send, can } = useStateMachine({
+      initial: 'locked',
+      context: { coins: 0 },
+      states: {
+        locked: {
+          on: {
+            PUSH: { target: 'open', guard: ctx => ctx.coins > 0 },
+            COIN: { target: 'locked', action: (ctx) => { ctx.coins++; } },
+          },
+        },
+        open: {},
+      },
+    });
+
+    expect(can('PUSH')).toBeFalsy();
+    send('PUSH');
+    expect(state.value).toBe('locked');
+
+    send('COIN');
+    expect(can('PUSH')).toBeTruthy();
+    send('PUSH');
+    expect(state.value).toBe('open');
+  });
+
+  it('runs action, exit, and entry hooks in order', () => {
+    const order: string[] = [];
+
+    const { send } = useStateMachine({
+      initial: 'a',
+      states: {
+        a: {
+          exit: () => order.push('exit:a'),
+          on: { GO: { target: 'b', action: () => order.push('action') } },
+        },
+        b: {
+          entry: () => order.push('entry:b'),
+        },
+      },
+    });
+
+    send('GO');
+    expect(order).toEqual(['action', 'exit:a', 'entry:b']);
+  });
+
+  it('settles on the final state when hooks send follow-up events', () => {
+    const machine = useStateMachine({
+      initial: 'idle',
+      states: {
+        idle: { on: { START: 'transient' } },
+        transient: {
+          entry: () => machine.send('CONTINUE'),
+          on: { CONTINUE: 'done' },
+        },
+        done: {},
+      },
+    });
+
+    expect(machine.send('START')).toBe('done');
+    expect(machine.state.value).toBe('done');
+  });
+
+  it('keeps can() reactive across context-mutating self-transitions', () => {
+    const { send, can } = useStateMachine({
+      initial: 'locked',
+      context: { coins: 0 },
+      states: {
+        locked: {
+          on: {
+            PUSH: { target: 'open', guard: ctx => ctx.coins > 0 },
+            COIN: { target: 'locked', action: (ctx) => { ctx.coins++; } },
+          },
+        },
+        open: {},
+      },
+    });
+
+    const canPush = computed(() => can('PUSH'));
+
+    expect(canPush.value).toBeFalsy();
+
+    // Self-transition: the state string does not change, only the context.
+    send('COIN');
+
+    expect(canPush.value).toBeTruthy();
+  });
+
+  it('keeps the state ref in sync when a hook throws', () => {
+    const { state, send } = useStateMachine({
+      initial: 'a',
+      states: {
+        a: { on: { GO: 'b' } },
+        b: { entry: () => { throw new Error('boom'); } },
+      },
+    });
+
+    expect(() => send('GO')).toThrow('boom');
+    expect(state.value).toBe('b');
+  });
+
+  it('exposes the raw machine with its context', () => {
+    const onEnter = vi.fn();
+    const { machine, send } = useStateMachine({
+      initial: 'off',
+      context: { toggles: 0 },
+      states: {
+        off: { on: { TOGGLE: { target: 'on', action: (ctx) => { ctx.toggles++; } } } },
+        on: { entry: onEnter },
+      },
+    });
+
+    send('TOGGLE');
+
+    expect(machine.context.toggles).toBe(1);
+    expect(machine.current).toBe('on');
+    expect(machine.matches('on')).toBeTruthy();
+    expect(onEnter).toHaveBeenCalledTimes(1);
+  });
+});

vue/toolkit/src/composables/state/useStateMachine/index.ts

@@ -0,0 +1,122 @@
+import { shallowRef } from 'vue';
+import { StateMachine } from '@robonen/stdlib';
+import type { ExtractEvents, ExtractStates, SyncStateNodeConfig } from '@robonen/stdlib';
+import type { ShallowRef } from 'vue';
+
+export interface UseStateMachineReturn<
+  States extends string,
+  Events extends string,
+  Context,
+> {
+  /** Reactive current state of the machine. */
+  state: Readonly<ShallowRef<States>>;
+
+  /**
+   * Send an event to the machine, potentially causing a transition.
+   * Returns the state the machine settled on (entry/exit hooks may themselves
+   * send events; the returned state is the final one).
+   */
+  send: (event: Events) => States;
+
+  /** Reactive check: is the machine currently in `state`? */
+  matches: (state: States) => boolean;
+
+  /** Reactive check: can `event` cause a transition from the current state? */
+  can: (event: Events) => boolean;
+
+  /** The underlying stdlib machine (context access, non-reactive escape hatch). */
+  machine: StateMachine<States, Events, Context>;
+}
+
+/**
+ * @name useStateMachine
+ * @category State
+ * @description Reactive wrapper around the stdlib `StateMachine`: a type-safe
+ * finite state machine whose current state is exposed as a shallow ref, so
+ * templates and computeds can branch on `state`/`matches`/`can`.
+ *
+ * States, events, guards, and entry/exit hooks follow the stdlib
+ * `createMachine` config verbatim — this composable only adds reactivity.
+ *
+ * @param {object} config Machine config: `initial`, optional `context`, and `states`
+ * @returns {UseStateMachineReturn} Reactive state plus `send`/`matches`/`can` and the raw machine
+ *
+ * @example
+ * const { state, send, can } = useStateMachine({
+ *   initial: 'idle',
+ *   states: {
+ *     idle: { on: { FETCH: 'loading' } },
+ *     loading: { on: { RESOLVE: 'idle', REJECT: 'failed' } },
+ *     failed: { on: { RETRY: 'loading' } },
+ *   },
+ * });
+ *
+ * send('FETCH'); // state.value === 'loading'
+ * can('RETRY'); // false — reactive, usable in computeds/templates
+ *
+ * @since 0.2.0
+ */
+export function useStateMachine<
+  const States extends Record<string, SyncStateNodeConfig<Context>>,
+  Context,
+>(config: {
+  initial: NoInfer<ExtractStates<States>>;
+  context: Context;
+  states: States;
+}): UseStateMachineReturn<ExtractStates<States>, ExtractEvents<States>, Context>;
+
+export function useStateMachine<
+  const States extends Record<string, SyncStateNodeConfig<undefined>>,
+>(config: {
+  initial: NoInfer<ExtractStates<States>>;
+  states: States;
+}): UseStateMachineReturn<ExtractStates<States>, ExtractEvents<States>, undefined>;
+
+export function useStateMachine(config: {
+  initial: string;
+  context?: unknown;
+  // Overload-implementation signature (mirrors stdlib `createMachine`): `any`
+  // accepts every concrete `SyncStateNodeConfig<C>` — contravariant in `C` —
+  // and `Context = undefined` keeps the invariant `StateMachine<..., Context>`
+  // comparable with both public overloads.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  states: Record<string, SyncStateNodeConfig<any>>;
+}): UseStateMachineReturn<string, string, undefined> {
+  const machine = new StateMachine(config.initial, config.states, config.context as undefined);
+
+  const state = shallowRef(machine.current);
+
+  // Bumped on EVERY send: a self-transition leaves the state string unchanged
+  // (so `state` doesn't trigger) yet its action may mutate the context that
+  // `can()` guards read.
+  const epoch = shallowRef(0);
+
+  function send(event: string): string {
+    // Mirror the settled state (not send's return value — entry/exit hooks may
+    // send follow-up events) even when a hook throws: the machine has already
+    // advanced by the time hooks run.
+    try {
+      machine.send(event);
+    }
+    finally {
+      state.value = machine.current;
+      epoch.value++;
+    }
+
+    return machine.current;
+  }
+
+  function matches(value: string): boolean {
+    return state.value === value;
+  }
+
+  function can(event: string): boolean {
+    // Track the send epoch (it covers state changes too) so callers re-evaluate
+    // after every transition, including context-mutating self-transitions.
+    void epoch.value;
+
+    return machine.can(event);
+  }
+
+  return { state, send, matches, can, machine };
+}

vue/toolkit/src/composables/storage/useCookie/demo.vue

@@ -28,7 +28,8 @@ function toggle(key: (typeof categories)[number]['key']) {
   consent.value = { ...consent.value, [key]: !consent.value[key] };
 }
 
-const supportsCookieStore = typeof window !== 'undefined' && 'cookieStore' in window;
+// Probing `globalThis` keeps this SSR-safe without a browser-only guard.
+const supportsCookieStore = 'cookieStore' in globalThis;
 
 // Show the raw cookie as the browser stores it.
 const rawCookie = ref('');

vue/writekit/package.json

@@ -19,7 +19,7 @@
     "url": "git+https://github.com/robonen/tools.git",
     "directory": "vue/writekit"
   },
-  "packageManager": "pnpm@11.7.0",
+  "packageManager": "pnpm@11.18.0",
   "engines": {
     "node": ">=24.16.0"
   },
@@ -63,16 +63,16 @@
     "@robonen/tsconfig": "workspace:*",
     "@robonen/tsdown": "workspace:*",
     "@vitest/browser": "catalog:",
-    "@vitest/browser-playwright": "^4.1.9",
+    "@vitest/browser-playwright": "^4.1.10",
     "@vue/test-utils": "catalog:",
     "eslint": "catalog:",
     "jsdom": "catalog:",
-    "playwright": "^1.61.0",
+    "playwright": "^1.62.0",
     "tsdown": "catalog:",
     "unplugin-vue": "^7.2.0",
     "vitest-browser-vue": "^2.1.0",
     "vue": "catalog:",
-    "vue-tsc": "^3.3.5"
+    "vue-tsc": "^3.3.8"
   },
   "dependencies": {
     "@robonen/crdt": "workspace:*",

vue/writekit/playground/package.json

@@ -16,8 +16,8 @@
   },
   "devDependencies": {
     "@robonen/tsconfig": "workspace:*",
-    "@vitejs/plugin-vue": "^6.0.7",
-    "vite": "^8.0.16",
-    "vue-tsc": "^3.3.5"
+    "@vitejs/plugin-vue": "^6.0.8",
+    "vite": "^8.1.5",
+    "vue-tsc": "^3.3.8"
   }
 }